# HG changeset patch # User Dominic Pinkman # Date 1276256343 -3600 # Node ID ae94777fff8f07421e6106c955685cbb1c1b95a3 # Parent 51a74ef9ed638b9b756d35af243496bd82142f42 Week 23 contribution of SDK documentation content. See release notes for details. Fixes bugs Bug 2714, Bug 462. diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-000ACB11-EDD0-5160-BC5E-4593F1BAF293.dita --- a/Symbian3/SDK/Source/GUID-000ACB11-EDD0-5160-BC5E-4593F1BAF293.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-000ACB11-EDD0-5160-BC5E-4593F1BAF293.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,64 +1,64 @@ - - - - - -Message -Queue OverviewThis topic describes the message queue overview. -

A message queue is a mechanism for passing data:

-
    -

  • between threads within -a process

    • -

  • between threads that -run in separate processes.

    • -
-

The mechanism provides a way to send data (messages) to an interested party -without needing to know whether anyone is listening nor needing to know the -identity of a recipient.

-

A message is an object, usually an instance of a class, that is placed -into a queue for delivery to recipients. A queue is normally created to deal -with messages of a given type. This means that a queue is created to deal -with messages of a defined (fixed) length. The size of a queue, i.e. the maximum -number of messages, or slots, it can contain is defined and fixed when the -queue is created. The size of message for which a queue is created, and the -size of the queue is arbitrary, being limited only by system resources.

-

A single queue can be shared by many readers and writers. Several threads -may be reading from and writing to the same message queue, but only one thread -can access the queue at a time. If multiple clients attempt to read from the -message queue a panic will be raised.

-

A message queue is represented by a DMsgQueue kernel side -object, to which the reader and the writer can open a handle, a RMsgQueue object. -A message queue is a reference counted object, being derived from CObject, -which means that it is not persistent; it is deleted when the last handle -to it is closed. The queue itself is simply a block of memory divided into -slots, managed by the DMsgQueue object.

- - - -
Handle to a -message queue

A message queue is created, opened, written to and -read from through a message queue handle, an RMsgQueue object. -This is a templated class, where the template parameter defines the message -type.

RMsgQueue is derived from RMsgQueueBase, -which together form a thin template class/base class pair. RMsgQueueBase provides -the implementation, while RMsgQueue provides type safety. -An RMsgQueueBase object is a valid message queue handle, -but does not offer the type safety that RMsgQueue does.

- -

Message queues are used for one-way, one to one communications only. -The message queue is therefore unicast. If there are multiple readers of the -message queue only one will receive the message.

-
Visibility -of a message queue

A message queue can be:

    -

  • named and be visible -to all processes - a global queue

    • -

  • local to the current -process, i.e. not visible to any other process - a local queue

    • -
+ + + + + +Message +Queue OverviewThis topic describes the message queue overview. +

A message queue is a mechanism for passing data:

+
    +

  • between threads within +a process

    • +

  • between threads that +run in separate processes.

    • +
+

The mechanism provides a way to send data (messages) to an interested party +without needing to know whether anyone is listening nor needing to know the +identity of a recipient.

+

A message is an object, usually an instance of a class, that is placed +into a queue for delivery to recipients. A queue is normally created to deal +with messages of a given type. This means that a queue is created to deal +with messages of a defined (fixed) length. The size of a queue, i.e. the maximum +number of messages, or slots, it can contain is defined and fixed when the +queue is created. The size of message for which a queue is created, and the +size of the queue is arbitrary, being limited only by system resources.

+

A single queue can be shared by many readers and writers. Several threads +may be reading from and writing to the same message queue, but only one thread +can access the queue at a time. If multiple clients attempt to read from the +message queue a panic will be raised.

+

A message queue is represented by a DMsgQueue kernel side +object, to which the reader and the writer can open a handle, a RMsgQueue object. +A message queue is a reference counted object, being derived from CObject, +which means that it is not persistent; it is deleted when the last handle +to it is closed. The queue itself is simply a block of memory divided into +slots, managed by the DMsgQueue object.

+ + + +
Handle to a +message queue

A message queue is created, opened, written to and +read from through a message queue handle, an RMsgQueue object. +This is a templated class, where the template parameter defines the message +type.

RMsgQueue is derived from RMsgQueueBase, +which together form a thin template class/base class pair. RMsgQueueBase provides +the implementation, while RMsgQueue provides type safety. +An RMsgQueueBase object is a valid message queue handle, +but does not offer the type safety that RMsgQueue does.

+ +

Message queues are used for one-way, one to one communications only. +The message queue is therefore unicast. If there are multiple readers of the +message queue only one will receive the message.

+
Visibility +of a message queue

A message queue can be:

    +

  • named and be visible +to all processes - a global queue

    • +

  • local to the current +process, i.e. not visible to any other process - a local queue

    • +
 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-006C503D-1E52-450D-A4DA-8C19B141E09F.dita --- a/Symbian3/SDK/Source/GUID-006C503D-1E52-450D-A4DA-8C19B141E09F.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-006C503D-1E52-450D-A4DA-8C19B141E09F.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,137 +1,137 @@ - - - - - -Introduction -to Intermixing C and C++When porting an open source application or any C (or C++) applications -on top of Symbian/S60 using P.I.P.S., the developer will come across situations -where C and C++ (and Symbian C++ as well) codes will be used together. The -open source community implements a vast number of libraries that export C -APIs to the user of such libraries. -
When -and why to use C linkage

While porting such applications, -if developers have to intermix C and C++ code, they then have to depend on -C++ language features like extern "C" for giving C linkage to some set of -APIs. This is required because C and C++ compilers handle function prototype -in a different way. C++ compilers use name mangling, (or name decoration) -to generate unique names for identifiers in a program. It is because of this -technique, in C++, that it is possible to overload any functions (this requires -that all the overloaded functions should have a different argument list). -The C++ mangled name for any identifier contains all the necessary information -that may be needed by the linker, such as linkage type, scope, calling convention, -and others.

All identifiers (function names or variable names) declared -or defined in C++ source or headers are subject to name mangling. When it -comes to C, however, there is nothing called name mangling or overloading. -It applies when the developer tries to use C APIs by including corresponding -headers. To avoid name mangling, the developer should mention explicitly that -those APIs are C APIs, by using the extern "C" keyword.

-
Syntax -of extern C

The syntax of extern "C" is shown below:

extern "C" declaration ; -

The declaration (or definition) that immediately follows extern -"C" has the C linkage.

extern "C" { - declaration ; - declaration ; - ... -}

Everything between the curly braces has C linkage, unless -declared otherwise.

-
How -to use extern C

While writing header files with C functions -which will be included by both C and C++ source files, the user must use extern -"C" properly. See the example below:

/*File: GoodCHeader.h */ -/* Can be used by C/C++ header and source files directly */ - -#ifdef __cplusplus -extern "C" { -#endif -/* Write C function declarations here */ -void Function1(int, int); -char* Function3(char*, int); -int Function2(int); -#ifdef __cplusplus -} /* extern "C" */ -#endif -

Using ifdef __cplusplus is required since -C does not support or recognize the extern keyword. It is -C++ that provides the mechanisms for mixing C and C++ codes in the same program. -To be precise, C++ supports mixing codes that are compiled by C and C++ compatible -compilers in the same program.

If the C header is already defined and -it does not have all the APIs defined under extern "C", then while including -such a header in C++ source or header files, extern "C" should be used as -in the example below:

*File: PureCHeader.h */ -/* If C++ header/source files need to include this header, extern "C" should be used*/ -/* Define all C APIs here*/ -void Function1(int, int); -char* Function3(char*, int); -int Function2(int); -#endif - - -//File: CSource.cpp -// C++ source file using PureCHeader.h -extern "C" { -#include "PureCHeader.h" -} -void Foo() { - // use those C APIs here - int ret = Function2(10); -} -
-
Mixing -C and C++ features using extern "C"

The developer -can use all the features of C++ except templates within C by giving those -functions extern "C" linkage. See the example below:

#include <iostream> -using namespace std; - -extern "C" { - -//Can give C linkage to this class!! -class Sample{ -public: - Sample(int a = 10) : iMem(a) { } - void Display() { cout<<"iMem is : "<<iMemend1; } -private: - int iMem; -}; - -/* -//Can not give C linkage to template!! -//If we uncomment this code, then it will give a compilation error. -template<class DataType> void Foo(DataType data) { -}*/ -}
-
Extending C -codes with C++ Codes

Using C linkage, C codes like structures and -functions that manipulate those structures can be extended efficiently in -a C++ source file as in the example below:

/* File: CHeader.h */ -typedef struct{ - char* name; - int id; - float price; -} Item; - -int Push(Item* item); -int Pop(Item* item); - - - -/* File: CppHeader.h */ -//Give external linkage to C structure -extern "C" { -# include "CHeader.h" -} - -class MyStack : public Item { -public: - MyStack(char* aName, int aId, float aPrice) : name(aName), id(aId), price(aPrice) { } - int PushOnToStack() { return Push(this);} - int PopFromStack() { return Pop(this); } -}; -
+ + + + + +Introduction +to Intermixing C and C++When porting an open source application or any C (or C++) applications +on top of Symbian/S60 using P.I.P.S., the developer will come across situations +where C and C++ (and Symbian C++ as well) codes will be used together. The +open source community implements a vast number of libraries that export C +APIs to the user of such libraries. +
When +and why to use C linkage

While porting such applications, +if developers have to intermix C and C++ code, they then have to depend on +C++ language features like extern "C" for giving C linkage to some set of +APIs. This is required because C and C++ compilers handle function prototype +in a different way. C++ compilers use name mangling, (or name decoration) +to generate unique names for identifiers in a program. It is because of this +technique, in C++, that it is possible to overload any functions (this requires +that all the overloaded functions should have a different argument list). +The C++ mangled name for any identifier contains all the necessary information +that may be needed by the linker, such as linkage type, scope, calling convention, +and others.

All identifiers (function names or variable names) declared +or defined in C++ source or headers are subject to name mangling. When it +comes to C, however, there is nothing called name mangling or overloading. +It applies when the developer tries to use C APIs by including corresponding +headers. To avoid name mangling, the developer should mention explicitly that +those APIs are C APIs, by using the extern "C" keyword.

+
Syntax +of extern C

The syntax of extern "C" is shown below:

extern "C" declaration ; +

The declaration (or definition) that immediately follows extern +"C" has the C linkage.

extern "C" { + declaration ; + declaration ; + ... +}

Everything between the curly braces has C linkage, unless +declared otherwise.

+
How +to use extern C

While writing header files with C functions +which will be included by both C and C++ source files, the user must use extern +"C" properly. See the example below:

/*File: GoodCHeader.h */ +/* Can be used by C/C++ header and source files directly */ + +#ifdef __cplusplus +extern "C" { +#endif +/* Write C function declarations here */ +void Function1(int, int); +char* Function3(char*, int); +int Function2(int); +#ifdef __cplusplus +} /* extern "C" */ +#endif +

Using ifdef __cplusplus is required since +C does not support or recognize the extern keyword. It is +C++ that provides the mechanisms for mixing C and C++ codes in the same program. +To be precise, C++ supports mixing codes that are compiled by C and C++ compatible +compilers in the same program.

If the C header is already defined and +it does not have all the APIs defined under extern "C", then while including +such a header in C++ source or header files, extern "C" should be used as +in the example below:

*File: PureCHeader.h */ +/* If C++ header/source files need to include this header, extern "C" should be used*/ +/* Define all C APIs here*/ +void Function1(int, int); +char* Function3(char*, int); +int Function2(int); +#endif + + +//File: CSource.cpp +// C++ source file using PureCHeader.h +extern "C" { +#include "PureCHeader.h" +} +void Foo() { + // use those C APIs here + int ret = Function2(10); +} +
+
Mixing +C and C++ features using extern "C"

The developer +can use all the features of C++ except templates within C by giving those +functions extern "C" linkage. See the example below:

#include <iostream> +using namespace std; + +extern "C" { + +//Can give C linkage to this class!! +class Sample{ +public: + Sample(int a = 10) : iMem(a) { } + void Display() { cout<<"iMem is : "<<iMemend1; } +private: + int iMem; +}; + +/* +//Can not give C linkage to template!! +//If we uncomment this code, then it will give a compilation error. +template<class DataType> void Foo(DataType data) { +}*/ +}
+
Extending C +codes with C++ Codes

Using C linkage, C codes like structures and +functions that manipulate those structures can be extended efficiently in +a C++ source file as in the example below:

/* File: CHeader.h */ +typedef struct{ + char* name; + int id; + float price; +} Item; + +int Push(Item* item); +int Pop(Item* item); + + + +/* File: CppHeader.h */ +//Give external linkage to C structure +extern "C" { +# include "CHeader.h" +} + +class MyStack : public Item { +public: + MyStack(char* aName, int aId, float aPrice) : name(aName), id(aId), price(aPrice) { } + int PushOnToStack() { return Push(this);} + int PopFromStack() { return Pop(this); } +}; +
 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-01029B52-55E0-5598-994F-BB5DE73D37EE.dita --- a/Symbian3/SDK/Source/GUID-01029B52-55E0-5598-994F-BB5DE73D37EE.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-01029B52-55E0-5598-994F-BB5DE73D37EE.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,16 +1,16 @@ - - - - - -What are LayersThis topic describes the concept of a Layer in the Communications Framework.

A Layer is a horizontal division of functionality in a stack.

A Layer matches the concept of the Layer in the seven-layer International Organization for Standardization's OSI Model. A Layer also matches the concept of the Layer in the five layer model used to describe TCP/IP.

A Layer can contain a single Communications Protocol. A Layer can also contain a number of related protocols collected into a single unit. TLS, TCP, IP, Ethernet are examples of the protocols.

The concept of a Layer allows device creators to have different implementations in a given Layer. When a data connection starts or when the environment changes, the best protocol can be selected.

The following diagram shows the concept. The diagram also shows the position of the Sockets Server Client APIs.

- Layers in the Communications Framework -

Although each Layer contains a different protocol, the Communications Framework allows separate protocols to make a single Layer. For example: NCP, LCP and HDLC together make the PPP protocol. TCP, UDP, ICMP, IP together make the TCP/IP group of protocols. Each of these groups of protocols can be put together into a single Layer.

The number of Layers only depends on the configuration of the Communications Stack. The top Layer has the Sockets Server. The bottom Layer has the drivers for the communication hardware . Each Layer interacts only with the Layer immediately above and the Layer immediately below.

The framework APIs that connect the protocols in each Layer are consistent across the Communications Framework. All protocols share a common method of communication that is independent of protocol behaviour. A common method of communication allows protocols to be stacked. The Communications Framework provides flexibility in the configuration of the protocol stacks for each device. The following diagram shows a number of protocols at each Layer.

- Protocols arranged in Layers in the Communications Framework - Socket Server \ No newline at end of file + + + + + +What are LayersThis topic describes the concept of a Layer in the Communications Framework.

A Layer is a horizontal division of functionality in a stack.

A Layer matches the concept of the Layer in the seven-layer International Organization for Standardization's OSI Model. A Layer also matches the concept of the Layer in the five layer model used to describe TCP/IP.

A Layer can contain a single Communications Protocol. A Layer can also contain a number of related protocols collected into a single unit. TLS, TCP, IP, Ethernet are examples of the protocols.

The concept of a Layer allows device creators to have different implementations in a given Layer. When a data connection starts or when the environment changes, the best protocol can be selected.

The following diagram shows the concept. The diagram also shows the position of the Sockets Server Client APIs.

+ Layers in the Communications Framework +

Although each Layer contains a different protocol, the Communications Framework allows separate protocols to make a single Layer. For example: NCP, LCP and HDLC together make the PPP protocol. TCP, UDP, ICMP, IP together make the TCP/IP group of protocols. Each of these groups of protocols can be put together into a single Layer.

The number of Layers only depends on the configuration of the Communications Stack. The top Layer has the Sockets Server. The bottom Layer has the drivers for the communication hardware . Each Layer interacts only with the Layer immediately above and the Layer immediately below.

The framework APIs that connect the protocols in each Layer are consistent across the Communications Framework. All protocols share a common method of communication that is independent of protocol behaviour. A common method of communication allows protocols to be stacked. The Communications Framework provides flexibility in the configuration of the protocol stacks for each device. The following diagram shows a number of protocols at each Layer.

+ Protocols arranged in Layers in the Communications Framework + Socket Server \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-010627ED-7BCD-4AF1-BECB-661E21015E6E.dita --- a/Symbian3/SDK/Source/GUID-010627ED-7BCD-4AF1-BECB-661E21015E6E.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-010627ED-7BCD-4AF1-BECB-661E21015E6E.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,24 +1,25 @@ - - - - - -Password -query -

A specific case of the Data query is the Password query, used for confidential -information such as passwords or PINs. It uses the password editor, which -functions much like any other editor, except that instead of the actual data, -a dummy character (asterisk) represents each input character. In case of a -numeric-only password, the asterisks appear as soon as characters are entered. -In case of alphanumeric input, to support typing characters by repeated presses -of the same numeric key, the character is displayed normally for a short time, -and then changed into an asterisk.

-
Using password queries -in C++ applications

For implementation information, see Queries.

+ + + + + +Password +query +

A specific case of the Data query is the Password query, used for confidential +information such as passwords or PINs. It uses the password editor, which +functions much like any other editor, except that instead of the actual data, +a dummy character (asterisk) represents each input character. In case of a +numeric-only password, the asterisks appear as soon as characters are entered. +In case of alphanumeric input, to support typing characters by repeated presses +of the same numeric key, the character is displayed normally for a short time, +and then changed into an asterisk.

+
Using +password queries in applications

For implementation +information, see Queries.

 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-016704BE-DC2B-5AD3-B9BE-76A327678B38_d0e255924_href.jpg Binary file Symbian3/SDK/Source/GUID-016704BE-DC2B-5AD3-B9BE-76A327678B38_d0e255924_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-016704BE-DC2B-5AD3-B9BE-76A327678B38_d0e259632_href.jpg Binary file Symbian3/SDK/Source/GUID-016704BE-DC2B-5AD3-B9BE-76A327678B38_d0e259632_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0181F4BD-51A2-49AF-9DAC-517F8BAD8DBC-master.png Binary file Symbian3/SDK/Source/GUID-0181F4BD-51A2-49AF-9DAC-517F8BAD8DBC-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0181F4BD-51A2-49AF-9DAC-517F8BAD8DBC_d0e52617_href.png Binary file Symbian3/SDK/Source/GUID-0181F4BD-51A2-49AF-9DAC-517F8BAD8DBC_d0e52617_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0181F4BD-51A2-49AF-9DAC-517F8BAD8DBC_d0e58536_href.png Binary file Symbian3/SDK/Source/GUID-0181F4BD-51A2-49AF-9DAC-517F8BAD8DBC_d0e58536_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0185D5DC-5142-42C3-8FFB-8EB76D49AB06.dita --- a/Symbian3/SDK/Source/GUID-0185D5DC-5142-42C3-8FFB-8EB76D49AB06.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-0185D5DC-5142-42C3-8FFB-8EB76D49AB06.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,52 +1,52 @@ - - - - - -Requesting -RAM SynchronouslyThis section describes how an application can request for free -RAM synchronously. -

Perform the steps -described in Allowing -Large Memory Allocation.

 -

Requesting -free RAM synchronously is easy to implement because no active object is needed -and is recommended when there is no need to perform any other task while waiting -for the request to complete. This approach is not recommended in case of a -server, as synchronous call blocks the server and it cannot serve its clients -during synchronous wait.

 - -Request free memory. - User::LeaveIfError(iOomMonitorSession.RequestFreeMemory(KLargeValueToAllocate)); -DoFunctionRequiring_KLargeValueToAllocate_Bytes(); - - -

The following code snippet illustrates an synchronous request -for 2MB RAM:

TInt KLargeValueToAllocate = 2097152; //2MB - -// Create an OOM Monitor session -ROomMonitorSession oomMonitorSession; -CleanUpClosePushL(oomMonitorSession); -User::LeaveIfError(oomMonitorSession.Connect()); - -// Request free memory -User::LeaveIfError(iOomMonitorSession.RequestFreeMemory(KLargeValueToAllocate)); -DoFunctionRequiring_KLargeValueToAllocate_Bytes(); - -// Tidy up -CleanupStack::PopAndDestroy(); //oomMonitorSession, calls Close() - - -OOM Monitor -Priority -OOM Monitor -Overview -OOM Monitor -Reference + + + + + +Requesting +RAM SynchronouslyThis section describes how an application can request for free +RAM synchronously. +

Perform the steps +described in Allowing +Large Memory Allocation.

 +

Requesting +free RAM synchronously is easy to implement because no active object is needed +and is recommended when there is no need to perform any other task while waiting +for the request to complete. This approach is not recommended in case of a +server, as synchronous call blocks the server and it cannot serve its clients +during synchronous wait.

 + +Request free memory. + User::LeaveIfError(iOomMonitorSession.RequestFreeMemory(KLargeValueToAllocate)); +DoFunctionRequiring_KLargeValueToAllocate_Bytes(); + + +

The following code snippet illustrates an synchronous request +for 2MB RAM:

TInt KLargeValueToAllocate = 2097152; //2MB + +// Create an OOM Monitor session +ROomMonitorSession oomMonitorSession; +CleanUpClosePushL(oomMonitorSession); +User::LeaveIfError(oomMonitorSession.Connect()); + +// Request free memory +User::LeaveIfError(iOomMonitorSession.RequestFreeMemory(KLargeValueToAllocate)); +DoFunctionRequiring_KLargeValueToAllocate_Bytes(); + +// Tidy up +CleanupStack::PopAndDestroy(); //oomMonitorSession, calls Close() + + +OOM Monitor +Priority +OOM Monitor +Overview +OOM Monitor +Reference \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-018A685B-5C9D-5C7C-8615-D413ABBF7CFB_d0e242288_href.png Binary file Symbian3/SDK/Source/GUID-018A685B-5C9D-5C7C-8615-D413ABBF7CFB_d0e242288_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-018A685B-5C9D-5C7C-8615-D413ABBF7CFB_d0e246025_href.png Binary file Symbian3/SDK/Source/GUID-018A685B-5C9D-5C7C-8615-D413ABBF7CFB_d0e246025_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-01979029-C009-5FD3-9925-2B7945FB96A6.dita --- a/Symbian3/SDK/Source/GUID-01979029-C009-5FD3-9925-2B7945FB96A6.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-01979029-C009-5FD3-9925-2B7945FB96A6.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,34 +1,34 @@ - - - - - -Restarting a Network Connection TutorialThis section describes the steps used to start a network connection that was stopped due to contention.
Introduction

A low priority connection is terminated when a contention issue occurs and the incoming connection has a higher priority. The low priority connection can be restarted when the higher priority connection is complete. For example, if an always-on Internet connection is terminated to enable the user to send an MMS, the Internet connection is restarted when the message is sent.

Introduction

  1. To terminate the high priority connection on of the following occurs:

    1. The Connection Provider (CPR) receives a TStopNormal message to terminate the process.

    2. The connection remains idle and is automatically terminated.

  2. The PDP Tier Manager does the following:

    1. Indicates to the PDP Meta-Connection Provider (MCPR) of the low priority connection that it can restore the connection.

    2. The PDP MCPR sends an availability notification to the CConnection of the low priority connection.

  3. CConnection of the low priority connection receives the availability notification and uses RConnection::Start(TConnPrefList) to establish the connection.

Restoring a connection

Use the following code to ensure a stopped connection is restored when the higher priority connection has completed.

- - TConnPrefList* prefs = TConnPrefList::NewL(); - CleanupStack::PushL(prefs); - TConnAPPref* APPref = TConnAPPref::NewL(iSnapNumber); - CleanupStack::PushL(APPref); - TConnAutoStartPref* autoPref = TConnAutoStartPref::NewL(); - CleanupStack::PushL(autoPref); - prefs->AppendL(APPref); - prefs->AppendL(autoPref); - - error = iConnection->Start(*prefs); //Synchronous start. - // For asynchronous variant iConnection->Start(*iPrefs, iStatus), you need to // store “prefs” as a class member and delete them in RunL . - - delete APPref; - delete autoPref; - prefs->Remove(0); - prefs->Remove(0); - delete prefs; - -
What is Contention? What is Contention - Management? What are Access Point + + + + + +Restarting a Network Connection TutorialThis section describes the steps used to start a network connection that was stopped due to contention.
Introduction

A low priority connection is terminated when a contention issue occurs and the incoming connection has a higher priority. The low priority connection can be restarted when the higher priority connection is complete. For example, if an always-on Internet connection is terminated to enable the user to send an MMS, the Internet connection is restarted when the message is sent.

Introduction

  1. To terminate the high priority connection on of the following occurs:

    1. The Connection Provider (CPR) receives a TStopNormal message to terminate the process.

    2. The connection remains idle and is automatically terminated.

  2. The PDP Tier Manager does the following:

    1. Indicates to the PDP Meta-Connection Provider (MCPR) of the low priority connection that it can restore the connection.

    2. The PDP MCPR sends an availability notification to the CConnection of the low priority connection.

  3. CConnection of the low priority connection receives the availability notification and uses RConnection::Start(TConnPrefList) to establish the connection.

Restoring a connection

Use the following code to ensure a stopped connection is restored when the higher priority connection has completed.

+ + TConnPrefList* prefs = TConnPrefList::NewL(); + CleanupStack::PushL(prefs); + TConnAPPref* APPref = TConnAPPref::NewL(iSnapNumber); + CleanupStack::PushL(APPref); + TConnAutoStartPref* autoPref = TConnAutoStartPref::NewL(); + CleanupStack::PushL(autoPref); + prefs->AppendL(APPref); + prefs->AppendL(autoPref); + + error = iConnection->Start(*prefs); //Synchronous start. + // For asynchronous variant iConnection->Start(*iPrefs, iStatus), you need to // store “prefs” as a class member and delete them in RunL . + + delete APPref; + delete autoPref; + prefs->Remove(0); + prefs->Remove(0); + delete prefs; + +
What is Contention? What is Contention + Management? What are Access Point Priorities? \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-02072A1B-6F60-457B-8F26-2B25A6EA7C5F-master.png Binary file Symbian3/SDK/Source/GUID-02072A1B-6F60-457B-8F26-2B25A6EA7C5F-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-02072A1B-6F60-457B-8F26-2B25A6EA7C5F_d0e57338_href.png Binary file Symbian3/SDK/Source/GUID-02072A1B-6F60-457B-8F26-2B25A6EA7C5F_d0e57338_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-02072A1B-6F60-457B-8F26-2B25A6EA7C5F_d0e62220_href.png Binary file Symbian3/SDK/Source/GUID-02072A1B-6F60-457B-8F26-2B25A6EA7C5F_d0e62220_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-02072A1B-6F60-457B-8F26-2B25A6EA7C5F_d0e67292_href.png Binary file Symbian3/SDK/Source/GUID-02072A1B-6F60-457B-8F26-2B25A6EA7C5F_d0e67292_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-02072A1B-6F60-457B-8F26-2B25A6EA7C5F_d0e68994_href.png Binary file Symbian3/SDK/Source/GUID-02072A1B-6F60-457B-8F26-2B25A6EA7C5F_d0e68994_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-02072A1B-6F60-457B-8F26-2B25A6EA7C5F_d0e74136_href.png Binary file Symbian3/SDK/Source/GUID-02072A1B-6F60-457B-8F26-2B25A6EA7C5F_d0e74136_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-021E8B9C-4A1B-4C6D-B69E-4337A766C39A.dita --- a/Symbian3/SDK/Source/GUID-021E8B9C-4A1B-4C6D-B69E-4337A766C39A.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-021E8B9C-4A1B-4C6D-B69E-4337A766C39A.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,25 +1,25 @@ - - - - - -Porting -applications from S60 5th Edition to Symbian^3This section describes the changes required for applications to -work on Symbian^3. - -Add the following -macro in your application's MMP files. This is required because the structure -of the source code has changed. -APP_LAYER_SYSTEMINCLUDE - -Modify -the applications to support single-tap. - - + + + + + +Porting +applications from S60 5th Edition to Symbian^3This section describes the changes required for applications to +work on Symbian^3. + +Add the following +macro in your application's MMP files. This is required because the structure +of the source code has changed. +APP_LAYER_SYSTEMINCLUDE + +Modify +the applications to support single-tap. + + \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-023D30F0-C1E8-5E09-92AD-C5A7963DCF70_d0e304438_href.jpg Binary file Symbian3/SDK/Source/GUID-023D30F0-C1E8-5E09-92AD-C5A7963DCF70_d0e304438_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-023D30F0-C1E8-5E09-92AD-C5A7963DCF70_d0e310453_href.jpg Binary file Symbian3/SDK/Source/GUID-023D30F0-C1E8-5E09-92AD-C5A7963DCF70_d0e310453_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-02521DB0-53C4-55D5-856F-BD478E134B73_d0e333616_href.png Binary file Symbian3/SDK/Source/GUID-02521DB0-53C4-55D5-856F-BD478E134B73_d0e333616_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-02521DB0-53C4-55D5-856F-BD478E134B73_d0e339773_href.png Binary file Symbian3/SDK/Source/GUID-02521DB0-53C4-55D5-856F-BD478E134B73_d0e339773_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0259868F-8F88-5D9D-A9DE-9309C3BFBA85_d0e277562_href.png Binary file Symbian3/SDK/Source/GUID-0259868F-8F88-5D9D-A9DE-9309C3BFBA85_d0e277562_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0259868F-8F88-5D9D-A9DE-9309C3BFBA85_d0e281248_href.png Binary file Symbian3/SDK/Source/GUID-0259868F-8F88-5D9D-A9DE-9309C3BFBA85_d0e281248_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-02659624-4C27-573C-BE2E-0250D860BEA3.dita --- a/Symbian3/SDK/Source/GUID-02659624-4C27-573C-BE2E-0250D860BEA3.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-02659624-4C27-573C-BE2E-0250D860BEA3.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,14 +1,14 @@ - - - - - -Media Client Video Display OverviewThis document provides an overview of the Media Client Video Display library that is used by the Video Client library in the Multimedia Framework component.
Purpose

The Media Client Video Display library allows you to display video in a window and to support a graphic surface.

Media Client Video Display library details

The DLL that provides the functionality and the library to which your code must link is identified below.

DLL LIB Short description

mediaclientvideodisplay.dll

mediaclientvideodisplay.lib

These files are used to implement the display video functionality and support graphics surfaces.

Architecture

Media Client Video Display is a standalone library used by the Video Client library to support video display. This allows you to use video display functionality separately from the client utilities. The class diagram forCMediaClientVideoDisplay is as follows:

Description

The Media Client Video Display library is a client interface to access display functions. The display functions are as follows:

  • Adding a new window

  • Redrawing the window

  • Setting the video data for automatic and specified dimension scaling

  • Rotating the video image

  • Clipping the window

  • Setting the video extension on the screen that is relative to the window.

The Media Client Video Display library allows you to perform rendering of video to graphics surfaces. It provides APIs to:

  • Create the graphic surface

  • Update the graphic surface

  • Surface parameters changed during video play back

  • Remove the graphic surface.

APIs

The key class of Media Client Video Display is as follows:

API Description

CMediaClientVideoDisplay

This class is an interface to add or remove video display windows. The CMediaClientVideoDisplay class supports graphics surfaces and provides display handling functions like video extension, scaling and rotation.

Using Media Client Video Display

Clients use CMediaClientVideoDisplay to:

  • Display video in a window

  • Support graphics surfaces.

Media Client Video Display - Tutorial Video Client Overview Graphics Composition + + + + + +Media Client Video Display OverviewThis document provides an overview of the Media Client Video Display library that is used by the Video Client library in the Multimedia Framework component.
Purpose

The Media Client Video Display library allows you to display video in a window and to support a graphic surface.

Media Client Video Display library details

The DLL that provides the functionality and the library to which your code must link is identified below.

DLL LIB Short description

mediaclientvideodisplay.dll

mediaclientvideodisplay.lib

These files are used to implement the display video functionality and support graphics surfaces.

Architecture

Media Client Video Display is a standalone library used by the Video Client library to support video display. This allows you to use video display functionality separately from the client utilities. The class diagram forCMediaClientVideoDisplay is as follows:

Description

The Media Client Video Display library is a client interface to access display functions. The display functions are as follows:

  • Adding a new window

  • Redrawing the window

  • Setting the video data for automatic and specified dimension scaling

  • Rotating the video image

  • Clipping the window

  • Setting the video extension on the screen that is relative to the window.

The Media Client Video Display library allows you to perform rendering of video to graphics surfaces. It provides APIs to:

  • Create the graphic surface

  • Update the graphic surface

  • Surface parameters changed during video play back

  • Remove the graphic surface.

APIs

The key class of Media Client Video Display is as follows:

API Description

CMediaClientVideoDisplay

This class is an interface to add or remove video display windows. The CMediaClientVideoDisplay class supports graphics surfaces and provides display handling functions like video extension, scaling and rotation.

Using Media Client Video Display

Clients use CMediaClientVideoDisplay to:

  • Display video in a window

  • Support graphics surfaces.

Media Client Video Display + Tutorial Video Client Overview Graphics Composition Surfaces \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0268102D-D238-5C5E-818F-6ACC4A85B022_d0e7010_href.png Binary file Symbian3/SDK/Source/GUID-0268102D-D238-5C5E-818F-6ACC4A85B022_d0e7010_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0268102D-D238-5C5E-818F-6ACC4A85B022_d0e8285_href.png Binary file Symbian3/SDK/Source/GUID-0268102D-D238-5C5E-818F-6ACC4A85B022_d0e8285_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-026E865E-12FA-59A9-B923-309B65790E23.dita --- a/Symbian3/SDK/Source/GUID-026E865E-12FA-59A9-B923-309B65790E23.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-026E865E-12FA-59A9-B923-309B65790E23.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,85 +1,85 @@ - - - - - -Creating -a FAT Filename Conversion Plug-inThis section describes how to create a FAT Filename Conversion -plug-in DLL. -

This tutorial assumes that you have an understanding of the following:

    -

  • FAT -Filename Conversion Plug-ins Overview introduces Windows code page -and the main purpose of the Plug-ins component.

    • -
 -

The flowchart below shows the steps to create a Fat Filename Conversion -plug-in DLL.

- -

Note: To create the plug-in DLL, the unicodeconv.cpp file -is needed. It provides the functions to convert text between Unicode and a -foreign encoding. It is available on the Symbian Foundation web site.

This tutorial -uses the example of CP1250 to explain the process of creating -a plug-in DLL.

- -Create a source -file using a text editor and save it as, for example d:\charconvfiles\data\cp1250.txt. -This file contains pairs of hexadecimal numbers. The first number in each -pair is the encoding of a character in CP1250 and the second is the Unicode -encoding of the same character. -... -0x00 0x0000 #NULL -0x01 0x0001 #START OF HEADING -0x02 0x0002 #START OF TEXT -0x03 0x0003 #END OF TEXT -0x04 0x0004 #END OF TRANSMISSION -0x05 0x0005 #ENQUIRY -0x06 0x0006 #ACKNOWLEDGE -... -The source file has the same syntax as a cnvtool source file. For more -information about the syntax, refer to Cnvtool -Source File. - - -Start a command prompt to run the ConversionTable tool on the source -as follows:

cd d:\Symbian\epoc32\tools

ConversionTable.pl d:\charconvfiles\data\cp1250.txt

 -This process generates a C++ source code file called cp1250.cpp. -It is referred to as the ConversionTableTool-generated cpp file, which contains -the data structure. The data structure is used by unicodeconv.cpp for -the encoding conversion. - - -Create an mmp file which is used to build the plug-in DLL. -TARGET cp1250.dll -CAPABILITY All -TARGETTYPE dll - -UID 0x100039e6 0x10206A9C -VENDORID 0x70000001 - -OS_LAYER_SYSTEMINCLUDE -USERINCLUDE ../inc - -SOURCEPATH ../src -SOURCE unicodeconv.cpp - -SOURCEPATH +/build/generated/fatcharsetconv -SOURCE cp1250.cpp - -DEFFILE fatCnv.def - -LIBRARY euser.lib - -SMPSAFE - - -

Build the plug-in DLL and install it into the \sys\bin\ directory. -The DLL is then available to be loaded and called by the File Server.

 - -Using a FAT -Filename Conversion Plug-in + + + + + +Creating +a FAT Filename Conversion Plug-inThis section describes how to create a FAT Filename Conversion +plug-in DLL. +

This tutorial assumes that you have an understanding of the following:

    +

  • FAT +Filename Conversion Plug-ins Overview introduces Windows code page +and the main purpose of the Plug-ins component.

    • +
 +

The flowchart below shows the steps to create a Fat Filename Conversion +plug-in DLL.

+ +

Note: To create the plug-in DLL, the unicodeconv.cpp file +is needed. It provides the functions to convert text between Unicode and a +foreign encoding. It is available on the Symbian Foundation web site.

This tutorial +uses the example of CP1250 to explain the process of creating +a plug-in DLL.

+ +Create a source +file using a text editor and save it as, for example d:\charconvfiles\data\cp1250.txt. +This file contains pairs of hexadecimal numbers. The first number in each +pair is the encoding of a character in CP1250 and the second is the Unicode +encoding of the same character. +... +0x00 0x0000 #NULL +0x01 0x0001 #START OF HEADING +0x02 0x0002 #START OF TEXT +0x03 0x0003 #END OF TEXT +0x04 0x0004 #END OF TRANSMISSION +0x05 0x0005 #ENQUIRY +0x06 0x0006 #ACKNOWLEDGE +... +The source file has the same syntax as a cnvtool source file. For more +information about the syntax, refer to Cnvtool +Source File. + + +Start a command prompt to run the ConversionTable tool on the source +as follows:

cd d:\Symbian\epoc32\tools

ConversionTable.pl d:\charconvfiles\data\cp1250.txt

 +This process generates a C++ source code file called cp1250.cpp. +It is referred to as the ConversionTableTool-generated cpp file, which contains +the data structure. The data structure is used by unicodeconv.cpp for +the encoding conversion. + + +Create an mmp file which is used to build the plug-in DLL. +TARGET cp1250.dll +CAPABILITY All +TARGETTYPE dll + +UID 0x100039e6 0x10206A9C +VENDORID 0x70000001 + +OS_LAYER_SYSTEMINCLUDE +USERINCLUDE ../inc + +SOURCEPATH ../src +SOURCE unicodeconv.cpp + +SOURCEPATH +/build/generated/fatcharsetconv +SOURCE cp1250.cpp + +DEFFILE fatCnv.def + +LIBRARY euser.lib + +SMPSAFE + + +

Build the plug-in DLL and install it into the \sys\bin\ directory. +The DLL is then available to be loaded and called by the File Server.

 + +Using a FAT +Filename Conversion Plug-in \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-02970C7B-5B98-50C7-A324-0DDD71120DEB-master.png Binary file Symbian3/SDK/Source/GUID-02970C7B-5B98-50C7-A324-0DDD71120DEB-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-02970C7B-5B98-50C7-A324-0DDD71120DEB_d0e185592_href.png Binary file Symbian3/SDK/Source/GUID-02970C7B-5B98-50C7-A324-0DDD71120DEB_d0e185592_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-02BD38E7-A579-5BD5-9444-4E7C14C7809A.dita --- a/Symbian3/SDK/Source/GUID-02BD38E7-A579-5BD5-9444-4E7C14C7809A.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-02BD38E7-A579-5BD5-9444-4E7C14C7809A.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,67 +1,70 @@ - - - - - -Transparent -WindowsThis topic introduces the window transparency feature, which you -can use to create semi-transparent UI content over other UI content. In ScreenPlay -you can also use transparent windows to create semi-transparent UI content -over external content, such as video and OpenGL ES. For example, in ScreenPlay -you can display a semi-transparent dialog box over an OpenGL ES game. Transparent -windows are implemented using alpha compositing, which means that the transparency -information is embedded within the drawing commands. -

Note: Semi-transparent UI content over content provided by Direct -Screen Access (DSA) has never been supported and ScreenPlay does not change -this.

-

Variant: ScreenPlay and non-ScreenPlay. Target audience: -Application developers.

-
Alpha compositing

In alpha compositing, an alpha -channel is used to store opacity information along with the color values for -each pixel. For example, if the color is represented as RGB values, the pixel -values are typically stored as RGBA, where the final value is the alpha value. -This represents the percentage opacity. Like the RGB values, the alpha value -is frequently expressed in the range of 0 (completely transparent) to 255 -(fully opaque). For example, (0, 0, 0, 0) represents fully transparent black -and (255, 255, 255, 127) represents white that has 50% opacity.

Each -of the RGB values are multiplied by the alpha percentage to give the opacity -of the pixel. In order to reduce the need for multiplication during the compositing -process, the RGB values are sometimes multiplied by the alpha value before -storage. This is known as premultiplied alpha format. For example, -a premultiplied alpha representation of white that has 50% opacity is (127, -127, 127, 127).

-
Enabling transparency

To enable transparency, call -the RWindow::SetTransparencyAlphaChannel() method -on the window (which must be an RWindow type) -before it is activated. The transparency is then determined by the alpha values -of the content rendered to the window. Typically you set the background to -be fully or partially transparent, as shown in the following example:

// Set transparency mode on. -iWindow.SetTransparencyAlphaChannel(); - -// Set the background to be fully transparent black. -iWindow.SetBackgroundColor(TRgb(0,0,0,0)); - -// Activate the window. -iWindow.Activate(); - -// Begin drawing to the window. -...
-
Note

In earlier versions of the Symbian platform, -it was possible to create transparent windows using a mask and the RWindow class's SetTransparencyFactor(), SetTransparencyBitmap() and SetTransparencyWsBitmap() methods. This -mechanism is now deprecated and these methods are no longer functional.

A -new application and UI framework is planned for Symbian^4 (S^4). In order -for AVKON applications (and clients that draw using CWindowGc) -to work correctly on this new framework, the main view must be opaque. See How will the New Application -Architecture Affect my Applications? for more information.

- -Window Types - -How will -the New Application Architecture Affect my Applications? + + + + + +Transparent +WindowsThis topic introduces the window transparency feature, which you +can use to create semi-transparent UI content over other UI content. In ScreenPlay +you can also use transparent windows to create semi-transparent UI content +over external content, such as video and OpenGL ES. For example, in ScreenPlay +you can display a semi-transparent dialog box over an OpenGL ES game. Transparent +windows are implemented using alpha compositing, which means that the transparency +information is embedded within the drawing commands. +

Note: Semi-transparent UI content over content provided by Direct +Screen Access (DSA) has never been supported and ScreenPlay does not change +this.

+

Variant: ScreenPlay and non-ScreenPlay. Target audience: +Application developers.

+
Alpha compositing

In +alpha compositing, an alpha channel is used to store opacity information along +with the color values for each pixel. For example, if the color is represented +as RGB values, the pixel values are typically stored as RGBA, where the final +value is the alpha value. This represents the percentage opacity. Like the +RGB values, the alpha value is frequently expressed in the range of 0 (completely +transparent) to 255 (fully opaque). For example, (0, 0, 0, 0) represents fully +transparent black and (255, 255, 255, 127) represents white that has 50% opacity.

Each +of the RGB values are multiplied by the alpha percentage to give the opacity +of the pixel. In order to reduce the need for multiplication during the compositing +process, the RGB values are sometimes multiplied by the alpha value before +storage. This is known as premultiplied alpha format. For example, +a premultiplied alpha representation of white that has 50% opacity is (127, +127, 127, 127).

+
Enabling transparency

To +enable transparency, call the RWindow::SetTransparencyAlphaChannel() method +on the window (which must be an RWindow type) +before it is activated. The transparency is then determined by the alpha values +of the content rendered to the window. Typically you set the background to +be fully or partially transparent, as shown in the following example:

// Set transparency mode on. +iWindow.SetTransparencyAlphaChannel(); + +// Set the background to be fully transparent black. +iWindow.SetBackgroundColor(TRgb(0,0,0,0)); + +// Activate the window. +iWindow.Activate(); + +// Begin drawing to the window. +...
+
Note

In +earlier versions of the Symbian platform, it was possible to create transparent +windows using a mask and the RWindow class's SetTransparencyFactor(), SetTransparencyBitmap() and SetTransparencyWsBitmap() methods. This mechanism +is now deprecated and these methods are no longer functional.

A +new application and UI framework is planned for Symbian^4 (S^4). In order +for AVKON applications (and clients that draw using CWindowGc) +to work correctly on this new framework, the main view must be opaque. See How will the New Application +Architecture Affect my Applications? for more information.

+ +Window Types + +How will +the New Application Architecture Affect my Applications? +Drawing transparent +windows example \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-02F4AA24-283A-503D-8BA9-7C926DC7E306_d0e393621_href.png Binary file Symbian3/SDK/Source/GUID-02F4AA24-283A-503D-8BA9-7C926DC7E306_d0e393621_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-02F4AA24-283A-503D-8BA9-7C926DC7E306_d0e393783_href.png Binary file Symbian3/SDK/Source/GUID-02F4AA24-283A-503D-8BA9-7C926DC7E306_d0e393783_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0348B62D-1AE0-45F5-B06E-9EE2D83326E8.dita --- a/Symbian3/SDK/Source/GUID-0348B62D-1AE0-45F5-B06E-9EE2D83326E8.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-0348B62D-1AE0-45F5-B06E-9EE2D83326E8.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,33 +1,33 @@ - - - - - -Universal -indicators -

Universal indicators are small graphical icons. They inform the user about -issues such as unread messages, waiting voice mail, selected phone line, IR -and Bluetooth connection status, set clock alarm, home zone, and locked keypad. -Each status indicator has a priority number, which determines which icons -are displayed in case there are more of them than fit on the screen simultaneously.

-

In the Idle state and in the Phone application, the universal indicators -are displayed in the universal indicator area in the top-right corner (next -to the battery pane) in the status pane (see figure below).

-

Within applications other than Phone, status indicators appear in the universal -status indicator pane, which is combined with the clock display. Due to the -small size of this area, and also to avoid displaying unimportant things in -general, only the most important status indicators are displayed.

- -Universal status indicators displayed in the top-right corner - - -
Using -universal indicators in C++ applications

The universal -indicators are not accessible to applications.

+ + + + + +Universal +indicators +

Universal indicators are small graphical icons. They inform the user about +issues such as unread messages, waiting voice mail, selected phone line, IR +and Bluetooth connection status, set clock alarm, home zone, and locked keypad. +Each status indicator has a priority number, which determines which icons +are displayed in case there are more of them than fit on the screen simultaneously.

+

In the home screen and in the Phone application, the universal indicators +are displayed in the universal indicator area in the top-right corner (next +to the battery pane) in the status pane (see figure below).

+

Within applications other than Phone, status indicators appear in the universal +status indicator pane, which is combined with the clock display. Due to the +small size of this area, and also to avoid displaying unimportant things in +general, only the most important status indicators are displayed.

+ +Universal status indicators displayed in the top-right corner + + +
Using +universal indicators in applications

The universal +indicators are not accessible to applications.

 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-03671C88-6911-5184-A9D4-A2D2FD69A2B9_d0e413283_href.png Binary file Symbian3/SDK/Source/GUID-03671C88-6911-5184-A9D4-A2D2FD69A2B9_d0e413283_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-03671C88-6911-5184-A9D4-A2D2FD69A2B9_d0e413445_href.png Binary file Symbian3/SDK/Source/GUID-03671C88-6911-5184-A9D4-A2D2FD69A2B9_d0e413445_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0387B02E-9B81-5E61-A33E-D644251424A2-GENID-1-8-1-3-1-1-7-1-7-1-11-1.dita --- a/Symbian3/SDK/Source/GUID-0387B02E-9B81-5E61-A33E-D644251424A2-GENID-1-8-1-3-1-1-7-1-7-1-11-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,35 +0,0 @@ - - - - - -Layout -management -

Many factors have to be taken into consideration when laying out controls. -Component controls are normally laid out within their containers according -to the prevailing UI policy, skin, font, text style, zoom-factor and the sizes -and shapes of the controls themselves. A change to any one of these might -necessitate a new layout.

-

The Control Framework supports run-time layout management with the MCoeLayoutManager interface. -Each compound control knows which layout manager to call when it changes size. -The layout manager then takes responsibility for making any adjustments to -the layout.

-

A layout manager is associated with a compound control using:

- IMPORT_C virtual void SetLayoutManagerL(MCoeLayoutManager* aLayout); -

Note that this call passes 'ownership' so the caller does not need to retain -a pointer. A layout manager may be attached to more than one control so it -must implement its own reference count and delete itself when the count becomes -zero. SetLayoutManagerL() is also used to dissociate a layout -manager from a control by passing either NULL or a pointer to a different -layout manager.

-

The Control Framework does not provide any concrete layout managers. This -is the responsibility of the UI variant library or the application developer.

-

Though layout managers are now built into the control framework their use -is optional.

- \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0387B02E-9B81-5E61-A33E-D644251424A2-GENID-1-8-1-6-1-1-4-1-6-1-7-1-11-1.dita --- a/Symbian3/SDK/Source/GUID-0387B02E-9B81-5E61-A33E-D644251424A2-GENID-1-8-1-6-1-1-4-1-6-1-7-1-11-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,35 +0,0 @@ - - - - - -Layout -management -

Many factors have to be taken into consideration when laying out controls. -Component controls are normally laid out within their containers according -to the prevailing UI policy, skin, font, text style, zoom-factor and the sizes -and shapes of the controls themselves. A change to any one of these might -necessitate a new layout.

-

The Control Framework supports run-time layout management with the MCoeLayoutManager interface. -Each compound control knows which layout manager to call when it changes size. -The layout manager then takes responsibility for making any adjustments to -the layout.

-

A layout manager is associated with a compound control using:

- IMPORT_C virtual void SetLayoutManagerL(MCoeLayoutManager* aLayout); -

Note that this call passes 'ownership' so the caller does not need to retain -a pointer. A layout manager may be attached to more than one control so it -must implement its own reference count and delete itself when the count becomes -zero. SetLayoutManagerL() is also used to dissociate a layout -manager from a control by passing either NULL or a pointer to a different -layout manager.

-

The Control Framework does not provide any concrete layout managers. This -is the responsibility of the UI variant library or the application developer.

-

Though layout managers are now built into the control framework their use -is optional.

- \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0387B02E-9B81-5E61-A33E-D644251424A2.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-0387B02E-9B81-5E61-A33E-D644251424A2.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,35 @@ + + + + + +Layout +management +

Many factors have to be taken into consideration when laying out controls. +Component controls are normally laid out within their containers according +to the prevailing UI policy, skin, font, text style, zoom-factor and the sizes +and shapes of the controls themselves. A change to any one of these might +necessitate a new layout.

+

The Control Framework supports run-time layout management with the MCoeLayoutManager interface. +Each compound control knows which layout manager to call when it changes size. +The layout manager then takes responsibility for making any adjustments to +the layout.

+

A layout manager is associated with a compound control using:

+ IMPORT_C virtual void SetLayoutManagerL(MCoeLayoutManager* aLayout); +

Note that this call passes 'ownership' so the caller does not need to retain +a pointer. A layout manager may be attached to more than one control so it +must implement its own reference count and delete itself when the count becomes +zero. SetLayoutManagerL() is also used to dissociate a layout +manager from a control by passing either NULL or a pointer to a different +layout manager.

+

The Control Framework does not provide any concrete layout managers. This +is the responsibility of the UI variant library or the application developer.

+

Though layout managers are now built into the control framework their use +is optional.

+ \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-03A3E872-8183-4F56-976E-A6AF435742C6_d0e52515_href.png Binary file Symbian3/SDK/Source/GUID-03A3E872-8183-4F56-976E-A6AF435742C6_d0e52515_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-03A3E872-8183-4F56-976E-A6AF435742C6_d0e58606_href.png Binary file Symbian3/SDK/Source/GUID-03A3E872-8183-4F56-976E-A6AF435742C6_d0e58606_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-03A3E872-8183-4F56-976E-A6AF435742C6_d0e67355_href.png Binary file Symbian3/SDK/Source/GUID-03A3E872-8183-4F56-976E-A6AF435742C6_d0e67355_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-03A3E872-8183-4F56-976E-A6AF435742C6_d0e72556_href.png Binary file Symbian3/SDK/Source/GUID-03A3E872-8183-4F56-976E-A6AF435742C6_d0e72556_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-03AC137D-173A-558C-A2F3-9522870AC43C_d0e214249_href.png Binary file Symbian3/SDK/Source/GUID-03AC137D-173A-558C-A2F3-9522870AC43C_d0e214249_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-03AC137D-173A-558C-A2F3-9522870AC43C_d0e217986_href.png Binary file Symbian3/SDK/Source/GUID-03AC137D-173A-558C-A2F3-9522870AC43C_d0e217986_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-03BBEA31-3266-5B1C-9017-4EE7EA4AF1A8.dita --- a/Symbian3/SDK/Source/GUID-03BBEA31-3266-5B1C-9017-4EE7EA4AF1A8.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-03BBEA31-3266-5B1C-9017-4EE7EA4AF1A8.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,67 +1,67 @@ - - - - - -Creating -and Signing an Installation File -
Introduction

A Software Installation (SIS) file -can be generated as an unsigned file, a self-signed or signed file. Self-signed -and unsigned packages are considered to be unknown, and are installed -by the Software Installer, depending on the security policy of the Symbian -device.

If the SIS file is signed, the Software -Installer validates the certificate chains and based on verification, installs -the SIS file or aborts the installation.

-
Procedure
    -

  1. Create a private key-public -key pair and certificate request using the MakeKeys tool. -For details, see MaKeKeys -Tutorial.

    2. -

  2. Submit the certificate -request to a Certificate Authority (CA) and receive an authenticated digital -certificate.

    3. -

  3. Create a package (PKG) -file containing all the elements required to create the installation file. -For details see PKG -File Format .

    4. -

  4. Run MakeSIS at -the command prompt to create an unsigned SIS file. Specify the PKG file as -input argument, as shown in the following example:

    makesis mypackage.pkg

    MakeSIS generates an unsigned SIS file.

    5. -

  5. Run SignSIS at -the command prompt to sign the unsigned SIS file. Specify the unsigned SIS -file as input, and public key certificate and private key as arguments, as -shown in the following example:

    signsis trustedchain.pem eecertkey.key mypackage.sis

    Based on the certificate provided as input, SignSiS generates -a signed SIS file. For details, see Signing

    6. -
As an alternative to step 4 and 5, run the CreateSIS tool -at the command prompt to generate and sign the installation file. Specify -the trusted certificate-key pairs as arguments, as shown in the following -example: createsis create -cert trustedchain.pem -key eecertkey.key mypackage.pkg -

The process of creating an installation file can be -understood using the following illustration:

- -
-
Notes

While creating a SIS file using the CreateSIS tool, -if you do not specify the key or certificate on the command line the create method -generates a key and a matching self-signed certificate, and uses it to sign -the resulting SIS file.

The generated certificate and key is dumped -into the current working directory as cert-gen.cer and key-gen.key files. -If key-gen.key exists, the certificate and key filenames -are indexed incrementally. That is, cert-genx.cer and key-genx.key, -where x is the incremental index.

Note: The passphrase -encryption is not an option. It must be provided with the -pass option. -If this option is not specified, CreateSIS prompts for the passphrase -during key generation.

- -CreateSIS - -MakeSIS - -SignSIS - + + + + + +Creating +and Signing an Installation File +
Introduction

A Software Installation (SIS) file +can be generated as an unsigned file, a self-signed or signed file. Self-signed +and unsigned packages are considered to be unknown, and are installed +by the Software Installer, depending on the security policy of the Symbian +device.

If the SIS file is signed, the Software +Installer validates the certificate chains and based on verification, installs +the SIS file or aborts the installation.

+
Procedure
    +

  1. Create a private key-public +key pair and certificate request using the MakeKeys tool. +For details, see MaKeKeys +Tutorial.

    2. +

  2. Submit the certificate +request to a Certificate Authority (CA) and receive an authenticated digital +certificate.

    3. +

  3. Create a package (PKG) +file containing all the elements required to create the installation file. +For details see PKG +File Format .

    4. +

  4. Run MakeSIS at +the command prompt to create an unsigned SIS file. Specify the PKG file as +input argument, as shown in the following example:

    makesis mypackage.pkg

    MakeSIS generates an unsigned SIS file.

    5. +

  5. Run SignSIS at +the command prompt to sign the unsigned SIS file. Specify the unsigned SIS +file as input, and public key certificate and private key as arguments, as +shown in the following example:

    signsis trustedchain.pem eecertkey.key mypackage.sis

    Based on the certificate provided as input, SignSiS generates +a signed SIS file. For details, see Signing

    6. +
As an alternative to step 4 and 5, run the CreateSIS tool +at the command prompt to generate and sign the installation file. Specify +the trusted certificate-key pairs as arguments, as shown in the following +example: createsis create -cert trustedchain.pem -key eecertkey.key mypackage.pkg +

The process of creating an installation file can be +understood using the following illustration:

+ +
+
Notes

While creating a SIS file using the CreateSIS tool, +if you do not specify the key or certificate on the command line the create method +generates a key and a matching self-signed certificate, and uses it to sign +the resulting SIS file.

The generated certificate and key is dumped +into the current working directory as cert-gen.cer and key-gen.key files. +If key-gen.key exists, the certificate and key filenames +are indexed incrementally. That is, cert-genx.cer and key-genx.key, +where x is the incremental index.

Note: The passphrase +encryption is not an option. It must be provided with the -pass option. +If this option is not specified, CreateSIS prompts for the passphrase +during key generation.

+ +CreateSIS + +MakeSIS + +SignSIS + \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-043CFB8D-8780-478C-A3B2-FE5838795665-master.png Binary file Symbian3/SDK/Source/GUID-043CFB8D-8780-478C-A3B2-FE5838795665-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-043CFB8D-8780-478C-A3B2-FE5838795665_d0e53370_href.png Binary file Symbian3/SDK/Source/GUID-043CFB8D-8780-478C-A3B2-FE5838795665_d0e53370_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-043CFB8D-8780-478C-A3B2-FE5838795665_d0e59136_href.png Binary file Symbian3/SDK/Source/GUID-043CFB8D-8780-478C-A3B2-FE5838795665_d0e59136_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-045F3455-2B5A-5B20-ABCE-ED202DC5078A_d0e5846_href.png Binary file Symbian3/SDK/Source/GUID-045F3455-2B5A-5B20-ABCE-ED202DC5078A_d0e5846_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-045F3455-2B5A-5B20-ABCE-ED202DC5078A_d0e7121_href.png Binary file Symbian3/SDK/Source/GUID-045F3455-2B5A-5B20-ABCE-ED202DC5078A_d0e7121_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-04B044E7-5F10-47BC-B95F-27B62C2870E8.dita --- a/Symbian3/SDK/Source/GUID-04B044E7-5F10-47BC-B95F-27B62C2870E8.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,19 +0,0 @@ - - - - - -Keypad -tone -

A tone can be generated whenever a key event occurs. The tones for short -key presses (actually a key down event) and long key presses are different; -a key repeat event uses the long key press tone.

-

The keypad tone can be adjusted or turned ON or OFF by the -user.

- \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-04D917A1-E1A0-5149-9660-80A1146D0984.dita --- a/Symbian3/SDK/Source/GUID-04D917A1-E1A0-5149-9660-80A1146D0984.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-04D917A1-E1A0-5149-9660-80A1146D0984.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,59 +1,59 @@ - - - - - -OpenGLES -Collection OverviewOpenGL ES is a cross-platform API for 2D and 3D graphics on embedded -systems. It consists of a subset of desktop OpenGL, which is a widely adopted -2D and 3D graphics API, creating a low-level interface between software and -graphics acceleration. OpenGL ES includes profiles for floating-point and -fixed-point systems and the EGL specification for portably binding to native -windowing systems. -

Variant: ScreenPlay and non-ScreenPlay.

-

The Symbian platform supports two versions of OpenGL ES:

-
    -

  • OpenGL ES 1.X, which -is for fixed function hardware and offers acceleration, image quality and -performance.

    • -

  • OpenGL ES 2.X, which -is for programmable hardware and enables fully programmable 3D graphics and -shader objects.

    • -
-

OpenGL ES is an open standard developed by the Khronos Group (www.khronos.org).

-

The following diagram shows the direct use of OpenGL ES by an application -through the public OpenGL ES interface together with EGL. On the Symbian platform, -both OpenGL ES and EGL have a component (shown in blue) that declares the -interface, and both require an implementation that implements that interface -(shown in green).

- - OpenGLES component relationships - - -

It is possible for the OpenGL ES and EGL implementations to communicate -through a private interface that is not standardized by Symbian.

-
    -

  • The OpenGLES -Interface component provides a consistent interface to OpenGL ES on -the Symbian platform, enabling cross-device compatibility. The component includes -the Khronos-released header files (which incorporate some minor changes, such -as in-source comments). It also provides some Symbian-specific header files -and LIB, DEF and MMP files and UIDs. It does not provide any implementations -of the APIs.

    • -

  • EGL is -an interface between rendering APIs such as OpenGL ES or OpenVG and an underlying -native platform window system.

    • - -
- -OpenGLES -Collection -EGL - Collection + + + + + +OpenGLES +Collection OverviewOpenGL ES is a cross-platform API for 2D and 3D graphics on embedded +systems. It consists of a subset of desktop OpenGL, which is a widely adopted +2D and 3D graphics API, creating a low-level interface between software and +graphics acceleration. OpenGL ES includes profiles for floating-point and +fixed-point systems and the EGL specification for portably binding to native +windowing systems. +

Variant: ScreenPlay and non-ScreenPlay.

+

The Symbian platform supports two versions of OpenGL ES:

+
    +

  • OpenGL ES 1.X, which +is for fixed function hardware and offers acceleration, image quality and +performance.

    • +

  • OpenGL ES 2.X, which +is for programmable hardware and enables fully programmable 3D graphics and +shader objects.

    • +
+

OpenGL ES is an open standard developed by the Khronos Group (www.khronos.org).

+

The following diagram shows the direct use of OpenGL ES by an application +through the public OpenGL ES interface together with EGL. On the Symbian platform, +both OpenGL ES and EGL have a component (shown in blue) that declares the +interface, and both require an implementation that implements that interface +(shown in green).

+ + OpenGLES component relationships + + +

It is possible for the OpenGL ES and EGL implementations to communicate +through a private interface that is not standardized by Symbian.

+
    +

  • The OpenGLES +Interface component provides a consistent interface to OpenGL ES on +the Symbian platform, enabling cross-device compatibility. The component includes +the Khronos-released header files (which incorporate some minor changes, such +as in-source comments). It also provides some Symbian-specific header files +and LIB, DEF and MMP files and UIDs. It does not provide any implementations +of the APIs.

    • +

  • EGL is +an interface between rendering APIs such as OpenGL ES or OpenVG and an underlying +native platform window system.

    • + +
+ +OpenGLES +Collection +EGL + Collection \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0504B740-FB22-4399-B16D-BE6030B512B3.dita --- a/Symbian3/SDK/Source/GUID-0504B740-FB22-4399-B16D-BE6030B512B3.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-0504B740-FB22-4399-B16D-BE6030B512B3.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,32 +1,32 @@ - - - - - -Split -view inputs -

Split view mode inputs are opened similar to the full screen inputs. Virtual -ITU-T and QWERTY keyboards can be displayed in the split view mode. The application -can decide whether to use the full screen input or split view input.

-

Split view input uses the application’s own editor field, and the application -remains partly visible when the input is opened. Applications have the responsibility -of keeping the editor visible while user is typing. When the input opens, -the status pane is hidden. Split view is closed by tapping the specific closing -button present within the input.

- -Split view ITU-T - - - -Split view QWERTY - - -

In hybrid devices, when the hardware keyboard is opened, the virtual keyboard -(full screen or split view) disappears.

+ + + + + +Split +view inputs +

Split view mode inputs are opened similar to the full screen inputs. Virtual +ITU-T and QWERTY keyboards can be displayed in the split view mode. The application +can decide whether to use the full screen input or split view input.

+

Split view input uses the application’s own editor field, and the application +remains partly visible when the input is opened. Applications have the responsibility +of keeping the editor visible while user is typing. When the input opens, +the status pane is hidden. Split view is closed by tapping the specific closing +button present within the input.

+ +Split view ITU-T + + + +Split view QWERTY + + +

In hybrid devices, when the hardware keyboard is opened, the virtual keyboard +(full screen or split view) disappears.

 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0528A294-AC1B-5CDD-B59C-A105F39D748F_d0e190203_href.png Binary file Symbian3/SDK/Source/GUID-0528A294-AC1B-5CDD-B59C-A105F39D748F_d0e190203_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0528A294-AC1B-5CDD-B59C-A105F39D748F_d0e195211_href.png Binary file Symbian3/SDK/Source/GUID-0528A294-AC1B-5CDD-B59C-A105F39D748F_d0e195211_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-053FFF2B-6FB1-5065-B9D1-047477F3DE01.dita --- a/Symbian3/SDK/Source/GUID-053FFF2B-6FB1-5065-B9D1-047477F3DE01.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-053FFF2B-6FB1-5065-B9D1-047477F3DE01.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,38 +1,38 @@ - - - - - -Introduction -to dictionary storesA dictionary store is a store where all streams are accessed through -a UID, rather than directly by stream ID. -

A dictionary store contains streams in the usual way but, in addition, -the root stream is a stream dictionary. That is, the external representation -of a CStreamDictionary object is a list of two-way associations -between UIDs and stream ids.

-

The following diagram illustrates the concept of the dictionary store.

- -Dictionary store - - -

The interface to a dictionary store is provided by the CDictionaryStore abstract -class. The classes for concrete dictionary stores are derived from this abstract -class; for example, CDictionaryFileStore is a concrete dictionary -store class which is implemented using a file store.

-

Note that a dictionary store does not derive from CStreamStore, -but owns a persistent store, a CPersistentStore type, and -a stream dictionary, a CStreamDictionary type, as part of -its implementation.

-

See also

-

File based dictionary -store

-

Stream dictionaries

-

Stream ID

-

UID manipulation

+ + + + + +Introduction +to dictionary storesA dictionary store is a store where all streams are accessed through +a UID, rather than directly by stream ID. +

A dictionary store contains streams in the usual way but, in addition, +the root stream is a stream dictionary. That is, the external representation +of a CStreamDictionary object is a list of two-way associations +between UIDs and stream ids.

+

The following diagram illustrates the concept of the dictionary store.

+ +Dictionary store + + +

The interface to a dictionary store is provided by the CDictionaryStore abstract +class. The classes for concrete dictionary stores are derived from this abstract +class; for example, CDictionaryFileStore is a concrete dictionary +store class which is implemented using a file store.

+

Note that a dictionary store does not derive from CStreamStore, +but owns a persistent store, a CPersistentStore type, and +a stream dictionary, a CStreamDictionary type, as part of +its implementation.

+

See also

+

File based dictionary +store

+

Stream dictionaries

+

Stream ID

+

UID manipulation

 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-055E42B2-27E7-45F2-8450-5CCF4E1DEB15_d0e63611_href.png Binary file Symbian3/SDK/Source/GUID-055E42B2-27E7-45F2-8450-5CCF4E1DEB15_d0e63611_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-055E42B2-27E7-45F2-8450-5CCF4E1DEB15_d0e68845_href.png Binary file Symbian3/SDK/Source/GUID-055E42B2-27E7-45F2-8450-5CCF4E1DEB15_d0e68845_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-056165A7-E8A1-4868-8051-9EC58C5A3342.dita --- a/Symbian3/SDK/Source/GUID-056165A7-E8A1-4868-8051-9EC58C5A3342.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-056165A7-E8A1-4868-8051-9EC58C5A3342.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,69 +1,69 @@ - - - - - -Usability -considerations -

All touch and gestural interfaces have to appear competent and safe. The -interface must appear such that it is not going to misuse users' personal -data or break down. Optimizing system performance is critical here. Low screen -refresh rate and latent images do not give the impression of a trustworthy -touch UI. The use of touch screen and sensors may also increase battery consumption -of mobile devices.

-

Touch screens consume most power during touch operations, and reducing -unnecessary user interaction can help increase power efficiency. Specifically -with resistive touch screens, avoiding excessively long touch and drag user -actions is recommended. The continuous touch event flow keeps the CPU busy. -The screen lock turns off the touch completely. To learn more about both optimizing -system performance and battery life, see the Power Management section at the Symbian Foundation.

 -

The best products predict the needs of their users and then fulfill those -needs in unexpectedly pleasing ways. Adaptive targets are one way to do this. - Controls that match the users actions well are another way devices can be -clever.

-

Interaction design

-

Use appropriate and simple interaction logic:

-
    -

  • Navigation and controls must be clear and meaningful to prevent mistakes: -strokes along the touch panel must produce a logical outcome.

    • -

  • The coolest interaction in the world is empty unless it has clear meaning -for the person performing it. When using indirect controls, the UI response -must relate to the action the user is performing.

    • -

  • Meaningful controls are easier to learn and remember.

    • -
-

Touch UI can employ direct or indirect controls, or a combination of both:

-
    -

  • Direct controls allow users to simply tap the item they want to manipulate -right on the screen itself, move it, make it bigger, scroll it, and so on. -For more information, see UI -components and Touch -support for common UI components.

    • -

  • Indirect controls use some other means to manipulate an object, for -example, shaking, tilting, flipping, waving and so on. For more information, -see Sensor interaction.

    • -

  • Although Symbian platform allows the use of scrollbars, it is common -to reverse the page scrolling orientation in applications such as browser. -In absence of scrollbars, users will flick or drag the page upwards rather -than pull a scrollbar down to move the page up, that is, to scroll down. In -this case, scrollbars are used as navigation indicators.

    • -
- - - -

Direct taps and strokes are far easier for the user to understand and pick -up than abstract, indirect ones. A single view must always employ only a few -indirect strokes, so that the controls do not confuse the user.

-

Visual design

-

On touch screens, it is important to make a clear distinction between touchable -areas, and non-touchable areas, such as text. Borders, glow effects, or other -indicators can be used to highlight the interaction.Theme design alone -is not sufficient for indicating touch functionality, where one theme may -indicate touch, another may not.

-

See also:

+ + + + + +Usability +considerations +

All touch and gestural interfaces have to appear competent and safe. The +interface must appear such that it is not going to misuse users' personal +data or break down. Optimizing system performance is critical here. Low screen +refresh rate and latent images do not give the impression of a trustworthy +touch UI. The use of touch screen and sensors may also increase battery consumption +of mobile devices.

+

Touch screens consume most power during touch operations, and reducing +unnecessary user interaction can help increase power efficiency. Specifically +with resistive touch screens, avoiding excessively long touch and drag user +actions is recommended. The continuous touch event flow keeps the CPU busy. +The screen lock turns off the touch completely. To learn more about both optimizing +system performance and battery life, see the Power Management section at the Symbian Foundation.

 +

The best products predict the needs of their users and then fulfill those +needs in unexpectedly pleasing ways. Adaptive targets are one way to do this. + Controls that match the users actions well are another way devices can be +clever.

+

Interaction design

+

Use appropriate and simple interaction logic:

+
    +

  • Navigation and controls must be clear and meaningful to prevent mistakes: +strokes along the touch panel must produce a logical outcome.

    • +

  • The coolest interaction in the world is empty unless it has clear meaning +for the person performing it. When using indirect controls, the UI response +must relate to the action the user is performing.

    • +

  • Meaningful controls are easier to learn and remember.

    • +
+

Touch UI can employ direct or indirect controls, or a combination of both:

+
    +

  • Direct controls allow users to simply tap the item they want to manipulate +right on the screen itself, move it, make it bigger, scroll it, and so on. +For more information, see UI +components and Touch +support for common UI components.

    • +

  • Indirect controls use some other means to manipulate an object, for +example, shaking, tilting, flipping, waving and so on. For more information, +see Sensor interaction.

    • +

  • Although Symbian platform allows the use of scrollbars, it is common +to reverse the page scrolling orientation in applications such as browser. +In absence of scrollbars, users will flick or drag the page upwards rather +than pull a scrollbar down to move the page up, that is, to scroll down. In +this case, scrollbars are used as navigation indicators.

    • +
+ + + +

Direct taps and strokes are far easier for the user to understand and pick +up than abstract, indirect ones. A single view must always employ only a few +indirect strokes, so that the controls do not confuse the user.

+

Visual design

+

On touch screens, it is important to make a clear distinction between touchable +areas, and non-touchable areas, such as text. Borders, glow effects, or other +indicators can be used to highlight the interaction.Theme design alone +is not sufficient for indicating touch functionality, where one theme may +indicate touch, another may not.

+

See also:

 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-057891A5-2394-489E-9323-91BE256F2188-master.png Binary file Symbian3/SDK/Source/GUID-057891A5-2394-489E-9323-91BE256F2188-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-057891A5-2394-489E-9323-91BE256F2188_d0e64300_href.png Binary file Symbian3/SDK/Source/GUID-057891A5-2394-489E-9323-91BE256F2188_d0e64300_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-057891A5-2394-489E-9323-91BE256F2188_d0e69537_href.png Binary file Symbian3/SDK/Source/GUID-057891A5-2394-489E-9323-91BE256F2188_d0e69537_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-058D9E7F-5F4B-5656-BA49-16ED2D1451AE.dita --- a/Symbian3/SDK/Source/GUID-058D9E7F-5F4B-5656-BA49-16ED2D1451AE.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,246 +0,0 @@ - - - - - -UIDs -
Hash algorithm UIDs - - - -UID -Description -Value -RFC standard - - - - -

KMd2Uid

-

MD2, Message-Digest Algorithm

-

0x10283173

-

RFC -1319

- - -

KMd4Uid

-

MD4, Message-Digest Algorithm (Output: 128 bit message digest)

-

0x2000B341

-

RFC -1320

- - -

KMd5Uid

-

MD5 ,Message-Digest Algorithm (output:128-bit "fingerprint" or "message -digest)

-

0x10283174

-

RFC -1321

- - -

KSha1Uid

-

Secure Hash Algorithm(output: 160-bit message digest)

-

0x10283175

-

FIPS -180-1 and RFC -3174

- - -

KSha224Uid

-

Sha224 algorithm

-

0x2000E258

-

FIPS 180-2 (with change notice), RFC3874 and FIPS 180-3

- - -

KSha256Uid

-

Sha256 algorithm

-

0x2000E259

-

FIPS 180-2 and RFC 4634

- - -

KSha384Uid

-

Sha384 algorithm

-

0x2000E25A

-

FIPS 180-2 and RFC 4634

- - -

KSha512Uid

-

Sha512 algorithm

-

0x2000E25B

-

FIPS 180-2 and RFC 4634

- - - -

The hash algorithm UIDs are used by the following APIs:

    -

  • CryptoSpi::CHashFactory::CreateHashL()

    • -

  • CryptoSpi::CRuleSelector::CreateHashL()

    • -

  • CryptoSpi::CCryptoPluginEntry::CreateHashL()

    • -

  • CryptoSpi::CHashFactory::CreateAsyncHashL()

    • -

  • CryptoSpi::CRuleSelector::CreateAsyncHashL()

    • -
-
Random algorithm UIDs - - - -UID -Description -Value - - - - -

KRandomUid

-

Random algorithm UID

-

0x10283178

- - - -

The random algorithm UIDs are used by the following APIs:

    -

  • CryptoSpi::CRandomFactory::CreateRandomL()

    • -

  • CryptoSpi::CRuleSelector::CreateRandomL()

    • -

  • CryptoSpi::CRandomFactory::CreateAsyncRandomL()

    • -

  • CryptoSpi::CRuleSelector::CreateAsyncRandomL()

    • -
-
Symmetric key algorithm UIDs - - - -UID -Description -Value - - - - -

KDesUid

-

Des algorithm UID

-

0x10283179

- - -

K3DesUid

-

3Des algorithm UID

-

0x1028317a

- - -

KRc2Uid

-

RC2 algorithm UID

-

0x1028317b

- - -

KArc4Uid

-

ARC4 algorithm UID

-

0x1028317c

- - -

KAesUid

-

AES algorithm UID

-

0x1028317d

- - -

KMisty1Uid

-

Misty1 algorithm UID

-

0x102831be

- - -

KMisty2Uid

-

Misty2 algorithm UID

-

0x102831bf

- - -

KKasumiUid

-

Kasumi algorithm UID

-

0x102831c0

- - - -

The symmetric key algorithm UIDs are used by the following API:

    -

  • CryptoSpi::CSymmetricCipher::CSymmetricCipher()

    • -
-
Asymmetric key algorithm UIDs - - - -UID -Description -Value - - - - -

KRsaCipherUid

-

RSA Cipher algorithm UID

-

0x1028317e

- - -

KRsaSignerUid

-

RSA Signer algorithm UID

-

0x1028317f

- - -

KDsaSignerUid

-

DSA Signer algorithm UID

-

0x10283180

- - -

KDHAgreementUid

-

DH Agreement algorithm UID

-

0x10283183

- - - -

The asymmetric key algorithm UIDs are used by the following API:

    -

  • CryptoSpi::CAsymmetricCipher::CAsymmetricCipher()

    • -
-
Operation modes - - - -UID -Description -Value - - - - -

KOperationModeNoneUid

-

None Mode UID

-

0x10283190

- - -

KOperationModeECBUid

-

ECB Mode UID

-

0x10283191

- - -

KOperationModeCBCUid

-

CBC Mode UID

-

0x10283192

- - -

KOperationModeOFBUid

-

OFB Mode UID

-

0x10283193

- - -

KOperationModeCFBUid

-

CFB Mode UID

-

0x10283194

- - -

KOperationModeCTRUid

-

CTR Mode UID

-

0x10283195

- - - -

The operation modes are used by the following APIs:

    -

  • CryptoSpi::CHashFactory::CreateHashL()

    • -

  • CryptoSpi::CHashFactory::CreateAsyncHashL()

    • -
- \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-05C87497-738B-473C-B5B2-BE46D32225F5-master.png Binary file Symbian3/SDK/Source/GUID-05C87497-738B-473C-B5B2-BE46D32225F5-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-05C87497-738B-473C-B5B2-BE46D32225F5_d0e66467_href.png Binary file Symbian3/SDK/Source/GUID-05C87497-738B-473C-B5B2-BE46D32225F5_d0e66467_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-05C87497-738B-473C-B5B2-BE46D32225F5_d0e71711_href.png Binary file Symbian3/SDK/Source/GUID-05C87497-738B-473C-B5B2-BE46D32225F5_d0e71711_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-05D6AB1C-8548-58C6-AA6C-EE362FF49247-GENID-1-8-1-3-1-1-5-1-3-1.dita --- a/Symbian3/SDK/Source/GUID-05D6AB1C-8548-58C6-AA6C-EE362FF49247-GENID-1-8-1-3-1-1-5-1-3-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,171 +0,0 @@ - - - - - -Bitmap -Animation Overview -
Purpose

This document shows you how to create an -animation using the Bitmap Animation framework.

-
Architectural relationships

The Bitmap Animation -framework (bmpanim.dll) uses the font and bitmap server -(fbscli.dll) to provide the bitmap images (CFbsBitmap s).

An -animation DLL (bmpansrv.dll), loaded by the Window Server, -is used to perform the animation.

The animation DLL uses the bitgdi -component (bitgdi.dll) to draw the bitmaps.

-
Description

To use a bitmap animation in your application -you need to:

    -

  • define one or more animation -frames, each of which owns a bitmap,

    • -

  • assign the frames to -an animation container,

    • -

  • create an animation -player object and pass the animation container to it. This communicates with -the window server to start and stop playing the animation inside a window.

    • -

Collectively, these steps make up the Bitmap Animation framework. -The key client side classes that are involved in these steps are:

    -

  • CBitmapFrameData,

    • -

  • CBitmapAnimClientData,

    • -

  • RBitmapAnim.

    • -

The rest of this document describes each of these steps, starting -with the animation frame.

-
Defining an animation frame

The CBitmapFrameData class -represents a single frame in an animation. The following properties of a frame -can be set:

    -

  • the bitmap image,

    • -

  • the mask, which is used -for making parts of the image transparent,

    • -

  • the time the frame is -displayed, in milliseconds,

    • -

  • the position in the -window where the frame is displayed.

    • -

These properties can either be set in CBitmapFrameData::NewL() or -by calling various setter functions, described below.

Setting the -image and mask bitmaps

The following code loads the bitmap and -mask from a multi bitmap file, and constructs the frame, setting its bitmap -and mask, which it takes ownership of:

CFbsBitmap* bitmap=new (ELeave) CFbsBitmap; // load the image bitmap from an mbm file -CleanupStack::PushL(bitmap); -User::LeaveIfError(bitmap->Load(KMBMFileName, EMbmAnimFrame1)); -CFbsBitmap* mask=new (ELeave) CFbsBitmap; // load the mask from the same mbm file -CleanupStack::PushL(mask); -User::LeaveIfError(mask->Load(KMBMFileName, EMbmAnimFrameMask1)); -CBitmapFrameData* frame1 = CBitmapFrameData::NewL(bitmap, mask); -CleanupStack::Pop(2); // bitmap, mask

CBitmapFrameData::SetBitmap() and CBitmapFrameData::SetMask() could alternatively be used.

An animation can have multiple frames, -each of which has an image and mask bitmap. Each frame stores a flag to indicate -whether or not it owns the bitmaps. If the frame owns the bitmaps, they are -deleted in the frame’s destructor. This flag can be set or unset by calling CBitmapFrameData::SetBitmapsOwnedExternally(). -By default, bitmaps are owned by the frame.

The mask is used in the -standard way for a bitmap mask, so pixels in the bitmap image that map to -black pixels in the mask are drawn, while pixels that map to white pixels -in the mask are not, so appear transparent.

Setting the time interval

The -time period for the frame to be displayed on the screen is set in milliseconds:

frame1->SetInterval(125);

Note -that a default time interval can be set in the frame container (described -in the next section) by calling CBitmapAnimClientData::SetFrameInterval(). -Any value set in the container will apply to frames that have not set an interval -themselves.

Setting the frame’s position

The position -of the frame relative to the animation window is set using CBitmapFrameData::SetPosition():

TPoint framePos(3,6); -frame1->SetPosition(framePos);

Note that the position can also -be specified in RBitmapAnim; if so, this value applies -to all frames.

When you have finished defining the animation frame(s), -use the frame container class, CBitmapAnimClientData, to -create the animation.

-
Defining an animation

Frames are grouped into an -animation frame container (CBitmapAnimClientData), which -allows the following behaviour to be set:

    -

  • append frames to the -container,

    • -

  • set a default display -interval for all frames, (note that the time interval set by an individual -frame takes precedence, for that frame, over the default interval),

    • -

  • set one of the following -play modes for the animation: play once, loop or bounce (plays forwards and -backwards),

    • -

  • set the animation to -flash,

    • -

  • provide an additional -bitmap frame to use for the background to the animation (explained below).

    • -

Appending frames

First, create the frame container, -and append the frame(s) to it in the correct sequence:

CBitmapAnimClientData* animFrames=CBitmapAnimClientData::NewL(); -CleanupStack::PushL(animFrames); -animFrames->AppendFrameL(*frame1); -animFrames->AppendFrameL(*frame2); // etc.

Setting the default -display interval

A default display interval can be set for the -animation:

animFrames->SetFrameInterval(100);

This -applies only to frames which have not specified their own interval (using CBitmapFrameData::SetInterval()). -In this example, the default interval for frames without their own interval -is 100 milliseconds (0.1 second). It can be used to ensure that all frames -are displayed for the same length of time.

Setting the play mode

There -are three play modes: play once, play repeatedly in the same direction ('loop') -and play forwards and backwards repeatedly ('bounce'). This code sets the -animation to play once:

animFrames->SetPlayMode(CBitmapAnimClientData::EPlay);

Other properties

CBitmapAnimClientData::SetFlash() and CBitmapAnimClientData::SetBackgroundFrame() are used to set/unset the flash flag and the background frame, respectively. -The flash flag determines whether the animation should flash or not.

The -background frame, which is optional, is used to clear the current frame before -drawing the next one. If no background frame is provided by the client, the -window server creates its own background frame using the original screen contents, -and updates it when the animation window is redrawn.

If the client-provided -background frame contains an image bitmap and a mask, the background image -used is a combination of the screen contents and the supplied background bitmap. -If the client-provided background frame has a bitmap but no mask, the bitmap -is used as the background.

-
Playing the animation

When the animation is ready -to play, it must be packaged and sent to the window server’s animation DLL. -This is done through an animation player (RBitmapAnim) -object.

RBitmapAnim allows you to do the following:

    -

  • specify the window in -which the animation is displayed,

    • -

  • associate the animation -with an RAnimDll object, which provides a connection to -the window server,

    • -

  • pass the animation object -to the window server’s animation DLL,

    • -

  • specify the number of -times the animation should play,

    • -

  • start and stop playing -the animation. Optionally the animation can start playing from a particular -frame.

    • -

Note that after the animation object has been set up and passed to -the window server, the general attributes of the animation, namely the flash -property, the default display time for each frame and the play mode can still -be changed, using the following RBitmapAnim functions:

    -

  • SetFlashL(),

    • -

  • SetFrameIntervalL(),

    • -

  • SetPlayModeL().

    • -

Any changes to these properties made using RBitmapAnim will -override the values previously set in CBitmapAnimClientData.

Constructing -the animation player

RAnimDll is a handle -to the server-side animation DLL. It is used to load the window server animation -DLL, bmpansrv.dll, which provides the functions that -perform the frames animation. The RAnimDll instance is passed -to the RBitmapAnim constructor.

RAnimDll animDLL(iEikonEnv->WsSession()); // session is used to interact with the window server -_LIT(KDllName, "BMPANSRV.DLL"); -User::LeaveIfError(animDll.Load(KDllName)); -RBitmapAnim animPlayer(animDLL); -animPlayer.ConstructL(Window());

Passing the animation object -to the window server

The animation frame container (CBitmapAnimClientData) -should be passed via the RBitmapAnim object to the window -server. This is done using the function SetBitmapAnimDataL(). -Note that calling this function does not cause the animation to start playing:

animPlayer.SetBitmapAnimDataL(*animFrames);

Setting -the number of cycles

If the animation should play more than once, -the number of cycles should be set:

animPlayer.SetNumberOfCyclesL(10);

Note that if the animation's play mode is 'bounce', the number of cycles -must be set to at least two to ensure a complete animation routine.

Setting -the position

To set the animation’s position, use SetPositionL(). -This value is an offset from the origin of the animation window.

TPoint animPos(20,40); -animPlayer.SetPositionL(animPos);

Starting/stopping the -animation

The RBitmapAnim::StartL() and RBitmapAnim::StopL() functions -send commands to the animation DLL to start/stop the animation routine.

Calling RBitmapAnim::DisplayFrameL() before -the animation has started sets the frame from which the animation should start -playing.

Freeing resources

After they have been finished -with, Close() should be called on the RAnimDll and RBitmapAnim objects.

animPlayer.Close(); -animDLL.Close();
-
See also
    -

  • Animation Overview

    • -

  • Introduction -to the Font and Bitmap Server

    • -
- \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-05D6AB1C-8548-58C6-AA6C-EE362FF49247-GENID-1-8-1-6-1-1-4-1-4-1-3-1.dita --- a/Symbian3/SDK/Source/GUID-05D6AB1C-8548-58C6-AA6C-EE362FF49247-GENID-1-8-1-6-1-1-4-1-4-1-3-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,171 +0,0 @@ - - - - - -Bitmap -Animation Overview -
Purpose

This document shows you how to create an -animation using the Bitmap Animation framework.

-
Architectural relationships

The Bitmap Animation -framework (bmpanim.dll) uses the font and bitmap server -(fbscli.dll) to provide the bitmap images (CFbsBitmap s).

An -animation DLL (bmpansrv.dll), loaded by the Window Server, -is used to perform the animation.

The animation DLL uses the bitgdi -component (bitgdi.dll) to draw the bitmaps.

-
Description

To use a bitmap animation in your application -you need to:

    -

  • define one or more animation -frames, each of which owns a bitmap,

    • -

  • assign the frames to -an animation container,

    • -

  • create an animation -player object and pass the animation container to it. This communicates with -the window server to start and stop playing the animation inside a window.

    • -

Collectively, these steps make up the Bitmap Animation framework. -The key client side classes that are involved in these steps are:

    -

  • CBitmapFrameData,

    • -

  • CBitmapAnimClientData,

    • -

  • RBitmapAnim.

    • -

The rest of this document describes each of these steps, starting -with the animation frame.

-
Defining an animation frame

The CBitmapFrameData class -represents a single frame in an animation. The following properties of a frame -can be set:

    -

  • the bitmap image,

    • -

  • the mask, which is used -for making parts of the image transparent,

    • -

  • the time the frame is -displayed, in milliseconds,

    • -

  • the position in the -window where the frame is displayed.

    • -

These properties can either be set in CBitmapFrameData::NewL() or -by calling various setter functions, described below.

Setting the -image and mask bitmaps

The following code loads the bitmap and -mask from a multi bitmap file, and constructs the frame, setting its bitmap -and mask, which it takes ownership of:

CFbsBitmap* bitmap=new (ELeave) CFbsBitmap; // load the image bitmap from an mbm file -CleanupStack::PushL(bitmap); -User::LeaveIfError(bitmap->Load(KMBMFileName, EMbmAnimFrame1)); -CFbsBitmap* mask=new (ELeave) CFbsBitmap; // load the mask from the same mbm file -CleanupStack::PushL(mask); -User::LeaveIfError(mask->Load(KMBMFileName, EMbmAnimFrameMask1)); -CBitmapFrameData* frame1 = CBitmapFrameData::NewL(bitmap, mask); -CleanupStack::Pop(2); // bitmap, mask

CBitmapFrameData::SetBitmap() and CBitmapFrameData::SetMask() could alternatively be used.

An animation can have multiple frames, -each of which has an image and mask bitmap. Each frame stores a flag to indicate -whether or not it owns the bitmaps. If the frame owns the bitmaps, they are -deleted in the frame’s destructor. This flag can be set or unset by calling CBitmapFrameData::SetBitmapsOwnedExternally(). -By default, bitmaps are owned by the frame.

The mask is used in the -standard way for a bitmap mask, so pixels in the bitmap image that map to -black pixels in the mask are drawn, while pixels that map to white pixels -in the mask are not, so appear transparent.

Setting the time interval

The -time period for the frame to be displayed on the screen is set in milliseconds:

frame1->SetInterval(125);

Note -that a default time interval can be set in the frame container (described -in the next section) by calling CBitmapAnimClientData::SetFrameInterval(). -Any value set in the container will apply to frames that have not set an interval -themselves.

Setting the frame’s position

The position -of the frame relative to the animation window is set using CBitmapFrameData::SetPosition():

TPoint framePos(3,6); -frame1->SetPosition(framePos);

Note that the position can also -be specified in RBitmapAnim; if so, this value applies -to all frames.

When you have finished defining the animation frame(s), -use the frame container class, CBitmapAnimClientData, to -create the animation.

-
Defining an animation

Frames are grouped into an -animation frame container (CBitmapAnimClientData), which -allows the following behaviour to be set:

    -

  • append frames to the -container,

    • -

  • set a default display -interval for all frames, (note that the time interval set by an individual -frame takes precedence, for that frame, over the default interval),

    • -

  • set one of the following -play modes for the animation: play once, loop or bounce (plays forwards and -backwards),

    • -

  • set the animation to -flash,

    • -

  • provide an additional -bitmap frame to use for the background to the animation (explained below).

    • -

Appending frames

First, create the frame container, -and append the frame(s) to it in the correct sequence:

CBitmapAnimClientData* animFrames=CBitmapAnimClientData::NewL(); -CleanupStack::PushL(animFrames); -animFrames->AppendFrameL(*frame1); -animFrames->AppendFrameL(*frame2); // etc.

Setting the default -display interval

A default display interval can be set for the -animation:

animFrames->SetFrameInterval(100);

This -applies only to frames which have not specified their own interval (using CBitmapFrameData::SetInterval()). -In this example, the default interval for frames without their own interval -is 100 milliseconds (0.1 second). It can be used to ensure that all frames -are displayed for the same length of time.

Setting the play mode

There -are three play modes: play once, play repeatedly in the same direction ('loop') -and play forwards and backwards repeatedly ('bounce'). This code sets the -animation to play once:

animFrames->SetPlayMode(CBitmapAnimClientData::EPlay);

Other properties

CBitmapAnimClientData::SetFlash() and CBitmapAnimClientData::SetBackgroundFrame() are used to set/unset the flash flag and the background frame, respectively. -The flash flag determines whether the animation should flash or not.

The -background frame, which is optional, is used to clear the current frame before -drawing the next one. If no background frame is provided by the client, the -window server creates its own background frame using the original screen contents, -and updates it when the animation window is redrawn.

If the client-provided -background frame contains an image bitmap and a mask, the background image -used is a combination of the screen contents and the supplied background bitmap. -If the client-provided background frame has a bitmap but no mask, the bitmap -is used as the background.

-
Playing the animation

When the animation is ready -to play, it must be packaged and sent to the window server’s animation DLL. -This is done through an animation player (RBitmapAnim) -object.

RBitmapAnim allows you to do the following:

    -

  • specify the window in -which the animation is displayed,

    • -

  • associate the animation -with an RAnimDll object, which provides a connection to -the window server,

    • -

  • pass the animation object -to the window server’s animation DLL,

    • -

  • specify the number of -times the animation should play,

    • -

  • start and stop playing -the animation. Optionally the animation can start playing from a particular -frame.

    • -

Note that after the animation object has been set up and passed to -the window server, the general attributes of the animation, namely the flash -property, the default display time for each frame and the play mode can still -be changed, using the following RBitmapAnim functions:

    -

  • SetFlashL(),

    • -

  • SetFrameIntervalL(),

    • -

  • SetPlayModeL().

    • -

Any changes to these properties made using RBitmapAnim will -override the values previously set in CBitmapAnimClientData.

Constructing -the animation player

RAnimDll is a handle -to the server-side animation DLL. It is used to load the window server animation -DLL, bmpansrv.dll, which provides the functions that -perform the frames animation. The RAnimDll instance is passed -to the RBitmapAnim constructor.

RAnimDll animDLL(iEikonEnv->WsSession()); // session is used to interact with the window server -_LIT(KDllName, "BMPANSRV.DLL"); -User::LeaveIfError(animDll.Load(KDllName)); -RBitmapAnim animPlayer(animDLL); -animPlayer.ConstructL(Window());

Passing the animation object -to the window server

The animation frame container (CBitmapAnimClientData) -should be passed via the RBitmapAnim object to the window -server. This is done using the function SetBitmapAnimDataL(). -Note that calling this function does not cause the animation to start playing:

animPlayer.SetBitmapAnimDataL(*animFrames);

Setting -the number of cycles

If the animation should play more than once, -the number of cycles should be set:

animPlayer.SetNumberOfCyclesL(10);

Note that if the animation's play mode is 'bounce', the number of cycles -must be set to at least two to ensure a complete animation routine.

Setting -the position

To set the animation’s position, use SetPositionL(). -This value is an offset from the origin of the animation window.

TPoint animPos(20,40); -animPlayer.SetPositionL(animPos);

Starting/stopping the -animation

The RBitmapAnim::StartL() and RBitmapAnim::StopL() functions -send commands to the animation DLL to start/stop the animation routine.

Calling RBitmapAnim::DisplayFrameL() before -the animation has started sets the frame from which the animation should start -playing.

Freeing resources

After they have been finished -with, Close() should be called on the RAnimDll and RBitmapAnim objects.

animPlayer.Close(); -animDLL.Close();
-
See also
    -

  • Animation Overview

    • -

  • Introduction -to the Font and Bitmap Server

    • -
- \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-05D6AB1C-8548-58C6-AA6C-EE362FF49247.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-05D6AB1C-8548-58C6-AA6C-EE362FF49247.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,171 @@ + + + + + +Bitmap +Animation Overview +
Purpose

This document shows you how to create an +animation using the Bitmap Animation framework.

+
Architectural relationships

The Bitmap Animation +framework (bmpanim.dll) uses the font and bitmap server +(fbscli.dll) to provide the bitmap images (CFbsBitmap s).

An +animation DLL (bmpansrv.dll), loaded by the Window Server, +is used to perform the animation.

The animation DLL uses the bitgdi +component (bitgdi.dll) to draw the bitmaps.

+
Description

To use a bitmap animation in your application +you need to:

    +

  • define one or more animation +frames, each of which owns a bitmap,

    • +

  • assign the frames to +an animation container,

    • +

  • create an animation +player object and pass the animation container to it. This communicates with +the window server to start and stop playing the animation inside a window.

    • +

Collectively, these steps make up the Bitmap Animation framework. +The key client side classes that are involved in these steps are:

    +

  • CBitmapFrameData,

    • +

  • CBitmapAnimClientData,

    • +

  • RBitmapAnim.

    • +

The rest of this document describes each of these steps, starting +with the animation frame.

+
Defining an animation frame

The CBitmapFrameData class +represents a single frame in an animation. The following properties of a frame +can be set:

    +

  • the bitmap image,

    • +

  • the mask, which is used +for making parts of the image transparent,

    • +

  • the time the frame is +displayed, in milliseconds,

    • +

  • the position in the +window where the frame is displayed.

    • +

These properties can either be set in CBitmapFrameData::NewL() or +by calling various setter functions, described below.

Setting the +image and mask bitmaps

The following code loads the bitmap and +mask from a multi bitmap file, and constructs the frame, setting its bitmap +and mask, which it takes ownership of:

CFbsBitmap* bitmap=new (ELeave) CFbsBitmap; // load the image bitmap from an mbm file +CleanupStack::PushL(bitmap); +User::LeaveIfError(bitmap->Load(KMBMFileName, EMbmAnimFrame1)); +CFbsBitmap* mask=new (ELeave) CFbsBitmap; // load the mask from the same mbm file +CleanupStack::PushL(mask); +User::LeaveIfError(mask->Load(KMBMFileName, EMbmAnimFrameMask1)); +CBitmapFrameData* frame1 = CBitmapFrameData::NewL(bitmap, mask); +CleanupStack::Pop(2); // bitmap, mask

CBitmapFrameData::SetBitmap() and CBitmapFrameData::SetMask() could alternatively be used.

An animation can have multiple frames, +each of which has an image and mask bitmap. Each frame stores a flag to indicate +whether or not it owns the bitmaps. If the frame owns the bitmaps, they are +deleted in the frame’s destructor. This flag can be set or unset by calling CBitmapFrameData::SetBitmapsOwnedExternally(). +By default, bitmaps are owned by the frame.

The mask is used in the +standard way for a bitmap mask, so pixels in the bitmap image that map to +black pixels in the mask are drawn, while pixels that map to white pixels +in the mask are not, so appear transparent.

Setting the time interval

The +time period for the frame to be displayed on the screen is set in milliseconds:

frame1->SetInterval(125);

Note +that a default time interval can be set in the frame container (described +in the next section) by calling CBitmapAnimClientData::SetFrameInterval(). +Any value set in the container will apply to frames that have not set an interval +themselves.

Setting the frame’s position

The position +of the frame relative to the animation window is set using CBitmapFrameData::SetPosition():

TPoint framePos(3,6); +frame1->SetPosition(framePos);

Note that the position can also +be specified in RBitmapAnim; if so, this value applies +to all frames.

When you have finished defining the animation frame(s), +use the frame container class, CBitmapAnimClientData, to +create the animation.

+
Defining an animation

Frames are grouped into an +animation frame container (CBitmapAnimClientData), which +allows the following behaviour to be set:

    +

  • append frames to the +container,

    • +

  • set a default display +interval for all frames, (note that the time interval set by an individual +frame takes precedence, for that frame, over the default interval),

    • +

  • set one of the following +play modes for the animation: play once, loop or bounce (plays forwards and +backwards),

    • +

  • set the animation to +flash,

    • +

  • provide an additional +bitmap frame to use for the background to the animation (explained below).

    • +

Appending frames

First, create the frame container, +and append the frame(s) to it in the correct sequence:

CBitmapAnimClientData* animFrames=CBitmapAnimClientData::NewL(); +CleanupStack::PushL(animFrames); +animFrames->AppendFrameL(*frame1); +animFrames->AppendFrameL(*frame2); // etc.

Setting the default +display interval

A default display interval can be set for the +animation:

animFrames->SetFrameInterval(100);

This +applies only to frames which have not specified their own interval (using CBitmapFrameData::SetInterval()). +In this example, the default interval for frames without their own interval +is 100 milliseconds (0.1 second). It can be used to ensure that all frames +are displayed for the same length of time.

Setting the play mode

There +are three play modes: play once, play repeatedly in the same direction ('loop') +and play forwards and backwards repeatedly ('bounce'). This code sets the +animation to play once:

animFrames->SetPlayMode(CBitmapAnimClientData::EPlay);

Other properties

CBitmapAnimClientData::SetFlash() and CBitmapAnimClientData::SetBackgroundFrame() are used to set/unset the flash flag and the background frame, respectively. +The flash flag determines whether the animation should flash or not.

The +background frame, which is optional, is used to clear the current frame before +drawing the next one. If no background frame is provided by the client, the +window server creates its own background frame using the original screen contents, +and updates it when the animation window is redrawn.

If the client-provided +background frame contains an image bitmap and a mask, the background image +used is a combination of the screen contents and the supplied background bitmap. +If the client-provided background frame has a bitmap but no mask, the bitmap +is used as the background.

+
Playing the animation

When the animation is ready +to play, it must be packaged and sent to the window server’s animation DLL. +This is done through an animation player (RBitmapAnim) +object.

RBitmapAnim allows you to do the following:

    +

  • specify the window in +which the animation is displayed,

    • +

  • associate the animation +with an RAnimDll object, which provides a connection to +the window server,

    • +

  • pass the animation object +to the window server’s animation DLL,

    • +

  • specify the number of +times the animation should play,

    • +

  • start and stop playing +the animation. Optionally the animation can start playing from a particular +frame.

    • +

Note that after the animation object has been set up and passed to +the window server, the general attributes of the animation, namely the flash +property, the default display time for each frame and the play mode can still +be changed, using the following RBitmapAnim functions:

    +

  • SetFlashL(),

    • +

  • SetFrameIntervalL(),

    • +

  • SetPlayModeL().

    • +

Any changes to these properties made using RBitmapAnim will +override the values previously set in CBitmapAnimClientData.

Constructing +the animation player

RAnimDll is a handle +to the server-side animation DLL. It is used to load the window server animation +DLL, bmpansrv.dll, which provides the functions that +perform the frames animation. The RAnimDll instance is passed +to the RBitmapAnim constructor.

RAnimDll animDLL(iEikonEnv->WsSession()); // session is used to interact with the window server +_LIT(KDllName, "BMPANSRV.DLL"); +User::LeaveIfError(animDll.Load(KDllName)); +RBitmapAnim animPlayer(animDLL); +animPlayer.ConstructL(Window());

Passing the animation object +to the window server

The animation frame container (CBitmapAnimClientData) +should be passed via the RBitmapAnim object to the window +server. This is done using the function SetBitmapAnimDataL(). +Note that calling this function does not cause the animation to start playing:

animPlayer.SetBitmapAnimDataL(*animFrames);

Setting +the number of cycles

If the animation should play more than once, +the number of cycles should be set:

animPlayer.SetNumberOfCyclesL(10);

Note that if the animation's play mode is 'bounce', the number of cycles +must be set to at least two to ensure a complete animation routine.

Setting +the position

To set the animation’s position, use SetPositionL(). +This value is an offset from the origin of the animation window.

TPoint animPos(20,40); +animPlayer.SetPositionL(animPos);

Starting/stopping the +animation

The RBitmapAnim::StartL() and RBitmapAnim::StopL() functions +send commands to the animation DLL to start/stop the animation routine.

Calling RBitmapAnim::DisplayFrameL() before +the animation has started sets the frame from which the animation should start +playing.

Freeing resources

After they have been finished +with, Close() should be called on the RAnimDll and RBitmapAnim objects.

animPlayer.Close(); +animDLL.Close();
+
See also
    +

  • Animation Overview

    • +

  • Introduction +to the Font and Bitmap Server

    • +
+ \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-063020E5-51C0-45C3-8B8B-015385FA0928.dita --- a/Symbian3/SDK/Source/GUID-063020E5-51C0-45C3-8B8B-015385FA0928.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-063020E5-51C0-45C3-8B8B-015385FA0928.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,37 +1,37 @@ - - - - - -Redirect -Printf ExampleRedirect standard I/O to a file -

This example illustrates how to redirect standard I/O to a file. The libc library -provides freopen() API to redirect all standard IOs (namely -- stderr, stdin or stdout). Application first prints launching information -at the console and then opens one file to redirect standard output using freopen(). -Calling freopen() once more, the user can change the filename -during execution. This helps to redirect application printf() messages -into a log file.

-
Download

Click -on the following link to download the example: redirectprintf.zip

Click: browse to view the example code.

-
Design and -Implementation

The following sections provide information about -the implementation of the example.

Capabilities

The program -capabilities are defined in redirectprintf.mmp : CAPABILITY -NONE.
-
Building and -Using To build the example application, go to the redirectprintf\group -directory and build the application. The definition for the whole application -can be found in the bld.inf file in the group subdirectory of the applications -main directory.

The application is simple console based application. It -has its own default icon and can be launched from the UI both -in the emulator and in the device. The application can be launched by: Executing -redirectprintf from eshell. Clicking default icon with display text redirectprintf -within the install folder launcher application.

+ + + + + +Redirect +Printf ExampleRedirect standard I/O to a file +

This example illustrates how to redirect standard I/O to a file. The libc library +provides freopen() API to redirect all standard IOs (namely +- stderr, stdin or stdout). Application first prints launching information +at the console and then opens one file to redirect standard output using freopen(). +Calling freopen() once more, the user can change the filename +during execution. This helps to redirect application printf() messages +into a log file.

+
Download

Click +on the following link to download the example: redirectprintf.zip

Click: browse to view the example code.

+
Design and +Implementation

The following sections provide information about +the implementation of the example.

Capabilities

The program +capabilities are defined in redirectprintf.mmp : CAPABILITY +NONE.
+
Building and +Using To build the example application, go to the redirectprintf\group +directory and build the application. The definition for the whole application +can be found in the bld.inf file in the group subdirectory of the applications +main directory.

The application is simple console based application. It +has its own default icon and can be launched from the UI both +in the emulator and in the device. The application can be launched by: Executing +redirectprintf from eshell. Clicking default icon with display text redirectprintf +within the install folder launcher application.

\ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-06676D89-FDE7-58FD-9D2E-3C984CD24BAC-GENID-1-8-1-3-1-1-7-1-8-1-4-1.dita --- a/Symbian3/SDK/Source/GUID-06676D89-FDE7-58FD-9D2E-3C984CD24BAC-GENID-1-8-1-3-1-1-7-1-8-1-4-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,22 +0,0 @@ - - - - - -Embedded -applications -

Embedded applications are required by the application architecture. These -applications’ root controls should have a z -order that causes only -the currently-active application to be displayed, and only that application -to be able to receive pointer events.

-

Additionally, only the currently active application — with its menu bar, -active dialogs, and so on — should be able to process key events.

-

The requirements of embedded applications are supported by stack-like behavior -at each priority level within the controls maintained by the app UI.

- \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-06676D89-FDE7-58FD-9D2E-3C984CD24BAC-GENID-1-8-1-6-1-1-4-1-6-1-8-1-4-1.dita --- a/Symbian3/SDK/Source/GUID-06676D89-FDE7-58FD-9D2E-3C984CD24BAC-GENID-1-8-1-6-1-1-4-1-6-1-8-1-4-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,22 +0,0 @@ - - - - - -Embedded -applications -

Embedded applications are required by the application architecture. These -applications’ root controls should have a z -order that causes only -the currently-active application to be displayed, and only that application -to be able to receive pointer events.

-

Additionally, only the currently active application — with its menu bar, -active dialogs, and so on — should be able to process key events.

-

The requirements of embedded applications are supported by stack-like behavior -at each priority level within the controls maintained by the app UI.

- \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-06676D89-FDE7-58FD-9D2E-3C984CD24BAC.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-06676D89-FDE7-58FD-9D2E-3C984CD24BAC.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,22 @@ + + + + + +Embedded +applications +

Embedded applications are required by the application architecture. These +applications’ root controls should have a z -order that causes only +the currently-active application to be displayed, and only that application +to be able to receive pointer events.

+

Additionally, only the currently active application — with its menu bar, +active dialogs, and so on — should be able to process key events.

+

The requirements of embedded applications are supported by stack-like behavior +at each priority level within the controls maintained by the app UI.

+ \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-06730728-30C5-51FD-BD37-FB62F2958D28.dita --- a/Symbian3/SDK/Source/GUID-06730728-30C5-51FD-BD37-FB62F2958D28.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-06730728-30C5-51FD-BD37-FB62F2958D28.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,33 +1,32 @@ - - - - - -Calendar -Conversion Overview -

This topic describes date conversion between Gregorian and Chinese calendars.

-
Download

Click on the following link to download -the example: Calcon.zip

Click: browse to view the example code.

-
Architectural Relationships

The TDateTime class -is used to represent the Gregorian calendar date. The class TChineseDate is -used to represent the Chinese calendar date. CChineseCalendarConverter is -used for conversion in either direction between a Gregorian date and a Chinese -date.

The CChineseCalendarConverter interface is -implemented by a separate plug-in, which is not provided by this component. -If the plug-in is not available the interface returns an error.

-
Description

The API consists of two calendar classes: TDateTime and CChineseCalendarConverter, which converts between TDateTime and TChineseDate formats -in both directions. Chinese dates are calculated using the -2636 epoch. This -is equivalent to 2637 BCE (Before Common Era).

-
Class summary
    -

  • CChineseCalendarConverter

    • -

  • TDateTime

    • -

  • TChineseDate

    • -

  • TDateTime

    • -
+ + + + + +Calendar Conversion Overview +

This topic describes date conversion between Gregorian and Chinese +calendars.

+
Download

Click on the following link to +download the example: Calcon.zip

Click: browse to view the example code.

+
Architectural Relationships

The TDateTime class is used to represent the Gregorian calendar +date. The class TChineseDate is used to represent +the Chinese calendar date. CChineseCalendarConverter is used for conversion in either direction between a Gregorian date +and a Chinese date.

The CChineseCalendarConverter interface is implemented by a separate plug-in, which is not provided +by this component. If the plug-in is not available the interface returns +an error.

+
Description

The API consists of two calendar +classes: TDateTime and CChineseCalendarConverter, which converts between TDateTime and TChineseDate formats in both directions. Chinese dates +are calculated using the -2636 epoch. This is equivalent to 2637 BCE +(Before Common Era).

+
Class summary
    +

  • CChineseCalendarConverter

    • +

  • ESock::TDateTime

    • +

  • TChineseDate

    • +
 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-067BC702-4F66-5CAF-952D-7CFA35F5EB1E.dita --- a/Symbian3/SDK/Source/GUID-067BC702-4F66-5CAF-952D-7CFA35F5EB1E.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-067BC702-4F66-5CAF-952D-7CFA35F5EB1E.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,13 +1,13 @@ - - - - - -Twip to Pixel Mapping

This topic provides an introduction to two classes that embody the important GUI features of device independence and the ability to zoom.

Two desirable facilities of a GUI are:

  • device independence

  • zooming to reveal greater levels of detail or, conversely, more of a document

These two facilities are embodied in the two classes MGraphicsDeviceMap and TZoomFactor.

Device independence is facilitated by storing drawings and text in device-independent form and then converting the device-independent units (twips) into device-dependent units (pixels) for different devices such as screens and printers. The conversion interface is MGraphicsDeviceMap, and it is implemented by graphics devices.

TZoomFactor also implements this interface. It takes a mapping between twips and pixels, and then also applies a zooming factor: the larger the zooming factor, the more pixels per twip. The relationship between the classes is shown below:

Note that TZoomFactor not only implements MGraphicsDeviceMap but also uses it. The point is that the MGraphicsDeviceMap -supporting object used can either be a graphics device, or another TZoomFactor. This allows zooming to be applied to an already zoomed mapping.

Using TZoomFactor and + + + + + +Twip to Pixel Mapping

This topic provides an introduction to two classes that embody the important GUI features of device independence and the ability to zoom.

Two desirable facilities of a GUI are:

  • device independence

  • zooming to reveal greater levels of detail or, conversely, more of a document

These two facilities are embodied in the two classes MGraphicsDeviceMap and TZoomFactor.

Device independence is facilitated by storing drawings and text in device-independent form and then converting the device-independent units (twips) into device-dependent units (pixels) for different devices such as screens and printers. The conversion interface is MGraphicsDeviceMap, and it is implemented by graphics devices.

TZoomFactor also implements this interface. It takes a mapping between twips and pixels, and then also applies a zooming factor: the larger the zooming factor, the more pixels per twip. The relationship between the classes is shown below:

Note that TZoomFactor not only implements MGraphicsDeviceMap but also uses it. The point is that the MGraphicsDeviceMap -supporting object used can either be a graphics device, or another TZoomFactor. This allows zooming to be applied to an already zoomed mapping.

Using TZoomFactor and MGraphicsDeviceMap Graphics Device Interface Concepts \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-06B287CD-C19A-4CAC-8378-5563C552448B-master.png Binary file Symbian3/SDK/Source/GUID-06B287CD-C19A-4CAC-8378-5563C552448B-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-06B287CD-C19A-4CAC-8378-5563C552448B_d0e58084_href.png Binary file Symbian3/SDK/Source/GUID-06B287CD-C19A-4CAC-8378-5563C552448B_d0e58084_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-06B287CD-C19A-4CAC-8378-5563C552448B_d0e61483_href.png Binary file Symbian3/SDK/Source/GUID-06B287CD-C19A-4CAC-8378-5563C552448B_d0e61483_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-074F3499-54FE-58BC-A0F4-D8EA632AF76B.dita --- a/Symbian3/SDK/Source/GUID-074F3499-54FE-58BC-A0F4-D8EA632AF76B.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-074F3499-54FE-58BC-A0F4-D8EA632AF76B.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,48 +1,48 @@ - - - - - -Externalising a Swizzle

Typically, externalizing a Swizzle is a two stage process which involves:

  • externalizing the in-memory object which the Swizzle represents, to its own stream

  • externalizing the resulting stream ID.

For example, given a container type object, CClassABC, with a data member TSwizzle<CClassB> iB representing a CClassB object in memory, the diagram below illustrates the result of storing the container object.

The following code fragments illustrates the process.

iB is a CClassB type component of a class CClassABC, and is represented by a Swizzle. The data member is defined as:

class CCClassABC : public CBase - { - ... - TSwizzle<CClassB> iB; - ... - } -

Typically, a CClassB object is constructed and assigned to iB; this uses the Swizzle’s assignment operator:

iB = CClassB::NewL();

The Swizzle now represents the CClassB object by pointer.

The StoreL() member function of CClassABC constructs a store map, an object of type CStoreMap, before calling StoreComponentsL() to externalise the swizzled CClassB object to its own stream.

TStreamId CClassABC::StoreL() const - { - CStoreMap* map=CStoreMap::NewLC(iStore); - StoreComponentsL(*map); - - RStoreWriteStream stream(*map); - TStreamId id=stream.CreateLC(iStore); - ExternalizeL(stream); - stream.CommitL(); - - map->Reset(); - CleanupStack::PopAndDestroy(2); - return id; - }

The variable iStore is a member of CClassABC containing a reference to the store.

StoreComponentsL() externalises the swizzled CClassB object by calling CClassB ’s own StoreL() member function which constructs a stream, externalises itself to the stream and returns the ID of that stream:

void CClassABC::StoreComponentsL(CStoreMap& aMap) const - { - ... - TStreamId id; - if (iB) - { - id = iB->StoreL(iStore); // Id of the CClassB stream - aMap.BindL(iB,id); - } - ... - }

The Swizzle must represent the CClassB type object as a pointer, i.e. the swizzled object must be in memory. The operator-> applied to the Swizzle iB gives access to the StoreL() member function of the CClassB object.

The condition if (iB) is equivalent to if - (iB.IsPtr()) and returns true only if the Swizzle represents the CClassB object as a pointer . The act of externalizing the CClassB object, does not, and need not change the way that the Swizzle represents that object. Here, the CClassB object remains in memory and the Swizzle maintains its representation of it as a pointer, even after it has been externalised.

The Stream ID of the externalised CClassB object is stored in the store map along with the associated Swizzle using CStoreMap ’s BindL() member function .The store map is used again later when the stream ID is externalised as part of CClassABC ’s data.

The ExternalizeL() member function of CClassABC externalises CClassABC's member data. This includes the stream ID of the externalised CClassB object which is externalised by applying the templated stream operator<< to the Swizzle iB.

void CCompound::ExternalizeL(RWriteStream& aStream) const - { - ... - aStream << iB - ... - } -

At this point, the Swizzle still represents the CClassB object as a pointer, and the object itself is still in memory.

The mechanism underlying the implementation of the stream operator<<, assumes that the stream ID associated with the Swizzle has been placed in the store map. It also assumes that the RStoreWriteStream object has been constructed, specifying the store map as an externalizer.

The end result of the operation aStream << iB;, is to externalise, to the stream, the stream ID associated with the Swizzle iB. The following diagram shows this:

 \ No newline at end of file + + + + + +Externalising a Swizzle

Typically, externalizing a Swizzle is a two stage process which involves:

  • externalizing the in-memory object which the Swizzle represents, to its own stream

  • externalizing the resulting stream ID.

For example, given a container type object, CClassABC, with a data member TSwizzle<CClassB> iB representing a CClassB object in memory, the diagram below illustrates the result of storing the container object.

The following code fragments illustrates the process.

iB is a CClassB type component of a class CClassABC, and is represented by a Swizzle. The data member is defined as:

class CCClassABC : public CBase + { + ... + TSwizzle<CClassB> iB; + ... + } +

Typically, a CClassB object is constructed and assigned to iB; this uses the Swizzle’s assignment operator:

iB = CClassB::NewL();

The Swizzle now represents the CClassB object by pointer.

The StoreL() member function of CClassABC constructs a store map, an object of type CStoreMap, before calling StoreComponentsL() to externalise the swizzled CClassB object to its own stream.

TStreamId CClassABC::StoreL() const + { + CStoreMap* map=CStoreMap::NewLC(iStore); + StoreComponentsL(*map); + + RStoreWriteStream stream(*map); + TStreamId id=stream.CreateLC(iStore); + ExternalizeL(stream); + stream.CommitL(); + + map->Reset(); + CleanupStack::PopAndDestroy(2); + return id; + }

The variable iStore is a member of CClassABC containing a reference to the store.

StoreComponentsL() externalises the swizzled CClassB object by calling CClassB ’s own StoreL() member function which constructs a stream, externalises itself to the stream and returns the ID of that stream:

void CClassABC::StoreComponentsL(CStoreMap& aMap) const + { + ... + TStreamId id; + if (iB) + { + id = iB->StoreL(iStore); // Id of the CClassB stream + aMap.BindL(iB,id); + } + ... + }

The Swizzle must represent the CClassB type object as a pointer, i.e. the swizzled object must be in memory. The operator-> applied to the Swizzle iB gives access to the StoreL() member function of the CClassB object.

The condition if (iB) is equivalent to if + (iB.IsPtr()) and returns true only if the Swizzle represents the CClassB object as a pointer . The act of externalizing the CClassB object, does not, and need not change the way that the Swizzle represents that object. Here, the CClassB object remains in memory and the Swizzle maintains its representation of it as a pointer, even after it has been externalised.

The Stream ID of the externalised CClassB object is stored in the store map along with the associated Swizzle using CStoreMap ’s BindL() member function .The store map is used again later when the stream ID is externalised as part of CClassABC ’s data.

The ExternalizeL() member function of CClassABC externalises CClassABC's member data. This includes the stream ID of the externalised CClassB object which is externalised by applying the templated stream operator<< to the Swizzle iB.

void CCompound::ExternalizeL(RWriteStream& aStream) const + { + ... + aStream << iB + ... + } +

At this point, the Swizzle still represents the CClassB object as a pointer, and the object itself is still in memory.

The mechanism underlying the implementation of the stream operator<<, assumes that the stream ID associated with the Swizzle has been placed in the store map. It also assumes that the RStoreWriteStream object has been constructed, specifying the store map as an externalizer.

The end result of the operation aStream << iB;, is to externalise, to the stream, the stream ID associated with the Swizzle iB. The following diagram shows this:

 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-07A42662-87A1-4537-89B9-F87DFC8481E8.dita --- a/Symbian3/SDK/Source/GUID-07A42662-87A1-4537-89B9-F87DFC8481E8.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-07A42662-87A1-4537-89B9-F87DFC8481E8.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,29 +1,28 @@ - - - - - -Signal -and battery indicators -

The top-left area of the screen is used for the cellular signal strength -indicator, and the corresponding top-right area for the battery level indicator.

- -Signal and battery indicators on the sides of the status pane. Other -status indicators are visible below the Navi pane. - - -

The signal indicator is a part of the Status pane, and it is displayed -in all states where the Status pane exists. Indicators consist of a bar graph -that indicates the current battery or signal level and an icon that describes -battery or in signal indicator connected cellular network and its connection -state.

-
Using -signal and battery indicators in C++ applications

The -signal and battery indicators are not accessible to applications.

+ + + + + +Signal +and battery indicators +

The top-left area of the screen is used for the cellular signal strength +indicator, and the corresponding top-right area for the battery level indicator.

+ +Signal and battery indicators on the sides of the status pane. + + +

The signal indicator is a part of the Status pane, and it is displayed +in all states where the Status pane exists. Indicators consist of a bar graph +that indicates the current battery or signal level and an icon that describes +battery or in signal indicator connected cellular network and its connection +state.

+
Using +signal and battery indicators in applications

The signal and battery +indicators are not accessible to applications.

 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-07B6D7EE-575A-5E8E-A2BB-8893F84F7F6D_d0e323166_href.jpg Binary file Symbian3/SDK/Source/GUID-07B6D7EE-575A-5E8E-A2BB-8893F84F7F6D_d0e323166_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-07B6D7EE-575A-5E8E-A2BB-8893F84F7F6D_d0e329323_href.jpg Binary file Symbian3/SDK/Source/GUID-07B6D7EE-575A-5E8E-A2BB-8893F84F7F6D_d0e329323_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-07D2ED79-90B2-4ABC-A61F-108DAEE21955.dita --- a/Symbian3/SDK/Source/GUID-07D2ED79-90B2-4ABC-A61F-108DAEE21955.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-07D2ED79-90B2-4ABC-A61F-108DAEE21955.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,144 +1,144 @@ - - - - - -Implementing -framework requirements -Application Menu -

In the Symbian platform, mobile device users start applications from -the application menu. When the mobile device user selects an application, -the application framework calls the application's entry point to launch the -application. In some cases, applications can also be started by other executables.

-Application launch -

When an application starts, objects are created in the following order:

-
    -

  1. application -(CAknApplication)

    2. -

  2. document (CAknDocument)

    -
    3. -

  3. UI controller -(CAknAppUI or CAknAppViewUI depending -upon your approach)

    4. -

  4. view controller -(CAknView) in Symbian -view applications

    5. -

  5. view (CCoeControl)

    -
    6. -
-
Entry point -

The two methods that you need to implement for the entry point are as -follows:

-
    -

  • an entry point for the application, with the following syntax:

    - -GLDEF_C TInt E32Main() - { - return EikStart::RunApplication( NewApplication ); - } -

    where:

    -

    E32Main() is the entry point method called by the -application framework

    -

    return EikStart::RunApplication(NewApplication ) calls EikStart::RunApplication()

    -     -
    • -

  • a non-leaving factory method that creates a new instance -of the application class, or NULL if the class cannot -be instantiated. The expected syntax is as follows:

    - -LOCAL_C CApaApplication* NewApplication() - { - return new CMyAppClass; - } -

    where:

    -

    NewApplication() is a method that returns a pointer -to a CApaApplication object.

    -

    return new CMyAppClass returns an instance of the -application class as created by the CAknApplication derived -class

    -

    The application framework expects the factory method to have exactly -this prototype. In other words, the factory function should be like the above -code fragment.

    -     -
    • -
-
-
CAknApplication -

You must implement at least the following two methods in your CAknApplication derived -class:

-
    -

  • a method that returns the application UID. The syntax is -as follows:

    -TUid CMyAppClass::AppDllUid() const - { - return KUidMyApp; - } -

    where:

    - -

    CApaApplication::AppDllUid() is used to get the application -UID

    -

    KUidMyApp is the UID for your application, which -is typically declared in an application header file.

    -     -

    The application framework calls the AppDllUid() method -to get the application UID. The application framework checks to see if there -is an instance of the application with the same UID already running. If so, -then the application framework switches to the already existing application.

    - -

    You must return the same UID that you declared for the UID3 in the mmp and registration files.

    -     -
    • -

  • a factory function for creating an object of the document -class for your application. The expected syntax is as follows:

    -CApaDocument* CMyAppClass::CreateDocumentL() - { - return CMyAppDocument::NewL( *this ); - } - -

    where:

    - -

    CEikApplication::CreateDocumentL() is called by the -application framework.

    -

    return CMyAppDocument::NewL( *this ) returns an -instance of the CAknDocument derived class of your application. -It represents the data that relates to a particular instance of the application -and owns the application UI -controller.

    -     -
    • -
- -

The application framework owns the document object and is responsible -for destroying it.

- -
-
CAknDocument -

You must implement a CAknDocument derived class for -your application, even if you do not store data, as this is the class that -owns the UI controller for -your application. The expected syntax for creating the UI controller class -is as follows:

-CEikAppUi* CMyAppDocument::CreateAppUiL() - { - return new ( ELeave ) CMyAppAppUi; - } -

where:

-
    -

  • CEikDocument::CreateAppUiL() carries out -the first phase construction of the UI controller

    • -

  • new ( ELeave ) CMyAppAppUi is a method -that creates an instance of the UI controller class of your application

    -
    • -
-

The application framework owns the UI controller object of the application -and is responsible for destroying it. There are two alternate classes from -which you can derive your UI controller class, CAknAppUi or CAknViewAppUi.

-

For more information on the UI controller options, see UI controller

-
+ + + + + +Implementing +framework requirements +Application Menu +

In the Symbian platform, mobile device users start applications from +the application menu. When the mobile device user selects an application, +the application framework calls the application's entry point to launch the +application. In some cases, applications can also be started by other executables.

+Application launch +

When an application starts, objects are created in the following order:

+
    +

  1. application +(CAknApplication)

    2. +

  2. document (CAknDocument)

    +
    3. +

  3. UI controller +(CAknAppUI or CAknAppViewUI depending +upon your approach)

    4. +

  4. view controller +(CAknView) in Symbian +view applications

    5. +

  5. view (CCoeControl)

    +
    6. +
+
Entry point +

The two methods that you need to implement for the entry point are as +follows:

+
    +

  • an entry point for the application, with the following syntax:

    + +GLDEF_C TInt E32Main() + { + return EikStart::RunApplication( NewApplication ); + } +

    where:

    +

    E32Main() is the entry point method called by the +application framework

    +

    return EikStart::RunApplication(NewApplication ) calls EikStart::RunApplication()

    +     +
    • +

  • a non-leaving factory method that creates a new instance +of the application class, or NULL if the class cannot +be instantiated. The expected syntax is as follows:

    + +LOCAL_C CApaApplication* NewApplication() + { + return new CMyAppClass; + } +

    where:

    +

    NewApplication() is a method that returns a pointer +to a CApaApplication object.

    +

    return new CMyAppClass returns an instance of the +application class as created by the CAknApplication derived +class

    +

    The application framework expects the factory method to have exactly +this prototype. In other words, the factory function should be like the above +code fragment.

    +     +
    • +
+
+
CAknApplication +

You must implement at least the following two methods in your CAknApplication derived +class:

+
    +

  • a method that returns the application UID. The syntax is +as follows:

    +TUid CMyAppClass::AppDllUid() const + { + return KUidMyApp; + } +

    where:

    + +

    CApaApplication::AppDllUid() is used to get the application +UID

    +

    KUidMyApp is the UID for your application, which +is typically declared in an application header file.

    +     +

    The application framework calls the AppDllUid() method +to get the application UID. The application framework checks to see if there +is an instance of the application with the same UID already running. If so, +then the application framework switches to the already existing application.

    + +

    You must return the same UID that you declared for the UID3 in the mmp and registration files.

    +     +
    • +

  • a factory function for creating an object of the document +class for your application. The expected syntax is as follows:

    +CApaDocument* CMyAppClass::CreateDocumentL() + { + return CMyAppDocument::NewL( *this ); + } + +

    where:

    + +

    CEikApplication::CreateDocumentL() is called by the +application framework.

    +

    return CMyAppDocument::NewL( *this ) returns an +instance of the CAknDocument derived class of your application. +It represents the data that relates to a particular instance of the application +and owns the application UI +controller.

    +     +
    • +
+ +

The application framework owns the document object and is responsible +for destroying it.

+ +
+
CAknDocument +

You must implement a CAknDocument derived class for +your application, even if you do not store data, as this is the class that +owns the UI controller for +your application. The expected syntax for creating the UI controller class +is as follows:

+CEikAppUi* CMyAppDocument::CreateAppUiL() + { + return new ( ELeave ) CMyAppAppUi; + } +

where:

+
    +

  • CEikDocument::CreateAppUiL() carries out +the first phase construction of the UI controller

    • +

  • new ( ELeave ) CMyAppAppUi is a method +that creates an instance of the UI controller class of your application

    +
    • +
+

The application framework owns the UI controller object of the application +and is responsible for destroying it. There are two alternate classes from +which you can derive your UI controller class, CAknAppUi or CAknViewAppUi.

+

For more information on the UI controller options, see UI controller

+
 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-07F65EEA-5969-5E56-9570-245712FB3EE3_d0e240067_href.png Binary file Symbian3/SDK/Source/GUID-07F65EEA-5969-5E56-9570-245712FB3EE3_d0e240067_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-07F65EEA-5969-5E56-9570-245712FB3EE3_d0e243804_href.png Binary file Symbian3/SDK/Source/GUID-07F65EEA-5969-5E56-9570-245712FB3EE3_d0e243804_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-08152DC3-2A5D-42AC-B722-3D49275FE548_d0e11707_href.png Binary file Symbian3/SDK/Source/GUID-08152DC3-2A5D-42AC-B722-3D49275FE548_d0e11707_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-08152DC3-2A5D-42AC-B722-3D49275FE548_d0e12976_href.png Binary file Symbian3/SDK/Source/GUID-08152DC3-2A5D-42AC-B722-3D49275FE548_d0e12976_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0822B030-E776-4BD5-B9C9-23D3821BCE1F.dita --- a/Symbian3/SDK/Source/GUID-0822B030-E776-4BD5-B9C9-23D3821BCE1F.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-0822B030-E776-4BD5-B9C9-23D3821BCE1F.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,152 +1,154 @@ - - - - - -Selection -list -

A selection list is a common means of displaying and accessing data in -applications. When a selection list is displayed, the application is typically -in a permanent state, which means that the user can leave the application, -open another application, and later return to the same state. Selection lists -are displayed in the main pane.

-

Typically, the user can open items in a selection list, leading into another, -more detailed view of the item within the application. In addition to browsing -and selecting items, other functions are available in the Options menu (see Options menu).

-

The usage of the Selection key in selection lists deserves special attention. -Depending on the case, it can do the following actions:

-
    -

  • Selects the item in focus. This should happen whenever it is assumed -that it is clear to the user what happens. Selecting can mean:

      -

    • Opening an item, such as a folder or a date in Calendar, leading to -a detailed view.

      • -

    • Executing a command when the focused item is a command.

      • -
    • -

  • Opens the context sensitive Options menu. This should only happen when -the user cannot be assumed to know what happens if the Selection key is pressed. -The menu should contain only high-priority options associated with the item -in focus, not general items such as Settings, Help, or Exit. The maximum amount -of options in the context sensitive Options menu is four.

    • -
-

The two types of Selection key actions should not be mixed within one list; -one or the other should happen for every item in the list.

- -Select action opens a view - - - -Select action performs a command - - - -Context sensitive Options menu opened with the Selection key - - -

The keypad functions for selection lists are as follows:

-Default key events -in selection list - - - -

Arrow up / down

 -

Moves the focus in the list.

 - - -

Arrow left / right

 -

May be ignored, or may have navigation functions associated with -them (see Navigation).

 - - -

Selection key

 -

Selects the item; see the discussion above.

 - - -

Left softkey (Options)

 -

Opens the Options menu (see Options -menu).

 - - -

Right softkey (Back; Exit)

 -

Back stepping (seeNavigation).

 - - -

Clear

 -

Deletes the item if it can be deleted (confirmation from the user -is required); otherwise ignored.

 - - -

Edit

 -

Ignored, or a marking function if the list is markable (see Markable list).

 - - -

Numeric keypad

 -

May be ignored, or may have specific functions within the state.

 - - -

Other keys

 -

Do the default action of the key.

 - - - -
-

-

The following table lists the default touch events for selection list:

-Default touch -events for Selection list. - - - - - - -

User action

 -

State change

 -

Feedback

 - - - - -

Touch down

 -

No effect

 -

Highlight is shown.

Tactile: Basic list effect and audio -feedback is provided with touch down event.

 - - -

Touch release

 -

Item is activated.

 -

Highlight disappears.

Tactile: Basic list effect is provided -with touch release event.

 - - -

Touch down and hold

 -

Stylus pop-up menu is opened.

 -

Highlight is shown. Animation is shown to indicate the opening pop-up.

Tactile: -If activates a long touch, then increasing long touch effect is provided with -hold event. Pop-up effect is provided when the pop-up is opened.

 - - -

Touch event combinations, refer to Dragging -and flicking events.

 -

Refer to Dragging -and flicking events.

 -

Tactile: Refer to Dragging -and flicking events.

 - - - -
- -Selection lists - - -
Using -selection lists in C++ applications

The API to use for selection -lists is the Lists API. For implementation information, -see Using the Lists API.

+ + + + + +Selection +list +

A selection list is a common means of displaying and accessing data in +applications. When a selection list is displayed, the application is typically +in a permanent state, which means that the user can leave the application, +open another application, and later return to the same state. Selection lists +are displayed in the main pane.

+

Typically, the user can open items in a selection list, leading into another, +more detailed view of the item within the application. In addition to browsing +and selecting items, other functions are available in the Options menu (see Options menu).

+

The usage of the Selection key in selection lists deserves special attention. +Depending on the case, it can do the following actions:

+
    +

  • Selects the item in focus. This should happen whenever it is assumed +that it is clear to the user what happens. Selecting can mean:

      +

    • Opening an item, such as a folder or a date in Calendar, leading to +a detailed view.

      • +

    • Executing a command when the focused item is a command.

      • +
    • +

  • Opens the context sensitive Options menu. This should only happen when +the user cannot be assumed to know what happens if the Selection key is pressed. +The menu should contain only high-priority options associated with the item +in focus, not general items such as Settings, Help, or Exit. The maximum amount +of options in the context sensitive Options menu is four.

    • +
+

The two types of Selection key actions should not be mixed within one list; +one or the other should happen for every item in the list.

+ +Select action opens a view + + + +Select action performs a command + + + +Context sensitive Options menu opened with the Selection key + + +

The keypad functions for selection lists are as follows:

+Default key events +in selection list + + + +

Key events

 +

Description

 + + + + +

Arrow up / Arrow down

 +

Moves up or down to next visible item in a list.

 + + +

Arrow left / Arrow right

 +

May be ignored, or may have navigation functions associated with +them (see Navigation).

 + + +

Selection key

 +

Selects the item; see the discussion above.

 + + +

Left softkey (Options)

 +

Opens the Options menu (see Options +menu).

 + + +

Right softkey (Back; Exit)

 +

Back stepping (seeNavigation).

 + + +

Clear

 +

Deletes the item if it can be deleted (confirmation from the user +is required); otherwise ignored.

 + + +

Edit

 +

Ignored, or a marking function if the list is markable (see Markable list).

 + + +

Numeric keypad

 +

May be ignored, or may have specific functions within the state.

 + + +

Other keys

 +

Do the default action of the key.

 + + + +
+

+

The following table lists the default touch events for selection list:

+Default touch +events for Selection list. + + + +

User action

 +

State change

 +

Feedback

 + + + + +

Touch down

 +

No effect

 +

Highlight is shown.

Tactile: Basic list effect and audio +feedback is provided with touch down event.

 + + +

Touch release

 +

Item is activated.

 +

Highlight disappears.

Tactile: Basic list effect is provided +with touch release event.

 + + +

Touch down and hold

 +

Stylus pop-up menu is opened.

 +

Highlight is shown. Animation is shown to indicate the opening pop-up.

Tactile: +If activates a long touch, then increasing long touch effect is provided with +hold event. Pop-up effect is provided when the pop-up is opened.

 + + +

Touch event combinations, refer to Dragging +and flicking events.

 +

Refer to Dragging +and flicking events.

 +

Tactile: Refer to Dragging +and flicking events.

 + + + +
+ +Selection lists + + +
Using +selection lists in applications

The API to use for selection lists +is the Lists API. For implementation information, see Using the Lists API.

 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-084C5F8F-3310-5BDE-BB4B-110361D45AB0_d0e220093_href.png Binary file Symbian3/SDK/Source/GUID-084C5F8F-3310-5BDE-BB4B-110361D45AB0_d0e220093_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-084C5F8F-3310-5BDE-BB4B-110361D45AB0_d0e223830_href.png Binary file Symbian3/SDK/Source/GUID-084C5F8F-3310-5BDE-BB4B-110361D45AB0_d0e223830_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-085CD9C3-706F-51E7-A1D5-95483D3C9254_d0e117574_href.png Binary file Symbian3/SDK/Source/GUID-085CD9C3-706F-51E7-A1D5-95483D3C9254_d0e117574_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-085CD9C3-706F-51E7-A1D5-95483D3C9254_d0e124112_href.png Binary file Symbian3/SDK/Source/GUID-085CD9C3-706F-51E7-A1D5-95483D3C9254_d0e124112_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-08937880-C381-4C8B-AC17-7162C1243E23_d0e68807_href.png Binary file Symbian3/SDK/Source/GUID-08937880-C381-4C8B-AC17-7162C1243E23_d0e68807_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-08A6B93F-92CD-5182-B142-D353E78016F3_d0e406599_href.png Binary file Symbian3/SDK/Source/GUID-08A6B93F-92CD-5182-B142-D353E78016F3_d0e406599_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-08A6B93F-92CD-5182-B142-D353E78016F3_d0e406761_href.png Binary file Symbian3/SDK/Source/GUID-08A6B93F-92CD-5182-B142-D353E78016F3_d0e406761_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-08B878D0-C0DA-46CC-ACC2-E576E5A3D937.dita --- a/Symbian3/SDK/Source/GUID-08B878D0-C0DA-46CC-ACC2-E576E5A3D937.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-08B878D0-C0DA-46CC-ACC2-E576E5A3D937.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,65 +1,58 @@ - - - - - -Main -pane -

The main pane is the main area of the screen where an application can display -its data.

-

There are a number of standard components for applications to use in the -main pane as listed in the following table:

-Standard components -for applications to use in main pane - - - -Pane -Description - - - - -

List

 -

There are several standard list types to choose from (see Lists and grids for -a detailed description of the list types).

In the landscape mode, two -row lists are most commonly stretched to be displayed in one row, which enables -displaying more items in landscape. List stretching is ON by default, but -application can decide to disable it.

 - - -

Grid

 -

Items can be presented on a two-directional grid.

 - - -

Find pane

 -

The Find pane is used together with a list, and it allows the user -to search list items alphabetically (see Find -pane for more information about the Find pane).

 - - -

Status indicators

 -

Status indicators are displayed in the Universal indicator pane. -See Universal indicators for -more details on Status indicators.

 - - -

Soft indicators

 -

Soft indicators only exist in the Idle state. See Indicators for -more information on status indicators and soft indicators.

 - - - -
-

Applications can also use the main pane area to freely draw whatever is -needed. In that case, however, the responsibility for the look and feel is -entirely on the application's designer.

-

For information on how to implement -your application using the Symbian application and UI frameworks, see Application and UI frameworks.

+ + + + + +Main pane +

The main pane is the main area of the screen where an application can display +its data.

+

There are a number of standard components for applications to use in the +main pane as listed in the following table:

+Standard components +for applications to use in main pane + + + +Pane +Description + + + + +

List

 +

There are several standard list types to choose from (see Lists and grids for +a detailed description of the list types).

In the landscape mode, two +row lists are most commonly stretched to be displayed in one row, which enables +displaying more items in landscape. List stretching is ON by default, but +application can decide to disable it.

 + + +

Grid

 +

Items can be presented on a two-directional grid.

 + + +

Find pane

 +

The Find pane is used together with a list, and it allows the user +to search list items alphabetically (see Find +pane for more information about the Find pane).

 + + +

Soft indicators

 +

Soft indicators only exist in the home screen. See Indicators for +more information on status indicators and soft indicators.

 + + + +
+

Applications can also use the main pane area to freely draw whatever is +needed. In that case, however, the responsibility for the look and feel is +entirely on the application's designer.

+

For information on how to implement +your application using the Symbian application and UI frameworks, see Application and UI frameworks.

 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-08E31D57-A84D-5B6B-B16F-3F7025A763E9_d0e236873_href.png Binary file Symbian3/SDK/Source/GUID-08E31D57-A84D-5B6B-B16F-3F7025A763E9_d0e236873_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-08E31D57-A84D-5B6B-B16F-3F7025A763E9_d0e240610_href.png Binary file Symbian3/SDK/Source/GUID-08E31D57-A84D-5B6B-B16F-3F7025A763E9_d0e240610_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-09044578-9ADB-540F-A854-A818EA3970B7_d0e240374_href.png Binary file Symbian3/SDK/Source/GUID-09044578-9ADB-540F-A854-A818EA3970B7_d0e240374_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-09044578-9ADB-540F-A854-A818EA3970B7_d0e244111_href.png Binary file Symbian3/SDK/Source/GUID-09044578-9ADB-540F-A854-A818EA3970B7_d0e244111_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-09142C26-0AFA-510E-836D-010EE07A1549_d0e188596_href.png Binary file Symbian3/SDK/Source/GUID-09142C26-0AFA-510E-836D-010EE07A1549_d0e188596_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-09142C26-0AFA-510E-836D-010EE07A1549_d0e193658_href.png Binary file Symbian3/SDK/Source/GUID-09142C26-0AFA-510E-836D-010EE07A1549_d0e193658_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-09263C33-EE63-530C-A6B9-70806F0BC16D_d0e469457_href.png Binary file Symbian3/SDK/Source/GUID-09263C33-EE63-530C-A6B9-70806F0BC16D_d0e469457_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-09263C33-EE63-530C-A6B9-70806F0BC16D_d0e469621_href.png Binary file Symbian3/SDK/Source/GUID-09263C33-EE63-530C-A6B9-70806F0BC16D_d0e469621_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-092C18D4-A525-5562-9BF6-41435E400290.dita --- a/Symbian3/SDK/Source/GUID-092C18D4-A525-5562-9BF6-41435E400290.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-092C18D4-A525-5562-9BF6-41435E400290.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,41 +1,34 @@ - - - - - -LibpThread -Example - Using P.I.P.S OECORE -

This example application shows, using a P.I.P.S. (P.I.P.S. Is POSIX on -the Symbian platform) program, the use of the LibpThread library to demonstrate -simple multi-threading and synchronisation.

-

The purpose is to create a basic multithreading example showing the usage -of the LibpThread APIs. This example also shows how multi-threading is used -to achieve concurrency in tasks and sharing of resources.

-
Download

Click -on the following link to download the example: LibpThreadExample.zip

Click: browse to view the example code.

-
Description

The -following sections provide more information about the steps that the example -performs.

Thread Synchronisation

The example creates -three threads named ThreadOne, ThreadTwo and ThreadThree. The threads write -"One", "Two" and "Three" five times in a text file. The text file, located -in epoc32\winscw\c\newfile.txt, is used as a shared resource -for all three threads. A mutex is used to ensure that first ThreadOne writes -in the file, then ThreadTwo and then ThreadThree. If the mutex is not used -all the threads can simultaneously write in the file. This can be seen by -commenting out pthread_mutex_lock and pthread_mutex_unlock in -the code.

-
Related APIs

pthread_mutex_lock

pthread_mutex_unlock

pthread_join

pthread_mutex_t

-
Build

The Symbian build -process describes how to build this example application.

The -example builds an executable called LibpThreadExample.exe in -the standard locations.

To run the example, start LibpThreadExample.exe from -the file system or from your IDE. After launching the executable, depending -on the emulator you are using, you may need to navigate away from the application -launcher or shell screen to view the console.

+ + + + + +LibpThread Example - Using P.I.P.S OECORE +

This example application shows, using a P.I.P.S. (P.I.P.S. Is POSIX +on the Symbian platform) program, the use of the LibpThread library +to demonstrate simple multi-threading and synchronisation.

+

The purpose is to create a basic multithreading example showing +the usage of the LibpThread APIs. This example also shows how multi-threading +is used to achieve concurrency in tasks and sharing of resources.

+
Download

Click on the following link to download the example: LibpThreadExample.zip

Click: browse to view the example code.

+
Description

The following sections provide more information about the steps +that the example performs.

Thread Synchronisation

The example creates three threads named ThreadOne, +ThreadTwo and ThreadThree. The threads write "One", "Two" and "Three" +five times in a text file. The text file, located in epoc32\winscw\c\newfile.txt, is used as a shared resource for all three threads. A mutex is +used to ensure that first ThreadOne writes in the file, then ThreadTwo +and then ThreadThree. If the mutex is not used all the threads can +simultaneously write in the file. This can be seen by commenting out pthread_mutex_lock and pthread_mutex_unlock in the code.

+
Related +APIs

pthread_mutex_lock(pthread_mutex_t *)

pthread_mutex_unlock(pthread_mutex_t *)

pthread_join(pthread_t,void **)

pthread_mutex_t

+
Build

The Symbian +build process describes how to build this example application.

The example builds an executable called LibpThreadExample.exe in the standard locations.

To run the example, start LibpThreadExample.exe from the file system or from your +IDE. After launching the executable, depending on the emulator you +are using, you may need to navigate away from the application launcher +or shell screen to view the console.

\ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0991E536-97B2-4EAA-9448-A090BD073140_d0e71768_href.png Binary file Symbian3/SDK/Source/GUID-0991E536-97B2-4EAA-9448-A090BD073140_d0e71768_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0991E536-97B2-4EAA-9448-A090BD073140_d0e76917_href.png Binary file Symbian3/SDK/Source/GUID-0991E536-97B2-4EAA-9448-A090BD073140_d0e76917_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-09A58B23-68EA-58D7-BBC9-E7F4C4BF55D7_d0e354144_href.png Binary file Symbian3/SDK/Source/GUID-09A58B23-68EA-58D7-BBC9-E7F4C4BF55D7_d0e354144_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-09A58B23-68EA-58D7-BBC9-E7F4C4BF55D7_d0e360224_href.png Binary file Symbian3/SDK/Source/GUID-09A58B23-68EA-58D7-BBC9-E7F4C4BF55D7_d0e360224_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-09E44FE5-6BEE-49FF-8BBF-CBB3C066EE10.dita --- a/Symbian3/SDK/Source/GUID-09E44FE5-6BEE-49FF-8BBF-CBB3C066EE10.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-09E44FE5-6BEE-49FF-8BBF-CBB3C066EE10.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,64 +1,64 @@ - - - - - -Listening -for Channel ChangesThe sensor channel APIs enable you to receive notifications when -a sensor channel is added or removed. This ensures that you are informed of -changes to sensor channels whenever there is a change. For example, you can -receive notifications when a specific proximity sensor channel is added. -

Before listening -for channel changes, you must open -the sensor channel.

 - -Create a channel -listener implementation for the MSensrvChannelListener interface. -class ChannelListener:public MSensrvChannelListener - { - public: - void ChannelChangeDetected(const TSensrvChannelInfo &aDetectedChannel, TSensrvChannelChangeType aChangeType) - { - ... - //Implementation - } - void ChannelDetectionError(CSensrvChannelFinder aChannelFinder, TSensrvErrorSeverity aError) - { - ... - //Implementation - } - void GetChannelListenerInterfaceL(TUid aInterfaceUid, TAny *aInterface) - { - ... - //Implementation - } - }; - -Start channel listening -by passing an instance of the channel listener implementation, using CSensrvChannelFinder::SetChannelListenerL() function. -//Instance of the channel listener implementation -ChannelListener channelListener; -//Channel search parameters -TSensrvChannelInfo &searchParameters -... -CSensrvChannelFinder* finder = CSensrvChannelFinder::NewLC(); -... -channel->SetChannelListenerL(channelListener, searchParameters); -... -

This listens for channels that meet the supplied search parameters. -When a channel change occurs, a ChannelChangeDetected notification -is delivered through the MSensrvChannelListener interface.

 - -Stop channel listening -by passing a NULL parameter to the CSensrvChannelFinder::SetChannelListenerL() function. -ChannelListener channelListener=NULL; -finder->SetChannelListenerL(channelListener, searchParameters); - - + + + + + +Listening +for Channel ChangesThe sensor channel APIs enable you to receive notifications when +a sensor channel is added or removed. This ensures that you are informed of +changes to sensor channels whenever there is a change. For example, you can +receive notifications when a specific proximity sensor channel is added. +

Before listening +for channel changes, you must open +the sensor channel.

 + +Create a channel +listener implementation for the MSensrvChannelListener interface. +class ChannelListener:public MSensrvChannelListener + { + public: + void ChannelChangeDetected(const TSensrvChannelInfo &aDetectedChannel, TSensrvChannelChangeType aChangeType) + { + ... + //Implementation + } + void ChannelDetectionError(CSensrvChannelFinder aChannelFinder, TSensrvErrorSeverity aError) + { + ... + //Implementation + } + void GetChannelListenerInterfaceL(TUid aInterfaceUid, TAny *aInterface) + { + ... + //Implementation + } + }; + +Start channel listening +by passing an instance of the channel listener implementation, using CSensrvChannelFinder::SetChannelListenerL() function. +//Instance of the channel listener implementation +ChannelListener channelListener; +//Channel search parameters +TSensrvChannelInfo &searchParameters +... +CSensrvChannelFinder* finder = CSensrvChannelFinder::NewLC(); +... +channel->SetChannelListenerL(channelListener, searchParameters); +... +

This listens for channels that meet the supplied search parameters. +When a channel change occurs, a ChannelChangeDetected notification +is delivered through the MSensrvChannelListener interface.

 + +Stop channel listening +by passing a NULL parameter to the CSensrvChannelFinder::SetChannelListenerL() function. +ChannelListener channelListener=NULL; +finder->SetChannelListenerL(channelListener, searchParameters); + + \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0A13A931-016C-5325-97AF-2DE0B210DF2F.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-0A13A931-016C-5325-97AF-2DE0B210DF2F.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,200 @@ + + + + + +Window Server Client-Side Library OverviewThe Window Server keeps track of window sizes, positions, +visibility and validity (keeping window content up to date). It also +receives and distributes user input in the form of key presses and +pointer events. +

Note that much of the Window Server API is low-level and is encapsulated +in the UI Control Framework API.

+
Window +Server client-side library details

The following table +shows the DLLs that provides the functionality and the library to +which your code must link.

+ + + + +DLL +LIB +Short description + + + + +

ws32_nga.dll

+

ws32.lib

+

The Window Server client-side library for the ScreenPlay variant.

+ + +

ws32_nonnga.dll

+

ws32.lib

+

The Window Server client-side library for the non-ScreenPlay variant.

+ + + +

The details of the client-side API are very similar in +the two variants. There are some additional features in the ScreenPlay +variant for displaying surfaces.

+
Architecture

The Window Server is used by all applications that have a user +interface. The primary user input for these applications comes from +the keyboard and pointer, and their primary user-visible output is +to the screen. These input and output devices are shared between all +applications on the system. Each client thread opens a session to +the server, and issues requests for service.

+ Window Server +

The Window Server controls access by many client applications, +to the machine’s screen, keyboard and pointer.

+ +

The Window Server thread runs at a higher priority than +any application; only the kernel runs at a higher priority. Therefore, +all applications' requests for screen updates, and all handling of +machine events such as pointers and keys, are handled at higher priority +than any individual application.

Each client application runs +in its own thread. The Window Server presents an interface to client +applications such that they can run without direct interaction with +the other applications on the machine. Drawing is clipped to the visible +area of the application’s windows. Pointer events are only received +if they are related to the application’s windows. Similarly, keyboard +events are only given to an application whose window group has focus +or to one that has captured them. A client application may ignore +the majority of events relating to other applications. It won't even +be told about most of them.

Each client application communicates +with the Window Server using a Window Server session, or other object +created from the session. The application waits to receive events +by setting up one or more active objects. Events include user input +and requests that windows be redrawn. Applications may create systems +of windows and draw to them.

+
Window +server client-side API

The following diagram shows the +key classes in the Window Server client-side library. Below the diagram +we provide a summary of the key concepts.

+ Window Server client-side API classes + + + + + + +Concept +Description + + + + +

Session

+

A Window Server session allows an application to control +and interrogate its windows, the events it wishes to receive, and +all other window groups connected to the Window Server. A session +is encapsulated by RWsSession.

+ + +

Events

+

Applications function by waiting for events and handling +them. Common events are user input, and requests that windows be redrawn. +The Window Server session is used to request and obtain events. Most +events (such as key and point events) are encapsulated in TWsEvent.

A redraw event tells the application +what screen area needs redrawing. It is encapsulated in TWsRedrawEvent.

+ + +

Window group

+

A window group is special non-displayable type of window, +which can be considered as the root window of an application. Keyboard +events and focus are associated with it, and it can have a name, used +for such things as lists of running applications. A window group is +provided by RWindowGroup.

+ + +

Drawable windows

+

Drawable windows allow applications to draw to the screen. +They have operations to control size, position, visibility, scrolling, +z-order, and parent/child relationships. In a standard drawable window, +areas that become invalid (e.g. when an overlaying window is removed) +must be redrawn by the client application. It is provided by RWindow.

A backed-up drawable window's content +is stored by the Window Server, and redrawn by the server when it +becomes invalid. It is provided by RBackedUpWindow.

These window types are derived from a sequence of base +classes, RWindowTreeNode, RWindowBase, and RDrawableWindow.

+ + +

Graphics

+

Applications draw to drawable windows through a windows +graphics context provided by a windows graphics device. These implement +the abstract graphics context and graphics device interfaces respectively, +as defined in the Graphics API.

The windows graphics context +is provided by CWindowGc; the windows graphics +device by CWsScreenDevice. The bitmap class, CFbsBitmap, is extended for most efficient use with the +Window Server by CWsBitmap.

+ + +

Sprites and cursors

+

A sprite is an arbitrary-shaped bitmap that can be moved +without applications having to redraw the underlying screen. It has +one or more sprite members, each containing a bitmap image and a time +interval for that bitmap to be displayed. The sprite class is RWsSprite; the sprite member class is TSpriteMember.

A specialized sprite type is provided for pointer cursors, +which automatically track the position of a pointer. It is provided +by RWsPointerCursor.

Text cursors are handled +by the class CTextView. They can take the form +of a text or a line cursor.

+ + +

Animation client

+

Third-parties can write Window Server plug-in DLLs, as defined +in the Animation API, that perform animations. Providers of such animation +DLLs must also provide a client-side interface to allow applications +to control the animation. The base class for an animation client-side +interface is RAnim.

Clients must request +an animation DLL to be loaded before the animations provided by it +can be used. This is done through RAnimDll.

+ + +

Transparent windows

+

Transparent windows enable you to display semi-transparent +bitmaps on a window. The window must be an RWindow. Methods to create transparent windows can be found in the RWindow class.

+ + +

Surfaces

+

In ScreenPlay, applications (such as games and video) that +use a rendering API that can potentially benefit from hardware acceleration +(depending on hardware) can render directly to graphics surfaces. A surface is a hardware independent buffer for holding an image +or part of a scene. Surfaces are identified using a 128 bit surface +ID in a TSurfaceId class.

The Window Server +delegates the composition of surfaces to a composition engine which +has an adaptation part that enables device creators to take advantage +of graphics processing hardware if it is available. However, this +is largely transparent to application developers.

See External Surfaces for more information.

 + + +

Direct Screen Access (DSA)

+

Mainly used in the non-ScreenPlay variant, DSA enables applications +that require high frame rates (such as video and games) to bypass +the Window Server and write to the screen directly. This avoids client-server +communication and as a result is faster. However, some interaction +with the Window Server is needed to prevent the application from drawing +over other application's data.

In ScreenPlay, Symbian recommends +the use of external surfaces in preference to DSA. However, support for +DSA is maintained for backward compatibility reasons, although there +are some subtle changes in the support offered.

ScreenPlay does +not support the mixing of CWindowGc and DSA rendering +to the same window. When DSA rendering is present, any CWindowGc rendering to the same window is ignored. For example, an application +that uses CWindowGC rendering in one part of a window +and DSA rendering in another part will not work as expected in a ScreenPlay +environment. Similarly, CWindowGc rendering can no +longer be used to seed the DSA content as it could previously. However, CWindowGc rendering can be provided but it is not rendered +until the DSA rendering finishes. It is therefore best to avoid mixing +the rendering types in the same window.

 + + + +
+ +Window +Server Client-Side Library + \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0A61CB48-B8EA-5516-B24E-65898CDF2566.dita --- a/Symbian3/SDK/Source/GUID-0A61CB48-B8EA-5516-B24E-65898CDF2566.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-0A61CB48-B8EA-5516-B24E-65898CDF2566.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,629 +1,629 @@ - - - - - -How -to Configure Multithreaded C32 Serial Comms: TutorialThis page describes how a device manufacturer can configure -the grouping of CSYs into various threads.

The Serial Server -on Symbian platform supports the use of multiple threads in order to separate -the serial plug-in CSY modules. The first section provides a brief migration -guide, while the subsequent sections provide more detail on the specific parameters -and behaviour, and other advanced information.

- -
Introduction

The -Comms Configurator (c32start) uses a configuration Comms -Module Ini file (.CMI) to load Comms Provider Modules (CPMs) into the Rootserver -process. Each CMI file represents exactly one CPM loaded inside Rootserver. -CPMs are the name given to threads running inside the Rootserver process, -since they extend the thread concept by adding a wrapper of extra information -and functionality used to manage the threads.

The Comms Configurator -searches for the CMI files in the \private\101f7988 folders -by searching from Y: to A: and then Z:. The folder 101f7988 is -the secure area for the Comms Configurator process and its name derives from -the UID for the process - as specified by the requirements for Data Caging. If the files are found in the ROM (usually Z:) they are not then -copied to any other drive but only read in-place. Thus, a later configuration -of CMI files installed on another media/drive other than the ROM drive can -be used to override the original ROM configuration. The Configurator reads -these files only once during boot so any further changes will not take effect -until the next system boot.

-
Quick Migration Guide

This section provides a brief -description of how to migrate a configuration from the old single-threaded -C32 Serial Server to the new multi-threaded server. As there are numerous -potential configurations with the multi-threaded server, this migration guide -should be used as a first step to getting any old settings migrated over and -thus allowing the server to continue working after an upgrade of Symbian platform.

Once -migrated, the other sections in this article provide further useful information -regarding configuring CMI files for better performance in line with the requirements -of the particular device.

The quick migration involves two steps:

    -

  • apply any special configuration -used with the previous single-threaded C32 Serial Server to the new configuration -files supplied with the multi-threaded server

    • -

  • adjust the default set -of configuration files supplied with the multi-threaded server to suit the -particular serial plug-ins in use

    • -

These two steps are explained in more detail in the following sections.

Migrating settings

The original single-threaded Serial Server -was controlled by a single configuration file called (by default) c32.cmi, -located in \private\101f7988. A default version of this -file shipped with Symbian platform, although a device manufacturer could change -this file. The default version of this file was:

## Comms Configurator config file for the C32 server - -[Loader] -Name=CCommServer -FileName=c32.dll -ThreadFunctionOrdinal=87 -IsServer=1 -IsSticky=1 -Priority=EPriorityMuchMore -StackSize=8192 -ScaledStartupState=0x1085 -HeapOption=EDefaultHeap -MinHeapSize=256 -MaxHeapSize=524288 -SystemCritical=1

The multi-threaded C32 Serial Server (C32MT) -ships by default with five configuration files, since by default it supports -five different threads. These configuration files are:

\private\101f7988\c32.cmi -\private\101f7988\c32_first.cmi -\private\101f7988\c32_second.cmi -\private\101f7988\c32_third.cmi -\private\101f7988\c32_fourth.cmi

They are an extended version -of the original CMI file that shipped with the single-threaded C32. For example, -the first of these configuration files (c32.cmi) looks like:

# c32_main - Comms Configurator config file forming part of the Default C32 server configuration - -[Loader] -Name=C32_Main -FileName=c32.dll -ThreadFunctionOrdinal=87 -IsSticky=0 -IsServer=1 -Priority=EPriorityMuchMore -StackSize=16384 -ScaledStartupState=0x1085 -HeapOption=ENewHeap -MinHeapSize=256 -MaxHeapSize=524288 -SystemCritical=1 -Group=C32SerComms -OnDemand=0 -# Don't check heap if shutting down with EImmediate (KCF_ModuleImmediateNoCheck) -ControlFlags=4 -[IniData] -Role=Dealer -WorkerId=0

The first step in migrating is to ensure that any -unique configuration used with the old server is migrated across to the new -server. The particular parameters that should be considered in this procedure -are:

Priority -StackSize -ScaledStartupState -MinHeapSize -MaxHeapSize -SystemCritical

These parameters would need migrating to each -of the five new CMI files. The following notes relate to deliberate changes -to parameter values between the single and multi-threaded servers:

- -
HeapOption
-

The value of HeapOption is different between the old -and new files - this was made to aid in debugging the new multi-threaded server -by separating its memory from the rest of the comms system. It can be safely -changed back if desired.

- - -
IsSticky
-

The value of IsSticky has changed from 1 to 0. The IsSticky parameter -is normally unused in a production system for the Serial Server since the -server runs as a SystemCritical thread and thus cannot be -shutdown and, if it panics, the phone would reboot. The change was made to -facilitate testing, since in a test environment the Serial Server can be shutdown, -and to facilitate this the value of IsSticky must be set -to 0.

- - -
StackSize
-

The value of StackSize has increased from 8192 for -the single-threaded C32 to 16384 for C32MT. This change is due to the increased -stack usage of the multi-threaded C32. The value used - 16384 - was based -on the value proven to work with the similar ESock multi-threaded server. -It is possible that this value could be trimmed back towards 8192 to save -memory depending on the CSYs being used, since the ECUART CSY has been tested -to work with the multi-threaded C32 server with a stack size of just 8192, -and CSYs are usually much less memory-demanding than the protocols being used -in ESock.

- -

Assigning -CSY plug-ins to threads

The second part of migration to the new -multi-threaded serial server is to alter the default set of CMI files to match -the plug-ins (CSYs) in use and the desired operation. This step is not mandatory -since by default C32 will load all plug-ins correctly. But, it is worth considering -at this stage whether the default configuration needs some changes to match -the requirements of the device.

There are three broad configurations -available, which are defined by whether one or more CSYs are run in the main -thread for efficiency. The default configuration supplied with Symbian platform -runs all the CSYs outside the main thread since this ensures that no CSY can -deny service to the main server thread. It is expected that this configuration -will suit most situations, but for more information on the other configurations, -see the later section Typical -Thread Configuration Examples.

As mentioned earlier, the default -configuration uses five threads. The description for each of these is given -in the following table:

- - - -Worker ID -Summary -CMI file -Description - - - - -

0

 -

Main thread

-

c32.cmi

-

Runs the serial server to service client requests and pass on to -the CSYs, possibly in other threads. This thread is expected to be started -at device boot.

- - -

1

 -

USB thread

-

c32_first.cmi

-

Runs the USB CSY (ECACM). This is separated from all other threads -so that USB can run at high-speed uninterrupted. This thread is only started -when a client requires a USB connection.

- - -

2

 -

Baseband thread

-

c32_second.cmi

-

Runs the RS232 CSY (ECUART). This thread runs the ECUART plug-in -separately since ECUART is sometimes used to connect to the baseband. If a -different CSY is being used to connect to the baseband, it can be added to -this CMI file and ECUART either moved to another thread, or removed altogether. -As the baseband requires a high speed and fast response time, it is recommended -that the baseband CSY should be run in this thread to separate it from all -other CSYs. This thread is only started when a client requires the CSY.

- - -

3

 -

Bluetooth and IrDA thread

-

c32_third.cmi

-

Runs the Bluetooth and IrDA CSYs. These CSYs usually do not have -high requirements for throughput or response and thus can run together. This -thread is only started when one of its CSYs is required by a client.

- - -

4

 -

Default thread

-

c32_fourth.cmi

-

Runs any unlisted CSYs. If C32 is asked to load a CSY for which -no thread has been identified in a CMI file, then C32 will load the CSY in -this thread. This thread is only started when required.

- - - -

For a particular device, the above configuration may need to be -changed to address the requirements of the device. Typical adjustments to -consider are:

    -

  1. Change the CSY name -for Worker ID 2 to match the baseband CSY, and then either move ECUART to -Worker ID 3 or into its own new thread, or don't add it to any CMI file if -the device doesn't use the ECUART CSY

    2. -

  2. Add any extra low-performance -CSYs to Worker ID 3 so that they run together with Bluetooth and IrDA. Extra -CSYs could be run in a new separate thread but there is a memory cost for -each new thread added so this should be considered (8K is typically allocated -to a new thread, see Process, -thread, stack and memory useful information, and there is a limit to -the number of threads with their own heaps that can be started in the Root -Server).

    3. -

  3. For any extra high-performance -CSYs, create a new CMI file so that these can run separately from the other -CSYs. See Creating -A New CMI below

    4. -

  4. Prioritise important -threads (or reduce the priority of lesser threads). Candidates for increased -priority would be the Main, USB and Baseband threads. Care should be taken -when adjusting thread priorities since these affect the whole Comms system -- more guidance on setting thread priorities is available in the document How -To Assign Thread Priorities elsewhere in this developer library.

    5. -

When making these adjustments note that there is no cost involved -with mentioning CSYs that may never be loaded.

-
Overview of the C32 multi-threaded CMI files

C32 -Multithreading uses the same Dealer/Player terminology/concepts as Esock Multithreading. -The Dealer is the main C32 Comms Provider Module (CPM) which runs the -C32 server; a Player is a C32 CPM that only runs one or more CSYs and takes -the client requests from the Dealer module.

For example:

C32.cmi

[Loader] -Name=C32_Main -FileName=c32.dll -ThreadFunctionOrdinal=87 -IsServer=1 -IsSticky=0 -ThreadPriority=EPriorityMuchMore -StackSize=16384 -ScaledStartupState=0x1085 -HeapOption=ENewHeap -MinHeapSize=256 -MaxHeapSize=524288 -SystemCritical=1 -Group=C32SerComms -OnDemand=0 -[IniData] -Role=Dealer -WorkerId=0 -

The ThreadFunctionOrdinal identifier must -refer to the correct ordinal number of the main thread function for the DLL -file containing the Comms Provider Module. Due to binary compatibility considerations -this must be placed at ordinal "87" in the export table. A Comms Provider -Module/CPM is essentially a thread managed by the Comms Configurator.

The -description of each of the settings under [Loader] that are -specific to C32 and the settings under [IniData] are described -in further detail below.

As well as the C32 server thread, any other -CPMs that C32 needs must also have their own CMI file. One such example file -is:

C32_Default.cmi

[Loader] -Name=C32_Default -FileName=c32.dll -ThreadFunctionOrdinal=87 -IsServer=1 -IsSticky=0 -ThreadPriority=EPriorityMuchMore -StackSize=16384 -ScaledStartupState=0x3040 -HeapOption=EShareHeap -SharedHeapName=C32_Main -MinHeapSize=256 -MaxHeapSize=524288 -SystemCritical=0 -Group=C32SerComms -OnDemand=1 -Binding0=C32_Default:4,C32_Main:0,ECustom,42,42 -[IniData] -Role=Player -WorkerId=4 -CSYList=*
-
C32 CMI Parameter -Descriptions

This section gives details about the parameters available -in the CMI file relevant to C32. The CMI file has two sections - a [Loader] section -and an [IniData] section. The [Loader] section -parameters are defined for the CPM, and the ones relevant to C32MT are detailed -below. The [IniData] section contains parameters specific -to a CPM. If further information on the format of the CMI file itself or the [Loader] parameters -is required, please refer to the document Comms Process Starter/Config -Design Document section 3.1.1. This document is located in this -developer library as well as in the comms-infras\rootserver\Documentation folder.

A note on CMI processing

No mechanism is provided to change -CMI files at run-time, since they are designed to be configured for inclusion -in a ROM and then not changed through the life of a phone product. After-market -changing of the configuration is supported via the installation of CMI files -in a non-ROM folder which then take precedence over the ROM files when the -device is next rebooted. Thus, any CMI configuration file problems should -become apparent during the early stages of phone development.

A bad -configuration will panic in debug builds to signal the user to change/edit -the .CMI files in order to make a desired and correct configuration. -In urel builds a bad configuration may survive (unless the .CMI files -are very malformed) but at a cost that all CSYs are loaded in the Dealer Thread -(Workerid=0) making it in effect a single threaded system.

The -panic numbers used by the C32 Serial Server for internal server faults are -defined in the enum TECommFault.

CMI [Loader] Parameters relevant to C32

OnDemand

This indicates whether the CPM is started as part -of the Configurator’s CPM load on boot ("0"), or whether the CPM should only -be loaded via an explicit request to Configurator ("1"). The default value -is "0". The OnDemand parameter for the main thread can only -be "0" if mentioned. For Player modules the setting can be either "0" or "1". -If a Player thread is not marked as OnDemand=1 then it will -load during the boot sequence. If the main thread (Workerid=0) -is marked as OnDemand=1, then this is a configuration error -and C32 can never be started (although in theory this is possible - see Footnote -1 below). Players marked to load at boot up do not load any CSYs implicitly -as part of the boot load.

All Player modules for C32 must be marked -with OnDemand=1 since the C32 Dealer must instigate a Player -load. If a Player thread is not marked as OnDemand=0 then -it will load during the boot sequence.

Group

All CMI files for C32 must map to the same Group ID. -The actual Group ID for the C32 group is C32SerComms. CMI -files for C32 Players that do not have a Group member will never be loaded -by C32 (assuming OnDemand=1 is set for the Player threads).

If -there is no group defined in any CMI files and therefore no [IniData] is -processed for any of them, then C32 will simply assign all CSYs to load into -the Dealer thread.

Name

This parameter is used to -identify the CPM to the Configurator and is used to name the thread for the -kernel. It is stored by C32 for all CMI files in the C32SerComms group for -use when requesting Configurator to load or unload a CPM. As this value is -easily configurable and is used to name the thread to the kernel, software -should not rely on the name of any C32 thread being any particular string. -Prior to the multithreaded C32 (C32MT), the C32 thread was conventionally -known as CCommServer. However, with C32 now potentially having -a multiplicity of threads, other schemes are probable such as C32_Main, -C32_USB and C32_BaseBand or C32_BT-IR and C32_Default

The -Dealer and all Players in the C32 group can have any name since C32 will find -them as part of the same group (see Group above). The names in the C32 group -should all be unique – if the same name is found twice or more C32 will panic -in debug builds but attempt to recover in release builds by only processing -the first that it finds. This is still a highly risky situation since if C32 -needs to start that module in order to accommodate a CSY, Configurator may -load the wrong CMI file when creating the new thread.

When introducing -new CMIs, care should be taken to change the BindingN line -in CMI to reflect the new modulename and WorkerId.

CMI [IniData] Parameters relevant to C32

In the case where -C32 has a CMI file that loads the C32 binary during boot up, but the CMI file -does not have an [IniData] section, C32 will assume that -this CMI is for the main thread and that the CMI is a pre-C32MT file. However, -for C32MT, this is an undesired configuration and should be rectified. Old -versions of c32.cmi are only kept in the source distribution -to support backwards compatibility and should not be used in a system which -has C32MT present. In such backwards-compatible modes of C32MT, the main thread -will host a Player in case no other CMI files are present.

Role

The -value for this parameter should be either Dealer or Player. -Only one Dealer can exist in a C32 system, but there can -be any number of Player s. If there are two or more Dealer CMI -files, the ScaledStartupState determines which Dealer CMI -starts first. If both the CMIs have the same ScaledStartupState, -then they are loaded in alphabetical order. Configurator is guaranteed to -start a C: CMI file before the Z: one. If they both have the same module name -then it is safe since Rootserver will refuse the load of the second module -with the same name failing with KErrAlreadyExists. However, -if the module name is different Rootserver will load them both and C32 will -detect that an instance of itself is already running and exit the second thread. -Only the IniData for the CMI file that was used to start the Dealer will be -processed, with all other Dealer CMI files being ignored. If the main thread -is to include a co-resident Player, the iniData should include the CSYList key-value -pair discussed below.

WorkerId

The ID number of this -thread inside the C32 system. The Id numbers should be a positive integer -or "0" in the case of the main thread (In case CMI file of WorkerId=0 has -anything else than Dealer as role, it is overridden with Role=Dealer, logging -a warning). The system expects subsequent ID numbers to be incremented up -from the main thread's ID. Where a CMI file in the C32 group does not have -a WorkerId, it is a bad configuration and will panic in debug builds. Allocating -the next higher number is not possible as this Player needs to be bound with -the Dealer using the BindingN line which accepts WorkerId parameter. -In case of duplicate WorkerId, a panic occurs as the second -module cannot be bound to the Dealer as the binding for the main thread has -already been done.

CSYList

A comma-separated list -of the filenames of the CSYs this thread will own. All CMIs in the C32 group -must have a CSY list, except for the Dealer which can optionally have a CSYList. -A Player with no CSYList represents a bad configuration as -a Player’s sole purpose is to load CSYs. Such a Player with no CSY list will -never be started by C32. A Dealer with no CSY list will act purely as a Dealer. -A Dealer with a CSY list becomes a Dealer with a co-resident Player inside -its thread. CSYList param determines if the CPM will host -a Player or not.

If a CSY appears in more than one CMI file, then -the CSY will be assigned to one thread, but not necessarily that with the -least number of CSYs in it.

The comma-separated list should not have -any spaces or other white space in it, and each CSY name must be an alphanumeric -string. The CSY name is not case sensitive, and should not have the .CSY extension. -C32 does not check whether the supplied CSY names actually exist as binaries, -since it only refers to the list when a client asks to load a particular CSY.

If -an asterix ("*") appears as a CSY name in the CSY list, this is inferred by -C32 as meaning that this thread is also to be used to load any CSYs not mentioned -in any CMI file, and is known as the default thread. If two different -CMI files in the C32 group have the wildcard then only one CMI file will be -marked as being the host for unknown CSYs – it is not defined as to which -one. If no CMI file has a wildcard then C32 will assign the wildcard to an -unused Player thread so that all unlisted CSYs are isolated into their own -thread. This is overridden if the only CMI file is for the Dealer, in which -case the Dealer will load all CSYs into its own co-resident Player, since -the Dealer cannot request the Configurator to start a module for which there -is not an associated CMI file.

-
Important Notes

Field -names in the [IniData] are case sensitive, but fields values -are not.

The BindingN line is responsible for binding -the Player CPM with Dealer. If you leave out the BindingN line -from the CMI then the new Player will in essence remain as an island and no -requests for loading or any subsequent operation can be passed to it from -Dealer. This will not result in a panic.

The C32_Main.cmi doesn’t -have a BindingN line since it is a Dealer and thus does not -need to bind to another Dealer.

-
Creating A -New CMI

To create a new CMI file, copy an existing Player CMI file, -rename it and change the necessary parameters as detailed below. The examples -below assume that the base CMI used was the supplied c32_fourth.cmi. -The following parameters need to be changed to make a valid configuration -file:

In [Loader] section are:

    -

  • Name - This -is the module name of CPM.

    • -

  • BindingN - BindingN -line is changed to reflect the new module name and WorkerId value

    • -

In [IniData] section:

    -

  • WorkerId - This -value is numeric and must be unique

    • -

  • CSYList - Contains -CSYs which you want to load in this new CPM, separated by commas, no white -spaces allowed.

    • -

Since the additional CMI being added is a Player, -the Role field remains the same and it can not be changed to Dealer as -the CPM with WorkerId=0 is the one and only Dealer in the -C32MT.

[Loader] -# Change the Name value to your CSY name -Name=C32_Default //

Change the Name value -to the name of your CSY, e.g.

Name=C32_MyCSYs FileName=c32.dll -ThreadFunctionOrdinal=87 -ThreadPriority=EPriorityMuchMore -StackSize=16384 -ScaledStartupState=0x3040 -HeapOption=ENewHeap -MinHeapSize=256 -MaxHeapSize=524288 -SystemCritical=1 -Group=C32SerComms -OnDemand=1

Change the BindingN line to refer to your CSY, for -example change from

# Change the BindingN line to refer to your CSYs -Binding0=C32_Default:4,C32_Main:0,ECustom,42,42

to

Binding0=C32_MyCSYs:5,C32_Main:0,ECustom,42,42

And -in the [IniData] section:

[IniData] -# Make sure Role is set to "Player" -Role=Player

Change the WorkerId, for example from WorkerId=4 to

WorkerId=5

and -change the CSYList to specify your CSYs, e.g. change "CSYList=XX,YY,zz" -to

CSYList=MyCSY1,MyCSY2
-
Typical Thread -Configuration Examples

This section describes the three broad configurations -for threading available for the C32 Serial Server. Each has different potential -effects on the performance of C32.

The three broad configurations -available, with a summary of their costs and benefits, are detailed in the -following table:

- - - - -Configuration -Advantages -Disadvantages - - - - -

1

 -

Run all CSYs outside the main thread [Default supplied CMI set]

-
    -

  • Some CSYs can be promoted -ahead of others using thread priorities

    • -

  • Main thread cannot ever -stall when any CSY stalls

    • -

  • Stackable CSYs are possible: -a CSY can connect to another CSY through the C32 API as long as both are in -different threads

    • -
 -
    -

  • Operations on CSYs are -a bit slower due to increased overhead of inter-thread communication

    • -

  • Complex to debug

    • -
 - - -

2

 -

Run some CSYs in the main thread

-
    -

  • CSYs in the main thread -avoid the overhead of inter-thread communication

    • -

  • Some CSYs can be promoted -ahead of others using thread priorities

    • -

  • Main thread cannot stall -when a CSY in a separate thread stalls

    • -

  • Stackable CSYs are possible: -a CSY can connect to another CSY through the C32 API as long as both are in -different threads

    • -
 -
    -

  • If any CSY in the main -thread stalls, the whole server stalls

    • -

  • No means to prioritise -one CSY ahead of others (without changing the CSY code)

    • -

  • Operations on CSYs outside -the main thread are a bit slower due to the increased overhead of inter-thread -communication

    • -

  • Complex to debug

    • -
 - - -

3

 -

Run all CSYs in the main thread [Default configuration when any -CMI files are corrupt]

-
    -

  • Simplest to debug since -no inter-thread communication

    • -

  • All CSYs avoid the overhead -of inter-thread communication

    • -
 -
    -

  • If any CSY stalls, the -whole server stalls

    • -

  • No means to prioritise -one CSY ahead of others (without changing the CSY code)

    • -

  • No stackable CSYs are -possible

    • -
 - - - -

The default set of CMI files supplied with Symbian platform -is based on the first broad configuration since it was decided that the small -cost of running all CSYs outside the main thread is justified by the increased -reliability to the whole C32 system of ensuring no CSY can deny service to -the C32 server. Each of these configurations is explained in more detail below.

- Figure 1 - No CSYs in main thread: RootServer with 4 -C32 CPMs - -

Referring to Figure 1, the following can be observed:

    -

  1. The Main Thread has WorkerId=0, -Role as Dealer and is configured to load no CSY

    2. -

  2. The Player Thread 1 -has WorkerId=1, Role as Player and is configured to load -ECACM CSY

    3. -

  3. The Player Thread 2 -has WorkerId=2, Role as Player and is configured to load -ECUART CSY

    4. -

  4. The Player Thread 3 -has WorkerId=3, Role as Player and is configured to load unlisted csy. -What unlisted csy means here is that apart from ECACM and ECUART, if any new -csy is to be loaded, it will get loaded in this thread.

    5. -

The [IniData] section for the above CPMs would look like:

[IniData] -Role=Dealer -WorkerId=0 - [IniData] -Role=Player -WorkerId=1 -CSYList=ECACM - [IniData] -Role=Player -WorkerId=2 -CSYList=ECUART - [IniData] -Role=Player -WorkerId=3 -CSYList=* - - Figure 2 - All CSYs in main thread: RootServer with single -C32 CPM - -

In Figure 2 the CPM loads any CSYs, and so should contain CSYList tag -in the IniData section.

The Main Thread has WorkerId=0, -Role as Dealer and is configured to load any CSY. In this configuration -since it is a single thread, all the CSYs will be loaded in the same thread.

The [IniData] section -for above CPM would look like:

[IniData] -Role=Dealer -WorkerId=0 -CSYList=* - - Figure 3 - Some CSYs in main thread: RootServer with -3 CPMs - -

From Figure 3, the following can be observed.

    -

  1. The Main Thread has WorkerId=0, -Role as Dealer and is configured to load HSDPA csy

    2. -

  2. The Player Thread 1 -has WorkerId=1, Role as Player and is configured to load -ECACM csy

    3. -

  3. The Player Thread 2 -has WorkerId=2, Role as Player and is configured to load -an unlisted csy

    4. -

The IniData section for above CPMs would look like:

[IniData] -Role=Dealer -WorkerId=0 -CSYList=HSDPA - [IniData] -Role=Player -WorkerId=1 -CSYList=ECACM [IniData] -Role=Player -WorkerId=2 -CSYList=*
-
Footnotes
- -
Footnote 1
-

In theory the C32 main thread (Workerid=0) could be -marked as on-demand and started by the first client to connect to it. This -might be useful since it would save device boot time for a device that does -not need serial comms as part of boot up. The process would require the client -to connect to Configurator and load the C32 main module explicitly. For this -to work the main Module’s name would have to be fixed (the reference system -uses “C32_Main ”) so that the client can identify it to Configurator -- which is not a big problem, and the client would need the appropriate capabilities -(also not a big problem as the client could well be inside Rootserver too). -The other problem is that making it on-demand requires that it is still started -by a priviledged process before any unpriviledged process attempts to use -the C32 API (since this will fail unless no CSYs require any capabilities). -Therefore, for on-demand main thread-loading to work, intimate details about -the specific configuration of CSYs for a device and their potential clients -would be needed.

- -
+ + + + + +How +to Configure Multithreaded C32 Serial Comms: TutorialThis page describes how a device manufacturer can configure +the grouping of CSYs into various threads.

The Serial Server +on Symbian platform supports the use of multiple threads in order to separate +the serial plug-in CSY modules. The first section provides a brief migration +guide, while the subsequent sections provide more detail on the specific parameters +and behaviour, and other advanced information.

+ +
Introduction

The +Comms Configurator (c32start) uses a configuration Comms +Module Ini file (.CMI) to load Comms Provider Modules (CPMs) into the Rootserver +process. Each CMI file represents exactly one CPM loaded inside Rootserver. +CPMs are the name given to threads running inside the Rootserver process, +since they extend the thread concept by adding a wrapper of extra information +and functionality used to manage the threads.

The Comms Configurator +searches for the CMI files in the \private\101f7988 folders +by searching from Y: to A: and then Z:. The folder 101f7988 is +the secure area for the Comms Configurator process and its name derives from +the UID for the process - as specified by the requirements for Data Caging. If the files are found in the ROM (usually Z:) they are not then +copied to any other drive but only read in-place. Thus, a later configuration +of CMI files installed on another media/drive other than the ROM drive can +be used to override the original ROM configuration. The Configurator reads +these files only once during boot so any further changes will not take effect +until the next system boot.

+
Quick Migration Guide

This section provides a brief +description of how to migrate a configuration from the old single-threaded +C32 Serial Server to the new multi-threaded server. As there are numerous +potential configurations with the multi-threaded server, this migration guide +should be used as a first step to getting any old settings migrated over and +thus allowing the server to continue working after an upgrade of Symbian platform.

Once +migrated, the other sections in this article provide further useful information +regarding configuring CMI files for better performance in line with the requirements +of the particular device.

The quick migration involves two steps:

    +

  • apply any special configuration +used with the previous single-threaded C32 Serial Server to the new configuration +files supplied with the multi-threaded server

    • +

  • adjust the default set +of configuration files supplied with the multi-threaded server to suit the +particular serial plug-ins in use

    • +

These two steps are explained in more detail in the following sections.

Migrating settings

The original single-threaded Serial Server +was controlled by a single configuration file called (by default) c32.cmi, +located in \private\101f7988. A default version of this +file shipped with Symbian platform, although a device manufacturer could change +this file. The default version of this file was:

## Comms Configurator config file for the C32 server + +[Loader] +Name=CCommServer +FileName=c32.dll +ThreadFunctionOrdinal=87 +IsServer=1 +IsSticky=1 +Priority=EPriorityMuchMore +StackSize=8192 +ScaledStartupState=0x1085 +HeapOption=EDefaultHeap +MinHeapSize=256 +MaxHeapSize=524288 +SystemCritical=1

The multi-threaded C32 Serial Server (C32MT) +ships by default with five configuration files, since by default it supports +five different threads. These configuration files are:

\private\101f7988\c32.cmi +\private\101f7988\c32_first.cmi +\private\101f7988\c32_second.cmi +\private\101f7988\c32_third.cmi +\private\101f7988\c32_fourth.cmi

They are an extended version +of the original CMI file that shipped with the single-threaded C32. For example, +the first of these configuration files (c32.cmi) looks like:

# c32_main - Comms Configurator config file forming part of the Default C32 server configuration + +[Loader] +Name=C32_Main +FileName=c32.dll +ThreadFunctionOrdinal=87 +IsSticky=0 +IsServer=1 +Priority=EPriorityMuchMore +StackSize=16384 +ScaledStartupState=0x1085 +HeapOption=ENewHeap +MinHeapSize=256 +MaxHeapSize=524288 +SystemCritical=1 +Group=C32SerComms +OnDemand=0 +# Don't check heap if shutting down with EImmediate (KCF_ModuleImmediateNoCheck) +ControlFlags=4 +[IniData] +Role=Dealer +WorkerId=0

The first step in migrating is to ensure that any +unique configuration used with the old server is migrated across to the new +server. The particular parameters that should be considered in this procedure +are:

Priority +StackSize +ScaledStartupState +MinHeapSize +MaxHeapSize +SystemCritical

These parameters would need migrating to each +of the five new CMI files. The following notes relate to deliberate changes +to parameter values between the single and multi-threaded servers:

+ +
HeapOption
+

The value of HeapOption is different between the old +and new files - this was made to aid in debugging the new multi-threaded server +by separating its memory from the rest of the comms system. It can be safely +changed back if desired.

+ + +
IsSticky
+

The value of IsSticky has changed from 1 to 0. The IsSticky parameter +is normally unused in a production system for the Serial Server since the +server runs as a SystemCritical thread and thus cannot be +shutdown and, if it panics, the phone would reboot. The change was made to +facilitate testing, since in a test environment the Serial Server can be shutdown, +and to facilitate this the value of IsSticky must be set +to 0.

+ + +
StackSize
+

The value of StackSize has increased from 8192 for +the single-threaded C32 to 16384 for C32MT. This change is due to the increased +stack usage of the multi-threaded C32. The value used - 16384 - was based +on the value proven to work with the similar ESock multi-threaded server. +It is possible that this value could be trimmed back towards 8192 to save +memory depending on the CSYs being used, since the ECUART CSY has been tested +to work with the multi-threaded C32 server with a stack size of just 8192, +and CSYs are usually much less memory-demanding than the protocols being used +in ESock.

+ +

Assigning +CSY plug-ins to threads

The second part of migration to the new +multi-threaded serial server is to alter the default set of CMI files to match +the plug-ins (CSYs) in use and the desired operation. This step is not mandatory +since by default C32 will load all plug-ins correctly. But, it is worth considering +at this stage whether the default configuration needs some changes to match +the requirements of the device.

There are three broad configurations +available, which are defined by whether one or more CSYs are run in the main +thread for efficiency. The default configuration supplied with Symbian platform +runs all the CSYs outside the main thread since this ensures that no CSY can +deny service to the main server thread. It is expected that this configuration +will suit most situations, but for more information on the other configurations, +see the later section Typical +Thread Configuration Examples.

As mentioned earlier, the default +configuration uses five threads. The description for each of these is given +in the following table:

+ + + +Worker ID +Summary +CMI file +Description + + + + +

0

 +

Main thread

+

c32.cmi

+

Runs the serial server to service client requests and pass on to +the CSYs, possibly in other threads. This thread is expected to be started +at device boot.

+ + +

1

 +

USB thread

+

c32_first.cmi

+

Runs the USB CSY (ECACM). This is separated from all other threads +so that USB can run at high-speed uninterrupted. This thread is only started +when a client requires a USB connection.

+ + +

2

 +

Baseband thread

+

c32_second.cmi

+

Runs the RS232 CSY (ECUART). This thread runs the ECUART plug-in +separately since ECUART is sometimes used to connect to the baseband. If a +different CSY is being used to connect to the baseband, it can be added to +this CMI file and ECUART either moved to another thread, or removed altogether. +As the baseband requires a high speed and fast response time, it is recommended +that the baseband CSY should be run in this thread to separate it from all +other CSYs. This thread is only started when a client requires the CSY.

+ + +

3

 +

Bluetooth and IrDA thread

+

c32_third.cmi

+

Runs the Bluetooth and IrDA CSYs. These CSYs usually do not have +high requirements for throughput or response and thus can run together. This +thread is only started when one of its CSYs is required by a client.

+ + +

4

 +

Default thread

+

c32_fourth.cmi

+

Runs any unlisted CSYs. If C32 is asked to load a CSY for which +no thread has been identified in a CMI file, then C32 will load the CSY in +this thread. This thread is only started when required.

+ + + +

For a particular device, the above configuration may need to be +changed to address the requirements of the device. Typical adjustments to +consider are:

    +

  1. Change the CSY name +for Worker ID 2 to match the baseband CSY, and then either move ECUART to +Worker ID 3 or into its own new thread, or don't add it to any CMI file if +the device doesn't use the ECUART CSY

    2. +

  2. Add any extra low-performance +CSYs to Worker ID 3 so that they run together with Bluetooth and IrDA. Extra +CSYs could be run in a new separate thread but there is a memory cost for +each new thread added so this should be considered (8K is typically allocated +to a new thread, see Process, +thread, stack and memory useful information, and there is a limit to +the number of threads with their own heaps that can be started in the Root +Server).

    3. +

  3. For any extra high-performance +CSYs, create a new CMI file so that these can run separately from the other +CSYs. See Creating +A New CMI below

    4. +

  4. Prioritise important +threads (or reduce the priority of lesser threads). Candidates for increased +priority would be the Main, USB and Baseband threads. Care should be taken +when adjusting thread priorities since these affect the whole Comms system +- more guidance on setting thread priorities is available in the document How +To Assign Thread Priorities elsewhere in this developer library.

    5. +

When making these adjustments note that there is no cost involved +with mentioning CSYs that may never be loaded.

+
Overview of the C32 multi-threaded CMI files

C32 +Multithreading uses the same Dealer/Player terminology/concepts as Esock Multithreading. +The Dealer is the main C32 Comms Provider Module (CPM) which runs the +C32 server; a Player is a C32 CPM that only runs one or more CSYs and takes +the client requests from the Dealer module.

For example:

C32.cmi

[Loader] +Name=C32_Main +FileName=c32.dll +ThreadFunctionOrdinal=87 +IsServer=1 +IsSticky=0 +ThreadPriority=EPriorityMuchMore +StackSize=16384 +ScaledStartupState=0x1085 +HeapOption=ENewHeap +MinHeapSize=256 +MaxHeapSize=524288 +SystemCritical=1 +Group=C32SerComms +OnDemand=0 +[IniData] +Role=Dealer +WorkerId=0 +

The ThreadFunctionOrdinal identifier must +refer to the correct ordinal number of the main thread function for the DLL +file containing the Comms Provider Module. Due to binary compatibility considerations +this must be placed at ordinal "87" in the export table. A Comms Provider +Module/CPM is essentially a thread managed by the Comms Configurator.

The +description of each of the settings under [Loader] that are +specific to C32 and the settings under [IniData] are described +in further detail below.

As well as the C32 server thread, any other +CPMs that C32 needs must also have their own CMI file. One such example file +is:

C32_Default.cmi

[Loader] +Name=C32_Default +FileName=c32.dll +ThreadFunctionOrdinal=87 +IsServer=1 +IsSticky=0 +ThreadPriority=EPriorityMuchMore +StackSize=16384 +ScaledStartupState=0x3040 +HeapOption=EShareHeap +SharedHeapName=C32_Main +MinHeapSize=256 +MaxHeapSize=524288 +SystemCritical=0 +Group=C32SerComms +OnDemand=1 +Binding0=C32_Default:4,C32_Main:0,ECustom,42,42 +[IniData] +Role=Player +WorkerId=4 +CSYList=*
+
C32 CMI Parameter +Descriptions

This section gives details about the parameters available +in the CMI file relevant to C32. The CMI file has two sections - a [Loader] section +and an [IniData] section. The [Loader] section +parameters are defined for the CPM, and the ones relevant to C32MT are detailed +below. The [IniData] section contains parameters specific +to a CPM. If further information on the format of the CMI file itself or the [Loader] parameters +is required, please refer to the document Comms Process Starter/Config +Design Document section 3.1.1. This document is located in this +developer library as well as in the comms-infras\rootserver\Documentation folder.

A note on CMI processing

No mechanism is provided to change +CMI files at run-time, since they are designed to be configured for inclusion +in a ROM and then not changed through the life of a phone product. After-market +changing of the configuration is supported via the installation of CMI files +in a non-ROM folder which then take precedence over the ROM files when the +device is next rebooted. Thus, any CMI configuration file problems should +become apparent during the early stages of phone development.

A bad +configuration will panic in debug builds to signal the user to change/edit +the .CMI files in order to make a desired and correct configuration. +In urel builds a bad configuration may survive (unless the .CMI files +are very malformed) but at a cost that all CSYs are loaded in the Dealer Thread +(Workerid=0) making it in effect a single threaded system.

The +panic numbers used by the C32 Serial Server for internal server faults are +defined in the enum TECommFault.

CMI [Loader] Parameters relevant to C32

OnDemand

This indicates whether the CPM is started as part +of the Configurator’s CPM load on boot ("0"), or whether the CPM should only +be loaded via an explicit request to Configurator ("1"). The default value +is "0". The OnDemand parameter for the main thread can only +be "0" if mentioned. For Player modules the setting can be either "0" or "1". +If a Player thread is not marked as OnDemand=1 then it will +load during the boot sequence. If the main thread (Workerid=0) +is marked as OnDemand=1, then this is a configuration error +and C32 can never be started (although in theory this is possible - see Footnote +1 below). Players marked to load at boot up do not load any CSYs implicitly +as part of the boot load.

All Player modules for C32 must be marked +with OnDemand=1 since the C32 Dealer must instigate a Player +load. If a Player thread is not marked as OnDemand=0 then +it will load during the boot sequence.

Group

All CMI files for C32 must map to the same Group ID. +The actual Group ID for the C32 group is C32SerComms. CMI +files for C32 Players that do not have a Group member will never be loaded +by C32 (assuming OnDemand=1 is set for the Player threads).

If +there is no group defined in any CMI files and therefore no [IniData] is +processed for any of them, then C32 will simply assign all CSYs to load into +the Dealer thread.

Name

This parameter is used to +identify the CPM to the Configurator and is used to name the thread for the +kernel. It is stored by C32 for all CMI files in the C32SerComms group for +use when requesting Configurator to load or unload a CPM. As this value is +easily configurable and is used to name the thread to the kernel, software +should not rely on the name of any C32 thread being any particular string. +Prior to the multithreaded C32 (C32MT), the C32 thread was conventionally +known as CCommServer. However, with C32 now potentially having +a multiplicity of threads, other schemes are probable such as C32_Main, +C32_USB and C32_BaseBand or C32_BT-IR and C32_Default

The +Dealer and all Players in the C32 group can have any name since C32 will find +them as part of the same group (see Group above). The names in the C32 group +should all be unique – if the same name is found twice or more C32 will panic +in debug builds but attempt to recover in release builds by only processing +the first that it finds. This is still a highly risky situation since if C32 +needs to start that module in order to accommodate a CSY, Configurator may +load the wrong CMI file when creating the new thread.

When introducing +new CMIs, care should be taken to change the BindingN line +in CMI to reflect the new modulename and WorkerId.

CMI [IniData] Parameters relevant to C32

In the case where +C32 has a CMI file that loads the C32 binary during boot up, but the CMI file +does not have an [IniData] section, C32 will assume that +this CMI is for the main thread and that the CMI is a pre-C32MT file. However, +for C32MT, this is an undesired configuration and should be rectified. Old +versions of c32.cmi are only kept in the source distribution +to support backwards compatibility and should not be used in a system which +has C32MT present. In such backwards-compatible modes of C32MT, the main thread +will host a Player in case no other CMI files are present.

Role

The +value for this parameter should be either Dealer or Player. +Only one Dealer can exist in a C32 system, but there can +be any number of Player s. If there are two or more Dealer CMI +files, the ScaledStartupState determines which Dealer CMI +starts first. If both the CMIs have the same ScaledStartupState, +then they are loaded in alphabetical order. Configurator is guaranteed to +start a C: CMI file before the Z: one. If they both have the same module name +then it is safe since Rootserver will refuse the load of the second module +with the same name failing with KErrAlreadyExists. However, +if the module name is different Rootserver will load them both and C32 will +detect that an instance of itself is already running and exit the second thread. +Only the IniData for the CMI file that was used to start the Dealer will be +processed, with all other Dealer CMI files being ignored. If the main thread +is to include a co-resident Player, the iniData should include the CSYList key-value +pair discussed below.

WorkerId

The ID number of this +thread inside the C32 system. The Id numbers should be a positive integer +or "0" in the case of the main thread (In case CMI file of WorkerId=0 has +anything else than Dealer as role, it is overridden with Role=Dealer, logging +a warning). The system expects subsequent ID numbers to be incremented up +from the main thread's ID. Where a CMI file in the C32 group does not have +a WorkerId, it is a bad configuration and will panic in debug builds. Allocating +the next higher number is not possible as this Player needs to be bound with +the Dealer using the BindingN line which accepts WorkerId parameter. +In case of duplicate WorkerId, a panic occurs as the second +module cannot be bound to the Dealer as the binding for the main thread has +already been done.

CSYList

A comma-separated list +of the filenames of the CSYs this thread will own. All CMIs in the C32 group +must have a CSY list, except for the Dealer which can optionally have a CSYList. +A Player with no CSYList represents a bad configuration as +a Player’s sole purpose is to load CSYs. Such a Player with no CSY list will +never be started by C32. A Dealer with no CSY list will act purely as a Dealer. +A Dealer with a CSY list becomes a Dealer with a co-resident Player inside +its thread. CSYList param determines if the CPM will host +a Player or not.

If a CSY appears in more than one CMI file, then +the CSY will be assigned to one thread, but not necessarily that with the +least number of CSYs in it.

The comma-separated list should not have +any spaces or other white space in it, and each CSY name must be an alphanumeric +string. The CSY name is not case sensitive, and should not have the .CSY extension. +C32 does not check whether the supplied CSY names actually exist as binaries, +since it only refers to the list when a client asks to load a particular CSY.

If +an asterix ("*") appears as a CSY name in the CSY list, this is inferred by +C32 as meaning that this thread is also to be used to load any CSYs not mentioned +in any CMI file, and is known as the default thread. If two different +CMI files in the C32 group have the wildcard then only one CMI file will be +marked as being the host for unknown CSYs – it is not defined as to which +one. If no CMI file has a wildcard then C32 will assign the wildcard to an +unused Player thread so that all unlisted CSYs are isolated into their own +thread. This is overridden if the only CMI file is for the Dealer, in which +case the Dealer will load all CSYs into its own co-resident Player, since +the Dealer cannot request the Configurator to start a module for which there +is not an associated CMI file.

+
Important Notes

Field +names in the [IniData] are case sensitive, but fields values +are not.

The BindingN line is responsible for binding +the Player CPM with Dealer. If you leave out the BindingN line +from the CMI then the new Player will in essence remain as an island and no +requests for loading or any subsequent operation can be passed to it from +Dealer. This will not result in a panic.

The C32_Main.cmi doesn’t +have a BindingN line since it is a Dealer and thus does not +need to bind to another Dealer.

+
Creating A +New CMI

To create a new CMI file, copy an existing Player CMI file, +rename it and change the necessary parameters as detailed below. The examples +below assume that the base CMI used was the supplied c32_fourth.cmi. +The following parameters need to be changed to make a valid configuration +file:

In [Loader] section are:

    +

  • Name - This +is the module name of CPM.

    • +

  • BindingN - BindingN +line is changed to reflect the new module name and WorkerId value

    • +

In [IniData] section:

    +

  • WorkerId - This +value is numeric and must be unique

    • +

  • CSYList - Contains +CSYs which you want to load in this new CPM, separated by commas, no white +spaces allowed.

    • +

Since the additional CMI being added is a Player, +the Role field remains the same and it can not be changed to Dealer as +the CPM with WorkerId=0 is the one and only Dealer in the +C32MT.

[Loader] +# Change the Name value to your CSY name +Name=C32_Default //

Change the Name value +to the name of your CSY, e.g.

Name=C32_MyCSYs FileName=c32.dll +ThreadFunctionOrdinal=87 +ThreadPriority=EPriorityMuchMore +StackSize=16384 +ScaledStartupState=0x3040 +HeapOption=ENewHeap +MinHeapSize=256 +MaxHeapSize=524288 +SystemCritical=1 +Group=C32SerComms +OnDemand=1

Change the BindingN line to refer to your CSY, for +example change from

# Change the BindingN line to refer to your CSYs +Binding0=C32_Default:4,C32_Main:0,ECustom,42,42

to

Binding0=C32_MyCSYs:5,C32_Main:0,ECustom,42,42

And +in the [IniData] section:

[IniData] +# Make sure Role is set to "Player" +Role=Player

Change the WorkerId, for example from WorkerId=4 to

WorkerId=5

and +change the CSYList to specify your CSYs, e.g. change "CSYList=XX,YY,zz" +to

CSYList=MyCSY1,MyCSY2
+
Typical Thread +Configuration Examples

This section describes the three broad configurations +for threading available for the C32 Serial Server. Each has different potential +effects on the performance of C32.

The three broad configurations +available, with a summary of their costs and benefits, are detailed in the +following table:

+ + + + +Configuration +Advantages +Disadvantages + + + + +

1

 +

Run all CSYs outside the main thread [Default supplied CMI set]

+
    +

  • Some CSYs can be promoted +ahead of others using thread priorities

    • +

  • Main thread cannot ever +stall when any CSY stalls

    • +

  • Stackable CSYs are possible: +a CSY can connect to another CSY through the C32 API as long as both are in +different threads

    • +
 +
    +

  • Operations on CSYs are +a bit slower due to increased overhead of inter-thread communication

    • +

  • Complex to debug

    • +
 + + +

2

 +

Run some CSYs in the main thread

+
    +

  • CSYs in the main thread +avoid the overhead of inter-thread communication

    • +

  • Some CSYs can be promoted +ahead of others using thread priorities

    • +

  • Main thread cannot stall +when a CSY in a separate thread stalls

    • +

  • Stackable CSYs are possible: +a CSY can connect to another CSY through the C32 API as long as both are in +different threads

    • +
 +
    +

  • If any CSY in the main +thread stalls, the whole server stalls

    • +

  • No means to prioritise +one CSY ahead of others (without changing the CSY code)

    • +

  • Operations on CSYs outside +the main thread are a bit slower due to the increased overhead of inter-thread +communication

    • +

  • Complex to debug

    • +
 + + +

3

 +

Run all CSYs in the main thread [Default configuration when any +CMI files are corrupt]

+
    +

  • Simplest to debug since +no inter-thread communication

    • +

  • All CSYs avoid the overhead +of inter-thread communication

    • +
 +
    +

  • If any CSY stalls, the +whole server stalls

    • +

  • No means to prioritise +one CSY ahead of others (without changing the CSY code)

    • +

  • No stackable CSYs are +possible

    • +
 + + + +

The default set of CMI files supplied with Symbian platform +is based on the first broad configuration since it was decided that the small +cost of running all CSYs outside the main thread is justified by the increased +reliability to the whole C32 system of ensuring no CSY can deny service to +the C32 server. Each of these configurations is explained in more detail below.

+ Figure 1 - No CSYs in main thread: RootServer with 4 +C32 CPMs + +

Referring to Figure 1, the following can be observed:

    +

  1. The Main Thread has WorkerId=0, +Role as Dealer and is configured to load no CSY

    2. +

  2. The Player Thread 1 +has WorkerId=1, Role as Player and is configured to load +ECACM CSY

    3. +

  3. The Player Thread 2 +has WorkerId=2, Role as Player and is configured to load +ECUART CSY

    4. +

  4. The Player Thread 3 +has WorkerId=3, Role as Player and is configured to load unlisted csy. +What unlisted csy means here is that apart from ECACM and ECUART, if any new +csy is to be loaded, it will get loaded in this thread.

    5. +

The [IniData] section for the above CPMs would look like:

[IniData] +Role=Dealer +WorkerId=0 + [IniData] +Role=Player +WorkerId=1 +CSYList=ECACM + [IniData] +Role=Player +WorkerId=2 +CSYList=ECUART + [IniData] +Role=Player +WorkerId=3 +CSYList=* + + Figure 2 - All CSYs in main thread: RootServer with single +C32 CPM + +

In Figure 2 the CPM loads any CSYs, and so should contain CSYList tag +in the IniData section.

The Main Thread has WorkerId=0, +Role as Dealer and is configured to load any CSY. In this configuration +since it is a single thread, all the CSYs will be loaded in the same thread.

The [IniData] section +for above CPM would look like:

[IniData] +Role=Dealer +WorkerId=0 +CSYList=* + + Figure 3 - Some CSYs in main thread: RootServer with +3 CPMs + +

From Figure 3, the following can be observed.

    +

  1. The Main Thread has WorkerId=0, +Role as Dealer and is configured to load HSDPA csy

    2. +

  2. The Player Thread 1 +has WorkerId=1, Role as Player and is configured to load +ECACM csy

    3. +

  3. The Player Thread 2 +has WorkerId=2, Role as Player and is configured to load +an unlisted csy

    4. +

The IniData section for above CPMs would look like:

[IniData] +Role=Dealer +WorkerId=0 +CSYList=HSDPA + [IniData] +Role=Player +WorkerId=1 +CSYList=ECACM [IniData] +Role=Player +WorkerId=2 +CSYList=*
+
Footnotes
+ +
Footnote 1
+

In theory the C32 main thread (Workerid=0) could be +marked as on-demand and started by the first client to connect to it. This +might be useful since it would save device boot time for a device that does +not need serial comms as part of boot up. The process would require the client +to connect to Configurator and load the C32 main module explicitly. For this +to work the main Module’s name would have to be fixed (the reference system +uses “C32_Main ”) so that the client can identify it to Configurator +- which is not a big problem, and the client would need the appropriate capabilities +(also not a big problem as the client could well be inside Rootserver too). +The other problem is that making it on-demand requires that it is still started +by a priviledged process before any unpriviledged process attempts to use +the C32 API (since this will fail unless no CSYs require any capabilities). +Therefore, for on-demand main thread-loading to work, intimate details about +the specific configuration of CSYs for a device and their potential clients +would be needed.

+ +
 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0A932926-281D-5465-9F38-E5FA8AA7EBD4.dita --- a/Symbian3/SDK/Source/GUID-0A932926-281D-5465-9F38-E5FA8AA7EBD4.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-0A932926-281D-5465-9F38-E5FA8AA7EBD4.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,25 +1,25 @@ - - - - - -How -to use the SIP Codec API -

This section provides the information about the protocol and error handling -related to the SIP Codec API.

-
Protocol

The -following illustration shows the steps for creating a CSIPContactHeader instance. -

-Creating a Contact Header - -
-
Error handling

If -an error occurs during a synchronous operation initiated by the client, the -function that is called exits with the correct error code.

+ + + + + +How +to use the SIP Codec API +

This section provides the information about the protocol and error handling +related to the SIP Codec API.

+
Protocol

The +following illustration shows the steps for creating a CSIPContactHeader instance. +

+Creating a Contact Header + +
+
Error handling

If +an error occurs during a synchronous operation initiated by the client, the +function that is called exits with the correct error code.

 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0AD34BA6-D0C5-5AD7-B8E1-F737BB5FC0AC.dita --- a/Symbian3/SDK/Source/GUID-0AD34BA6-D0C5-5AD7-B8E1-F737BB5FC0AC.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-0AD34BA6-D0C5-5AD7-B8E1-F737BB5FC0AC.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,111 +1,111 @@ - - - - - -Redraw -StoresRedraw stores store the sequence of drawing commands representing -window contents. Whenever possible, the Window Server performs server-initiated -redraws by repeating the sequence of stored commands, rather than by sending -redraw requests to the client. This minimises the number of client-server -transactions and means that redraws are done as soon as the server detects -that they are needed. This topic explains some of the background to redraw -stores. -

Variant: Both (ScreenPlay and non-ScreenPlay). Target audience: -Device creators.

-

The classes involved with redraw stores are as follows:

- - Redraw stores class diagram - - -

CWsRedrawMsgWindow is the class representing a redraw -store. Draw commands are stored in a number of segments, stored in the nested -class CRedrawSegment.

-

Redraw drawing takes place as follows:

-
    -

  1. A call to RWindow::Invalidate() causes -either the whole window, or a rectangle within it, to be marked as invalid.

    2. -

  2. Next, a call to RWindow::BeginRedraw() is -made, either for the whole window or for a rectangle within it.

    3. -

  3. Draw operations take -place.

    4. -

  4. Finally there is a call -to RWindow::EndRedraw().

    5. -
-

In this sequence, the draw operations within the BeginRedraw() and EndRedraw() brackets -are interpreted as replacing whatever drawing was previously present -in the affected rectangle.

-

It is important to bracket all drawing within BeginRedraw(TRect) and EndRedraw(TRect) calls. -In ScreenPlay, the Window Server ignores all drawing not within BeginRedraw() and EndRedraw() brackets -and triggers a full-window redraw. In debug builds, there is an option to -panic clients violating this convention.

-

For more information, see Redraw -Drawing.

-
Redraw segments and non-redraw handling

When the -Window Server receives a batch of redraw drawing, everything between a BeginRedraw/EndRedraw -bracket is stored in a single redraw segment. The segment is marked -as ESegmentTypePendingRedraw while it is being received, -and ESegmentTypeRedraw once it is complete.

Redraw -segments have a region to which they apply. For ESegmentTypeRedraw, -the region is initially set to be the rectangle passed into the BeginRedraw() call. -When a newESegmentTypeRedraw is created, its region is subtracted -from the regions of all existing segments. This reflects the fact that redraw -drawing replaces existing drawing. If, as a consequence of new redraw -drawing, the region of an existing segment becomes empty, that segment is -discarded. Its drawing has been replaced everywhere, so it is no longer needed.

What -happens to drawing that is received between an EndRedraw and -the next BeginRedraw —and which is therefore non-redraw -drawing —depends on which variant is in use:

    -

  • In ScreenPlay, non-redraw -drawing is not stored in a segment but instead triggers the Window Server -to invalidate the entire window. This means that the client application must -then perform a full window redraw.

    • -

  • In the non-ScreenPlay -variant, non-redraw drawing is stored in a segment marked as ESegmentTypeNonRedraw. -For these segments the region is initially set to be the whole window and -does not affect the regions of existing segments, because non-redraw drawing -is drawn over existing drawing.

    • -
-
Redraw store playback

When playback is required, -the redraw store goes through the redraw segments and replays them if the -region for the segment intersects the region that is to be redrawn. It follows -from the way that they are managed that the regions of redraw segments are -mutually disjoint. This means that in ScreenPlay they can be replayed in any -order. This is also true in the non-ScreenPlay when there are only redraw -segments present.

In the non-ScreenPlay variant, any non-redraw segments -are replayed in earliest-first order, because they draw on top of earlier -drawing.

-
Aging of non-redraw segments

Variant: -Non-ScreenPlay only.

Non-redraw segments can cause inefficient operation -of redraw stores. For this reason, in the non-ScreenPlay variant where non-redraw -segments are still used, the Window Server "ages" them. That is, non-redraw -segments are considered to have a finite lifetime, after which they are discarded. -When a non-redraw segment is discarded, the Window Server makes a redraw request -to the client asking it to provide new draw operations for the invalid region.

The -lifetime for non-redraw segments is set in the WSINI.INI -file using the parameter NONREDRAWAGELIMIT, followed -by a duration in microseconds. If this line is not present in the WSINI.INI, -a default of one second is used.

-
Atomic Redraws

Variant: Both (ScreenPlay -and non-ScreenPlay).

Another WSINI.INI -file setting that affects redraw storing is ATOMICREDRAWS. -If this parameter is present, new draw operations received after a BeginRedraw() are -not considered valid until the corresponding EndRedraw() is -received. In particular, a new segment does not replace existing segments -until it is complete. This has the consequence that if redraw store playback -is required before the EndRedraw() for a new segment is received, -draw operations from old segments for that region are used instead. Thus drawing -within Begin/EndRedraw brackets can be considered as an atomic -operation. This eliminates one potential source of flicker.

- -Graphics -and Drawing -The wsini.ini -File Reference + + + + + +Redraw +StoresRedraw stores store the sequence of drawing commands representing +window contents. Whenever possible, the Window Server performs server-initiated +redraws by repeating the sequence of stored commands, rather than by sending +redraw requests to the client. This minimises the number of client-server +transactions and means that redraws are done as soon as the server detects +that they are needed. This topic explains some of the background to redraw +stores. +

Variant: Both (ScreenPlay and non-ScreenPlay). Target audience: +Device creators.

+

The classes involved with redraw stores are as follows:

+ + Redraw stores class diagram + + +

CWsRedrawMsgWindow is the class representing a redraw +store. Draw commands are stored in a number of segments, stored in the nested +class CRedrawSegment.

+

Redraw drawing takes place as follows:

+
    +

  1. A call to RWindow::Invalidate() causes +either the whole window, or a rectangle within it, to be marked as invalid.

    2. +

  2. Next, a call to RWindow::BeginRedraw() is +made, either for the whole window or for a rectangle within it.

    3. +

  3. Draw operations take +place.

    4. +

  4. Finally there is a call +to RWindow::EndRedraw().

    5. +
+

In this sequence, the draw operations within the BeginRedraw() and EndRedraw() brackets +are interpreted as replacing whatever drawing was previously present +in the affected rectangle.

+

It is important to bracket all drawing within BeginRedraw(TRect) and EndRedraw(TRect) calls. +In ScreenPlay, the Window Server ignores all drawing not within BeginRedraw() and EndRedraw() brackets +and triggers a full-window redraw. In debug builds, there is an option to +panic clients violating this convention.

+

For more information, see Redraw +Drawing.

+
Redraw segments and non-redraw handling

When the +Window Server receives a batch of redraw drawing, everything between a BeginRedraw/EndRedraw +bracket is stored in a single redraw segment. The segment is marked +as ESegmentTypePendingRedraw while it is being received, +and ESegmentTypeRedraw once it is complete.

Redraw +segments have a region to which they apply. For ESegmentTypeRedraw, +the region is initially set to be the rectangle passed into the BeginRedraw() call. +When a newESegmentTypeRedraw is created, its region is subtracted +from the regions of all existing segments. This reflects the fact that redraw +drawing replaces existing drawing. If, as a consequence of new redraw +drawing, the region of an existing segment becomes empty, that segment is +discarded. Its drawing has been replaced everywhere, so it is no longer needed.

What +happens to drawing that is received between an EndRedraw and +the next BeginRedraw —and which is therefore non-redraw +drawing —depends on which variant is in use:

    +

  • In ScreenPlay, non-redraw +drawing is not stored in a segment but instead triggers the Window Server +to invalidate the entire window. This means that the client application must +then perform a full window redraw.

    • +

  • In the non-ScreenPlay +variant, non-redraw drawing is stored in a segment marked as ESegmentTypeNonRedraw. +For these segments the region is initially set to be the whole window and +does not affect the regions of existing segments, because non-redraw drawing +is drawn over existing drawing.

    • +
+
Redraw store playback

When playback is required, +the redraw store goes through the redraw segments and replays them if the +region for the segment intersects the region that is to be redrawn. It follows +from the way that they are managed that the regions of redraw segments are +mutually disjoint. This means that in ScreenPlay they can be replayed in any +order. This is also true in the non-ScreenPlay when there are only redraw +segments present.

In the non-ScreenPlay variant, any non-redraw segments +are replayed in earliest-first order, because they draw on top of earlier +drawing.

+
Aging of non-redraw segments

Variant: +Non-ScreenPlay only.

Non-redraw segments can cause inefficient operation +of redraw stores. For this reason, in the non-ScreenPlay variant where non-redraw +segments are still used, the Window Server "ages" them. That is, non-redraw +segments are considered to have a finite lifetime, after which they are discarded. +When a non-redraw segment is discarded, the Window Server makes a redraw request +to the client asking it to provide new draw operations for the invalid region.

The +lifetime for non-redraw segments is set in the WSINI.INI +file using the parameter NONREDRAWAGELIMIT, followed +by a duration in microseconds. If this line is not present in the WSINI.INI, +a default of one second is used.

+
Atomic Redraws

Variant: Both (ScreenPlay +and non-ScreenPlay).

Another WSINI.INI +file setting that affects redraw storing is ATOMICREDRAWS. +If this parameter is present, new draw operations received after a BeginRedraw() are +not considered valid until the corresponding EndRedraw() is +received. In particular, a new segment does not replace existing segments +until it is complete. This has the consequence that if redraw store playback +is required before the EndRedraw() for a new segment is received, +draw operations from old segments for that region are used instead. Thus drawing +within Begin/EndRedraw brackets can be considered as an atomic +operation. This eliminates one potential source of flicker.

+ +Graphics +and Drawing +The wsini.ini +File Reference \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0B0EF90E-45A4-467F-8CD9-33FBC612B3BD_d0e4153_href.png Binary file Symbian3/SDK/Source/GUID-0B0EF90E-45A4-467F-8CD9-33FBC612B3BD_d0e4153_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0B0EF90E-45A4-467F-8CD9-33FBC612B3BD_d0e5428_href.png Binary file Symbian3/SDK/Source/GUID-0B0EF90E-45A4-467F-8CD9-33FBC612B3BD_d0e5428_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0B151FE8-21E1-58A1-BEB3-5502EDF052C0_d0e79276_href.png Binary file Symbian3/SDK/Source/GUID-0B151FE8-21E1-58A1-BEB3-5502EDF052C0_d0e79276_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0B151FE8-21E1-58A1-BEB3-5502EDF052C0_d0e85988_href.png Binary file Symbian3/SDK/Source/GUID-0B151FE8-21E1-58A1-BEB3-5502EDF052C0_d0e85988_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0B1A4D73-AB81-586C-9D95-A0F5EE1F4BC7_d0e327379_href.png Binary file Symbian3/SDK/Source/GUID-0B1A4D73-AB81-586C-9D95-A0F5EE1F4BC7_d0e327379_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0B1A4D73-AB81-586C-9D95-A0F5EE1F4BC7_d0e333536_href.png Binary file Symbian3/SDK/Source/GUID-0B1A4D73-AB81-586C-9D95-A0F5EE1F4BC7_d0e333536_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0B2245C5-766B-5CF1-8A0C-DD98CEEEBB05.dita --- a/Symbian3/SDK/Source/GUID-0B2245C5-766B-5CF1-8A0C-DD98CEEEBB05.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,12 +0,0 @@ - - - - - -Random Number Generation (RNG)

Random Number Generation (RNG) generates cryptographically strong random numbers for use by cryptographic applications such as one-time pads and Initialization Vectors. The applications rely on RNG for its randomness, unpredictability and irreproducibility.

 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0B24B36D-F4C5-508A-A65B-18E4E4C45C37.dita --- a/Symbian3/SDK/Source/GUID-0B24B36D-F4C5-508A-A65B-18E4E4C45C37.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-0B24B36D-F4C5-508A-A65B-18E4E4C45C37.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,30 +1,95 @@ - - - - - -Overview

This document introduces you to the Snapshot API.

Purpose

This API allows the client to request snapshot data in a specified image format for both still images and video. The client can specify the properties of the snapshot, such as size, background colour and position to be used. For example, details about whether the snapshot has been scaled.

Snapshot API Library Details

The DLL that provides the functionality and the library to which your code must link is identified below.

DLL LIB Short Description

ecamsnapshot.dll

euser.lib

ecampluginsupport.lib

ecamhistogram.lib

These files are used for implementing the Snapshot APIs.

Architectural Relationship

This is part of the camera component.

Description

The client application using this API should provide McameraObserver2 interface to be signalled, with event KuidECamEventCameraSnapshot, when snapshot data is available to be retrieved from the Ecam server. The client can then retrieve the snapshot data from the server.

Key Snapshot API Classes

The key classes that make up the Snapshot API are as follows:

  • CCamera::CCameraSnapshot

    This class allows a client to request snapshot data in a specified image format for both still images and video.

    • CCameraSnapshot::SupportedFormats()

      Gets a list of the camera formats for which the server supports snapshots.

    • CCamera::CCameraSnapshot::PrepareSnapshotL() -

      Selects snapshot parameters. The following example shows how to do this:

      // Gets the list of supported formats for snapshots -TUint suppFormats = snap->SupportedFormats(); - -CCamera::TFormat format = CCamera::EFormatJpeg; -if(suppFormats & format) - { - // Sets the properties of the snapshot data including - // background colour and the position of the snapshot - TSize sShotSize(90,50); - TRgb bgrndColor(100,100,100); - TBool aspectRatio = ETrue; - TPoint orgPos(2,2); - - snap->PrepareSnapshotL(format, orgPos, sShotSize, bgrndColor,aspectRatio); -

    • - CCamera::CCameraSnapshot::IsSnapshotActive()

      Determines if the snapshot feature is active.

    • CCamera::CCameraSnapshot::StartSnapshot() -

      Request notifications from the Camera.

    • CCamera::CCameraSnapshot::StopSnapshot()

      Stops receiving snapshot notifications.

    • CCamera::CCameraSnapshot::SnapshotDataL() -

      Returns the snapshot data from server to the client.

  • McameraSnapshot

  • McameraSnapshot2

  • CCameraDirectSnapshot

  • McameraDirectSnapshot

Using Snapshot API

Clients can use the Snapshot API to:

  • Create snapshots for still images and video.

  • View the captured images on the display instantly.

See also

Overview of the Camera component

The Snapshot tutorial

\ No newline at end of file + + + + + +Overview +

This document introduces you to the Snapshot API.

+
Purpose

This +API allows the client to request snapshot data in a specified image format +for both still images and video. The client can specify the properties of +the snapshot, such as size, background colour and position to be used. For +example, details about whether the snapshot has been scaled.

Snapshot +API Library Details

The DLL that provides the functionality and +the library to which your code must link is identified below.

+ + + +DLL +LIB +Short Description + + + + +

ecamsnapshot.dll

+

euser.lib

ecampluginsupport.lib

ecamhistogram.lib

+

These files are used for implementing the Snapshot APIs.

+ + + +
+
Architectural +Relationship

This is part of the camera component.

+
Description

The +client application using this API should provide McameraObserver2 interface +to be signalled, with event KuidECamEventCameraSnapshot, +when snapshot data is available to be retrieved from the Ecam server. The +client can then retrieve the snapshot data from the server.

+
Key Snapshot +API Classes

The key classes that make up the Snapshot API are as +follows:

    +

  • CCamera::CCameraSnapshot

    This +class allows a client to request snapshot data in a specified image format +for both still images and video.

      +

    • CCameraSnapshot::SupportedFormats()

      Gets +a list of the camera formats for which the server supports snapshots.

      • +

    • CCamera::CCameraSnapshot::PrepareSnapshotL() +

      Selects snapshot parameters. The +following example shows how to do this:

      // Gets the list of supported formats for snapshots +TUint suppFormats = snap->SupportedFormats(); + +CCamera::TFormat format = CCamera::EFormatJpeg; +if(suppFormats & format) + { + // Sets the properties of the snapshot data including + // background colour and the position of the snapshot + TSize sShotSize(90,50); + TRgb bgrndColor(100,100,100); + TBool aspectRatio = ETrue; + TPoint orgPos(2,2); + + snap->PrepareSnapshotL(format, orgPos, sShotSize, bgrndColor,aspectRatio); +
      • +

    • + CCamera::CCameraSnapshot::IsSnapshotActive()

      Determines +if the snapshot feature is active.

      • +

    • CCamera::CCameraSnapshot::StartSnapshot() +

      Request notifications from the Camera.

      • +

    • CCamera::CCameraSnapshot::StopSnapshot()

      Stops +receiving snapshot notifications.

      • +

    • CCamera::CCameraSnapshot::SnapshotDataL() +

      Returns the snapshot data from server +to the client.

      • +
    • +

  • MCameraSnapshot

    • +

  • MCameraSnapshot2

    • +

  • CCamera::CCameraDirectSnapshot

    • +

  • MCameraDirectSnapshot

    • +
+
Using Snapshot +API

Clients can use the Snapshot API to:

    +

  • Create snapshots for +still images and video.

    • +

  • View the captured images +on the display instantly.

    • +
+
See also

Overview of the Camera +component

The Snapshot tutorial

+ \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0BAE2D0E-604B-4A62-B5EB-AC68EAF7F589.dita --- a/Symbian3/SDK/Source/GUID-0BAE2D0E-604B-4A62-B5EB-AC68EAF7F589.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,26 +0,0 @@ - - - - - -Navigating -in applications -

The traditional hierarchical tree structure forms the basis for navigation. -The user can move forward from one node (state) by opening an available item -or selecting an option from a menu. The Back function (available in the right -softkey Back) returns to the previous level in the hierarchy. In the initial -state of an application (number 1 in the figure below), the Exit function -replaces Back in the right softkey and is used for closing the application.

- -Example of the basic state hierarchy in an application. The solid lines -indicate moving forward from a state into a sub-state. The dotted lines are -backward moves to the previous level. - - - \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0C01305E-9E73-4E44-BD13-361C93CC5E79_d0e265510_href.png Binary file Symbian3/SDK/Source/GUID-0C01305E-9E73-4E44-BD13-361C93CC5E79_d0e265510_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0C01305E-9E73-4E44-BD13-361C93CC5E79_d0e269218_href.png Binary file Symbian3/SDK/Source/GUID-0C01305E-9E73-4E44-BD13-361C93CC5E79_d0e269218_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0C19D3F1-CF60-4760-8A77-242E14647738.dita --- a/Symbian3/SDK/Source/GUID-0C19D3F1-CF60-4760-8A77-242E14647738.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-0C19D3F1-CF60-4760-8A77-242E14647738.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,43 +1,39 @@ - - - - - -Touch -UI observer interfaces -

To support the touch functionality in the UI components, following observer -interfaces are provided:

-
    -

  • Navigation decorator observer (MAknNaviDecoratorObserver)- -It is used in the navigation pane. The interface receives an event indicating -that the decorator’s right or left arrow has been tapped (or the navi label). -Based on the event received, the observer implementation performs an action -(for example, raise the volume or change focus to the next tab). This observer -is useful when custom controls needs to be implemented in the navigation -control. The observer can be set using CAknNavigationDecorator::SetNaviDecoratorObserver().

    • -

  • Long tap detector (CAknLongTapDetector) - It -is an AVKON component that an application or control can use to receive long -tap events.

    The long tap handler must inherit from MAknLongTapDetectorCallBack and -implement the HandleLongTapEventL() call back function for -long tap events.

    When the stylus/finger is held down in the same position, -an animation starts in about 0.15 s to show that the long tap functionality -has started. Animation is provided by AVKON and cannot be changed by the application -or control. However, animation can be turned off using the class CAknLongTapDetector in -the Touch UI utilities API.

    For implementation information, see the Touch UI utilities API specification.

    • -

  • Double-click support in lists - To receive double-click events -from a list or grid, the object that needs to be informed must implement and -register the MEikListBoxObserver interface via CEikListBox::SetListBoxObserver().

    After -registering, handle the EEventItemDoubleClicked event inHandleListBoxEventL() method.

    If -single click is enabled, EEventItemSingleClicked event should -be handled instead.

    • -

  • Title pane touch observer - The title pane touch observer enables -you to provide functionality for title pane touch events. For implementation -information, see the Title pane touch observer API specification.

    • -
+ + + + + +Touch +UI observer interfaces +

To support the touch functionality in the UI components, following observer +interfaces are provided:

+
    +

  • Navigation decorator observer (MAknNaviDecoratorObserver)- +It is used in the navigation pane. The interface receives an event indicating +that the decorator’s right or left arrow has been tapped (or the navi label). +Based on the event received, the observer implementation performs an action +(for example, raise the volume or change focus to the next tab). This observer +is useful when custom controls needs to be implemented in the navigation +control. The observer can be set using CAknNavigationDecorator::SetNaviDecoratorObserver().

    • +

  • Long tap detector (CAknLongTapDetector) - It +is an AVKON component that an application or control can use to receive long +tap events.

    The long tap handler must inherit from MAknLongTapDetectorCallBack and +implement the HandleLongTapEventL() call back function for +long tap events.

    When the stylus/finger is held down in the same position, +an animation starts in about 0.15 s to show that the long tap functionality +has started. Animation is provided by AVKON and cannot be changed by the application +or control. However, animation can be turned off using the class CAknLongTapDetector in +the Touch UI utilities API.

    For implementation information, see the Touch UI utilities API specification.

    • +

  • Title pane touch observer - The title pane touch observer enables +you to provide functionality for title pane touch events. For implementation +information, see the Title pane touch observer API specification.

    • +
+
See alsoTouch +support in lists
 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0C6CCACF-84B2-5715-BCF3-12330E6F05D4-GENID-1-8-1-3-1-1-9-1.dita --- a/Symbian3/SDK/Source/GUID-0C6CCACF-84B2-5715-BCF3-12330E6F05D4-GENID-1-8-1-3-1-1-9-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,14 +0,0 @@ - - - - - -Using Front -End Processor (FEPBASE)This section explains Front End Processor (FEP), and its implementations -and events. \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0C6CCACF-84B2-5715-BCF3-12330E6F05D4-GENID-1-8-1-6-1-1-4-1-8-1.dita --- a/Symbian3/SDK/Source/GUID-0C6CCACF-84B2-5715-BCF3-12330E6F05D4-GENID-1-8-1-6-1-1-4-1-8-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,14 +0,0 @@ - - - - - -Using Front -End Processor (FEPBASE)This section explains Front End Processor (FEP), and its implementations -and events. \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0C6CCACF-84B2-5715-BCF3-12330E6F05D4.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-0C6CCACF-84B2-5715-BCF3-12330E6F05D4.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,14 @@ + + + + + +Using Front +End Processor (FEPBASE)This section explains Front End Processor (FEP), and its implementations +and events. \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0C71B9C6-0782-5667-932A-07D770748DCE.dita --- a/Symbian3/SDK/Source/GUID-0C71B9C6-0782-5667-932A-07D770748DCE.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-0C71B9C6-0782-5667-932A-07D770748DCE.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,35 +1,37 @@ - - - - - -TextMTM -utilities -

In addition to the MTM component DLLs, a number of other programs are provided.

-
Example Code

Click on the following link to download -the example: TextMTM.zip

Click: browse to view the example code.

The files reproduced -here are the main files contained in the examples directory. Some extra files -may be needed to run the examples, and these will be found in the appropriate -examples directory

-
Common classes: txut

The txut project -provides source for a small utilities DLL, which holds code that must be shared -between the Client and the Server-side Text MTM components.

    -

  • TTxtProgress encapsulates -progress information. The Server-side MTM records its progress using this -class when performing copy and move operations. The User Interface MTM can -extract information from the class for display to the user.

    • -

  • CMTMTxtSettings encapsulates -access to the MTM's settings as they are stored in the central repository. TMTMTxtSetting encapsulates -the settings for a single TextMTM service. This contains only a single property: -the folder to which the service is mapped.

    • -

  • TxtUtils provides -static utility functions.

    • -
-
Classes used

TTxtProgressCMTMTxtSettings TMTMTxtSettingTxtUtils

+ + + + + +TextMTM utilities +

In addition to the MTM component DLLs, a number of other programs +are provided.

+
Example Code

Click on the following link +to download the example: TextMTM.zip

Click: browse to view the example code.

The files +reproduced here are the main files contained in the examples directory. +Some extra files may be needed to run the examples, and these will +be found in the appropriate examples directory

+
Common classes: txut

The txut project provides source for a small utilities DLL, which holds code +that must be shared between the Client and the Server-side Text MTM +components.

    +

  • TTxtProgress encapsulates progress information. The Server-side MTM records its +progress using this class when performing copy and move operations. +The User Interface MTM can extract information from the class for +display to the user.

    • +

  • CMTMTxtSettings encapsulates access to the MTM's settings as they are stored in +the central repository. TMTMTxtSetting encapsulates +the settings for a single TextMTM service. This contains only a single +property: the folder to which the service is mapped.

    • +

  • TxtUtils provides static utility functions.

    • +
+
Classes used
    +

  • TTxtProgressCMTMTxtSettings

    • +

  • TMTMTxtSettingTxtUtils

    • +
 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0C7CDC47-6B42-5A20-BED8-086DA81D272E.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-0C7CDC47-6B42-5A20-BED8-086DA81D272E.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,69 @@ + + + + + +PBE +-- guide +
    +

  • What is PBE?

    • +

  • What is PBE used for?

    • +

  • Base classes and their derived classes

    • +

  • Example +code

    • +
+
What is PBE?

PBE +provides an API to encrypt and decrypt data with a user-supplied password. +It is intended to be used by applications, such as editors or database programs, +that might provide the ability to encrypt a user's documents. It aims to be +secure and easy to use, and attempts to overcome the common pitfalls of encryption +based on user-supplied passwords. Specifically, it uses a PKCS#5 -based key derivation function to create the +symmetric key based on the user's password.

PKCS#5 is the Password Based Encryption standard produced +by RSA laboratories. It describes a method to generate a symmetric key based +on a password. We use PKCS#5 v2.0 (specified in RFC 2898), which is able to generate unlimited key +length.

The PBE algorithm generates a symmetric key based on a password, +which is provided by the user. To impede dictionary attacks, the password +is appended with a salt before being digested to produce the key; the salt +is generated using a pseudo random number generator. Furthermore, the PBE +algorithm by which the keys are derived is iterated a number of times, the +default being KDefaultIterations. As the ciphers operate +in CBC mode, a randomly selected Initialization Vector (IV) is passed to them +as a seed. Note that the salt value, iteration count value, and the IV (i.e., +the CPBEncryptParms object) do not have to be kept secret +and can be sent along with the ciphertext.

PBE provides APIs for encrypting +a single object (CPBEncryptElement) and multiple objects +(CPBEncryptSet). The latter is useful in the situation if +one wants random access to an encrypted source consisting of multiple, independent +elements; for example a database or a store.

+
What is PBE +used for?

PBE is used to implement Secure +Stream Encryption, which can be used, for example:

    +

  • to password protect +a database file

    • +

  • to store contacts encrypted +on a mobile phone.

    • +
+
Base classes +and their derived classes

The diagrams below show the main classes +used in password based encryption and which are implemented in pbe.dll. +Blue dotted arrows indicate that a class is contained or used by another class. +The arrows are labelled with the variable(s) through which the pointed class +is accessible. The color of the boxes indicates the type of Symbian class, +i.e., M, C, R or T class. +For detailed information on each component see the Cryptography API Reference +material.

+The inheritance diagram above shows the <codeph>CPBEncryptionBase</codeph> abstract +base class. Also shown are the following classes from the Cryptography API: <codeph>CPBEncryptElement</codeph>, <codeph>CPBEncryptSet</codeph>, <codeph>CPBAuthData</codeph>, <codeph>CPBEncryptionData</codeph>, and <codeph>CPBEncryptParams</codeph>. + + +The inheritance diagram above shows the <codeph>CPBEncryptor</codeph> abstract +base class. Also shown are the following classes from the Cryptography API: <codeph>CPBDecryptor</codeph>, <codeph>CPBDecryptorElement</codeph>, <codeph>CPBDecryptorSet</codeph>, <codeph>CSymmetricCipher</codeph>, <codeph>CPBEncryptorElement</codeph>, <codeph>CPBEncryptorSet</codeph>. + +
+ \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0C814ED6-3F64-4E0E-9C47-654AEDADBA90.dita --- a/Symbian3/SDK/Source/GUID-0C814ED6-3F64-4E0E-9C47-654AEDADBA90.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-0C814ED6-3F64-4E0E-9C47-654AEDADBA90.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,455 +1,455 @@ - - - - - -Going -Beyond Hello: A Tutorial for Symbian C++ ApplicationsThis tutorial shows how you can extend that basic example to create -a small paint application, along the way learning more about the application -frameworks (e.g. defining menus, how to handle touch-screen events, drawing -to the screen etc.). -

In the Symbian C++ -Quick Start you learned how to create a basic example application using -Carbide.c++, and how to build and run it on the Windows emulator and on a -device.

-

Comes with Code: File: -HelloSymbianWorld Example Code.zip

-
Application -Structure

Carbide.c++ offers two ways of exploring your project. -The traditional Project Explorer window, which can also be found in -Eclipse, lists the files belonging to the project in the same directory structure -as in the file system.

The Symbian Project Navigator contains -the same contents, but displays them in a logical hierarchy according to Symbian -Conventions.

You might wonder why a basic "Hello World" application -contains so many files. The answer is straightforward - a much simpler Hello -World wouldn’t be a very good starting point for real-world applications. -

Instead the wizard generates the project for a complete and readily -extensible application. The project separates code and data, and uses a form -of the model -view controller pattern for structuring your code. The application -already reacts to system events and contains everything that is required for -localization.

What are the directories of a project? - -

\group

    -

  • bld.inf: Component-definition file. This specifies the mmp files -that belong to your component, any shared header files that it exports, and -the default build targets (e.g. GCCE, WINSCW).

      -

    • Bld.inf is used to generate the makefiles and abld.bat used -to build for the command-line (see Symbian -C++ Quick Start).

      • -

    • This file is the starting point when you want to import a Symbian C++ -project into Carbide.c++, because it contains references to all executables -in your project (see the section on Importing Other Examples).

      • -
    • -

  • HelloWorld.mmp: Project-definition file. This specifies how -to build an executable (in this case HelloWorld.exe) in a -platform- and compiler-independent way. It contains information such as resource -files to be compiled, source files to include when compiling, and the libraries -to include when linking.

    • -

  • Icons_aif_scalable_dc.mk: Makefile used to create the application's -icon from the *.svg file in the /gfx folder.

    • -

\src

    -

  • HelloWorldApplication.cpp: This file contains the entry point -for the EXE file (E32Main()) as well as the implementation -of the Application class (which provides some basic functionality for the -GUI framework). Normally this is "boilerplate" code and you do not need to -make any changes.

    • -

  • HelloWorldDocument.cpp: This class is supposed to take care -of the persistent data model of your application and therefore provides some -functions to load and save .ini files. This mechanism is -disabled by default - for most applications you may treat this as "boilerplate" -code.

    • -

  • HelloWorldAppUi.cpp: This is the main controller of your application. -It contains the logic for handling application-wide events (so you don’t have -to handle, for example, the exit event in every view). It owns all the views -that you use.

    • -

  • HelloWorldContainerView.cpp: This is a kind of controller, which -is responsible for handling events and the UI elements of the currently visible -view. It’s not visible itself, but owns and manages the Container (below), -which corresponds to the view in the traditional model view controller pattern.

    • -

  • HelloWorldContainer.cpp: Contains the UI elements that should -be displayed by the view. Therefore, the ContainerView and the Container usually -have a very strong relationship.

    • -

During start-up, one class instance creates the next:

- -

\inc

    -

  • HelloWorldApplication.h, HelloWorldDocument.h, HelloWorldAppUi.h, HelloWorldContainerView.h, HelloWorldContainer.h: Header files corresponding to each of the main source files above.

    • -

  • HelloWorld.hrh: UIDs/identifiers for UI elements including views. -These are shared between the resource file definitions for UI elements and -the source code command handlers.

    • -

  • HelloWorld.pan: Panic code and method definitions.

    • -

\data

    -

  • HelloWorld_reg.rss: Contains registration information about -the application, such as its title.

    • -

  • HelloWorld.rss: Main resource file. Contains additional information -about the application, as well as user interface and text resource definitions. -

    • -

  • HelloWorld.loc, HelloWorld.l01: Localization files. Strings -used by UI are defined in separate localization resource files. Each file -has the format .lxx, where xx is a language specific -numeric file extension - e.g. UK English is ‘01’, French ‘02’ and German ‘03’. -The .loc file is a kind of junction that #includes the -language specific files. The languages are compiled into separate resource -files (extension .rxx; the resource file for the current -language is loaded by the UI framework at runtime

    • -

\gfx

    -

  • list_icon.bmp, list_icon_mask.bmp, mark_icon.bmp, mark_icon_mask.bmp: -Bitmap and bitmap masks. These are compiled into the MultiBitMap (mbm) -format for display in the application.

    • -

  • qgn_menu_HelloWorld.svg: SVG-T image that gets compiled into -the HelloWorld_aif.mif MultiImageFile (mif) -used for the application icon.

    • -

\sis

    -

  • HelloWorld.pkg: Defines the contents that should be packaged -into the installable .sis file for the device. This includes -the executable as well as all resources required by the application (graphics -and so on).

    • -

  • HelloWorld.sis: Compressed and self-contained installation file -for the device. Compiled based on the package file.

    • -

  • HelloWorld.sisx: .sis file which has been signed -with a certificate (in this case self-signed).

    • -
-
Extending -Hello World – Drawing

To make our application a little bit more -interactive, we are going to implement a simple paint tool, allowing the user -to draw lines by touching the screen.

We could draw the lines directly -on the screen, but then everything would get lost when something caused our -application to redraw the screen – for example, a telephone call that came -through while our application was running. Therefore, we have to draw the -lines to a bitmap, which is simply copied to the screen whenever required. -

Another solution (more difficult but also more flexible!) would be -to store all lines in a list and to iterate over the list each time the application -needs to draw the contents of the screen.

-
Using the -SDK Documentation

The class that can handle bitmap data is called CFbsBitmap. -Let’s take a look at the documentation for this class to find out more about -the required header files, libraries and available methods.

Search the -online documentation for the class you're interested in, in this case CFbsBitmap. CFbsBitmap -in Os Font_and_Bitmap_Server should be (one of the) first topics you -find.

If you're working offline you can also search for documentation -in the SDK. Start menu: Start - S60 Developer Tools - 5th Edition -SDK, v1.0 - SDK Documentation

Right at the top of the -reference page you will see that the header file we need to use is FBS.H and -the library we need to link against is called fbscli.lib.

- -

This class is capable of storing a bitmap. It's also possible to -get direct access to the bitmap data. However for more convenient methods -of drawing we will work through a drawing device and context.

To -find out more about bitmaps, contexts and drawing functions, Search for ‘bitmaps’ in the documentation, and go to the page Bitmaps -in Using Bitmaps, or Using Bitmaps in Using Graphics Device Interfaces. - Symbian provides several different device and context classes. For our -application we’re going to use CFbsBitmapDevice (header file: bitdev.h, -library: bitgdi.lib) and CFbsBitGc (header -file: bitstd.h, library: bitgdi.lib).

-
Adding Libraries -To a Project

In the previous step, we determined that we need two -libraries in order to use all three bitmap-related classes: fbscli.lib and bitgdi.lib. -To add them to our project, open the HelloWorld.mmp project -file (in the /group/ folder if you’re using the Project -Explorer window). Switch to the Libraries tab. At the top of -this page, you will see a list of included libraries. fbscli.lib is -already in the list, so we don’t need to add it. However bitgdi.lib is -missing.

There are more libraries in the list than are used by our -project (added by the wizard!). These cause no harm so we choose not to remove -them.

Click on the Add button. Search for bitgdi.lib in -the list and add it to the Libraries list.

- -

When you’re finished, make sure that both libraries are in the Libraries list. -

When you compile your application again, Carbide.c++ will detect -the changes in the .mmp file and ask you what to do. Click on Compile and -Link to update the project with the changes we have made to the .mmp file. - -

-
Creating Bitmaps

Now -the libraries have been added, we can use the bitmap classes in our project. -Open the file HelloWorldContainer.h and add the following -include statements:

#include <fbs.h> -#include <bitdev.h> -#include <bitstd.h> -

We also need to store the bitmap objects as instance (member) -variables. Add the following definitions to a private section of the CHelloWorldContainer class. -Be careful not to write anything into areas managed by the UI designer, because -your changes could be overwritten. These areas are marked by comments. -

private: -CFbsBitmap* iBitmap; -CFbsBitmapDevice* iBmpDevice; -CFbsBitGc* iBmpGc;

Symbian C++ uses some naming conventions. Instance variables should have a lowercase i at -the beginning of the variable name (iBitmap). Arguments should -be marked by an a (aBitmap). Normal local variables that -you create inside a function do not need any prefix. That way, you instantly -know where the variable is coming from – this is very important when deleting -objects. Next, we want to create the bitmap. Define and implement a new -method:

void CHelloWorldContainer::CreateBitmapsL()

Let’s -go line by line through the required code for this method: First, we have -to make sure that any previous objects are deleted if they already exist. -This would be required (for example) if the running application needs to re-create -the bitmap because the screen layout changes. You don’t need to add an if -statement to check if the pointer is NULL beforehand – the C++ delete statement -only deletes the object if the pointer is not NULL. You do however need to -ensure that the objects are set to NULL after deletion to avoid possible "double -deletion" in the destructor.

delete iBitmap; iBitmap = NULL; -delete iBmpDevice; iBmpDevice = NULL; -delete iBmpGc; iBmpGc = NULL;

This following line of code should -look familiar – it simply creates an instance of the CFbsBitmap class: -

iBitmap = new (ELeave) CFbsBitmap();

The -(ELeave) parameter is Symbian C++ specific. This causes a leave (the -Symbian C++ equivalent of standard exceptions) if allocating the object fails -– for example, because there is not enough free memory. With the (ELeave), -you don’t have to manually check if the pointer is actually pointing to a -valid object after creating the object instance. You can find out more about -leaves in Fundamentals -of C++.

We do not handle the potential leave here; that’s -why the method name (CreateBitmapL()) has a trailing L to -show that it can also leave. More on this topic in a moment.

Now, -it’s time to let the CFbsBitmap class allocate the memory -for the bitmap it is going to manage. The available drawing size for our container -can be queried by the method Size() from its base class. EColor16MU specifies -the color depth – in this case, it’s a true color display mode with 32 bits -per pixel; the top byte is unused. The color mode EColor16MA would -use the top byte for the alpha channel, several other modes are available -as well.

iBitmap->Create(Size(), EColor16MU); -

The next line creates a graphics device based on the bitmap. A graphics -device represents the medium being drawn to and is needed to create a graphics -context. The use of a NewL() method is common in Symbian -C++; it is a static factory function which returns a fully constructed object -of the desired type.

iBmpDevice = CFbsBitmapDevice::NewL(iBitmap); -

A graphics context provides a large number of drawing operations, -along with state settings defining how the drawing is performed. The bitmap -graphics context used here is a specialization of the generic graphics context -and adds some methods that can be used for bitmaps only – such as clearing -and copying rectangular areas.

iBmpDevice->CreateContext(iBmpGc); -

Whenever you create objects, it’s best to think about where and when -they are going to be deleted right away. Memory leaks are a serious issue -on a mobile device where no virtual memory is available and the main memory -is limited to 30-80 MB. Therefore, go to the destructor of CHelloWorldContainer and -add the required statements for deleting the three objects:

delete iBmpGc; -delete iBmpDevice; -delete iBitmap;

The next step addresses the remaining -question: where to call the CreateBitmapsL() method. Of course, -you could do this from the construction methods of the class. But what if, -while your application is running, the user physically turns the phone, causing -it to switch from portrait to landscape mode? Because the bitmap was created -with the portrait size in mind, the user would no longer be able to use the -full screen for drawing.

Therefore, we have to react to events that -inform us when the screen size is changed. In those situations, SizeChanged() is -executed. When the container is first constructed, its size changes as well. -Because of this, we can simply call our CreateBitmapsL() method -from within SizeChanged():

void CHelloWorldContainer::SizeChanged() - { - CCoeControl::SizeChanged(); - LayoutControls(); - // [[[ begin generated region: do not modify [Generated Contents] - // ]]] end generated region [Generated Contents] - if (!iBitmap || (iBitmap && iBitmap->SizeInPixels() != Size())) - { - TRAPD(err, CreateBitmapsL()); - } - }

In the source code above, an additional check ensures -that the bitmap is only re-created if the size available for the container -is really different to the existing bitmap size – the SizeChanged() method -is also called, for example, when the option menu obscures part of our view. -This does not affect the available space for our drawing area and therefore -should not lead to re-creating the bitmap.

But what is the TRAPD() statement -doing here? Let’s use this to take a closer look at the concept of leaves.

Leaves

When -programming using Symbian C++, an L is appended to the name of methods that -can leave (usually because it contains other methods that can leave and does -not choose to "TRAP" them). Note: this is a helpful convention, but is not -checked or required by the compiler.

Our CreateBitmapsL() method -contains two methods that can leave: the (ELeave) parameter -causes a leave if there is not enough memory to allocate the object. The NewL() method -from the graphics device also has a trailing L – meaning -that this method can also leave. We did not catch any (all) of those leaves -in the CreateBitmapsL() method so it was named with a trailing L. -

Any leaves are passed up in the call stack until caught by a TRAPD macro. -The SizeChanged() method traps any leaves from CreateBitmapsL() and -consequently does not need to have a trailing L. -

The error code of the leave is stored in the err variable, which -is declared as a normal integer by this macro. It would be a good idea to -take a look at the contents of this variable and to handle errors instead -of ignoring them as we’re doing here. But for the sake of simplicity, we do -not handle any errors that might occur in this situation.

Tip

A -good way to automatically check your code for potential problems is to use -the CodeScanner tool that comes with Carbide.c++. It is a static code-analysis -tool looking at Symbian coding rules and standards. Find out more at: http://carbidehelp.nokia.com/help/topic/com.nokia.carbide.cpp.codescanner/html/codescanner.htm

-
Handling Touch -Events

Before we start handling the touch events, we need one more -instance variable in our code. To draw a line from one touch position to the -next, it’s necessary to save the first position. Therefore, add the following -private instance variable to CHelloWorldContainer: TPoint iLastPos;

TPoint is -a convenience class that stores two integers that can be used as co-ordinates. -Additionally, it provides some methods to modify the point. We do not need -to initialize the variable in the constructor of the CHelloWorldContainer class -– the container class is indirectly derived from the class CBase, -which automatically zero-initializes all member variables. Touch events -are delivered to the container class, which is responsible for managing the -visible UI content in the main pane of your application. To handle the events -ourselves, we have to override the following method in CHelloWorldContainer:

void -CHelloWorldContainer::HandlePointerEventL(const TPointerEvent& aPointerEvent)

Define -this method in the header file (can be private or protected) and add its implementation -in the .cpp file. The information about the new event -is sent through the argument aPointerEvent. We are interested -in the up event for the first button (there is only one in current touch devices; -you can’t click with a right button as you would with a mouse). Whenever the -user releases the stylus or finger from the touch screen, we want to draw -a line to this position. Put the following code into this if statement: if (aPointerEvent.iType == TPointerEvent::EButton1Up) - { - }

Drawing the line itself is rather simple. First, define -the color and style that should be used for drawing, then call the function -for drawing the line. Note that the settings concerning the color and style -stay active until they are changed again in this graphics context – you do -not need to set them every time when executing consecutive drawing operations.

iBmpGc->SetPenColor(KRgbRed); -iBmpGc->SetPenSize(TSize(2,2)); -iBmpGc->DrawLine(iLastPos, aPointerEvent.iPosition);

Next, we -have to save the new position, because it will be required as the starting -point for the next line.

iLastPos = aPointerEvent.iPosition;

Finally, -issue a request to the framework to redraw the screen. Otherwise, the user -won’t see the new line!

DrawDeferred();

At the end -of the method, also call the HandlePointerEventL() method -of the base class (the container is derived from CCoeControl, -because it is a normal UI control by itself):

CCoeControl::HandlePointerEventL(aPointerEvent);

To -sum it up, this is the final code for the HandlePointerEvent() method:

void CHelloWorldContainer::HandlePointerEventL(const TPointerEvent& aPointerEvent) - { - if (aPointerEvent.iType == TPointerEvent::EButton1Up) - { - iBmpGc->SetPenColor(KRgbRed); - iBmpGc->SetPenSize(TSize(2,2)); - iBmpGc->DrawLine(iLastPos, aPointerEvent.iPosition); - iLastPos = aPointerEvent.iPosition; - DrawDeferred(); - } - CCoeControl::HandlePointerEventL(aPointerEvent); - }

We’ve already added all the code required for drawing -to the bitmap, but this bitmap still has to be transferred to the screen. -The CHelloWorldContainer::Draw() method is called when the -system wants the contents of the container to be redrawn. Therefore, we need -to add the following line of code to the end of the Draw() method, -which copies the bitmap to the top left of the graphics context of the screen:

gc.BitBlt(TPoint(0, -0), iBitmap);

Now compile the project. It should already work – -you can draw red lines by just clicking inside the main pane of the emulator!

- -
-
Defining -a Menu

The application would be improved if the user could clear -the drawing during use, rather than having to restart it. This section shows -how you add and handle menu items to provide this functionality, and to exit -the application Open the HelloWorldContainer.uidesign document. -You can find it in the root folder of your project in the Project Explorer or -in the UI Designs folder of the Symbian Project Navigator.

Click -on the Options menu item below the UI design to reveal the menu. As -indicated, you simply need to click on the empty menu item and start typing.

- -

Add two menu items – Clear (for clearing the image) and Exit (for -closing the application).

Then click once on the Exit menu item -to select it. Go to the Behavior group of the Properties window -and change the command ID to EAknCmdExit (this is available -in the drop-down list). This command will also be sent to your application -if the operating system wants to shut it down, for example, when the phone -does not have enough memory left. Therefore, it is necessary that every application -always responds to this event and instantly shuts the application down. It -is already handled by the basic application that the Carbide.c++ wizard generated -for you; you don’t need to implement the command handling for this event yourself.

- -

If you try your application now, you will see that the Exit menu -item already works.

Tip

When testing the application, -always quit your application using the Exit command (rather than just -closing the emulator). The application environment will then automatically -check for memory leaks. If you just shut down the emulator you may not discover -the leak until much later, making it a lot more difficult to find the cause.

-
Clearing the -Drawing

Whenever the Clear menu item is selected the view -class method CHelloWorldContainerView::HandleCommandL() is -called with the command ID of the menu item as a parameter.

If we -want to handle the menu item, the UI designer can create the necessary code -for us. Right-click on the menu item and choose Handle ‘selected’ Event. -The UI designer will ask you to save the design – choose Yes. The code -will then be generated and you will jump into the code view to a new method -called HandleClearMenuItemSelectedL() – a more convenient -place to put your command-handling code than directly in a big HandleCommandL() method -that receives all commands. The auto-generated source code therefore calls -the new extra method from within HandleCommandL() (take a -look at that method to see what really happens).

- -

Now, we only need to tell the container that it should clear its -bitmap buffer. To do this, create a new public method in the container:

void CHelloWorldContainer::ClearDrawing() - { - iBmpGc->Clear(); - DrawDeferred(); - }

Now, call this method from the menu item handler method. -As explained in the section about the application architecture, the view class -(CHelloWorldContainerView) is the controller and owner for/of -the container class (CHelloWorldContainer). Therefore, this -class has a pointer to the container as an instance variable, which you can -use to clear the drawing.

TBool CHelloWorldContainerView::HandleClearMenuItemSelectedL(TInt aCommand) - { - iHelloWorldContainer->ClearDrawing(); - return ETrue; - }

The menu command should now clear the image.

Congratulations, -you have completed the tutorial and have created your own small mobile painting -application!

-
Further Exercises

As -an exercise, it’s a good idea to extend the application by yourself – for -example, you could add some menu items that allow the end user to change the -color of the pen.

Tip

It’s a good idea to learn -keyboard shortcuts as early as possible, because they can significantly increase -the efficiency of your work. For example, you can press Ctrl + B to -build the project, instead of using the icon or the menu commands. Also very -helpful: Ctrl + Shift + F automatically formats and indents your code. -You can get a full list of commands by pressing Ctrl + 3. A hot keys -list appears when you press Ctrl + Shift + L.

Importing -Other Examples

The S60 SDK itself installs many examples; additional -applications can be downloaded from the developer.symbian.org and Forum Nokia -(see the Related Info section for more information). To import ready-made -applications in Carbide.c++, go to File | Import. In the following -dialog, select Symbian OS Bld.inf file and click Next.

- -

Now, click Browse and navigate to the bld.inf file -of the project you want to import. It’s usually stored in the /group/ subfolder -of the project.

- -

In the following step, select which SDKs you would like to use. The -same considerations as those explained when creating your Hello World application -apply.

- -

You can usually accept the default values for the next step and let -the wizard import everything.

In the last step, you have to define -the Project Properties. In most cases, you can leave the default values.

- -

Afterwards, the project is imported and you can start working. The -project contents will not be copied to the current Carbide.c++ workspace, -so you will work directly on the original directory and the original files. -Copy the project to a different directory first if you want to keep the original -project or example in its original state – for example, into the workspace -directory.

Troubleshooting: If importing the -project fails, take special care of the last step of the import process: the -root directory should be set correctly to the root directory of the project -and not one level above it. Also, the project name should be the same as the -last part of the root directory. From time to time, the default values are -not configured properly, causing problems in the import process.

Warning

Do -not use the standard (Eclipse) project import! The reason is that this import -method would also import all build configuration settings, including references -to installed SDKs and paths on the original system. Therefore, if you import -a project from somebody else but don’t have the SDK installed in exactly the -same directory, the build configurations will no longer work. The bld.inf import -method recreates the SDK bindings and only imports the real contents of the -project.

-
Summary

This -part of the tutorial has shown how we can extend the basic skeleton from the Symbian C++ Quick Start to -create a small paint application. The tutorial explains the application framework, -including how you define menus, how to handle touch-screen events, drawing -to the screen etc.

-
Related Info
    -

  • Symbian C++ -Quick Start

    • -

  • Getting -Started with Debugging on the Device

    • -

  • File: -HelloSymbianWorld Example Code.zip (code example associated with this -article)

    • -
+ + + + + +Going +Beyond Hello: A Tutorial for Symbian C++ ApplicationsThis tutorial shows how you can extend that basic example to create +a small paint application, along the way learning more about the application +frameworks (e.g. defining menus, how to handle touch-screen events, drawing +to the screen etc.). +

In the Symbian C++ +Quick Start you learned how to create a basic example application using +Carbide.c++, and how to build and run it on the Windows emulator and on a +device.

+

Comes with Code: File: +HelloSymbianWorld Example Code.zip

+
Application +Structure

Carbide.c++ offers two ways of exploring your project. +The traditional Project Explorer window, which can also be found in +Eclipse, lists the files belonging to the project in the same directory structure +as in the file system.

The Symbian Project Navigator contains +the same contents, but displays them in a logical hierarchy according to Symbian +Conventions.

You might wonder why a basic "Hello World" application +contains so many files. The answer is straightforward - a much simpler Hello +World wouldn’t be a very good starting point for real-world applications. +

Instead the wizard generates the project for a complete and readily +extensible application. The project separates code and data, and uses a form +of the model +view controller pattern for structuring your code. The application +already reacts to system events and contains everything that is required for +localization.

What are the directories of a project? + +

\group

    +

  • bld.inf: Component-definition file. This specifies the mmp files +that belong to your component, any shared header files that it exports, and +the default build targets (e.g. GCCE, WINSCW).

      +

    • Bld.inf is used to generate the makefiles and abld.bat used +to build for the command-line (see Symbian +C++ Quick Start).

      • +

    • This file is the starting point when you want to import a Symbian C++ +project into Carbide.c++, because it contains references to all executables +in your project (see the section on Importing Other Examples).

      • +
    • +

  • HelloWorld.mmp: Project-definition file. This specifies how +to build an executable (in this case HelloWorld.exe) in a +platform- and compiler-independent way. It contains information such as resource +files to be compiled, source files to include when compiling, and the libraries +to include when linking.

    • +

  • Icons_aif_scalable_dc.mk: Makefile used to create the application's +icon from the *.svg file in the /gfx folder.

    • +

\src

    +

  • HelloWorldApplication.cpp: This file contains the entry point +for the EXE file (E32Main()) as well as the implementation +of the Application class (which provides some basic functionality for the +GUI framework). Normally this is "boilerplate" code and you do not need to +make any changes.

    • +

  • HelloWorldDocument.cpp: This class is supposed to take care +of the persistent data model of your application and therefore provides some +functions to load and save .ini files. This mechanism is +disabled by default - for most applications you may treat this as "boilerplate" +code.

    • +

  • HelloWorldAppUi.cpp: This is the main controller of your application. +It contains the logic for handling application-wide events (so you don’t have +to handle, for example, the exit event in every view). It owns all the views +that you use.

    • +

  • HelloWorldContainerView.cpp: This is a kind of controller, which +is responsible for handling events and the UI elements of the currently visible +view. It’s not visible itself, but owns and manages the Container (below), +which corresponds to the view in the traditional model view controller pattern.

    • +

  • HelloWorldContainer.cpp: Contains the UI elements that should +be displayed by the view. Therefore, the ContainerView and the Container usually +have a very strong relationship.

    • +

During start-up, one class instance creates the next:

+ +

\inc

    +

  • HelloWorldApplication.h, HelloWorldDocument.h, HelloWorldAppUi.h, HelloWorldContainerView.h, HelloWorldContainer.h: Header files corresponding to each of the main source files above.

    • +

  • HelloWorld.hrh: UIDs/identifiers for UI elements including views. +These are shared between the resource file definitions for UI elements and +the source code command handlers.

    • +

  • HelloWorld.pan: Panic code and method definitions.

    • +

\data

    +

  • HelloWorld_reg.rss: Contains registration information about +the application, such as its title.

    • +

  • HelloWorld.rss: Main resource file. Contains additional information +about the application, as well as user interface and text resource definitions. +

    • +

  • HelloWorld.loc, HelloWorld.l01: Localization files. Strings +used by UI are defined in separate localization resource files. Each file +has the format .lxx, where xx is a language specific +numeric file extension - e.g. UK English is ‘01’, French ‘02’ and German ‘03’. +The .loc file is a kind of junction that #includes the +language specific files. The languages are compiled into separate resource +files (extension .rxx; the resource file for the current +language is loaded by the UI framework at runtime

    • +

\gfx

    +

  • list_icon.bmp, list_icon_mask.bmp, mark_icon.bmp, mark_icon_mask.bmp: +Bitmap and bitmap masks. These are compiled into the MultiBitMap (mbm) +format for display in the application.

    • +

  • qgn_menu_HelloWorld.svg: SVG-T image that gets compiled into +the HelloWorld_aif.mif MultiImageFile (mif) +used for the application icon.

    • +

\sis

    +

  • HelloWorld.pkg: Defines the contents that should be packaged +into the installable .sis file for the device. This includes +the executable as well as all resources required by the application (graphics +and so on).

    • +

  • HelloWorld.sis: Compressed and self-contained installation file +for the device. Compiled based on the package file.

    • +

  • HelloWorld.sisx: .sis file which has been signed +with a certificate (in this case self-signed).

    • +
+
Extending +Hello World – Drawing

To make our application a little bit more +interactive, we are going to implement a simple paint tool, allowing the user +to draw lines by touching the screen.

We could draw the lines directly +on the screen, but then everything would get lost when something caused our +application to redraw the screen – for example, a telephone call that came +through while our application was running. Therefore, we have to draw the +lines to a bitmap, which is simply copied to the screen whenever required. +

Another solution (more difficult but also more flexible!) would be +to store all lines in a list and to iterate over the list each time the application +needs to draw the contents of the screen.

+
Using the +SDK Documentation

The class that can handle bitmap data is called CFbsBitmap. +Let’s take a look at the documentation for this class to find out more about +the required header files, libraries and available methods.

Search the +online documentation for the class you're interested in, in this case CFbsBitmap. CFbsBitmap +in Os Font_and_Bitmap_Server should be (one of the) first topics you +find.

If you're working offline you can also search for documentation +in the SDK. Start menu: Start - S60 Developer Tools - 5th Edition +SDK, v1.0 - SDK Documentation

Right at the top of the +reference page you will see that the header file we need to use is FBS.H and +the library we need to link against is called fbscli.lib.

+ +

This class is capable of storing a bitmap. It's also possible to +get direct access to the bitmap data. However for more convenient methods +of drawing we will work through a drawing device and context.

To +find out more about bitmaps, contexts and drawing functions, Search for ‘bitmaps’ in the documentation, and go to the page Bitmaps +in Using Bitmaps, or Using Bitmaps in Using Graphics Device Interfaces. + Symbian provides several different device and context classes. For our +application we’re going to use CFbsBitmapDevice (header file: bitdev.h, +library: bitgdi.lib) and CFbsBitGc (header +file: bitstd.h, library: bitgdi.lib).

+
Adding Libraries +To a Project

In the previous step, we determined that we need two +libraries in order to use all three bitmap-related classes: fbscli.lib and bitgdi.lib. +To add them to our project, open the HelloWorld.mmp project +file (in the /group/ folder if you’re using the Project +Explorer window). Switch to the Libraries tab. At the top of +this page, you will see a list of included libraries. fbscli.lib is +already in the list, so we don’t need to add it. However bitgdi.lib is +missing.

There are more libraries in the list than are used by our +project (added by the wizard!). These cause no harm so we choose not to remove +them.

Click on the Add button. Search for bitgdi.lib in +the list and add it to the Libraries list.

+ +

When you’re finished, make sure that both libraries are in the Libraries list. +

When you compile your application again, Carbide.c++ will detect +the changes in the .mmp file and ask you what to do. Click on Compile and +Link to update the project with the changes we have made to the .mmp file. + +

+
Creating Bitmaps

Now +the libraries have been added, we can use the bitmap classes in our project. +Open the file HelloWorldContainer.h and add the following +include statements:

#include <fbs.h> +#include <bitdev.h> +#include <bitstd.h> +

We also need to store the bitmap objects as instance (member) +variables. Add the following definitions to a private section of the CHelloWorldContainer class. +Be careful not to write anything into areas managed by the UI designer, because +your changes could be overwritten. These areas are marked by comments. +

private: +CFbsBitmap* iBitmap; +CFbsBitmapDevice* iBmpDevice; +CFbsBitGc* iBmpGc;

Symbian C++ uses some naming conventions. Instance variables should have a lowercase i at +the beginning of the variable name (iBitmap). Arguments should +be marked by an a (aBitmap). Normal local variables that +you create inside a function do not need any prefix. That way, you instantly +know where the variable is coming from – this is very important when deleting +objects. Next, we want to create the bitmap. Define and implement a new +method:

void CHelloWorldContainer::CreateBitmapsL()

Let’s +go line by line through the required code for this method: First, we have +to make sure that any previous objects are deleted if they already exist. +This would be required (for example) if the running application needs to re-create +the bitmap because the screen layout changes. You don’t need to add an if +statement to check if the pointer is NULL beforehand – the C++ delete statement +only deletes the object if the pointer is not NULL. You do however need to +ensure that the objects are set to NULL after deletion to avoid possible "double +deletion" in the destructor.

delete iBitmap; iBitmap = NULL; +delete iBmpDevice; iBmpDevice = NULL; +delete iBmpGc; iBmpGc = NULL;

This following line of code should +look familiar – it simply creates an instance of the CFbsBitmap class: +

iBitmap = new (ELeave) CFbsBitmap();

The +(ELeave) parameter is Symbian C++ specific. This causes a leave (the +Symbian C++ equivalent of standard exceptions) if allocating the object fails +– for example, because there is not enough free memory. With the (ELeave), +you don’t have to manually check if the pointer is actually pointing to a +valid object after creating the object instance. You can find out more about +leaves in Fundamentals +of C++.

We do not handle the potential leave here; that’s +why the method name (CreateBitmapL()) has a trailing L to +show that it can also leave. More on this topic in a moment.

Now, +it’s time to let the CFbsBitmap class allocate the memory +for the bitmap it is going to manage. The available drawing size for our container +can be queried by the method Size() from its base class. EColor16MU specifies +the color depth – in this case, it’s a true color display mode with 32 bits +per pixel; the top byte is unused. The color mode EColor16MA would +use the top byte for the alpha channel, several other modes are available +as well.

iBitmap->Create(Size(), EColor16MU); +

The next line creates a graphics device based on the bitmap. A graphics +device represents the medium being drawn to and is needed to create a graphics +context. The use of a NewL() method is common in Symbian +C++; it is a static factory function which returns a fully constructed object +of the desired type.

iBmpDevice = CFbsBitmapDevice::NewL(iBitmap); +

A graphics context provides a large number of drawing operations, +along with state settings defining how the drawing is performed. The bitmap +graphics context used here is a specialization of the generic graphics context +and adds some methods that can be used for bitmaps only – such as clearing +and copying rectangular areas.

iBmpDevice->CreateContext(iBmpGc); +

Whenever you create objects, it’s best to think about where and when +they are going to be deleted right away. Memory leaks are a serious issue +on a mobile device where no virtual memory is available and the main memory +is limited to 30-80 MB. Therefore, go to the destructor of CHelloWorldContainer and +add the required statements for deleting the three objects:

delete iBmpGc; +delete iBmpDevice; +delete iBitmap;

The next step addresses the remaining +question: where to call the CreateBitmapsL() method. Of course, +you could do this from the construction methods of the class. But what if, +while your application is running, the user physically turns the phone, causing +it to switch from portrait to landscape mode? Because the bitmap was created +with the portrait size in mind, the user would no longer be able to use the +full screen for drawing.

Therefore, we have to react to events that +inform us when the screen size is changed. In those situations, SizeChanged() is +executed. When the container is first constructed, its size changes as well. +Because of this, we can simply call our CreateBitmapsL() method +from within SizeChanged():

void CHelloWorldContainer::SizeChanged() + { + CCoeControl::SizeChanged(); + LayoutControls(); + // [[[ begin generated region: do not modify [Generated Contents] + // ]]] end generated region [Generated Contents] + if (!iBitmap || (iBitmap && iBitmap->SizeInPixels() != Size())) + { + TRAPD(err, CreateBitmapsL()); + } + }

In the source code above, an additional check ensures +that the bitmap is only re-created if the size available for the container +is really different to the existing bitmap size – the SizeChanged() method +is also called, for example, when the option menu obscures part of our view. +This does not affect the available space for our drawing area and therefore +should not lead to re-creating the bitmap.

But what is the TRAPD() statement +doing here? Let’s use this to take a closer look at the concept of leaves.

Leaves

When +programming using Symbian C++, an L is appended to the name of methods that +can leave (usually because it contains other methods that can leave and does +not choose to "TRAP" them). Note: this is a helpful convention, but is not +checked or required by the compiler.

Our CreateBitmapsL() method +contains two methods that can leave: the (ELeave) parameter +causes a leave if there is not enough memory to allocate the object. The NewL() method +from the graphics device also has a trailing L – meaning +that this method can also leave. We did not catch any (all) of those leaves +in the CreateBitmapsL() method so it was named with a trailing L. +

Any leaves are passed up in the call stack until caught by a TRAPD macro. +The SizeChanged() method traps any leaves from CreateBitmapsL() and +consequently does not need to have a trailing L. +

The error code of the leave is stored in the err variable, which +is declared as a normal integer by this macro. It would be a good idea to +take a look at the contents of this variable and to handle errors instead +of ignoring them as we’re doing here. But for the sake of simplicity, we do +not handle any errors that might occur in this situation.

Tip

A +good way to automatically check your code for potential problems is to use +the CodeScanner tool that comes with Carbide.c++. It is a static code-analysis +tool looking at Symbian coding rules and standards. Find out more at: http://carbidehelp.nokia.com/help/topic/com.nokia.carbide.cpp.codescanner/html/codescanner.htm

+
Handling Touch +Events

Before we start handling the touch events, we need one more +instance variable in our code. To draw a line from one touch position to the +next, it’s necessary to save the first position. Therefore, add the following +private instance variable to CHelloWorldContainer: TPoint iLastPos;

TPoint is +a convenience class that stores two integers that can be used as co-ordinates. +Additionally, it provides some methods to modify the point. We do not need +to initialize the variable in the constructor of the CHelloWorldContainer class +– the container class is indirectly derived from the class CBase, +which automatically zero-initializes all member variables. Touch events +are delivered to the container class, which is responsible for managing the +visible UI content in the main pane of your application. To handle the events +ourselves, we have to override the following method in CHelloWorldContainer:

void +CHelloWorldContainer::HandlePointerEventL(const TPointerEvent& aPointerEvent)

Define +this method in the header file (can be private or protected) and add its implementation +in the .cpp file. The information about the new event +is sent through the argument aPointerEvent. We are interested +in the up event for the first button (there is only one in current touch devices; +you can’t click with a right button as you would with a mouse). Whenever the +user releases the stylus or finger from the touch screen, we want to draw +a line to this position. Put the following code into this if statement: if (aPointerEvent.iType == TPointerEvent::EButton1Up) + { + }

Drawing the line itself is rather simple. First, define +the color and style that should be used for drawing, then call the function +for drawing the line. Note that the settings concerning the color and style +stay active until they are changed again in this graphics context – you do +not need to set them every time when executing consecutive drawing operations.

iBmpGc->SetPenColor(KRgbRed); +iBmpGc->SetPenSize(TSize(2,2)); +iBmpGc->DrawLine(iLastPos, aPointerEvent.iPosition);

Next, we +have to save the new position, because it will be required as the starting +point for the next line.

iLastPos = aPointerEvent.iPosition;

Finally, +issue a request to the framework to redraw the screen. Otherwise, the user +won’t see the new line!

DrawDeferred();

At the end +of the method, also call the HandlePointerEventL() method +of the base class (the container is derived from CCoeControl, +because it is a normal UI control by itself):

CCoeControl::HandlePointerEventL(aPointerEvent);

To +sum it up, this is the final code for the HandlePointerEvent() method:

void CHelloWorldContainer::HandlePointerEventL(const TPointerEvent& aPointerEvent) + { + if (aPointerEvent.iType == TPointerEvent::EButton1Up) + { + iBmpGc->SetPenColor(KRgbRed); + iBmpGc->SetPenSize(TSize(2,2)); + iBmpGc->DrawLine(iLastPos, aPointerEvent.iPosition); + iLastPos = aPointerEvent.iPosition; + DrawDeferred(); + } + CCoeControl::HandlePointerEventL(aPointerEvent); + }

We’ve already added all the code required for drawing +to the bitmap, but this bitmap still has to be transferred to the screen. +The CHelloWorldContainer::Draw() method is called when the +system wants the contents of the container to be redrawn. Therefore, we need +to add the following line of code to the end of the Draw() method, +which copies the bitmap to the top left of the graphics context of the screen:

gc.BitBlt(TPoint(0, +0), iBitmap);

Now compile the project. It should already work – +you can draw red lines by just clicking inside the main pane of the emulator!

+ +
+
Defining +a Menu

The application would be improved if the user could clear +the drawing during use, rather than having to restart it. This section shows +how you add and handle menu items to provide this functionality, and to exit +the application Open the HelloWorldContainer.uidesign document. +You can find it in the root folder of your project in the Project Explorer or +in the UI Designs folder of the Symbian Project Navigator.

Click +on the Options menu item below the UI design to reveal the menu. As +indicated, you simply need to click on the empty menu item and start typing.

+ +

Add two menu items – Clear (for clearing the image) and Exit (for +closing the application).

Then click once on the Exit menu item +to select it. Go to the Behavior group of the Properties window +and change the command ID to EAknCmdExit (this is available +in the drop-down list). This command will also be sent to your application +if the operating system wants to shut it down, for example, when the phone +does not have enough memory left. Therefore, it is necessary that every application +always responds to this event and instantly shuts the application down. It +is already handled by the basic application that the Carbide.c++ wizard generated +for you; you don’t need to implement the command handling for this event yourself.

+ +

If you try your application now, you will see that the Exit menu +item already works.

Tip

When testing the application, +always quit your application using the Exit command (rather than just +closing the emulator). The application environment will then automatically +check for memory leaks. If you just shut down the emulator you may not discover +the leak until much later, making it a lot more difficult to find the cause.

+
Clearing the +Drawing

Whenever the Clear menu item is selected the view +class method CHelloWorldContainerView::HandleCommandL() is +called with the command ID of the menu item as a parameter.

If we +want to handle the menu item, the UI designer can create the necessary code +for us. Right-click on the menu item and choose Handle ‘selected’ Event. +The UI designer will ask you to save the design – choose Yes. The code +will then be generated and you will jump into the code view to a new method +called HandleClearMenuItemSelectedL() – a more convenient +place to put your command-handling code than directly in a big HandleCommandL() method +that receives all commands. The auto-generated source code therefore calls +the new extra method from within HandleCommandL() (take a +look at that method to see what really happens).

+ +

Now, we only need to tell the container that it should clear its +bitmap buffer. To do this, create a new public method in the container:

void CHelloWorldContainer::ClearDrawing() + { + iBmpGc->Clear(); + DrawDeferred(); + }

Now, call this method from the menu item handler method. +As explained in the section about the application architecture, the view class +(CHelloWorldContainerView) is the controller and owner for/of +the container class (CHelloWorldContainer). Therefore, this +class has a pointer to the container as an instance variable, which you can +use to clear the drawing.

TBool CHelloWorldContainerView::HandleClearMenuItemSelectedL(TInt aCommand) + { + iHelloWorldContainer->ClearDrawing(); + return ETrue; + }

The menu command should now clear the image.

Congratulations, +you have completed the tutorial and have created your own small mobile painting +application!

+
Further Exercises

As +an exercise, it’s a good idea to extend the application by yourself – for +example, you could add some menu items that allow the end user to change the +color of the pen.

Tip

It’s a good idea to learn +keyboard shortcuts as early as possible, because they can significantly increase +the efficiency of your work. For example, you can press Ctrl + B to +build the project, instead of using the icon or the menu commands. Also very +helpful: Ctrl + Shift + F automatically formats and indents your code. +You can get a full list of commands by pressing Ctrl + 3. A hot keys +list appears when you press Ctrl + Shift + L.

Importing +Other Examples

The S60 SDK itself installs many examples; additional +applications can be downloaded from the developer.symbian.org and Forum Nokia +(see the Related Info section for more information). To import ready-made +applications in Carbide.c++, go to File | Import. In the following +dialog, select Symbian OS Bld.inf file and click Next.

+ +

Now, click Browse and navigate to the bld.inf file +of the project you want to import. It’s usually stored in the /group/ subfolder +of the project.

+ +

In the following step, select which SDKs you would like to use. The +same considerations as those explained when creating your Hello World application +apply.

+ +

You can usually accept the default values for the next step and let +the wizard import everything.

In the last step, you have to define +the Project Properties. In most cases, you can leave the default values.

+ +

Afterwards, the project is imported and you can start working. The +project contents will not be copied to the current Carbide.c++ workspace, +so you will work directly on the original directory and the original files. +Copy the project to a different directory first if you want to keep the original +project or example in its original state – for example, into the workspace +directory.

Troubleshooting: If importing the +project fails, take special care of the last step of the import process: the +root directory should be set correctly to the root directory of the project +and not one level above it. Also, the project name should be the same as the +last part of the root directory. From time to time, the default values are +not configured properly, causing problems in the import process.

Warning

Do +not use the standard (Eclipse) project import! The reason is that this import +method would also import all build configuration settings, including references +to installed SDKs and paths on the original system. Therefore, if you import +a project from somebody else but don’t have the SDK installed in exactly the +same directory, the build configurations will no longer work. The bld.inf import +method recreates the SDK bindings and only imports the real contents of the +project.

+
Summary

This +part of the tutorial has shown how we can extend the basic skeleton from the Symbian C++ Quick Start to +create a small paint application. The tutorial explains the application framework, +including how you define menus, how to handle touch-screen events, drawing +to the screen etc.

+
Related Info
    +

  • Symbian C++ +Quick Start

    • +

  • Getting +Started with Debugging on the Device

    • +

  • File: +HelloSymbianWorld Example Code.zip (code example associated with this +article)

    • +
 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0C85D5DE-D78D-4DDB-BA00-6278690C1047.dita --- a/Symbian3/SDK/Source/GUID-0C85D5DE-D78D-4DDB-BA00-6278690C1047.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,16 +0,0 @@ - - - - - -Changes -and release information -

The Touch UI utilities API is an SDK API and first released in S60 5th -Edition.

- \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0CA7F22E-59D7-4D65-9D6C-735E4E0F0454.dita --- a/Symbian3/SDK/Source/GUID-0CA7F22E-59D7-4D65-9D6C-735E4E0F0454.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-0CA7F22E-59D7-4D65-9D6C-735E4E0F0454.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,64 +1,64 @@ - - - - - -Setting -Channel PropertiesThe channel properties can be configured using the CSensrvChannel::SetProperty() function. -

Before setting -channel properties, you must open -the sensor channel.

 - -Create a TSensrvProperty property -object for setting the KSensrvPropIdDataRate property -using the TSensrvProperty(const TSensrvPropertyId,const TInt,const -TInt) constructor. -... -TInt val=2; -TSensrvProperty sensrvProperty(KSensrvPropIdDataRate,KSensrvItemIndexNone,val); -... - -Set the KSensrvPropIdDataRate property -value by passing the property object that you created to CSensrvChannel::SetProperty(). -... -CSensrvChannel* channel; -... -TInt ret; -ret=channel->SetProperty(sensrvProperty); -... - - -

The following example explains how to set the x-axis of accelerometer -channel status from activated to deactivated.

The axis active property KSensrvPropIdAxisActive is -first retrieved using the CSensrvChannel::GetPropertyL() function. -If the axis is active, the new deactivated value is set in the retrieved -property object. Then the channel is updated with this updated property object -by using the CSensrvChannel::SetProperty() function.

TSensrvProperty property; - TInt err( KErrNone ); - TInt axisActive( 0 ); - iSensorChannel->GetPropertyL( KSensrvPropIdAxisActive, - TSensrvAccelerometerAxisData::Index::iAxisX, - property ); - property.GetValue( axisActive ); - if( 1 == axisActive ) - { - property.SetValue( 0 ); // A value other than 1 means that sensor axis is deactivated. - err = iSensorChannel->SetProperty( property ); - if( KErrNone == err ) - { - //Accelerometer x-axis was successfully deactivated - } - } - else - { - //Accelerometer x-axis is already inactive - } -

End the session -with the sensor channel using the CSensrvChannel::CloseChannel() function.

 + + + + + +Setting +Channel PropertiesThe channel properties can be configured using the CSensrvChannel::SetProperty() function. +

Before setting +channel properties, you must open +the sensor channel.

 + +Create a TSensrvProperty property +object for setting the KSensrvPropIdDataRate property +using the TSensrvProperty(const TSensrvPropertyId,const TInt,const +TInt) constructor. +... +TInt val=2; +TSensrvProperty sensrvProperty(KSensrvPropIdDataRate,KSensrvItemIndexNone,val); +... + +Set the KSensrvPropIdDataRate property +value by passing the property object that you created to CSensrvChannel::SetProperty(). +... +CSensrvChannel* channel; +... +TInt ret; +ret=channel->SetProperty(sensrvProperty); +... + + +

The following example explains how to set the x-axis of accelerometer +channel status from activated to deactivated.

The axis active property KSensrvPropIdAxisActive is +first retrieved using the CSensrvChannel::GetPropertyL() function. +If the axis is active, the new deactivated value is set in the retrieved +property object. Then the channel is updated with this updated property object +by using the CSensrvChannel::SetProperty() function.

TSensrvProperty property; + TInt err( KErrNone ); + TInt axisActive( 0 ); + iSensorChannel->GetPropertyL( KSensrvPropIdAxisActive, + TSensrvAccelerometerAxisData::Index::iAxisX, + property ); + property.GetValue( axisActive ); + if( 1 == axisActive ) + { + property.SetValue( 0 ); // A value other than 1 means that sensor axis is deactivated. + err = iSensorChannel->SetProperty( property ); + if( KErrNone == err ) + { + //Accelerometer x-axis was successfully deactivated + } + } + else + { + //Accelerometer x-axis is already inactive + } +

End the session +with the sensor channel using the CSensrvChannel::CloseChannel() function.

 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0CA8B17D-92D7-4293-B611-E0DDA05A6579_d0e36090_href.png Binary file Symbian3/SDK/Source/GUID-0CA8B17D-92D7-4293-B611-E0DDA05A6579_d0e36090_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0CA8B17D-92D7-4293-B611-E0DDA05A6579_d0e41657_href.png Binary file Symbian3/SDK/Source/GUID-0CA8B17D-92D7-4293-B611-E0DDA05A6579_d0e41657_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0CBD2728-DB7E-55FF-929A-E5BF279A1B66.dita --- a/Symbian3/SDK/Source/GUID-0CBD2728-DB7E-55FF-929A-E5BF279A1B66.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-0CBD2728-DB7E-55FF-929A-E5BF279A1B66.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,75 +1,75 @@ - - - - - -BIOMessageMgr: -BIO Message manager using the message server -

The BIO Message manager example comprises two projects BIOMessage.exe and BIOParser.dll. -The BIOMessage.exe example connects to the message server, -creates a BIO message and sends the registered parser DLL and message entry -to BIOParser.dll.

-
Download

Click -on the following link to download the example: Biomsgexample.zip

Click: browse to view the example code.

-
BIOMessage: BIO messaging using the message server

Description

This -example code demonstrates BIO messaging using RSendAs and RSendAsMessage and -other supporting classes as mentioned in the Class -Summary below.

The BIOMessage example -code provides the following functionality:

Creating a session

void CBioMessage::Connect();

Creates -a session with the message server using RSendAs.

The -generated console output looks like this:

- -

Creating a BIO message

void CBioMessage::Create(RSendAsMessage& aMessage);

This function does the following:

    -

  • creates a BIO message -of VCard type

    • -

  • sets the message body -text

    • -

  • adds the message recipients -for the message to be sent.

    • -

The generated console output looks like this:

- -

Sending the BIO message

void CBioMessage::Send(RSendAsMessage& aMessage);

Sends the message to the recipients.

The generated console output -looks like this:

- -

Creating the parser

CBioParser::NewL(CMsvEntry* aEntry);

Creates a CBioParser object based on the message entry.

Parsing -the BIO message

CBioParser::ParserL();

This -function does the following:

    -

  • calls ExtractMessageBodyL() to -extract the message body text from CMsvStore, the message -store

    • -

  • finds, loads and maintains -a reference count of client processes for a BIO parser DLL

    • -

  • parses the message body -text.

    • -

The generated console output looks like this:

- -

Class Summary

RSendAs

RSendAsMessage

CSendAsMessageTypes

CSendAsAccounts

CRegisteredParserDll

CBIODatabase

CMsvStore

-
BIOParser: BIO message parsing

Description

This -example code demonstrates the parsing of the message. CBIOExampleParser is -the wrapper class which uses CBaseScriptParser2 and other -supporting classes mentioned in the Class -Summary below.

The BIOParser example code -provides the following functionality:

Creating the parser

CBIOExampleParser* CBIOExampleParser::NewL(CRegisteredParserDll& aRegisteredParserDll, CMsvEntry& aEntry, RFs& aFs);

Creates a CBIOExampleParser object based on the registered -parser DLL and the message entry.

Parsing the BIO message

void CBIOExampleParser::ParseL();

Parses -the BIO message.

Processing the BIO message

CBIOExampleParser::ProcessL();

Processes -the parsed data.

Class -Summary

CBaseScriptParser2

-
Build

The BIOMessageMgr example -code includes the following project files for building the application: BIOParser.mmp, BIOMessage.mmp and bld.inf.

The Symbian -build process describes how to build this application.

In CodeWarrior: -firstly, 'make' the BIOParser.mcp which creates BIOParser.dll and BIOParser.lib in \epoc32\release\winscw\ <build_variant>, then secondly, -make BIOMessage.exe in the same directory. Run BIOMessage.mcp, -which runs BIOMessage.exe thus launching the emulator.

-
Usage

Launch the target. For emulator targets, -run: \epoc32\release\<wins or winscw>\<urel or udeb>\BIOMessage.exe. -If TechView emulator is used, to run the application go to System menu and -click on Open files / programs window. Start the "BIO Messaging Example" application.

Step -through each phase of the example by pressing the space bar or by tapping -on the window drawn by the example.

+ + + + + +BIOMessageMgr: +BIO Message manager using the message server +

The BIO Message manager example comprises two projects BIOMessage.exe and BIOParser.dll. +The BIOMessage.exe example connects to the message server, +creates a BIO message and sends the registered parser DLL and message entry +to BIOParser.dll.

+
Download

Click +on the following link to download the example: Biomsgexample.zip

Click: browse to view the example code.

+
BIOMessage: BIO messaging using the message server

Description

This +example code demonstrates BIO messaging using RSendAs and RSendAsMessage and +other supporting classes as mentioned in the Class +Summary below.

The BIOMessage example +code provides the following functionality:

Creating a session

void CBioMessage::Connect();

Creates +a session with the message server using RSendAs.

The +generated console output looks like this:

+ +

Creating a BIO message

void CBioMessage::Create(RSendAsMessage& aMessage);

This function does the following:

    +

  • creates a BIO message +of VCard type

    • +

  • sets the message body +text

    • +

  • adds the message recipients +for the message to be sent.

    • +

The generated console output looks like this:

+ +

Sending the BIO message

void CBioMessage::Send(RSendAsMessage& aMessage);

Sends the message to the recipients.

The generated console output +looks like this:

+ +

Creating the parser

CBioParser::NewL(CMsvEntry* aEntry);

Creates a CBioParser object based on the message entry.

Parsing +the BIO message

CBioParser::ParserL();

This +function does the following:

    +

  • calls ExtractMessageBodyL() to +extract the message body text from CMsvStore, the message +store

    • +

  • finds, loads and maintains +a reference count of client processes for a BIO parser DLL

    • +

  • parses the message body +text.

    • +

The generated console output looks like this:

+ +

Class Summary

RSendAs

RSendAsMessage

CSendAsMessageTypes

CSendAsAccounts

CRegisteredParserDll

CBIODatabase

CMsvStore

+
BIOParser: BIO message parsing

Description

This +example code demonstrates the parsing of the message. CBIOExampleParser is +the wrapper class which uses CBaseScriptParser2 and other +supporting classes mentioned in the Class +Summary below.

The BIOParser example code +provides the following functionality:

Creating the parser

CBIOExampleParser* CBIOExampleParser::NewL(CRegisteredParserDll& aRegisteredParserDll, CMsvEntry& aEntry, RFs& aFs);

Creates a CBIOExampleParser object based on the registered +parser DLL and the message entry.

Parsing the BIO message

void CBIOExampleParser::ParseL();

Parses +the BIO message.

Processing the BIO message

CBIOExampleParser::ProcessL();

Processes +the parsed data.

Class +Summary

CBaseScriptParser2

+
Build

The BIOMessageMgr example +code includes the following project files for building the application: BIOParser.mmp, BIOMessage.mmp and bld.inf.

The Symbian +build process describes how to build this application.

In CodeWarrior: +firstly, 'make' the BIOParser.mcp which creates BIOParser.dll and BIOParser.lib in \epoc32\release\winscw\ <build_variant>, then secondly, +make BIOMessage.exe in the same directory. Run BIOMessage.mcp, +which runs BIOMessage.exe thus launching the emulator.

+
Usage

Launch the target. For emulator targets, +run: \epoc32\release\<wins or winscw>\<urel or udeb>\BIOMessage.exe. +If TechView emulator is used, to run the application go to System menu and +click on Open files / programs window. Start the "BIO Messaging Example" application.

Step +through each phase of the example by pressing the space bar or by tapping +on the window drawn by the example.

\ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0CCCF088-E636-4C12-AA5E-3E2CB04424AD_d0e265567_href.png Binary file Symbian3/SDK/Source/GUID-0CCCF088-E636-4C12-AA5E-3E2CB04424AD_d0e265567_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0CCCF088-E636-4C12-AA5E-3E2CB04424AD_d0e269275_href.png Binary file Symbian3/SDK/Source/GUID-0CCCF088-E636-4C12-AA5E-3E2CB04424AD_d0e269275_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0CD18555-07EB-545D-9D47-D69A6BE6D2C8.dita --- a/Symbian3/SDK/Source/GUID-0CD18555-07EB-545D-9D47-D69A6BE6D2C8.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-0CD18555-07EB-545D-9D47-D69A6BE6D2C8.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,14 +1,14 @@ - - - - - -Standard SMS Converter

This section describes the Standard SMS Converter and the alphabet it supports.

Introduction

The Standard SMS Converter is a built-in converter based on the GSM 7-bit encoding. This converter is identified by the KCharacterSetIdentifierSms7Bit UID, which is defined in the charconv.h header file. To better understand the different character set of each SMS converter, the Standard SMS Converter is set as the baseline. Any differences or additions to the character set of Standard SMS Converter are listed.

For all of the converters, any undefined Unicode is converted to a question mark (?)–GSM code 0x37. Any code outside GSM 0x00 ~0x7F is converted to the Unicode replacement character 0xFFFD.

Alphabet

The highlighted boxes in Figure 1 illustrate the alphabet of the standard SMS converter:

  • GSM 7-bit default alphabet

  • GSM 7-bit default alphabet extension table

  • Extra lossy conversions–shown as Lossy Characters 1 in Figure 4.

Figure 1

- Alphabet of the Standard SMS Converter -

For information about the GSM 7-bit default alphabet and extension table, see 3GPP TS 23.038 V8.1.0. The table below lists the extra lossy conversions supported by the standard converter.

Character

Unicode

GSM

Converted Character

ç LATIN SMALL LETTER C WITH CEDILLA

0x00E7

0x09

Ç LATIN CAPITAL LETTER C WITH CEDILLA

δ GREEK SMALL LETTER DELTA

0x03B4

0x10

Δ GREEK CAPITAL LETTER DELTA

φ GREEK SMALL LETTER PHI

0x03C6

0x12

Φ GREEK CAPITAL LETTER PHI

ϕ GREEK PHI SYMBOL

0x03D5

0x12

Φ GREEK CAPITAL LETTER PHI

γ GREEK SMALL LETTER GAMMA

0x03B3

0x13

Γ GREEK CAPITAL LETTER GAMMA

λ GREEK SMALL LETTER LAMDA

0x03BB

0x14

Λ GREEK CAPITAL LETTER LAMDA

Ω GREEK CAPITAL LETTER OMEGA

0x03A9

0x15

Ω GREEK CAPITAL LETTER OMEGA

ω GREEK SMALL LETTER OMEGA

0x03C9

0x15

Ω GREEK CAPITAL LETTER OMEGA

ώ GREEK SMALL LETTER OMEGA WITH TONOS

0x03CE

0x15

Ω GREEK CAPITAL LETTER OMEGA

Ω OHM SIGN

0x2126

0x15

Ω GREEK CAPITAL LETTER OMEGA

π GREEK SMALL LETTER PI

0x03C0

0x16

Π GREEK CAPITAL LETTER PI

∏ N-ARY PRODUCT

0x220F

0x16

Π GREEK CAPITAL LETTER PI

ψ GREEK SMALL LETTER PSI

0x03C8

0x17

Ψ GREEK CAPITAL LETTER PSI

ς GREEK SMALL LETTER FINAL SIGMA

0x03C2

0x18

Σ GREEK CAPITAL LETTER SIGMA

σ GREEK SMALL LETTER SIGMA

0x03C3

0x18

Σ GREEK CAPITAL LETTER SIGMA

∑ N-ARY SUMMATION

0x2211

0x18

Σ GREEK CAPITAL LETTER SIGMA

θ GREEK SMALL LETTER THETA

0x03B8

0x19

Θ GREEK CAPITAL LETTER THETA

ϑ GREEK THETA SYMBOL

0x03D1

0x19

Θ GREEK CAPITAL LETTER THETA

ξ GREEK SMALL LETTER XI

0x03BE

0x1A

Ξ GREEK CAPITAL LETTER XI

(FORM FEED)

0x000C

0x1B0A

(PAGE BREAK)

À LATIN CAPITAL LETTER A WITH GRAVE

0x00C0

0x41

A LATIN CAPITAL LETTER A

Á LATIN CAPITAL LETTER A WITH ACUTE

0x00C1

0x41

A LATIN CAPITAL LETTER A

 LATIN CAPITAL LETTER A WITH CIRCUMFLEX

0x00C2

0x41

A LATIN CAPITAL LETTER A

à LATIN CAPITAL LETTER A WITH TILDE

0x00C3

0x41

A LATIN CAPITAL LETTER A

Ά GREEK CAPITAL LETTER ALPHA WITH TONOS

0x0386

0x41

A LATIN CAPITAL LETTER A

Α GREEK CAPITAL LETTER ALPHA

0x0391

0x41

A LATIN CAPITAL LETTER A

ά GREEK SMALL LETTER ALPHA WITH TONOS

0x03AC

0x41

A LATIN CAPITAL LETTER A

α GREEK SMALL LETTER ALPHA

0x03B1

0x41

A LATIN CAPITAL LETTER A

Β GREEK CAPITAL LETTER BETA

0x0392

0x42

B LATIN CAPITAL LETTER B

β GREEK SMALL LETTER BETA

0x03B2

0x42

B LATIN CAPITAL LETTER B

ϐ GREEK BETA SYMBOL

0x03D0

0x42

B LATIN CAPITAL LETTER B

È LATIN CAPITAL LETTER E WITH GRAVE

0x00C8

0x45

E LATIN CAPITAL LETTER E

Ê LATIN CAPITAL LETTER E WITH CIRCUMFLEX

0x00CA

0x45

E LATIN CAPITAL LETTER E

Ë LATIN CAPITAL LETTER E WITH DIAERESIS

0x00CB

0x45

E LATIN CAPITAL LETTER E

Έ GREEK CAPITAL LETTER EPSILON WITH TONOS

0x0388

0x45

E LATIN CAPITAL LETTER E

Ε GREEK CAPITAL LETTER EPSILON

0x0395

0x45

E LATIN CAPITAL LETTER E

έ GREEK SMALL LETTER EPSILON WITH TONOS

0x03AD

0x45

E LATIN CAPITAL LETTER E

ε GREEK SMALL LETTER EPSILON

0x03B5

0x45

E LATIN CAPITAL LETTER E

Ή GREEK CAPITAL LETTER ETA WITH TONOS

0x0389

0x48

H LATIN CAPITAL LETTER H

Η GREEK CAPITAL LETTER ETA

0x0397

0x48

H LATIN CAPITAL LETTER H

ή GREEK SMALL LETTER ETA WITH TONOS

0x03AE

0x48

H LATIN CAPITAL LETTER H

η GREEK SMALL LETTER ETA

0x03B7

0x48

H LATIN CAPITAL LETTER H

Ì LATIN CAPITAL LETTER I WITH GRAVE

0x00CC

0x49

I LATIN CAPITAL LETTER I

Í LATIN CAPITAL LETTER I WITH ACUTE

0x00CD

0x49

I LATIN CAPITAL LETTER I

Î LATIN CAPITAL LETTER I WITH CIRCUMFLEX

0x00CE

0x49

I LATIN CAPITAL LETTER I

Ï LATIN CAPITAL LETTER I WITH DIAERESIS

0x00CF

0x49

I LATIN CAPITAL LETTER I

Ί GREEK CAPITAL LETTER IOTA WITH TONOS

0x038A

0x49

I LATIN CAPITAL LETTER I

ΐ GREEK SMALL LETTER IOTA WITH DIALYTIKA AND TONOS

0x0390

0x49

I LATIN CAPITAL LETTER I

Ι GREEK CAPITAL LETTER IOTA

0x0399

0x49

I LATIN CAPITAL LETTER I

Ϊ GREEK CAPITAL LETTER IOTA WITH DIALYTIKA

0x03AA

0x49

I LATIN CAPITAL LETTER I

ί GREEK SMALL LETTER IOTA WITH TONOS

0x03AF

0x49

I LATIN CAPITAL LETTER I

ι GREEK SMALL LETTER IOTA

0x03B9

0x49

I LATIN CAPITAL LETTER I

ϊ GREEK SMALL LETTER IOTA WITH DIALYTIKA

0x03CA

0x49

I LATIN CAPITAL LETTER I

Κ GREEK CAPITAL LETTER KAPPA

0x039A

0x4B

K LATIN CAPITAL LETTER K

κ GREEK SMALL LETTER KAPPA

0x03BA

0x4B

K LATIN CAPITAL LETTER K

Μ GREEK CAPITAL LETTER MU

0x039C

0x4D

M LATIN CAPITAL LETTER M

μ GREEK SMALL LETTER MU

0x03BC

0x4D

M LATIN CAPITAL LETTER M

Ν GREEK CAPITAL LETTER NU

0x039D

0x4E

N LATIN CAPITAL LETTER N

ν GREEK SMALL LETTER NU

0x03BD

0x4E

N LATIN CAPITAL LETTER N

Ò LATIN CAPITAL LETTER O WITH GRAVE

0x00D2

0x4F

O LATIN CAPITAL LETTER O

Ó LATIN CAPITAL LETTER O WITH ACUTE

0x00D3

0x4F

O LATIN CAPITAL LETTER O

Ô LATIN CAPITAL LETTER O WITH CIRCUMFLEX

0x00D4

0x4F

O LATIN CAPITAL LETTER O

Õ LATIN CAPITAL LETTER O WITH TILDE

0x00D5

0x4F

O LATIN CAPITAL LETTER O

Ό GREEK CAPITAL LETTER OMICRON WITH TONOS

0x038C

0x4F

O LATIN CAPITAL LETTER O

Ο GREEK CAPITAL LETTER OMICRON

0x039F

0x4F

O LATIN CAPITAL LETTER O

ο GREEK SMALL LETTER OMICRON

0x03BF

0x4F

O LATIN CAPITAL LETTER O

ό GREEK SMALL LETTER OMICRON WITH TONOS

0x03CC

0x4F

O LATIN CAPITAL LETTER O

Ρ GREEK CAPITAL LETTER RHO

0x03A1

0x50

P LATIN CAPITAL LETTER P

ρ GREEK SMALL LETTER RHO

0x03C1

0x50

P LATIN CAPITAL LETTER P

Τ GREEK CAPITAL LETTER TAU

0x03A4

0x54

T LATIN CAPITAL LETTER T

τ GREEK SMALL LETTER TAU

0x03C4

0x54

T LATIN CAPITAL LETTER T

Ù LATIN CAPITAL LETTER U WITH GRAVE

0x00D9

0x55

U LATIN CAPITAL LETTER U

Ú LATIN CAPITAL LETTER U WITH ACUTE

0x00DA

0x55

U LATIN CAPITAL LETTER U

Û LATIN CAPITAL LETTER U WITH CIRCUMFLEX

0x00DB

0x55

U LATIN CAPITAL LETTER U

Χ GREEK CAPITAL LETTER CHI

0x03A7

0x58

X LATIN CAPITAL LETTER X

χ GREEK SMALL LETTER CHI

0x03C7

0x58

X LATIN CAPITAL LETTER X

Ý LATIN CAPITAL LETTER Y WITH ACUTE

0x00DD

0x59

Y LATIN CAPITAL LETTER Y

Ύ GREEK CAPITAL LETTER UPSILON WITH TONOS

0x038E

0x59

Y LATIN CAPITAL LETTER Y

Υ GREEK CAPITAL LETTER UPSILON

0x03A5

0x59

Y LATIN CAPITAL LETTER Y

Ϋ GREEK CAPITAL LETTER UPSILON WITH DIALYTIKA

0x03AB

0x59

Y LATIN CAPITAL LETTER Y

ΰ GREEK SMALL LETTER UPSILON WITH DIALYTIKA AND TONOS

0x03B0

0x59

Y LATIN CAPITAL LETTER Y

υ GREEK SMALL LETTER UPSILON

0x03C5

0x59

Y LATIN CAPITAL LETTER Y

ϋ GREEK SMALL LETTER UPSILON WITH DIALYTIKA

0x03CB

0x59

Y LATIN CAPITAL LETTER Y

ύ GREEK SMALL LETTER UPSILON WITH TONOS

0x03CD

0x59

Y LATIN CAPITAL LETTER Y

ϒ GREEK UPSILON WITH HOOK SYMBOL

0x03D2

0x59

Y LATIN CAPITAL LETTER Y

ϓ GREEK UPSILON WITH ACUTE AND HOOK SYMBOL

0x03D3

0x59

Y LATIN CAPITAL LETTER Y

ϔ GREEK UPSILON WITH DIAERESIS AND HOOK SYMBOL

0x03D4

0x59

Y LATIN CAPITAL LETTER Y

Ζ GREEK CAPITAL LETTER ZETA

0x0396

0x5A

Z LATIN CAPITAL LETTER Z

ζ GREEK SMALL LETTER ZETA

0x03b6

0x5A

Z LATIN CAPITAL LETTER Z

á LATIN SMALL LETTER A WITH ACUTE

0x00E1

0x61

a LATIN SMALL LETTER A

â LATIN SMALL LETTER A WITH CIRCUMFLEX

0x00E2

0x61

a LATIN SMALL LETTER A

ã LATIN SMALL LETTER A WITH TILDE

0x00E3

0x61

a LATIN SMALL LETTER A

ê LATIN SMALL LETTER E WITH CIRCUMFLEX

0x00EA

0x65

e LATIN SMALL LETTER E

ë LATIN SMALL LETTER E WITH DIAERESIS

0x00EB

0x65

e LATIN SMALL LETTER E

í LATIN SMALL LETTER I WITH ACUTE

0x00ED

0x69

i LATIN SMALL LETTER I

î LATIN SMALL LETTER I WITH CIRCUMFLEX

0x00EE

0x69

i LATIN SMALL LETTER I

ï LATIN SMALL LETTER I WITH DIAERESIS

0x00EF

0x69

i LATIN SMALL LETTER I

ó LATIN SMALL LETTER O WITH ACUTE

0x00f3

0x6F

o LATIN SMALL LETTER O

ô LATIN SMALL LETTER O WITH CIRCUMFLEX

0x00F4

0x6F

o LATIN SMALL LETTER O

õ LATIN SMALL LETTER O WITH TILDE

0x00F5

0x6F

o LATIN SMALL LETTER O

ú LATIN SMALL LETTER U WITH ACUTE

0x00FA

0x75

u LATIN SMALL LETTER U

û LATIN SMALL LETTER U WITH CIRCUMFLEX

0x00FB

0x75

u LATIN SMALL LETTER U

ý LATIN SMALL LETTER Y WITH ACUTE

0x00FD

0x79

y LATIN SMALL LETTER Y

ÿ LATIN SMALL LETTER Y WITH DIAERESIS

0x00FF

0x79

y LATIN SMALL LETTER Y

See also

SMS Encodings and Converters Overview

\ No newline at end of file + + + + + +Standard SMS Converter

This section describes the Standard SMS Converter and the alphabet it supports.

Introduction

The Standard SMS Converter is a built-in converter based on the GSM 7-bit encoding. This converter is identified by the KCharacterSetIdentifierSms7Bit UID, which is defined in the charconv.h header file. To better understand the different character set of each SMS converter, the Standard SMS Converter is set as the baseline. Any differences or additions to the character set of Standard SMS Converter are listed.

For all of the converters, any undefined Unicode is converted to a question mark (?)–GSM code 0x37. Any code outside GSM 0x00 ~0x7F is converted to the Unicode replacement character 0xFFFD.

Alphabet

The highlighted boxes in Figure 1 illustrate the alphabet of the standard SMS converter:

  • GSM 7-bit default alphabet

  • GSM 7-bit default alphabet extension table

  • Extra lossy conversions–shown as Lossy Characters 1 in Figure 4.

Figure 1

+ Alphabet of the Standard SMS Converter +

For information about the GSM 7-bit default alphabet and extension table, see 3GPP TS 23.038 V8.1.0. The table below lists the extra lossy conversions supported by the standard converter.

Character

Unicode

GSM

Converted Character

ç LATIN SMALL LETTER C WITH CEDILLA

0x00E7

0x09

Ç LATIN CAPITAL LETTER C WITH CEDILLA

δ GREEK SMALL LETTER DELTA

0x03B4

0x10

Δ GREEK CAPITAL LETTER DELTA

φ GREEK SMALL LETTER PHI

0x03C6

0x12

Φ GREEK CAPITAL LETTER PHI

ϕ GREEK PHI SYMBOL

0x03D5

0x12

Φ GREEK CAPITAL LETTER PHI

γ GREEK SMALL LETTER GAMMA

0x03B3

0x13

Γ GREEK CAPITAL LETTER GAMMA

λ GREEK SMALL LETTER LAMDA

0x03BB

0x14

Λ GREEK CAPITAL LETTER LAMDA

Ω GREEK CAPITAL LETTER OMEGA

0x03A9

0x15

Ω GREEK CAPITAL LETTER OMEGA

ω GREEK SMALL LETTER OMEGA

0x03C9

0x15

Ω GREEK CAPITAL LETTER OMEGA

ώ GREEK SMALL LETTER OMEGA WITH TONOS

0x03CE

0x15

Ω GREEK CAPITAL LETTER OMEGA

Ω OHM SIGN

0x2126

0x15

Ω GREEK CAPITAL LETTER OMEGA

π GREEK SMALL LETTER PI

0x03C0

0x16

Π GREEK CAPITAL LETTER PI

∏ N-ARY PRODUCT

0x220F

0x16

Π GREEK CAPITAL LETTER PI

ψ GREEK SMALL LETTER PSI

0x03C8

0x17

Ψ GREEK CAPITAL LETTER PSI

ς GREEK SMALL LETTER FINAL SIGMA

0x03C2

0x18

Σ GREEK CAPITAL LETTER SIGMA

σ GREEK SMALL LETTER SIGMA

0x03C3

0x18

Σ GREEK CAPITAL LETTER SIGMA

∑ N-ARY SUMMATION

0x2211

0x18

Σ GREEK CAPITAL LETTER SIGMA

θ GREEK SMALL LETTER THETA

0x03B8

0x19

Θ GREEK CAPITAL LETTER THETA

ϑ GREEK THETA SYMBOL

0x03D1

0x19

Θ GREEK CAPITAL LETTER THETA

ξ GREEK SMALL LETTER XI

0x03BE

0x1A

Ξ GREEK CAPITAL LETTER XI

(FORM FEED)

0x000C

0x1B0A

(PAGE BREAK)

À LATIN CAPITAL LETTER A WITH GRAVE

0x00C0

0x41

A LATIN CAPITAL LETTER A

Á LATIN CAPITAL LETTER A WITH ACUTE

0x00C1

0x41

A LATIN CAPITAL LETTER A

 LATIN CAPITAL LETTER A WITH CIRCUMFLEX

0x00C2

0x41

A LATIN CAPITAL LETTER A

à LATIN CAPITAL LETTER A WITH TILDE

0x00C3

0x41

A LATIN CAPITAL LETTER A

Ά GREEK CAPITAL LETTER ALPHA WITH TONOS

0x0386

0x41

A LATIN CAPITAL LETTER A

Α GREEK CAPITAL LETTER ALPHA

0x0391

0x41

A LATIN CAPITAL LETTER A

ά GREEK SMALL LETTER ALPHA WITH TONOS

0x03AC

0x41

A LATIN CAPITAL LETTER A

α GREEK SMALL LETTER ALPHA

0x03B1

0x41

A LATIN CAPITAL LETTER A

Β GREEK CAPITAL LETTER BETA

0x0392

0x42

B LATIN CAPITAL LETTER B

β GREEK SMALL LETTER BETA

0x03B2

0x42

B LATIN CAPITAL LETTER B

ϐ GREEK BETA SYMBOL

0x03D0

0x42

B LATIN CAPITAL LETTER B

È LATIN CAPITAL LETTER E WITH GRAVE

0x00C8

0x45

E LATIN CAPITAL LETTER E

Ê LATIN CAPITAL LETTER E WITH CIRCUMFLEX

0x00CA

0x45

E LATIN CAPITAL LETTER E

Ë LATIN CAPITAL LETTER E WITH DIAERESIS

0x00CB

0x45

E LATIN CAPITAL LETTER E

Έ GREEK CAPITAL LETTER EPSILON WITH TONOS

0x0388

0x45

E LATIN CAPITAL LETTER E

Ε GREEK CAPITAL LETTER EPSILON

0x0395

0x45

E LATIN CAPITAL LETTER E

έ GREEK SMALL LETTER EPSILON WITH TONOS

0x03AD

0x45

E LATIN CAPITAL LETTER E

ε GREEK SMALL LETTER EPSILON

0x03B5

0x45

E LATIN CAPITAL LETTER E

Ή GREEK CAPITAL LETTER ETA WITH TONOS

0x0389

0x48

H LATIN CAPITAL LETTER H

Η GREEK CAPITAL LETTER ETA

0x0397

0x48

H LATIN CAPITAL LETTER H

ή GREEK SMALL LETTER ETA WITH TONOS

0x03AE

0x48

H LATIN CAPITAL LETTER H

η GREEK SMALL LETTER ETA

0x03B7

0x48

H LATIN CAPITAL LETTER H

Ì LATIN CAPITAL LETTER I WITH GRAVE

0x00CC

0x49

I LATIN CAPITAL LETTER I

Í LATIN CAPITAL LETTER I WITH ACUTE

0x00CD

0x49

I LATIN CAPITAL LETTER I

Î LATIN CAPITAL LETTER I WITH CIRCUMFLEX

0x00CE

0x49

I LATIN CAPITAL LETTER I

Ï LATIN CAPITAL LETTER I WITH DIAERESIS

0x00CF

0x49

I LATIN CAPITAL LETTER I

Ί GREEK CAPITAL LETTER IOTA WITH TONOS

0x038A

0x49

I LATIN CAPITAL LETTER I

ΐ GREEK SMALL LETTER IOTA WITH DIALYTIKA AND TONOS

0x0390

0x49

I LATIN CAPITAL LETTER I

Ι GREEK CAPITAL LETTER IOTA

0x0399

0x49

I LATIN CAPITAL LETTER I

Ϊ GREEK CAPITAL LETTER IOTA WITH DIALYTIKA

0x03AA

0x49

I LATIN CAPITAL LETTER I

ί GREEK SMALL LETTER IOTA WITH TONOS

0x03AF

0x49

I LATIN CAPITAL LETTER I

ι GREEK SMALL LETTER IOTA

0x03B9

0x49

I LATIN CAPITAL LETTER I

ϊ GREEK SMALL LETTER IOTA WITH DIALYTIKA

0x03CA

0x49

I LATIN CAPITAL LETTER I

Κ GREEK CAPITAL LETTER KAPPA

0x039A

0x4B

K LATIN CAPITAL LETTER K

κ GREEK SMALL LETTER KAPPA

0x03BA

0x4B

K LATIN CAPITAL LETTER K

Μ GREEK CAPITAL LETTER MU

0x039C

0x4D

M LATIN CAPITAL LETTER M

μ GREEK SMALL LETTER MU

0x03BC

0x4D

M LATIN CAPITAL LETTER M

Ν GREEK CAPITAL LETTER NU

0x039D

0x4E

N LATIN CAPITAL LETTER N

ν GREEK SMALL LETTER NU

0x03BD

0x4E

N LATIN CAPITAL LETTER N

Ò LATIN CAPITAL LETTER O WITH GRAVE

0x00D2

0x4F

O LATIN CAPITAL LETTER O

Ó LATIN CAPITAL LETTER O WITH ACUTE

0x00D3

0x4F

O LATIN CAPITAL LETTER O

Ô LATIN CAPITAL LETTER O WITH CIRCUMFLEX

0x00D4

0x4F

O LATIN CAPITAL LETTER O

Õ LATIN CAPITAL LETTER O WITH TILDE

0x00D5

0x4F

O LATIN CAPITAL LETTER O

Ό GREEK CAPITAL LETTER OMICRON WITH TONOS

0x038C

0x4F

O LATIN CAPITAL LETTER O

Ο GREEK CAPITAL LETTER OMICRON

0x039F

0x4F

O LATIN CAPITAL LETTER O

ο GREEK SMALL LETTER OMICRON

0x03BF

0x4F

O LATIN CAPITAL LETTER O

ό GREEK SMALL LETTER OMICRON WITH TONOS

0x03CC

0x4F

O LATIN CAPITAL LETTER O

Ρ GREEK CAPITAL LETTER RHO

0x03A1

0x50

P LATIN CAPITAL LETTER P

ρ GREEK SMALL LETTER RHO

0x03C1

0x50

P LATIN CAPITAL LETTER P

Τ GREEK CAPITAL LETTER TAU

0x03A4

0x54

T LATIN CAPITAL LETTER T

τ GREEK SMALL LETTER TAU

0x03C4

0x54

T LATIN CAPITAL LETTER T

Ù LATIN CAPITAL LETTER U WITH GRAVE

0x00D9

0x55

U LATIN CAPITAL LETTER U

Ú LATIN CAPITAL LETTER U WITH ACUTE

0x00DA

0x55

U LATIN CAPITAL LETTER U

Û LATIN CAPITAL LETTER U WITH CIRCUMFLEX

0x00DB

0x55

U LATIN CAPITAL LETTER U

Χ GREEK CAPITAL LETTER CHI

0x03A7

0x58

X LATIN CAPITAL LETTER X

χ GREEK SMALL LETTER CHI

0x03C7

0x58

X LATIN CAPITAL LETTER X

Ý LATIN CAPITAL LETTER Y WITH ACUTE

0x00DD

0x59

Y LATIN CAPITAL LETTER Y

Ύ GREEK CAPITAL LETTER UPSILON WITH TONOS

0x038E

0x59

Y LATIN CAPITAL LETTER Y

Υ GREEK CAPITAL LETTER UPSILON

0x03A5

0x59

Y LATIN CAPITAL LETTER Y

Ϋ GREEK CAPITAL LETTER UPSILON WITH DIALYTIKA

0x03AB

0x59

Y LATIN CAPITAL LETTER Y

ΰ GREEK SMALL LETTER UPSILON WITH DIALYTIKA AND TONOS

0x03B0

0x59

Y LATIN CAPITAL LETTER Y

υ GREEK SMALL LETTER UPSILON

0x03C5

0x59

Y LATIN CAPITAL LETTER Y

ϋ GREEK SMALL LETTER UPSILON WITH DIALYTIKA

0x03CB

0x59

Y LATIN CAPITAL LETTER Y

ύ GREEK SMALL LETTER UPSILON WITH TONOS

0x03CD

0x59

Y LATIN CAPITAL LETTER Y

ϒ GREEK UPSILON WITH HOOK SYMBOL

0x03D2

0x59

Y LATIN CAPITAL LETTER Y

ϓ GREEK UPSILON WITH ACUTE AND HOOK SYMBOL

0x03D3

0x59

Y LATIN CAPITAL LETTER Y

ϔ GREEK UPSILON WITH DIAERESIS AND HOOK SYMBOL

0x03D4

0x59

Y LATIN CAPITAL LETTER Y

Ζ GREEK CAPITAL LETTER ZETA

0x0396

0x5A

Z LATIN CAPITAL LETTER Z

ζ GREEK SMALL LETTER ZETA

0x03b6

0x5A

Z LATIN CAPITAL LETTER Z

á LATIN SMALL LETTER A WITH ACUTE

0x00E1

0x61

a LATIN SMALL LETTER A

â LATIN SMALL LETTER A WITH CIRCUMFLEX

0x00E2

0x61

a LATIN SMALL LETTER A

ã LATIN SMALL LETTER A WITH TILDE

0x00E3

0x61

a LATIN SMALL LETTER A

ê LATIN SMALL LETTER E WITH CIRCUMFLEX

0x00EA

0x65

e LATIN SMALL LETTER E

ë LATIN SMALL LETTER E WITH DIAERESIS

0x00EB

0x65

e LATIN SMALL LETTER E

í LATIN SMALL LETTER I WITH ACUTE

0x00ED

0x69

i LATIN SMALL LETTER I

î LATIN SMALL LETTER I WITH CIRCUMFLEX

0x00EE

0x69

i LATIN SMALL LETTER I

ï LATIN SMALL LETTER I WITH DIAERESIS

0x00EF

0x69

i LATIN SMALL LETTER I

ó LATIN SMALL LETTER O WITH ACUTE

0x00f3

0x6F

o LATIN SMALL LETTER O

ô LATIN SMALL LETTER O WITH CIRCUMFLEX

0x00F4

0x6F

o LATIN SMALL LETTER O

õ LATIN SMALL LETTER O WITH TILDE

0x00F5

0x6F

o LATIN SMALL LETTER O

ú LATIN SMALL LETTER U WITH ACUTE

0x00FA

0x75

u LATIN SMALL LETTER U

û LATIN SMALL LETTER U WITH CIRCUMFLEX

0x00FB

0x75

u LATIN SMALL LETTER U

ý LATIN SMALL LETTER Y WITH ACUTE

0x00FD

0x79

y LATIN SMALL LETTER Y

ÿ LATIN SMALL LETTER Y WITH DIAERESIS

0x00FF

0x79

y LATIN SMALL LETTER Y

See also

SMS Encodings and Converters Overview

\ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0D093559-793F-5CDC-BB66-8FE1C8A3850E.dita --- a/Symbian3/SDK/Source/GUID-0D093559-793F-5CDC-BB66-8FE1C8A3850E.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-0D093559-793F-5CDC-BB66-8FE1C8A3850E.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,74 +1,74 @@ - - - - - -SQL -Optimization GuideThis document discusses SQL optimization techniques. -

Several best practice tips have been created as a response to customer -experience feedback. Use this guide to decide where to start optimizing.

-
Optimization -issues

SQL performance can be optimized by following good practice -in the design of databases, formulation of SQL queries, use of indexes and -other techniques.

Transient tables

Transient -tables are created by the database engine to compute intermediate results.

Transient -tables are stored on disk by default, which may result in unexpected I/O calls -that will probably have a negative impact on database performance.

Prevent datafile corruption

Datafile -corruption is corruption of the file containing a database with invalid data.

Datafile -corruption can occur after a system crash or loss of power. SQLite maintains -files called rollback journals from which the last valid state of a database -can be reconstructed. However, if a rollback journal is removed or renamed -during recovery from a crash, for instance in the course of application recovery -the database will remain corrupted.

SQL index tips

Indexes -are added either manually or automatically to columns of a data table to speed -up SELECT operations.

Indexes greatly speed up the performance of -SELECT statements but can impact on insertions, updates and deletions and -memory usage. It is not efficient to index all columns regardless of their -purpose and under certain circumstances indexes decrease performance. They -are best added to a database at the last stage of development.

SQL insertion tips

INSERT, like UPDATE and DELETE, is an inherently -fast operation but it can execute slowly if each individual operation is wrapped -in a transaction, which is the default behavior.

Multiple insertion -statements should be grouped into transactions by explicit use of the COMMIT -statement or else by use of TEMP tables which can be inserted into the database -as a batch in a single operation, and by reuse of prepared statements. Insert -statements should use bound parameters for reasons of efficiency and to prevent -SQL injection attacks.

SQL -schema tips

A database schema is a definition of its structure -including the tables, data types and keys.

The design of a database -can impact on the efficiency of the SQL queries run on it. Correct ordering -of columns in a table and use of keys makes a database more efficient, while -it is inefficient to store numerous large data structures such as BLOBs directly -in a database. Schemas are best kept small.

SQL expressions

An expression is the part of an SQL statement -which uses operators to combine values to form new values.

Some ways -of writing an expression are more efficient than others because of the way -the SQLite optimizer rewrites operators. It is also important to use constant -subexpressions within subqueries.

SQL -statement tips

Certain SQL statements have special case optimizations.

There -are special rules for using the MIN and MAX functions, the UNION and UNION -ALL operators and OFFSET clauses efficiently within SELECT statements.

SQL joins

SQL joins are used to combine multiple tables into -virtual tables.

A join on multiple tables involves reordering their -columns to construct the combined virtual table. The optimizer attempts to -perform this ordering in the most efficient way but is not always successful. -You can override the optimizer by using the CROSS JOIN operator.

ANALYZE command

The ANALYZE command is used to provide statistics -about the distribution of values in a populated database.

The ANALYZE -command creates a table SQLITE_STAT1 containing the statistical profile of -the database at the time when it was run. The optimizer uses that data to -choose between implementation options. Developers can also use the data to -make their own optimizations and they can modify the table to influence the -behavior of the optimizer.

SQL -WHERE clause tips

The SQL WHERE clause restricts the effect of -an SQL statement to rows satisfying the expression which it contains.

The -performance of a WHERE clause can be improved by following certain rules. -It is inefficient to use expressions within WHERE clauses instead of indexed -column names. Also, the AND operator should always be preferred to the OR -operator.

- -SQL Developer -Tips + + + + + +SQL +Optimization GuideThis document discusses SQL optimization techniques. +

Several best practice tips have been created as a response to customer +experience feedback. Use this guide to decide where to start optimizing.

+
Optimization +issues

SQL performance can be optimized by following good practice +in the design of databases, formulation of SQL queries, use of indexes and +other techniques.

Transient tables

Transient +tables are created by the database engine to compute intermediate results.

Transient +tables are stored on disk by default, which may result in unexpected I/O calls +that will probably have a negative impact on database performance.

Prevent datafile corruption

Datafile +corruption is corruption of the file containing a database with invalid data.

Datafile +corruption can occur after a system crash or loss of power. SQLite maintains +files called rollback journals from which the last valid state of a database +can be reconstructed. However, if a rollback journal is removed or renamed +during recovery from a crash, for instance in the course of application recovery +the database will remain corrupted.

SQL index tips

Indexes +are added either manually or automatically to columns of a data table to speed +up SELECT operations.

Indexes greatly speed up the performance of +SELECT statements but can impact on insertions, updates and deletions and +memory usage. It is not efficient to index all columns regardless of their +purpose and under certain circumstances indexes decrease performance. They +are best added to a database at the last stage of development.

SQL insertion tips

INSERT, like UPDATE and DELETE, is an inherently +fast operation but it can execute slowly if each individual operation is wrapped +in a transaction, which is the default behavior.

Multiple insertion +statements should be grouped into transactions by explicit use of the COMMIT +statement or else by use of TEMP tables which can be inserted into the database +as a batch in a single operation, and by reuse of prepared statements. Insert +statements should use bound parameters for reasons of efficiency and to prevent +SQL injection attacks.

SQL +schema tips

A database schema is a definition of its structure +including the tables, data types and keys.

The design of a database +can impact on the efficiency of the SQL queries run on it. Correct ordering +of columns in a table and use of keys makes a database more efficient, while +it is inefficient to store numerous large data structures such as BLOBs directly +in a database. Schemas are best kept small.

SQL expressions

An expression is the part of an SQL statement +which uses operators to combine values to form new values.

Some ways +of writing an expression are more efficient than others because of the way +the SQLite optimizer rewrites operators. It is also important to use constant +subexpressions within subqueries.

SQL +statement tips

Certain SQL statements have special case optimizations.

There +are special rules for using the MIN and MAX functions, the UNION and UNION +ALL operators and OFFSET clauses efficiently within SELECT statements.

SQL joins

SQL joins are used to combine multiple tables into +virtual tables.

A join on multiple tables involves reordering their +columns to construct the combined virtual table. The optimizer attempts to +perform this ordering in the most efficient way but is not always successful. +You can override the optimizer by using the CROSS JOIN operator.

ANALYZE command

The ANALYZE command is used to provide statistics +about the distribution of values in a populated database.

The ANALYZE +command creates a table SQLITE_STAT1 containing the statistical profile of +the database at the time when it was run. The optimizer uses that data to +choose between implementation options. Developers can also use the data to +make their own optimizations and they can modify the table to influence the +behavior of the optimizer.

SQL +WHERE clause tips

The SQL WHERE clause restricts the effect of +an SQL statement to rows satisfying the expression which it contains.

The +performance of a WHERE clause can be improved by following certain rules. +It is inefficient to use expressions within WHERE clauses instead of indexed +column names. Also, the AND operator should always be preferred to the OR +operator.

+ +SQL Developer +Tips \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0D093C3D-4D85-455E-B685-064A9B25B1FE.dita --- a/Symbian3/SDK/Source/GUID-0D093C3D-4D85-455E-B685-064A9B25B1FE.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-0D093C3D-4D85-455E-B685-064A9B25B1FE.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,107 +1,107 @@ - - - - - -Touch -UI user experience -

In general, the touch UI in the Symbian platform devices emulates the functionality -of the Arrow and Selection keys, but there are many deviations to this general -principle. Touch interaction design is a success if mobile device users choose -to use the stylus or finger even if all the same tasks can be performed using -the hardware keys. All Symbian platform common components are touch-enabled, -allowing full use with a finger.

-

The touch UI is designed to enable full task flow with touch, without the -need to switch to hardware keys. Thus, the design ensures that users can complete -a task with the chosen interaction method (keys or touch) from start to finish. -However, the touch UI offers some usability benefits compared to keyboard -use.

-

The following guidelines must be followed while designing applications -for touch use:

-
    -

  • Design decisions must be based on the real-time use cases.

    • -

  • Enable touch functionality only for obvious functions to make sure -that users can find them.

    • -

  • Keep in mind that not every item on the screen has to have a functionality -attached to it and that the functionality should not be too surprising or -radical.

    • -

  • Keep in mind that theme design alone is not sufficient as means of -indicating touch functionality; where one theme may indicate touch, another -may not.

    • -
-

In touch interaction, touch refers to pressing the finger or stylus against -the touch screen, tap corresponds to touch and release, while touch and drag -means touching and moving the finger or stylus along the screen. Basic touch -interaction is achieved through a short tap and long tap. In the short tap, -users place down and lift up a finger on the same item within a short period -of time. A long tap performs some specific actions (described in more detail -in Touch down and hold) -when users hold down the finger on a component for a set amount of time. The -following table lists the actions that take place on various finger movements.

-

The touch and drag functionality is not supported by Symbian platform -as an integrated part of the style, but it is supported in some selected applications -such as moving items in the Menu.

 -Touch events - - - -Touch type -Description - - - - -

Touch

 -

The following actions take place on touch:

    -

  • The component or control under the finger takes active focus.

    • -

  • The button under the finger changes its appearance to the pressed down -status.

    • -

  • Scrolling is activated if the finger is on a scrollbar.

    • -
 - - -

Tap

 -

The following actions take place on a tap (touch and release):

    -

  • The menu command under the finger is activated.

    • -

  • The button that was pressed down is released and the corresponding -function is performed (unless it is a latching button as in a toolbar).

    • -
 - - -

Touch and cancel

 -

Users can cancel any action on the objects on which they place the -finger by dragging the finger outside the object area before lifting it. If -the users drag the finger back onto the object before they lift it, the action -is performed.

 - - -

Touch and drag

 -

Users can place the finger on the screen and move it on the screen -without lifting it. This kind of dragging can be used to:

    -

  • Scroll lists and grids.

    • -

  • Select multiple objects in lists (see Touch -based multiple selection).

    • -

  • Browse menu items. When the finger moves on a menu item, the item is -focused and opens possible submenu panes. Lifting the finger performs the -focused menu command.

    • -

  • Highlight text in appropriate editor fields (paint it).

    • -

  • Perform application-specific functions, such as drawing lines or dragging -selections.

    • -
 - - - -
-
Using -touch events in C++ applications

For information on how to receive -touch events using application -and UI frameworks , see Window -server events and Pointer -events.

+ + + + + +Touch +UI user experience +

In general, the touch UI in the Symbian platform devices emulates the functionality +of the Arrow and Selection keys, but there are many deviations to this general +principle. Touch interaction design is a success if mobile device users choose +to use the stylus or finger even if all the same tasks can be performed using +the hardware keys. All Symbian platform common components are touch-enabled, +allowing full use with a finger.

+

The touch UI is designed to enable full task flow with touch, without the +need to switch to hardware keys. Thus, the design ensures that users can complete +a task with the chosen interaction method (keys or touch) from start to finish. +However, the touch UI offers some usability benefits compared to keyboard +use.

+

The following guidelines must be followed while designing applications +for touch use:

+
    +

  • Design decisions must be based on the real-time use cases.

    • +

  • Enable touch functionality only for obvious functions to make sure +that users can find them.

    • +

  • Keep in mind that not every item on the screen has to have a functionality +attached to it and that the functionality should not be too surprising or +radical.

    • +

  • Keep in mind that theme design alone is not sufficient as means of +indicating touch functionality; where one theme may indicate touch, another +may not.

    • +
+

In touch interaction, touch refers to pressing the finger or stylus against +the touch screen, tap corresponds to touch and release, while touch and drag +means touching and moving the finger or stylus along the screen. Basic touch +interaction is achieved through a short tap and long tap. In the short tap, +users place down and lift up a finger on the same item within a short period +of time. A long tap performs some specific actions (described in more detail +in Touch down and hold) +when users hold down the finger on a component for a set amount of time. The +following table lists the actions that take place on various finger movements.

+

The touch and drag functionality is not supported by Symbian platform +as an integrated part of the style, but it is supported in some selected applications +such as moving items in the Menu.

 +Touch events + + + +Touch type +Description + + + + +

Touch

 +

The following actions take place on touch:

    +

  • The component or control under the finger takes active focus.

    • +

  • The button under the finger changes its appearance to the pressed down +status.

    • +

  • Scrolling is activated if the finger is on a scrollbar.

    • +
 + + +

Tap

 +

The following actions take place on a tap (touch and release):

    +

  • The menu command under the finger is activated.

    • +

  • The button that was pressed down is released and the corresponding +function is performed (unless it is a latching button as in a toolbar).

    • +
 + + +

Touch and cancel

 +

Users can cancel any action on the objects on which they place the +finger by dragging the finger outside the object area before lifting it. If +the users drag the finger back onto the object before they lift it, the action +is performed.

 + + +

Touch and drag

 +

Users can place the finger on the screen and move it on the screen +without lifting it. This kind of dragging can be used to:

    +

  • Scroll lists and grids.

    • +

  • Select multiple objects in lists (see Touch +based multiple selection).

    • +

  • Browse menu items. When the finger moves on a menu item, the item is +focused and opens possible submenu panes. Lifting the finger performs the +focused menu command.

    • +

  • Highlight text in appropriate editor fields (paint it).

    • +

  • Perform application-specific functions, such as drawing lines or dragging +selections.

    • +
 + + + +
+
Using +touch events in applications

For information on how +to receive touch events using application +and UI frameworks , see Window +server events and Pointer +events.

 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0D1E30D8-D900-5FD9-BD1F-1B93BAD8AEF5.dita --- a/Symbian3/SDK/Source/GUID-0D1E30D8-D900-5FD9-BD1F-1B93BAD8AEF5.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-0D1E30D8-D900-5FD9-BD1F-1B93BAD8AEF5.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,12 +1,12 @@ - - - - - -What are fieldsThis topic describes the structure of a field. A field is an item that can be stored in the Comms Database.

A field is a container and an element. A field is the basic unit of information in the Comms Database.

A field is represented by the templated class CMDBField <T>. The template parameter defines the type of data that the field contains. For example TInt, TDesC, TBool

Fields are collected into records.

Getting data from a field

An overloaded conversion operator converts the data value in a CMDBField <T> object to the template type. The template type is the type defined by the characters T. The operator allows you to use a CMDBField<T> object on the right-hand side of an assignment call. The operator also allows you to pass a CMDBField<T> object into a function that requires items of the template type.

The value of a field in memory is NULL:

  • if the caller has not set the value

  • if the field as not been loaded from the Comms Database

If the value of a field is NULL after the field has been successfully loaded from the Comms Database, the field has been explicitly set to NULL by the writer of the record.

Setting data into a field

A field has an assignment operator. A type T field accepts a type T item on the right-hand side of an assignment.

A descriptor has variable length data. You need to set the size of the buffer that the field uses to store data. You must call SetMaxLengthL() on the CMDBField <T> object and pass the length of the data to be added. You then use the assignment operator. The length that you set must be enough or the assignment operator does not work. The SetL() function is an alternative method. This function calculates the length of a descriptor parameter for a descriptor field type and performs the allocation and assignment.

\ No newline at end of file + + + + + +What are fieldsThis topic describes the structure of a field. A field is an item that can be stored in the Comms Database.

A field is a container and an element. A field is the basic unit of information in the Comms Database.

A field is represented by the templated class CMDBField <T>. The template parameter defines the type of data that the field contains. For example TInt, TDesC, TBool

Fields are collected into records.

Getting data from a field

An overloaded conversion operator converts the data value in a CMDBField <T> object to the template type. The template type is the type defined by the characters T. The operator allows you to use a CMDBField<T> object on the right-hand side of an assignment call. The operator also allows you to pass a CMDBField<T> object into a function that requires items of the template type.

The value of a field in memory is NULL:

  • if the caller has not set the value

  • if the field as not been loaded from the Comms Database

If the value of a field is NULL after the field has been successfully loaded from the Comms Database, the field has been explicitly set to NULL by the writer of the record.

Setting data into a field

A field has an assignment operator. A type T field accepts a type T item on the right-hand side of an assignment.

A descriptor has variable length data. You need to set the size of the buffer that the field uses to store data. You must call SetMaxLengthL() on the CMDBField <T> object and pass the length of the data to be added. You then use the assignment operator. The length that you set must be enough or the assignment operator does not work. The SetL() function is an alternative method. This function calculates the length of a descriptor parameter for a descriptor field type and performs the allocation and assignment.

\ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0D3060BE-8C0F-564A-8979-C9A88C49C5E8_d0e78415_href.png Binary file Symbian3/SDK/Source/GUID-0D3060BE-8C0F-564A-8979-C9A88C49C5E8_d0e78415_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0D3060BE-8C0F-564A-8979-C9A88C49C5E8_d0e85127_href.png Binary file Symbian3/SDK/Source/GUID-0D3060BE-8C0F-564A-8979-C9A88C49C5E8_d0e85127_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0DD1EBC4-6068-5FE7-B649-CABA57E86195.dita --- a/Symbian3/SDK/Source/GUID-0DD1EBC4-6068-5FE7-B649-CABA57E86195.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-0DD1EBC4-6068-5FE7-B649-CABA57E86195.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,47 +1,47 @@ - - - - - -Drawing Polylines and Polygons

This topic provides examples that demonstrate how to draw a polyline and how to draw and fill a self-crossing polygon.

The example code assumes the array of points used when drawing these shapes is defined as follows:

... -// set up an array of points for drawing a polyline and a polygon etc. -// will be used relative to top left of rectangle -TPoint point1(20,20); -TPoint point2(100,190); -TPoint point3(110,90); -TPoint point4(50,150); -TPoint point5(200,150); -CArrayFix<TPoint>* mypoints = new CArrayFixFlat<TPoint>(5); -CleanupStack::PushL(mypoints); -mypoints->AppendL(point1); -mypoints->AppendL(point2); -mypoints->AppendL(point3); -mypoints->AppendL(point4); -mypoints->AppendL(point5); -... - -// switch statement with example cases -... -CleanupStack::PopAndDestroy(); // mypoints
Drawing a polyline

You can draw a polyline using DrawPolyLine() from an array of points.

... -// draw a polyline -gc.DrawPolyLine(mypoints); -...
Drawing a polygon

The following example code illustrates how to draw a filled polygon from an array of points. The polygon is self-crossing. Self-crossing polygons can be filled according to one of two rules, TFillRule::EAlternate (the default), or TFillRule::EWinding. These rules work with the concept of a winding number, as shown in the following figure:

- Winding numbers -

EWinding fills all areas, while EAlternate only fills areas with odd winding numbers.

Drawing a polygon using the EWinding fill rule

  1. Use SetBrushStyle() to set a cross-hatched brush style.

  2. Use DrawPolygon() to draw the polygon with the EWinding fill rule.

... -// draw self-crossing polygon using the winding fill rule -gc.SetBrushStyle(CGraphicsContext::ESquareCrossHatchBrush); -gc.SetBrushColor(black); -gc.DrawPolygon(mypoints,CGraphicsContext::EWinding); -...

Drawing a polygon using the EAlternate fill rule

  1. Use SetBrushStyle() to set a diamond cross-hatched brush style.

  2. Use DrawPolygon() to draw the polygon with the EAlternate fill rule.

... -// draw self-crossing polygon using the alternate fill rule -gc.SetBrushStyle(CGraphicsContext::EDiamondCrossHatchBrush); -gc.SetBrushColor(black); -gc.DrawPolygon(mypoints,CGraphicsContext::EAlternate); -...
Drawing + + + + + +Drawing Polylines and Polygons

This topic provides examples that demonstrate how to draw a polyline and how to draw and fill a self-crossing polygon.

The example code assumes the array of points used when drawing these shapes is defined as follows:

... +// set up an array of points for drawing a polyline and a polygon etc. +// will be used relative to top left of rectangle +TPoint point1(20,20); +TPoint point2(100,190); +TPoint point3(110,90); +TPoint point4(50,150); +TPoint point5(200,150); +CArrayFix<TPoint>* mypoints = new CArrayFixFlat<TPoint>(5); +CleanupStack::PushL(mypoints); +mypoints->AppendL(point1); +mypoints->AppendL(point2); +mypoints->AppendL(point3); +mypoints->AppendL(point4); +mypoints->AppendL(point5); +... + +// switch statement with example cases +... +CleanupStack::PopAndDestroy(); // mypoints
Drawing a polyline

You can draw a polyline using DrawPolyLine() from an array of points.

... +// draw a polyline +gc.DrawPolyLine(mypoints); +...
Drawing a polygon

The following example code illustrates how to draw a filled polygon from an array of points. The polygon is self-crossing. Self-crossing polygons can be filled according to one of two rules, TFillRule::EAlternate (the default), or TFillRule::EWinding. These rules work with the concept of a winding number, as shown in the following figure:

+ Winding numbers +

EWinding fills all areas, while EAlternate only fills areas with odd winding numbers.

Drawing a polygon using the EWinding fill rule

  1. Use SetBrushStyle() to set a cross-hatched brush style.

  2. Use DrawPolygon() to draw the polygon with the EWinding fill rule.

... +// draw self-crossing polygon using the winding fill rule +gc.SetBrushStyle(CGraphicsContext::ESquareCrossHatchBrush); +gc.SetBrushColor(black); +gc.DrawPolygon(mypoints,CGraphicsContext::EWinding); +...

Drawing a polygon using the EAlternate fill rule

  1. Use SetBrushStyle() to set a diamond cross-hatched brush style.

  2. Use DrawPolygon() to draw the polygon with the EAlternate fill rule.

... +// draw self-crossing polygon using the alternate fill rule +gc.SetBrushStyle(CGraphicsContext::EDiamondCrossHatchBrush); +gc.SetBrushColor(black); +gc.DrawPolygon(mypoints,CGraphicsContext::EAlternate); +...
Drawing to a Graphics Context Tutorials Drawing and Graphics Contexts \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0DEC4D1B-2CD6-49BC-92E4-F0CB0BCBFA9D-master.jpg Binary file Symbian3/SDK/Source/GUID-0DEC4D1B-2CD6-49BC-92E4-F0CB0BCBFA9D-master.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0DEC4D1B-2CD6-49BC-92E4-F0CB0BCBFA9D_d0e68726_href.jpg Binary file Symbian3/SDK/Source/GUID-0DEC4D1B-2CD6-49BC-92E4-F0CB0BCBFA9D_d0e68726_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0DEDC917-05C9-5D43-B839-73C043624BE9.dita --- a/Symbian3/SDK/Source/GUID-0DEDC917-05C9-5D43-B839-73C043624BE9.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-0DEDC917-05C9-5D43-B839-73C043624BE9.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,59 +1,59 @@ - - - - - - circularbuffer: -Circular Buffer ExampleThis example demonstrates the how to use the circular buffer classes CCirBuf and CCirBuffer. -
Purpose

This -example application shows how to construct and make use of circular buffers -containing integers, objects of user defined classes and objects of an R class.

-
Download

Click on the following link to download -the example: circularbuffer .zip

Click browse to view the example code.

-
class summary

CCirBuffer CCirBuf

-
Design and -implementation

Class diagram:

- Circular buffers example class diagram - -

The example creates a circular buffer of integers using CCirBuffer::Put() to -add elements and CCirBuffer::Get() to remove an element. -To demonstrate the circular nature of the buffer, the example:

    -

  • adds four elements until -the buffer is full,

    • -

  • tries to adds another -element to the buffer, which fails with a buffer full error message,

    • -

  • removes elements 1 and -2 from the buffer, leaving elements 3 and 4,

    • -

  • adds two new elements -(5 and 6) to the buffer,

    • -

  • removes all elements -(3, 4, 5 and 6) from the buffer.

    • -

Similar steps are performed using CCirBuf to add -(CCirBuf::Add()) and remove (CCirBuf::Remove()) -user-defined objects, and objects of an R class to and from -the buffer.

After removing R class objects from the circular buffer, -they must be closed in order to release the resource held by the R Class objects.

-
Building and -configuring

To build the example:

    -

  • You can build the example -from your IDE or the command line.

    If you use an IDE, import the bld.inf file -of the example into your IDE, and use the build command of the IDE.

    If -you use the command line, open a command prompt, and set the current directory -to the source code directory of the example. You can then build the example -with the SBSv1 build tools with the following commands:

    bldmake -bldfiles

    abld build

    How to use bldmake and How to use abld describe -how to use the SBSv1 build tools.

    • -

  • For the emulator, the -example builds an executable called circularbuffer.exe in -the epoc32\release\winscw\<udeb or urel>\ folder.

    • -
-
Running the -example

The user is prompted to press a key in order to progress -from one function to the next.

+ + + + + + circularbuffer: +Circular Buffer ExampleThis example demonstrates the how to use the circular buffer classes CCirBuf and CCirBuffer. +
Purpose

This +example application shows how to construct and make use of circular buffers +containing integers, objects of user defined classes and objects of an R class.

+
Download

Click on the following link to download +the example: circularbuffer .zip

Click browse to view the example code.

+
class summary

CCirBuffer CCirBuf

+
Design and +implementation

Class diagram:

+ Circular buffers example class diagram + +

The example creates a circular buffer of integers using CCirBuffer::Put() to +add elements and CCirBuffer::Get() to remove an element. +To demonstrate the circular nature of the buffer, the example:

    +

  • adds four elements until +the buffer is full,

    • +

  • tries to adds another +element to the buffer, which fails with a buffer full error message,

    • +

  • removes elements 1 and +2 from the buffer, leaving elements 3 and 4,

    • +

  • adds two new elements +(5 and 6) to the buffer,

    • +

  • removes all elements +(3, 4, 5 and 6) from the buffer.

    • +

Similar steps are performed using CCirBuf to add +(CCirBuf::Add()) and remove (CCirBuf::Remove()) +user-defined objects, and objects of an R class to and from +the buffer.

After removing R class objects from the circular buffer, +they must be closed in order to release the resource held by the R Class objects.

+
Building and +configuring

To build the example:

    +

  • You can build the example +from your IDE or the command line.

    If you use an IDE, import the bld.inf file +of the example into your IDE, and use the build command of the IDE.

    If +you use the command line, open a command prompt, and set the current directory +to the source code directory of the example. You can then build the example +with the SBSv1 build tools with the following commands:

    bldmake +bldfiles

    abld build

    How to use bldmake and How to use abld describe +how to use the SBSv1 build tools.

    • +

  • For the emulator, the +example builds an executable called circularbuffer.exe in +the epoc32\release\winscw\<udeb or urel>\ folder.

    • +
+
Running the +example

The user is prompted to press a key in order to progress +from one function to the next.

\ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0E21EAE4-BF71-55FD-9561-EA5530696627_d0e338735_href.png Binary file Symbian3/SDK/Source/GUID-0E21EAE4-BF71-55FD-9561-EA5530696627_d0e338735_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0E21EAE4-BF71-55FD-9561-EA5530696627_d0e344932_href.png Binary file Symbian3/SDK/Source/GUID-0E21EAE4-BF71-55FD-9561-EA5530696627_d0e344932_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0E55E007-913C-56DA-8BEF-7EC00FFCCE51_d0e304358_href.jpg Binary file Symbian3/SDK/Source/GUID-0E55E007-913C-56DA-8BEF-7EC00FFCCE51_d0e304358_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0E55E007-913C-56DA-8BEF-7EC00FFCCE51_d0e310373_href.jpg Binary file Symbian3/SDK/Source/GUID-0E55E007-913C-56DA-8BEF-7EC00FFCCE51_d0e310373_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0E695106-4139-4335-A11F-BD04418DD583.dita --- a/Symbian3/SDK/Source/GUID-0E695106-4139-4335-A11F-BD04418DD583.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-0E695106-4139-4335-A11F-BD04418DD583.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,132 +1,131 @@ - - - - - -Multi-selection -list -

Multi-selection lists are used when the purpose is to emphasize that it -is possible to select several items from a list at the same time. Typically, -there is an on-going operation that expects one or more items as input. An -example of this is when the user is creating a group, and a list of names -is offered as a multi-selection list.

-

In a multi-selection list, the user can browse the items and check and -uncheck any number of them. The state of each item is indicated in a checkbox -adjacent to the item. When the user accepts the list, information about the -marked items is passed to the application.

-

Items are checked and unchecked using the Selection key, and the list is -accepted with the left softkey Done/OK. Note that unlike in a markable list, -the Options softkey is not available: one can only check and uncheck items -and then accept or cancel the list.

- -Multi-selection lists: in the main pane (left) and in a setting editor -(right) - - -

The keypad functions for multi-selection lists are as follows:

-Default key event -in multi-selection list - - - -Key -Action - - - - -

Arrow up / down

 -

Moves the focus in the list.

 - - -

Arrow left / right

 -

Ignored (can be used to control tabs).

 - - -

Selection key

 -

Marks / unmarks the current item; toggle.

 - - -

Left softkey (Done)

 -

Accepts the list, passes the selections to the application.

 - - -

Right softkey (Cancel)

 -

Cancels the list, returns to the previous state.

 - - -

Clear, Edit, Call creation

 -

Ignored.

 - - -

Numeric keypad

 -

Ignored.

 - - -

Other keys

 -

Do the default action of the key.

 - - - -
-

-The default touch -events for multi-selection list - - - - - - -

User action

 -

State change

 -

Feedback

 - - - - -

Touch down

 -

No change

 -

Highlight is shown.

Tactile: Basic list effect and audio -feedback is provided with touch down event.

 - - -

Touch release

 -

The item is marked/unmarked.

 -

Highlight disappears.

Tactile: Basic effect is provided with -touch release event.

 - - -

Touch down and hold

 -

Inactive

 -

Tactile: No effect

 - - -

Touch down and move

 -

Refer to Dragging -and flicking events.

 -

Tactile: Refer to Dragging -and flicking events.

 - - -

Touch down, move and touch release within the list

 -

Refer to Dragging -and flicking events.

Touch release after movement does not mark/unmark -the item.

 -

Tactile: Refer to Dragging -and flicking events.

 - - - -
-

Using -multi-selection lists in C++ applications

The API to use for multi-selection -lists is the Lists API. For implementation information, -see Using the Lists API.

+ + + + + +Multi-selection +list +

Multi-selection lists are used when the purpose is to emphasize that it +is possible to select several items from a list at the same time. Typically, +there is an on-going operation that expects one or more items as input. An +example of this is when the user is creating a group, and a list of names +is offered as a multi-selection list.

+

In a multi-selection list, the user can browse the items and check and +uncheck any number of them. The state of each item is indicated in a checkbox +adjacent to the item. When the user accepts the list, information about the +marked items is passed to the application.

+

Items are checked and unchecked using the Selection key, and the list is +accepted with the left softkey Done/OK. +Note that unlike in a markable list, the Options softkey is not available: +one can only check and uncheck items and then accept or cancel the list.

+ +Multi-selection lists: in the main pane (left) and in a setting editor +(right) + + +

The keypad functions for multi-selection lists are as follows:

+Default key event +in multi-selection list + + + +Key +Action + + + + +

Arrow up / down

 +

Moves the focus in the list.

 + + +

Arrow left / right

 +

Ignored (can be used to control tabs).

 + + +

Selection key

 +

Marks / unmarks the current item; toggle.

 + + +

Left softkey (Done)

 +

Accepts the list, passes the selections to the application.

 + + +

Right softkey (Cancel)

 +

Cancels the list, returns to the previous state.

 + + +

Clear, Edit, Call creation

 +

Ignored.

 + + +

Numeric keypad

 +

Ignored.

 + + +

Other keys

 +

Do the default action of the key.

 + + + +
+

+The default touch +events for multi-selection list + + + + + + +

User action

 +

State change

 +

Feedback

 + + + + +

Touch down

 +

No change

 +

Highlight is shown.

Tactile: Basic list effect and audio +feedback is provided with touch down event.

 + + +

Touch release

 +

The item is marked/unmarked.

 +

Highlight disappears.

Tactile: Basic effect is provided with +touch release event.

 + + +

Touch down and hold

 +

Inactive

 +

Tactile: No effect

 + + +

Touch down and move

 +

Refer to Dragging +and flicking events.

 +

Tactile: Refer to Dragging +and flicking events.

 + + +

Touch down, move and touch release within the list

 +

Refer to Dragging +and flicking events.

Touch release after movement does not mark/unmark +the item.

 +

Tactile: Refer to Dragging +and flicking events.

 + + + +
+

Using +multi-selection lists in applications

The API to use +for multi-selection lists is the Lists API. For implementation information, see Using the Lists API.

 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0E91173A-BA80-5817-866A-7A284573EBCE_d0e281521_href.png Binary file Symbian3/SDK/Source/GUID-0E91173A-BA80-5817-866A-7A284573EBCE_d0e281521_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0E91173A-BA80-5817-866A-7A284573EBCE_d0e285207_href.png Binary file Symbian3/SDK/Source/GUID-0E91173A-BA80-5817-866A-7A284573EBCE_d0e285207_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0EBE5733-A267-5F4A-85AD-87C3ECF80731.dita --- a/Symbian3/SDK/Source/GUID-0EBE5733-A267-5F4A-85AD-87C3ECF80731.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-0EBE5733-A267-5F4A-85AD-87C3ECF80731.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,118 +1,118 @@ - - - - - -Dynamic -Resolution SwitchingScreenPlay provides support for externally connected displays, -such as TV-out. Previous versions of Symbian and the non-ScreenPlay variant -consider the size of all displays to be fixed, assuming them to be built into -the phone. However, for High-Definition Multimedia Interface (HDMI) and composite -video connectors, there is a range of resolutions that can change dynamically. -ScreenPlay provides an optional feature that supports switching between resolutions -at runtime. -

Variant: ScreenPlay.

-
The pre-ScreenPlay background

Early devices typically -had a screen size of 220 x 176 pixels. Over time, these were followed by higher -resolution screens, such as 440 x 252 pixels. Applications that were designed -for 220 x 176 pixel screens could run on 440 x 252 pixel screens because the -Window Server simply scaled the pixels by a factor of two.

However, -this approach did not work when phones with 320 x 240 pixel screens were introduced, -because each axis required a different scaling factor. Symbian introduced -the screen mode feature to handle this and similar use cases. Device -creators define in the wsini.ini -file a number of screen modes for each physical screen on the device. -For each screen mode the device creator defines parameters to control the -offset from the top left corner of the screen, the height and width in both -pixels and twips, X and Y axis scaling factors and so on. The -Window Server uses these to position and scale old applications so that they -can run on new phones with higher resolutions, as shown in the following diagram -(which is not drawn to scale). The screen mode is still used in the same way -in the non-ScreenPlay -variant.

-The screen mode enables old applications to run on new - phones with higher resolutions - -

There are several similar use cases, such as swapping between portrait -and landscape orientations and flip phones that have a flap that, when closed, -partially obscures the main screen. The Window Server uses the screen mode -parameters to display applications differently depending on whether the phone -is in portrait or landscape orientation and whether the flap is open or closed. -The screen mode represents the area that is presented to the application and -is available to application developers through CWsScreenDevice::SizeInPixels().

Defining -the screen modes in the wsini.ini -file in this way means that all possible screen sizes and resolutions -must be fixed and known at ROM building time. This approach has limitations -when working with technologies such as HDMI and composite video connectors, -where there is a very wide range of possible resolutions that may not be known -until runtime.

-
The ScreenPlay approach

In ScreenPlay the actual -resolution of the full composition/display area can be determined at runtime. -The full UI area is mapped to fill this display area but may be a lower virtual -resolution, which is scaled. The render stage chain handles the -scaling and positioning of applications and any external surfaces within the -UI, and the composition engine performs the scaling of the pixel data to the -actual display area at physical resolution. This has the advantage that the -scaling can be handled by the graphics acceleration hardware, if it is available.

Another -advantage of this approach is that it enables dynamic scaling of the pixels. -Usually pixels are square on a mobile phone display, but not square on many -external displays. When the square pixels from the device are displayed on -such a display, they may need to be scaled by different arbitrary factors -on each axis. This is called anisotropic scaling. In contrast, isotropic -scaling means that both pixel axes are scaled by the same arbitrary factor.

The -following diagram illustrates how the full UI area is mapped to fill the display/composition -area. The application's area (which corresponds to the screen mode) is referred -to as the application extent in ScreenPlay.

-Coordinate spaces in ScreenPlay - -

ScreenPlay handles application sizing and positioning in a fundamentally -different way from the non-ScreenPlay variant. Using a fixed offset to position -the application within the screen is inadequate when connecting to an external -HDMI display, for example, when the resolution may not be known until runtime. -For example, the offset designed for a QVGA display does not position the -application correctly in a higher resolution display, as shown in the following -diagram, where the red cross indicates the offset for a QVGA display.

-A fixed offset and several display resolutions (not drawn - to scale) - -

In ScreenPlay there is no scaling of the application extent relative -to the full UI area—there is always a 1:1 pixel correspondence between them. -In addition, although supported, the screen mode offset is not necessarily -used. Instead, the render stage chain selects an appropriate virtual resolution -and handles the positioning—for example, centering it and using a best fit -algorithm so that it takes up as much of the screen as possible or using the -offset as a minimum margin size. The device creator can choose how to implement -this in the render stages. In order to position the application correctly -within the UI area, the Window Server gets the positioning information from -the first render stage in the chain when the configuration or screen mode -changes.

ScreenPlay supports fixed screen modes in the wsini.ini -file, although the scaling parameters are not used. However, the screen -mode width and height in pixels and twips when specified and used together, -provide the pixel aspect ratio. In order to maintain backwards compatibility, -render stages should respect this aspect ratio whenever possible.

It -is possible for applications to determine and draw to the UI area outside -the application extent using the APIs described below. However, dynamic -screen modes provide an alternative mechanism for existing applications -to access the full UI area. This is particularly suitable for HDMI and similar -technologies where the resolution may not be known until runtime. To use this -approach, the device creator must define one or two screen modes in the wsini.ini file and -set their height and width in pixels to -1. One dynamic screen mode then represents -the current display configuration and the other one, if present, represents -the configuration when the screen is rotated by 90º or 270º. Using dynamic -screen modes means that the display configuration can be changed at runtime -according to the hardware that is available and detected by the composition -engine.

When a dynamic screen mode is used, the application extent -always fills the full UI space and the area returned by CWsScreenDevice::SizeInPixels() always -matches the actual resolution that is in use.

- -Graphics -Concepts - - + + + + + +Dynamic +Resolution SwitchingScreenPlay provides support for externally connected displays, +such as TV-out. Previous versions of Symbian and the non-ScreenPlay variant +consider the size of all displays to be fixed, assuming them to be built into +the phone. However, for High-Definition Multimedia Interface (HDMI) and composite +video connectors, there is a range of resolutions that can change dynamically. +ScreenPlay provides an optional feature that supports switching between resolutions +at runtime. +

Variant: ScreenPlay.

+
The pre-ScreenPlay background

Early devices typically +had a screen size of 220 x 176 pixels. Over time, these were followed by higher +resolution screens, such as 440 x 252 pixels. Applications that were designed +for 220 x 176 pixel screens could run on 440 x 252 pixel screens because the +Window Server simply scaled the pixels by a factor of two.

However, +this approach did not work when phones with 320 x 240 pixel screens were introduced, +because each axis required a different scaling factor. Symbian introduced +the screen mode feature to handle this and similar use cases. Device +creators define in the wsini.ini +file a number of screen modes for each physical screen on the device. +For each screen mode the device creator defines parameters to control the +offset from the top left corner of the screen, the height and width in both +pixels and twips, X and Y axis scaling factors and so on. The +Window Server uses these to position and scale old applications so that they +can run on new phones with higher resolutions, as shown in the following diagram +(which is not drawn to scale). The screen mode is still used in the same way +in the non-ScreenPlay +variant.

+The screen mode enables old applications to run on new + phones with higher resolutions + +

There are several similar use cases, such as swapping between portrait +and landscape orientations and flip phones that have a flap that, when closed, +partially obscures the main screen. The Window Server uses the screen mode +parameters to display applications differently depending on whether the phone +is in portrait or landscape orientation and whether the flap is open or closed. +The screen mode represents the area that is presented to the application and +is available to application developers through CWsScreenDevice::SizeInPixels().

Defining +the screen modes in the wsini.ini +file in this way means that all possible screen sizes and resolutions +must be fixed and known at ROM building time. This approach has limitations +when working with technologies such as HDMI and composite video connectors, +where there is a very wide range of possible resolutions that may not be known +until runtime.

+
The ScreenPlay approach

In ScreenPlay the actual +resolution of the full composition/display area can be determined at runtime. +The full UI area is mapped to fill this display area but may be a lower virtual +resolution, which is scaled. The render stage chain handles the +scaling and positioning of applications and any external surfaces within the +UI, and the composition engine performs the scaling of the pixel data to the +actual display area at physical resolution. This has the advantage that the +scaling can be handled by the graphics acceleration hardware, if it is available.

Another +advantage of this approach is that it enables dynamic scaling of the pixels. +Usually pixels are square on a mobile phone display, but not square on many +external displays. When the square pixels from the device are displayed on +such a display, they may need to be scaled by different arbitrary factors +on each axis. This is called anisotropic scaling. In contrast, isotropic +scaling means that both pixel axes are scaled by the same arbitrary factor.

The +following diagram illustrates how the full UI area is mapped to fill the display/composition +area. The application's area (which corresponds to the screen mode) is referred +to as the application extent in ScreenPlay.

+Coordinate spaces in ScreenPlay + +

ScreenPlay handles application sizing and positioning in a fundamentally +different way from the non-ScreenPlay variant. Using a fixed offset to position +the application within the screen is inadequate when connecting to an external +HDMI display, for example, when the resolution may not be known until runtime. +For example, the offset designed for a QVGA display does not position the +application correctly in a higher resolution display, as shown in the following +diagram, where the red cross indicates the offset for a QVGA display.

+A fixed offset and several display resolutions (not drawn + to scale) + +

In ScreenPlay there is no scaling of the application extent relative +to the full UI area—there is always a 1:1 pixel correspondence between them. +In addition, although supported, the screen mode offset is not necessarily +used. Instead, the render stage chain selects an appropriate virtual resolution +and handles the positioning—for example, centering it and using a best fit +algorithm so that it takes up as much of the screen as possible or using the +offset as a minimum margin size. The device creator can choose how to implement +this in the render stages. In order to position the application correctly +within the UI area, the Window Server gets the positioning information from +the first render stage in the chain when the configuration or screen mode +changes.

ScreenPlay supports fixed screen modes in the wsini.ini +file, although the scaling parameters are not used. However, the screen +mode width and height in pixels and twips when specified and used together, +provide the pixel aspect ratio. In order to maintain backwards compatibility, +render stages should respect this aspect ratio whenever possible.

It +is possible for applications to determine and draw to the UI area outside +the application extent using the APIs described below. However, dynamic +screen modes provide an alternative mechanism for existing applications +to access the full UI area. This is particularly suitable for HDMI and similar +technologies where the resolution may not be known until runtime. To use this +approach, the device creator must define one or two screen modes in the wsini.ini file and +set their height and width in pixels to -1. One dynamic screen mode then represents +the current display configuration and the other one, if present, represents +the configuration when the screen is rotated by 90º or 270º. Using dynamic +screen modes means that the display configuration can be changed at runtime +according to the hardware that is available and detected by the composition +engine.

When a dynamic screen mode is used, the application extent +always fills the full UI space and the area returned by CWsScreenDevice::SizeInPixels() always +matches the actual resolution that is in use.

+ +Graphics +Concepts + + \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0EBE8B44-1F42-4654-AC4D-A5F242FA49EB-master.png Binary file Symbian3/SDK/Source/GUID-0EBE8B44-1F42-4654-AC4D-A5F242FA49EB-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0EBE8B44-1F42-4654-AC4D-A5F242FA49EB_d0e52114_href.png Binary file Symbian3/SDK/Source/GUID-0EBE8B44-1F42-4654-AC4D-A5F242FA49EB_d0e52114_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0EBE8B44-1F42-4654-AC4D-A5F242FA49EB_d0e57857_href.png Binary file Symbian3/SDK/Source/GUID-0EBE8B44-1F42-4654-AC4D-A5F242FA49EB_d0e57857_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0EF25CCA-1E6B-5B62-8E77-9A670986C5EF.dita --- a/Symbian3/SDK/Source/GUID-0EF25CCA-1E6B-5B62-8E77-9A670986C5EF.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-0EF25CCA-1E6B-5B62-8E77-9A670986C5EF.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,20 +1,20 @@ - - - - - -Textual LoggingThis topic describes the textual logging mechanisms available to help debugging the Communication-related components.

Most Comms components can output debugging information. These components must be configured to output information, with the configuration procedure dependent on the logging mechanism used by the component. The following mechanisms are used to log the information:

  • Flogger - This logging mechanism is a file logger. It used to be the standard mechanism for Comms logging, but it is being replaced by CDU (below).

  • Comms Debug Utility (CDU) - This logging mechanism is currently used for the majority of Comms logging. It is the successor to Flogger and adds a two-phase logging system to give flexibility in debugging problems which are difficult to reproduce in debug binary files. It unifies Comms logging into one text file and allows the output to be redirected to RDebug for easier on-target debugging, or on emulator to the fast Windows Debug port. For more information see Post-processing CDU log files, Default CDU and Interpreting the log files.

    Note: The CDU API is not published and so its APIs cannot be used for adding new logging.

  • Unified Trace/UTrace/ULogger - This logging mechanism is currently used for a small amount of Comms logging. For more information see How to Use ULogger with Comms

  • Proprietary - This logging mechanism belongs to the component itself. A few components still use their own logging mechanisms, but these usually behave similarly to Flogger in that to obtain the logs the appropriate folder needs to exist while the component is running.

Note: When you enable logging for a component, the component may run significantly slower as it performs the logging. This could make reproducing a problem more difficult if the reduced component execution performance changes the sequence of events leading to the problem.

Post-processing CDU log files

The CDU log file format is designed to be viewed unprocessed. However, in some cases post-processing is required. Two post-processing tools are available:

  • Splitlog - is supplied in epoc32\tools and splits the single log.txt file into multiple files by each unique tag combination. This tool is used to extract embedded binary logging such as that for PPP described below in Component-Specific Debugging Help.

  • Networking Message Sequence Display Tool - processes a standard log.txt file to extract the Comms Framework messages and generates HTML/SVG output files for display on a suitable SVG-enabled browser.

    - Figure 1 - Example SVG output from the Message Sequence Display - Tool -
Default CDU

CDU provides a default configuration file which lists all the known components which use it, and also provides a reference listing of iby files and their respective component source code and log tags. Figure 2 provides a snapshot of the configuration file:

- Figure 2 - The default commsdbg.ini file -

The default CDU file is located at ..\comms-infras\commsdebugutility\group\commsdbgdefault.ini and is available for the emulator in epoc32\<data|release\winscw\<udeb|urel>>\z\resource\commsdbg.ini.

Interpreting the log files

Comms components have specific log file schemes with some similarities. The following are guidelines for interpreting the files:

  • Errors are logged - when a panic or other serious error condition is encountered. Often the last few log lines includes where the critical condition was reached, since usually the panic code or error code alone is not enough. If not, then often searching for "warning" or "error" in the earlier logging will identify where the problem began.

  • Multi-threaded module output prefixes thread number - ESock and the C32 Serial Server prefix the log lines with the thread number within the specific thread numbering scheme. For example:

    esock esock a 2e W0: CWorkerThread::ConstructL Init RS ChannelHandler -esock esock a 32 W4: SocketServer::InitL() Done! -esock Booting a 32 W4: CWorkerThread::ConstructL Init ProtocolManager + + + + + +Textual LoggingThis topic describes the textual logging mechanisms available to help debugging the Communication-related components.

    Most Comms components can output debugging information. These components must be configured to output information, with the configuration procedure dependent on the logging mechanism used by the component. The following mechanisms are used to log the information:

    • Flogger - This logging mechanism is a file logger. It used to be the standard mechanism for Comms logging, but it is being replaced by CDU (below).

    • Comms Debug Utility (CDU) - This logging mechanism is currently used for the majority of Comms logging. It is the successor to Flogger and adds a two-phase logging system to give flexibility in debugging problems which are difficult to reproduce in debug binary files. It unifies Comms logging into one text file and allows the output to be redirected to RDebug for easier on-target debugging, or on emulator to the fast Windows Debug port. For more information see Post-processing CDU log files, Default CDU and Interpreting the log files.

      Note: The CDU API is not published and so its APIs cannot be used for adding new logging.

    • Unified Trace/UTrace/ULogger - This logging mechanism is currently used for a small amount of Comms logging. For more information see How to Use ULogger with Comms

    • Proprietary - This logging mechanism belongs to the component itself. A few components still use their own logging mechanisms, but these usually behave similarly to Flogger in that to obtain the logs the appropriate folder needs to exist while the component is running.

    Note: When you enable logging for a component, the component may run significantly slower as it performs the logging. This could make reproducing a problem more difficult if the reduced component execution performance changes the sequence of events leading to the problem.

    Post-processing CDU log files

    The CDU log file format is designed to be viewed unprocessed. However, in some cases post-processing is required. Two post-processing tools are available:

    • Splitlog - is supplied in epoc32\tools and splits the single log.txt file into multiple files by each unique tag combination. This tool is used to extract embedded binary logging such as that for PPP described below in Component-Specific Debugging Help.

    • Networking Message Sequence Display Tool - processes a standard log.txt file to extract the Comms Framework messages and generates HTML/SVG output files for display on a suitable SVG-enabled browser.

      + Figure 1 - Example SVG output from the Message Sequence Display + Tool +
    Default CDU

    CDU provides a default configuration file which lists all the known components which use it, and also provides a reference listing of iby files and their respective component source code and log tags. Figure 2 provides a snapshot of the configuration file:

    + Figure 2 - The default commsdbg.ini file +

    The default CDU file is located at ..\comms-infras\commsdebugutility\group\commsdbgdefault.ini and is available for the emulator in epoc32\<data|release\winscw\<udeb|urel>>\z\resource\commsdbg.ini.

    Interpreting the log files

    Comms components have specific log file schemes with some similarities. The following are guidelines for interpreting the files:

    • Errors are logged - when a panic or other serious error condition is encountered. Often the last few log lines includes where the critical condition was reached, since usually the panic code or error code alone is not enough. If not, then often searching for "warning" or "error" in the earlier logging will identify where the problem began.

    • Multi-threaded module output prefixes thread number - ESock and the C32 Serial Server prefix the log lines with the thread number within the specific thread numbering scheme. For example:

      esock esock a 2e W0: CWorkerThread::ConstructL Init RS ChannelHandler +esock esock a 32 W4: SocketServer::InitL() Done! +esock Booting a 32 W4: CWorkerThread::ConstructL Init ProtocolManager

      The log lines indicate that ESock's Worker zero - the main thread - has initiated construction of its Rootserver (RS) communications channel, while Worker four has started constructing the Protocol Manager.

      Note: The "2e" and "32" numbers are the kernel's own numbers for these threads.

    \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0F09110F-3C4C-57D9-BA7D-19DD9A06B33B.dita --- a/Symbian3/SDK/Source/GUID-0F09110F-3C4C-57D9-BA7D-19DD9A06B33B.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-0F09110F-3C4C-57D9-BA7D-19DD9A06B33B.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,12 +1,12 @@ - - - - - -Editing media files

    You can use the MVS to edit media files (or "clips"). You can either crop a newly recorded file before saving it, or specify that only a portion of a saved file should play.

    Cropping a file

    You can crop a file - remove a specified number of seconds from the beginning or end of a file open for record - before saving it.

    Note: The audio or video cropped is deleted from the file and cannot be retrieved.

    To crop a file:

    1. In the Edit menu, click SetCropWindow. The Crop This Clip dialog box is displayed.

    2. Select the position of the Crop: offset from either the beginning or the end of the clip.

    3. Enter the Cropping Point: the offset in seconds.

    4. Click Crop! to crop the clip.

    Selecting a portion of a file to play

    Before you play a media file you can specify that you want to play only a portion of it.

    To select a portion of clip for playing:

    1. In the Edit menu, click Set PlayWindow. This displays the Set PlayWindow dialog box.

    2. Enter the Start and End times of the portion in milliseconds.

    3. Click OK to confirm the clip length.

      When you play the clip, only the selected portion is played.

    Clearing a selected portion

    To set the portion to play back to its original value (entire clip): from the Edit menu, click ClearPlayWindow.

    See Also

    Introduction to the MVS

    MVS GUI layout

    Recording media files

    Playing media files

    Configuring and clearing files

    \ No newline at end of file + + + + + +Editing media files

    You can use the MVS to edit media files (or "clips"). You can either crop a newly recorded file before saving it, or specify that only a portion of a saved file should play.

    Cropping a file

    You can crop a file - remove a specified number of seconds from the beginning or end of a file open for record - before saving it.

    Note: The audio or video cropped is deleted from the file and cannot be retrieved.

    To crop a file:

    1. In the Edit menu, click SetCropWindow. The Crop This Clip dialog box is displayed.

    2. Select the position of the Crop: offset from either the beginning or the end of the clip.

    3. Enter the Cropping Point: the offset in seconds.

    4. Click Crop! to crop the clip.

    Selecting a portion of a file to play

    Before you play a media file you can specify that you want to play only a portion of it.

    To select a portion of clip for playing:

    1. In the Edit menu, click Set PlayWindow. This displays the Set PlayWindow dialog box.

    2. Enter the Start and End times of the portion in milliseconds.

    3. Click OK to confirm the clip length.

      When you play the clip, only the selected portion is played.

    Clearing a selected portion

    To set the portion to play back to its original value (entire clip): from the Edit menu, click ClearPlayWindow.

    See Also

    Introduction to the MVS

    MVS GUI layout

    Recording media files

    Playing media files

    Configuring and clearing files

    \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0F593BE1-1220-4403-B04E-B8E8A9A49701.dita --- a/Symbian3/SDK/Source/GUID-0F593BE1-1220-4403-B04E-B8E8A9A49701.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-0F593BE1-1220-4403-B04E-B8E8A9A49701.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,80 +1,78 @@ - - - - - -UI concepts -

    The UI (User Interface) in devices based on the Symbian platform consists -of at least one display for showing output to mobile device users and keys -that allow mobile device users to enter input. The number, size, and resolution -of displays varies among legacy -S60 devices and devices based on the Symbian platform, as do the -keys available for input.

    -Symbian UI -

    The display consists of the following elements:

    -
      -

    • Window - An area on the display. There are windows -that take up the entire display, and other windows that only take up part -of the display. For example, pop-up windows do not cover the entire display. -Pop-up windows have frames and typically the underlying window is partly visible -behind the pop-up window. Access to windows is gained through controls.

      -
      • -

    • Pane - This is a sub-element of a window that is dedicated -to a specific purpose. Windows may contain several panes, and panes may contain -sub-panes.

      • -
    -
    Windows -

    The following figure illustrates a typical window for an application:

    -Symbian UI window -

    Typically, a window contains a status pane, a main pane, and a control -pane.

    - -

    Symbian UI can rotate between portrait and landscape layouts. For more -information on the design implications of this feature, see Symbian -UI with rotation.

    -     -

    By default, the status pane:

    -
      -

    • occupies the top part of the display

      • -

    • shows information on the current application and state, and -general information about the device status, such as signal and battery strength

      -
      • -

    • contains five sub-panes: title pane, context pane, navi -pane, signal pane, and battery pane/universal indicator pane

      -
      • -
    -

    The main pane is in the middle of the display. Applications display -their application state in the main pane.

    -

    By default, the control pane:

    -
      -

    • occupies the bottom part of the display

      • -

    • displays the labels associated with the two softkeys

      -
      • -

    • appears even when pop-up windows are on the display, although -they are not contained in the pop-up window.

      • -
    -

    Mobile device users navigate through applications based on input from -selections in the control pane or key presses. The traditional hierarchical -tree structure forms the basis for navigation, with mobile device users moving -from one node, which represents a state, to another.

    -

    The figure below illustrates an example of a basic state hierarchy.

    -Example of a basic state hierarchy in an application -
    -
    Tabs -

    The Symbian UI supports tabs, which allow you to collect information -for a state onto different pages. These tabs exist in the same node of the -navigation hierarchy. The concept of tabs is related to the term view.

    -

    The following figure illustrates the use of tabs in an application.

    -Windows with tabs -

    The following figures illustrates how tabs appear in the navigation -hierarchy.

    -Example of a hierarchy with tabs -

    See also:

    -
    + + + + + +UI concepts +

    The UI (User Interface) in devices based on the Symbian platform consists +of at least one display for showing output to mobile device users and keys +that allow mobile device users to enter input. The number, size, and resolution +of displays varies among legacy +S60 devices and devices based on the Symbian platform, as do the +keys available for input.

    +Device display and keypad controls +

    The display consists of the following elements:

    +
      +

    • Window - An area on the display. There are windows +that take up the entire display, and other windows that only take up part +of the display. For example, pop-up windows do not cover the entire display. +Pop-up windows have frames and typically the underlying window is partly visible +behind the pop-up window. Access to windows is gained through controls.

      +
      • +

    • Pane - This is a sub-element of a window that is dedicated +to a specific purpose. Windows may contain several panes, and panes may contain +sub-panes.

      • +
    +
    Windows +

    The following figure illustrates a typical window for an application:

    +Symbian UI window +

    Typically, a window contains a status pane, a main pane, and a control +pane.

    + +

    Symbian UI can rotate between portrait and landscape layouts. For more +information on the design implications of this feature, see Symbian +UI with rotation.

    +     +

    By default, the status pane:

    +
      +

    • occupies the top part of the display

      • +

    • shows information on the current application and state, and +general information about the device status, such as signal and battery strength

      +
      • +

    • contains title pane, context pane, navi +pane, signal pane, battery pane, universal indicator +pane and clock pane sub-panes.

      • +
    +

    The main pane is in the middle of the display. Applications display +their application state in the main pane.

    +

    By default, the control pane:

    +
      +

    • occupies the bottom part of the display

      • +

    • displays the labels associated with the two softkeys

      +
      • +
    +

    Mobile device users navigate through applications based on input from +selections in the control pane or key presses. The traditional hierarchical +tree structure forms the basis for navigation, with mobile device users moving +from one node, which represents a state, to another.

    +

    The figure below illustrates an example of a basic state hierarchy.

    +Example of a basic state hierarchy in an application +
    +
    Tabs +

    The Symbian UI supports tabs, which allow you to collect information +for a state onto different pages. These tabs exist in the same node of the +navigation hierarchy. The concept of tabs is related to the term view.

    +

    The following figure illustrates the use of tabs in an application.

    +Windows with tabs +

    The following figures illustrates how tabs appear in the navigation +hierarchy.

    +Example of a hierarchy with tabs +

    See also:

    +
     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0F784804-8452-4C92-ABB3-56B81BAED744.dita --- a/Symbian3/SDK/Source/GUID-0F784804-8452-4C92-ABB3-56B81BAED744.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-0F784804-8452-4C92-ABB3-56B81BAED744.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,54 +1,54 @@ - - - - - -Sensor -Services OverviewThe Sensor Services collection is a group of components that provide -APIs for extending sensors by means of plug-ins and providing channel-based -communication with the sensor hardware. -
    Key Concepts -and Terms
    - -
    Sensor
    -

    A sensor is a hardware measuring device connected to the Symbian -device, which measures a physical quantity in its immediate vicinity and converts -that quantity into small sets of numeric digital values.

    -     - -
    Sensor Subsystem (SSY)
    -

    Sensor Subsystems are plug-ins that connect the sensor hardware with -the sensor server.

    -     -
    -
    Architecture - -Sensor Services Architecture - -

    The Sensor Services collection consists of the following components:

      -

    • Sensor Framework, which provides sensor server and plug-in interfaces -for adding any new sensor plug-in as required. The framework also provides -sensor channel APIs for creating a medium (sensor channel) of exchange between -the client applications and the sensor hardware. The sensor plug-ins retrieve -data from sensor hardware (through sensor channels) and enable the client -applications to use the data for specific requirements.

      • -

    • Data Compensator, which uses data provided by the sensor plug-ins -to correct the sensor axis data based on the current orientation of the Symbian -device. This data can be used by the client applications to display the pages -in portrait or landscape views.

      • - -
    -
    Typical Uses
      -

    • Using Sensor -Channel APIs.

      • -

    • Compensating -Sensor Data for Display Orientation

      • - -
    + + + + + +Sensor +Services OverviewThe Sensor Services collection is a group of components that provide +APIs for extending sensors by means of plug-ins and providing channel-based +communication with the sensor hardware. +
    Key Concepts +and Terms
    + +
    Sensor
    +

    A sensor is a hardware measuring device connected to the Symbian +device, which measures a physical quantity in its immediate vicinity and converts +that quantity into small sets of numeric digital values.

    +     + +
    Sensor Subsystem (SSY)
    +

    Sensor Subsystems are plug-ins that connect the sensor hardware with +the sensor server.

    +     +
    +
    Architecture + +Sensor Services Architecture + +

    The Sensor Services collection consists of the following components:

      +

    • Sensor Framework, which provides sensor server and plug-in interfaces +for adding any new sensor plug-in as required. The framework also provides +sensor channel APIs for creating a medium (sensor channel) of exchange between +the client applications and the sensor hardware. The sensor plug-ins retrieve +data from sensor hardware (through sensor channels) and enable the client +applications to use the data for specific requirements.

      • +

    • Data Compensator, which uses data provided by the sensor plug-ins +to correct the sensor axis data based on the current orientation of the Symbian +device. This data can be used by the client applications to display the pages +in portrait or landscape views.

      • + +
    +
    Typical Uses
      +

    • Using Sensor +Channel APIs.

      • +

    • Compensating +Sensor Data for Display Orientation

      • + +
     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0FD02CAD-B687-50C0-8E44-74ED9B4A936E-master.png Binary file Symbian3/SDK/Source/GUID-0FD02CAD-B687-50C0-8E44-74ED9B4A936E-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0FD02CAD-B687-50C0-8E44-74ED9B4A936E_d0e382729_href.png Binary file Symbian3/SDK/Source/GUID-0FD02CAD-B687-50C0-8E44-74ED9B4A936E_d0e382729_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0FF61B9C-8B0D-5369-B0DA-29AA169B4308_d0e79728_href.png Binary file Symbian3/SDK/Source/GUID-0FF61B9C-8B0D-5369-B0DA-29AA169B4308_d0e79728_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-0FF61B9C-8B0D-5369-B0DA-29AA169B4308_d0e86440_href.png Binary file Symbian3/SDK/Source/GUID-0FF61B9C-8B0D-5369-B0DA-29AA169B4308_d0e86440_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-10540A35-7E8E-40F0-BF93-CBC01884550C_d0e4248_href.png Binary file Symbian3/SDK/Source/GUID-10540A35-7E8E-40F0-BF93-CBC01884550C_d0e4248_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-10540A35-7E8E-40F0-BF93-CBC01884550C_d0e5523_href.png Binary file Symbian3/SDK/Source/GUID-10540A35-7E8E-40F0-BF93-CBC01884550C_d0e5523_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-107AE89E-901E-535F-8D1A-EE347D7822B1.dita --- a/Symbian3/SDK/Source/GUID-107AE89E-901E-535F-8D1A-EE347D7822B1.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-107AE89E-901E-535F-8D1A-EE347D7822B1.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,80 +1,80 @@ - - - - - -ArchitectureThis topic describes the architecture of the Serial Communications -Server. -

    The Serial Communications Server uses the Symbian platform client/server -framework. Clients use R classes that send requests to the -Serial Communications Server. The server in turn passes requests to an appropriate -plug-in module that handles the particular communication protocol. These plug-in -modules are known as Serial Protocol Modules or CSYs. The Serial -Protocol Modules are loaded by the Serial Communications server, and are not -directly accessed by client applications. A Symbian platform phone may include -a number of Serial Protocol Modules as standard, such as for handling RS232 -and infra-red serial communications. The Serial Protocol Module API allows -new Serial Protocol Modules modules to be developed.

    -

    The Serial Communications Server provides a publishedAll API to access -the serial ports of the device. The Serial Communications Server provides -functionality such as timeouts and port sharing for all Serial Protocol Modules. -The Serial Protocol Modules provide the specific protocol and communicate -with the serial device driver. To communicate with the serial device driver, -the Serial Protocol Modules use publishedPartner APIs such as RBusDevComm. -The RBusDevComm API provides a handle to a channel to the -serial device driver. This device driver only implements the basic data transfer -and break operations, and is not intended for use directly by client applications. -The device driver is implemented using a Physical Device Driver (PDD) and -a Logical Device Driver (LDD). The PDD and LDD must be loaded before a Serial -Protocol Module can be used. For a device being tested, the application client -may need to load the PDD and LDD. For a device that is shipped, the boot sequence -normally loads the LDDs and PDDs. Figure 1 below shows the architecture and -the appropriate APIs at each level. Figure 2 below shows the architecture -with three Serial Protocol Modules loaded.

    - - Figure 1 - The architecture and the appropriate APIs at -each level - - - - Figure 2 - The architecture with three CSYs loaded - - - -

    Each serial port has a limited availability when multiple clients attempt -to use the port. The Serial Communications Server provides some functionality -to mediate between competing clients. This mediation is provided by the RComm::Open() and RComm::OpenWithAvailable() APIs. -However, the first client to access a port has control. If a client must get -access to a serial port, then that client must ensure it connects to the serial -port before other clients. The reliable method of ensuring access to a serial -port is for a client to connect as part of the device boot procedure. If a -client must have access to a serial port, then the device manufacturer should -specify which clients access ports during device boot.

    -
    Historical Notes
      -

    1. The framework supplied -by the Serial Communications Server for Serial Protocol Modules has a narrower -set of capabilities compared to the Socket Server for protocol developers.

      2. -

    2. In Symbian platform, -the Serial Communications Server was converted into a multi-threaded server. -The Serial Protocol Modules can be run in separate threads. This change did -not change the behaviour of the Serial Communications Server except for three -changes:

        -

      1. A serial protocol module -which blocks does not stop other Serial Protocol Modules from running

        2. -

      2. A serial protocol module -can run faster than other modules by changing the configured thread priority

        3. -

      3. A serial protocol module -can use the Serial Communications Server API and request services of another -serial protocol module

        4. -
      3. -
    -     - - Client/Server Overview + + + + + +ArchitectureThis topic describes the architecture of the Serial Communications +Server. +

    The Serial Communications Server uses the Symbian platform client/server +framework. Clients use R classes that send requests to the +Serial Communications Server. The server in turn passes requests to an appropriate +plug-in module that handles the particular communication protocol. These plug-in +modules are known as Serial Protocol Modules or CSYs. The Serial +Protocol Modules are loaded by the Serial Communications server, and are not +directly accessed by client applications. A Symbian platform phone may include +a number of Serial Protocol Modules as standard, such as for handling RS232 +and infra-red serial communications. The Serial Protocol Module API allows +new Serial Protocol Modules modules to be developed.

    +

    The Serial Communications Server provides a publishedAll API to access +the serial ports of the device. The Serial Communications Server provides +functionality such as timeouts and port sharing for all Serial Protocol Modules. +The Serial Protocol Modules provide the specific protocol and communicate +with the serial device driver. To communicate with the serial device driver, +the Serial Protocol Modules use publishedPartner APIs such as RBusDevComm. +The RBusDevComm API provides a handle to a channel to the +serial device driver. This device driver only implements the basic data transfer +and break operations, and is not intended for use directly by client applications. +The device driver is implemented using a Physical Device Driver (PDD) and +a Logical Device Driver (LDD). The PDD and LDD must be loaded before a Serial +Protocol Module can be used. For a device being tested, the application client +may need to load the PDD and LDD. For a device that is shipped, the boot sequence +normally loads the LDDs and PDDs. Figure 1 below shows the architecture and +the appropriate APIs at each level. Figure 2 below shows the architecture +with three Serial Protocol Modules loaded.

    + + Figure 1 - The architecture and the appropriate APIs at +each level + + + + Figure 2 - The architecture with three CSYs loaded + + + +

    Each serial port has a limited availability when multiple clients attempt +to use the port. The Serial Communications Server provides some functionality +to mediate between competing clients. This mediation is provided by the RComm::Open() and RComm::OpenWithAvailable() APIs. +However, the first client to access a port has control. If a client must get +access to a serial port, then that client must ensure it connects to the serial +port before other clients. The reliable method of ensuring access to a serial +port is for a client to connect as part of the device boot procedure. If a +client must have access to a serial port, then the device manufacturer should +specify which clients access ports during device boot.

    +
    Historical Notes
      +

    1. The framework supplied +by the Serial Communications Server for Serial Protocol Modules has a narrower +set of capabilities compared to the Socket Server for protocol developers.

      2. +

    2. In Symbian platform, +the Serial Communications Server was converted into a multi-threaded server. +The Serial Protocol Modules can be run in separate threads. This change did +not change the behaviour of the Serial Communications Server except for three +changes:

        +

      1. A serial protocol module +which blocks does not stop other Serial Protocol Modules from running

        2. +

      2. A serial protocol module +can run faster than other modules by changing the configured thread priority

        3. +

      3. A serial protocol module +can use the Serial Communications Server API and request services of another +serial protocol module

        4. +
      3. +
    +     + + Client/Server Overview     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-107F7BC4-F776-512D-AD6F-1674B7ED19B5_d0e281237_href.png Binary file Symbian3/SDK/Source/GUID-107F7BC4-F776-512D-AD6F-1674B7ED19B5_d0e281237_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-107F7BC4-F776-512D-AD6F-1674B7ED19B5_d0e284923_href.png Binary file Symbian3/SDK/Source/GUID-107F7BC4-F776-512D-AD6F-1674B7ED19B5_d0e284923_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-10C32642-CF1C-5C60-A81B-9D65F03A45C4_d0e220786_href.png Binary file Symbian3/SDK/Source/GUID-10C32642-CF1C-5C60-A81B-9D65F03A45C4_d0e220786_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-10C32642-CF1C-5C60-A81B-9D65F03A45C4_d0e224523_href.png Binary file Symbian3/SDK/Source/GUID-10C32642-CF1C-5C60-A81B-9D65F03A45C4_d0e224523_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-10CF321F-3298-4527-BFF5-0351085C7C8C.dita --- a/Symbian3/SDK/Source/GUID-10CF321F-3298-4527-BFF5-0351085C7C8C.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-10CF321F-3298-4527-BFF5-0351085C7C8C.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,24 +1,24 @@ - - - - - -Item -type combinations -

    A list can only be composed of items of the same type. However, it is possible -to use some item types for different purposes. An example is a setting list -that contains an item for accessing a sub-list of settings. In this item, -the value box is omitted so that the item looks like a regular selection item, -and selecting it opens another list. Similar techniques are possible with -other double item types, too.

    - -Setting list containing a non-setting item to access another view - - + + + + + +Item +type combinations +

    A list can only be composed of items of the same type. However, it is possible +to use some item types for different purposes. An example is a setting list +that contains an item for accessing a sub-list of settings. In this item, +the value box is omitted so that the item looks like a regular selection item, +and selecting it opens another list. Similar techniques are possible with +other double item types, too.

    + +Setting list containing a non-setting item to access another view + +     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-114C52FE-C8C5-4418-9C73-CEBB228C7542.dita --- a/Symbian3/SDK/Source/GUID-114C52FE-C8C5-4418-9C73-CEBB228C7542.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-114C52FE-C8C5-4418-9C73-CEBB228C7542.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,42 +1,42 @@ - - - - - -List -types -

    Based on the functionality, the following list categories can be identified:

    -
      -

    • Menu list

      • -

    • Selection list

      • -

    • Markable list

      • -

    • Multi-selection list

      • -

    • Setting list

      • -

    • Hierarchical list

      • -

    • Hierarchical column list

      • -

    • Forms

      • -
    -

    Lists belonging to one category may have different graphical appearances. -See List layouts for -information about different looking list items.

    -

    On the whole, list items and command should not be mixed, but in cases -where some command in a list would significantly boost efficiency and user -experience, it is perfectly acceptable to add one command onto the list. It -is important that there is no more than one command per list, and that the -command is placed as the first item on that list.

    -
    Using -different list types in C++ applications

    The APIs to use for lists -are the Lists API (for menu, selection, markable, and multi-selection -lists) and the Hierarchical lists API (for hierarchical and hierarchical -column lists). For implementation information, see Using the Lists API and Using the Hierarchical lists API.

    For forms, the -API is the Form API. For implementation information, see Using the Form API

    For list types other -than the hierarchical lists, the flags used to create the different list types -in resource files, are described in Listbox types in listbox resource definition.

    -

    See also:

     + + + + + +List +types +

    Based on the functionality, the following list categories can be identified:

    +
      +

    • Menu list

      • +

    • Selection list

      • +

    • Markable list

      • +

    • Multi-selection list

      • +

    • Setting list

      • +

    • Hierarchical list

      • +

    • Hierarchical column list

      • +

    • Forms

      • +
    +

    Lists belonging to one category may have different graphical appearances. +See List layouts for +information about different looking list items.

    +

    On the whole, list items and command should not be mixed, but in cases +where some command in a list would significantly boost efficiency and user +experience, it is perfectly acceptable to add one command onto the list. It +is important that there is no more than one command per list, and that the +command is placed as the first item on that list.

    +
    Using +different list types in applications

    The APIs to use +for lists are the Lists API (for menu, selection, markable, and multi-selection +lists) and the Hierarchical lists API (for hierarchical and hierarchical +column lists). For implementation information, see Using the Lists API and Using the Hierarchical lists API.

    For forms, the +API is the Form API. For implementation information, see Using the Form API

    For list types other than the +hierarchical lists, the flags used to create the different list types in resource +files, are described in Listbox types in listbox resource definition.

    +

    See also:

         \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1158BDD3-69F7-5892-9887-FAE30110E33C_d0e333499_href.png Binary file Symbian3/SDK/Source/GUID-1158BDD3-69F7-5892-9887-FAE30110E33C_d0e333499_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1158BDD3-69F7-5892-9887-FAE30110E33C_d0e339656_href.png Binary file Symbian3/SDK/Source/GUID-1158BDD3-69F7-5892-9887-FAE30110E33C_d0e339656_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-11A79174-485E-425C-9653-193B670A3F03-master.png Binary file Symbian3/SDK/Source/GUID-11A79174-485E-425C-9653-193B670A3F03-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-11A79174-485E-425C-9653-193B670A3F03_d0e51581_href.png Binary file Symbian3/SDK/Source/GUID-11A79174-485E-425C-9653-193B670A3F03_d0e51581_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-11A79174-485E-425C-9653-193B670A3F03_d0e56285_href.png Binary file Symbian3/SDK/Source/GUID-11A79174-485E-425C-9653-193B670A3F03_d0e56285_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-11A79174-485E-425C-9653-193B670A3F03_d0e57133_href.png Binary file Symbian3/SDK/Source/GUID-11A79174-485E-425C-9653-193B670A3F03_d0e57133_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-11A79174-485E-425C-9653-193B670A3F03_d0e64001_href.png Binary file Symbian3/SDK/Source/GUID-11A79174-485E-425C-9653-193B670A3F03_d0e64001_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-11A79174-485E-425C-9653-193B670A3F03_d0e68838_href.png Binary file Symbian3/SDK/Source/GUID-11A79174-485E-425C-9653-193B670A3F03_d0e68838_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-11A79174-485E-425C-9653-193B670A3F03_d0e73982_href.png Binary file Symbian3/SDK/Source/GUID-11A79174-485E-425C-9653-193B670A3F03_d0e73982_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-11B69814-5B3E-42AE-844E-998A7A08E654.dita --- a/Symbian3/SDK/Source/GUID-11B69814-5B3E-42AE-844E-998A7A08E654.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-11B69814-5B3E-42AE-844E-998A7A08E654.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,36 +1,36 @@ - - - - - -Permanent -note -

    Permanent notes remain on the screen for an indefinite time. The user cannot -dismiss them. For example, Insert SIM card.

    -
    - Using permanent notes in C++ applications

    The -API to use for the permanent note component is the Notes API. To use a permanent note with the -default icon, text, sound, and duration, create an instance of the note class CAknStaticNoteDialog.

    You -can change the icon or text displayed in the note, use a different kind of -sound, or change the note duration using the setter methods in the class CAknNoteDialog: SetIconL(), SetTextL(), SetTone(), and SetTimeout().

    - -     -Confirmation -note -Information -note -Warning note - -Error note - -Wait note - -Progress -note + + + + + +Permanent +note +

    Permanent notes remain on the screen for an indefinite time. The user cannot +dismiss them. For example, Insert SIM card.

    +
    + Using permanent notes in applications

    The +API to use for the permanent note component is the Notes API. To use a permanent note with the default icon, +text, sound, and duration, create an instance of the note class CAknStaticNoteDialog.

    You can change the icon +or text displayed in the note, use a different kind of sound, or change the +note duration using the setter methods in the class CAknNoteDialog: SetIconL(), SetTextL(), SetTone(), and SetTimeout().

    + +     +Confirmation +note +Information +note +Warning note + +Error note + +Wait note + +Progress +note     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-11C24609-3B6D-4B44-B003-FB0C07444A9E.dita --- a/Symbian3/SDK/Source/GUID-11C24609-3B6D-4B44-B003-FB0C07444A9E.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-11C24609-3B6D-4B44-B003-FB0C07444A9E.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,122 +1,123 @@ - - - - - -Scrollbars -

    With any list, grid or other component that can be scrolled vertically, -a scrollbar appears on the right-hand side of the component. The scrollbar -is displayed also on pop-up components.

    - -Scroll pane with scrollbar - - -
      -

    • The placement of the scroll handle on the scrollbar reflects the position -of the focus on the scrolling content.

      • -

    • The size of the scroll handle reflects the number of displayed items -relative to the total number of items on the scrolled component.

      • -

    • The scrollbar is displayed even when all items on the component can -be displayed in the same view without scrolling. When this is the case, the -scroll handle is displayed at the maximum size. The only exception is the -Application Shell, where scrollbar is not displayed if all items fit the same -view.

      • -
    -
    Scrollbars -in Touch UI

    In touch devices based on the Symbian platform, scrollbars -(vertical and horizontal) have a touch-enabled scroll box. The hardware keys -(Arrow keys) can also be used for scrolling when the scrollbars are visible. -The scrolling movement on the screen is smooth.

    For the scrollbar to -be more usable with touch, the actual scrollbar area is wider than the visible -scrollbar. When the user scrolls, the scrollbar has a related effect to indicate -the scrolling. Because the actual area of scrollbar is wider, the items appearing -on that area in scrollable list, grids, viewers cannot be touch-enabled, for -example,list icons in column D cannot be tapped.

    -Default control events for scrollbar. - - - -

    User action

     -

    State change

     -

    Feedback

     -     - - - -

    Touch down on a scrollbar, no thumb

     -

    Scrolling is activated when there is a scrollbar under the touch -event. Scrollbar thumb is moved towards the touch down position on the scroll -bar. Scrolling is done for a page at a time.

     -

    Scrollbar color is changed to indicate that the scrollbar has the -control.

    Tactile:

      -
    • No feedback is provided when touch down on a scrollbar and no thumb is -used.
      • -

    • Sensitive slider effect and audio feedback given when thumb is moved -towards the touch down position.

      • -

    • No feedback is provided with touch release.

      • -

     -     - -

    Touch down on a scrollbar thumb

     -

    Scrollbar thumb can be moved in desired direction. Scrollbar thumb -color is changed as an indication to the users that scrolling can be performed.

     -

    Scrollbar thumb color is changed to indicate scrolling activation.

    Tactile: -Sensitive slider effect and audio feedback provided with touch down and release -events.

     -     - -

    Touch down and hold scrollbar, no thumb

     -

    This action performs a “key repeat”. The scrollbar thumb is moved -towards the touch down position

     -

    Tactile: Sensitive slider effect and audio feedback provided with -touch down and with steps.

     -     - -

    Touch down and move

     -

    Scrollbar thumb is moved along with the touch event.

    Touch -down on scrollbar thumb, dragging and touch release are performed on the scrollbar -control area.

     -

    Tactile:

      -

    • Sensitive slider effect and audio feedback provided with touch down -event.

      • -

    • Smooth slider effect provided with the drag event.

      • -

    • Sensitive slider effect provided with touch release.

      • -

     -     - -

    Touch down on scrollbar thumb and move outside the scrollbar control -area

     -

    Scrollbar thumb remains in the position where it was when the finger -left the scrollbar control area.

    If the user moves the touch outside -the scrollbar control area and back, the thumb will continue to move along -with the touch event.

    After touch down on scrollbar thumb, touch is -dragged out from the scrollbar control area, without releasing the touch.

     -

    Tactile: Sensitive slider effect and audio feedback provided with -touch down. No feedback is provided if the thumb is not moving. If the thumb -moves, smooth slide feedback provided.

    If touch release happens -outside the scrollbar, no feedback is provided.

     -     - - -
    -
    Using -scrollbars in C++ applications

    The API to use for creating the scrollbar -component is the Scroller API.

    To use a scrollbar in your application, -first create a scrollbar frame using the class CEikScrollbarFrame. All scrollbar operations are executed via this scrollbar frame. -These operations include creating and destroying the scrollbar, setting its -visibility, and adjusting the scrollbar's model. The scrollbar itself can -be created using the method CreateDoubleSpanScrollBarsL() in the class CEikScrollBarFrame. -The class for the scrollbar is CAknDoubleSpanScrollBar. For implementation information, see Creating a scrollbar.

    Scrollbar models encapsulate -the range of integers which a scrollbar can represent, from zero to n, and -the current position of the scrollbar thumb within that range. To set the -scrollbar model, use the class TAknDoubleSpanScrollbarModel. For information on updating the scrollbar's position and size using -the scrollbar model, see Updating ArrowHead scrollbar attributes and Updating DoubleSpan scrollbar attributes.

    You can -control the scrollbar visibility using the method SetScrollbarVisibilityL() in the class CEikScrollbarFrame.

    To observed scrollbar events, -use the class MEikScrollbarObserver. For implementation information, see Observing scrollbar events.

    + + + + + +Scrollbars +

    With any list, grid or other component that can be scrolled vertically, +a scrollbar appears on the right-hand side of the component. The scrollbar +is displayed also on pop-up components.

    + +Scroll pane with scrollbar + + +
      +

    • The placement of the scroll handle on the scrollbar reflects the position +of the focus on the scrolling content.

      • +

    • The size of the scroll handle reflects the number of displayed items +relative to the total number of items on the scrolled component.

      • +

    • The scrollbar can be displayed in the same view without scrolling. +When this is the case, the scroll handle is displayed at the maximum size. +The only exception is the Application Shell, where scrollbar is not displayed +if all items fit the same view.

      • +
    +
    Scrollbars +in Touch UI

    In touch devices based on the Symbian platform, scrollbars +(vertical and horizontal) have a touch-enabled scroll box. The hardware keys +(Arrow keys) can also be used for scrolling when the scrollbars are visible.

    For +the scrollbar to be more usable with touch, the actual scrollbar area is wider +than the visible scrollbar. When the user scrolls, the scrollbar has a related +effect to indicate the scrolling. Because the actual area of scrollbar is +wider, the items appearing on that area in scrollable list, grids, viewers +cannot be touch-enabled, for example,list icons in column D cannot be tapped.

    Default control events +for scrollbar. + + + +

    User action

     +

    State change

     +

    Feedback

     +     + + + +

    Touch down on a scrollbar, no thumb

     +

    Scrolling is activated when there is a scrollbar under the touch +event. Scrollbar thumb is moved towards the touch down position on the scroll +bar. Scrolling is done for a page at a time.

     +

    Scrollbar color is changed to indicate that the scrollbar has the +control.

    Tactile:

      +
    • No feedback is provided when touch down on a scrollbar and no thumb is +used.
      • +

    • Sensitive slider effect and audio feedback given when thumb is moved +towards the touch down position.

      • +

    • No feedback is provided with touch release.

      • +

     +     + +

    Touch down on a scrollbar thumb

     +

    Scrollbar thumb can be moved in desired direction. Scrollbar thumb +color is changed as an indication to the users that scrolling can be performed.

     +

    Scrollbar thumb color is changed to indicate scrolling activation.

    Tactile: +Sensitive slider effect and audio feedback provided with touch down and release +events.

     +     + +

    Touch down and hold scrollbar, no thumb

     +

    This action performs a “key repeat”. The scrollbar thumb is moved +towards the touch down position

     +

    Tactile: Sensitive slider effect and audio feedback provided with +touch down and with steps.

     +     + +

    Touch down and move

     +

    Scrollbar thumb is moved along with the touch event.

    Touch +down on scrollbar thumb, dragging and touch release are performed on the scrollbar +control area.

     +

    Tactile:

      +

    • Sensitive slider effect and audio feedback provided with touch down +event.

      • +

    • Smooth slider effect provided with the drag event.

      • +

    • Sensitive slider effect provided with touch release.

      • +

     +     + +

    Touch down on scrollbar thumb and move outside the scrollbar control +area

     +

    Scrollbar thumb remains in the position where it was when the finger +left the scrollbar control area.

    If the user moves the touch outside +the scrollbar control area and back, the thumb will continue to move along +with the touch event.

    After touch down on scrollbar thumb, touch is +dragged out from the scrollbar control area, without releasing the touch.

     +

    Tactile: Sensitive slider effect and audio feedback provided with +touch down. No feedback is provided if the thumb is not moving. If the thumb +moves, smooth slide feedback provided.

    If touch release happens +outside the scrollbar, no feedback is provided.

     +     + + +
    +
    Using +scrollbars in applications

    The API to use for creating the scrollbar +component is the Scroller API.

    To use a scrollbar in your application, +first create a scrollbar frame using theCEikScrollbarFrame class. +All scrollbar operations are executed via this scrollbar frame. These operations +include creating and destroying the scrollbar, setting its visibility, and +adjusting the scrollbar's model. The scrollbar itself can be created using +the CEikScrollBarFrame::CreateDoubleSpanScrollBarsL() method. +The class for the scrollbar is CAknDoubleSpanScrollBar. For implementation information, see Creating a scrollbar.

    Scrollbar models encapsulate +the range of integers which a scrollbar can represent, from zero to n, and +the current position of the scrollbar thumb within that range. To set the +scrollbar model, use the TAknDoubleSpanScrollbarModel class. +For information on updating the scrollbar's position and size using the scrollbar +model, see Updating ArrowHead scrollbar attributes and Updating DoubleSpan scrollbar attributes.

    You can +control the scrollbar visibility using the CEikScrollbarFrame::SetScrollbarVisibilityL() method.

    To +observe scrollbar events, use the MEikScrollbarObserver class. +For implementation information, see Observing scrollbar events.

     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-11CBC0BA-3683-584A-9DC9-8BD3C9573F01_d0e107483_href.png Binary file Symbian3/SDK/Source/GUID-11CBC0BA-3683-584A-9DC9-8BD3C9573F01_d0e107483_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-11CBC0BA-3683-584A-9DC9-8BD3C9573F01_d0e114021_href.png Binary file Symbian3/SDK/Source/GUID-11CBC0BA-3683-584A-9DC9-8BD3C9573F01_d0e114021_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-11E35C60-12DF-4014-AB3F-0314D8536AC0_d0e13567_href.png Binary file Symbian3/SDK/Source/GUID-11E35C60-12DF-4014-AB3F-0314D8536AC0_d0e13567_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-11E35C60-12DF-4014-AB3F-0314D8536AC0_d0e14831_href.png Binary file Symbian3/SDK/Source/GUID-11E35C60-12DF-4014-AB3F-0314D8536AC0_d0e14831_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1248ED3E-438C-41E5-81D4-19FC721408BA_d0e81910_href.png Binary file Symbian3/SDK/Source/GUID-1248ED3E-438C-41E5-81D4-19FC721408BA_d0e81910_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1277D793-4A0A-50A7-9414-AEE93E906E80.dita --- a/Symbian3/SDK/Source/GUID-1277D793-4A0A-50A7-9414-AEE93E906E80.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-1277D793-4A0A-50A7-9414-AEE93E906E80.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,60 +1,60 @@ - - - - - -Sockets -Server Architecture -

    This section describes the architecture of the Sockets Server and the framework -that implements sockets in Symbian platform.

    -

    The sockets are similar in concept to Berkeley Software Distribution (BSD) -sockets from the University of California at Berkeley. The sockets provide -a generic interface to network level communications protocols for common operations -in network computing. Common operations are:

    -
      -

    • establish a connection

      • -

    • send data

      • -

    • receive data

      • -

    • configure network protocols

      • -
    -

    The Sockets Client API provides access to other network facilities. Examples -of network facilities are:

    -
      -

    • hostname resolution

      • -

    • service resolution

      • -

    • information about protocols

      • -

    • byte manipulation utilities

      • -
    -
    Required Background

    A -working knowledge of socket based communications is recommended in order to -understand how Symbian platform implements sockets.

    A knowledge of -the selected protocol is also required if the application is going to set -or get values specific to the protocol. For example, the knowledge is required -to understand the data returned from RSocketServ::GetProtocolInfo(). -The knowledge is also required if the application sets Quality -of Service (QoS) values.

    -
    Key Concepts/Terms

    The -Sockets Server starts when Symbian platform starts, and receives requests -for socket based communications. If a request is received for a particular -protocol, the Sockets Server loads the appropriate protocol modules to handle -that request.

    -
    Architectural -relationships

    The Sockets Server provides a generic client interface, -and a server to which particular protocol modules can be plugged in. A client -uses a particular protocol by supplying protocol-specific parameters to Sockets -API functions.

    - Figure 1 - The Socket Server's position in the Communications - Framework Architecture. - -

    The TCP/IP API enables clients to use sockets for TCP/IP, including -UDP, TCP, ICMP, IPv4, IPv6, ARP, and DNS.

    The IrDA Sockets API enables -clients to use sockets for IrDA infra-red.

    The Bluetooth Sockets API -enables clients to use sockets for Bluetooth.

    The SMS PRT API provides -the GSM SMS Protocol stack and the WAP protocol stack over SMS.

    + + + + + +Sockets +Server Architecture +

    This section describes the architecture of the Sockets Server and the framework +that implements sockets in Symbian platform.

    +

    The sockets are similar in concept to Berkeley Software Distribution (BSD) +sockets from the University of California at Berkeley. The sockets provide +a generic interface to network level communications protocols for common operations +in network computing. Common operations are:

    +
      +

    • establish a connection

      • +

    • send data

      • +

    • receive data

      • +

    • configure network protocols

      • +
    +

    The Sockets Client API provides access to other network facilities. Examples +of network facilities are:

    +
      +

    • hostname resolution

      • +

    • service resolution

      • +

    • information about protocols

      • +

    • byte manipulation utilities

      • +
    +
    Required Background

    A +working knowledge of socket based communications is recommended in order to +understand how Symbian platform implements sockets.

    A knowledge of +the selected protocol is also required if the application is going to set +or get values specific to the protocol. For example, the knowledge is required +to understand the data returned from RSocketServ::GetProtocolInfo(). +The knowledge is also required if the application sets Quality +of Service (QoS) values.

    +
    Key Concepts/Terms

    The +Sockets Server starts when Symbian platform starts, and receives requests +for socket based communications. If a request is received for a particular +protocol, the Sockets Server loads the appropriate protocol modules to handle +that request.

    +
    Architectural +relationships

    The Sockets Server provides a generic client interface, +and a server to which particular protocol modules can be plugged in. A client +uses a particular protocol by supplying protocol-specific parameters to Sockets +API functions.

    + Figure 1 - The Socket Server's position in the Communications + Framework Architecture. + +

    The TCP/IP API enables clients to use sockets for TCP/IP, including +UDP, TCP, ICMP, IPv4, IPv6, ARP, and DNS.

    The IrDA Sockets API enables +clients to use sockets for IrDA infra-red.

    The Bluetooth Sockets API +enables clients to use sockets for Bluetooth.

    The SMS PRT API provides +the GSM SMS Protocol stack and the WAP protocol stack over SMS.

    \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1293DE8C-E803-4ADF-9FA8-862519337331.dita --- a/Symbian3/SDK/Source/GUID-1293DE8C-E803-4ADF-9FA8-862519337331.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-1293DE8C-E803-4ADF-9FA8-862519337331.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,58 +1,58 @@ - - - - - -Software -installer -

    End users can install new software from a variety of sources: through -e-mail, Internet downloads, multimedia messaging service (MMS) and WAP push -messages, infrared and Bluetooth connections, PC Suite, and removable memory -cards. The diversity of software vendors and delivery channels requires a -sophisticated system for managing installed software.

    -

    The Symbian Software Installer uses digital signatures and certificates to -authenticate that the application being installed on a mobile device is from -a known vendor. The signature can be obtained through the Symbian -Signed process, and the default certificates installed in the mobile -device act as root certificates. During installation the signature is validated -against the certificates. If they match, the application is installed and -the requested capabilities are -stored in the executable, assuming that the root certificate can grant the -capabilities. Only user capabilities can be granted to unsigned or -self-signed applications, and these are always confirmed by the user.

    - -

    The end users have an option to cancel the installation if they detect -that the vendor of the software package and certificate authority are not -trustworthy. This is especially important when installing security-related -components (for example, VPN clients, firewalls and virus scanners) or other -business-related software.

    -     -

    The Software Installer ensures that no two applications have the same SID value -on a particular target device. The Software Installer has the TCB capability -to read and modify content in the \sys folder -and all its subfolders, which means that you can write to third-party application -executables in the \sys\bin folder when they are installed -through the Software Installer.

    -

    For more information on the Software Installer, see Secure -Software Install Tools.

    -

    The following figure illustrates the steps of software installation:

    -Installation process for signed packages -

    The Software Installer can install the following types of packages:

    -
      -

    • signed sis packages

      • -

    • Java archives (JAR) run by a Java virtual machine

      -
      • -

    • Web Runtime widgets

      • -
    -

    The Software Installer recognizes different devices, which allows you -to define the platforms and devices to which the software can be installed.

    - -

    If you receive an error message when using the Software Installer, see Troubleshooting -Installation Errors at the Symbian Foundation.

    + + + + + +Software +installer +

    End users can install new software from a variety of sources: through +e-mail, Internet downloads, multimedia messaging service (MMS) and WAP push +messages, infrared and Bluetooth connections, PC Suite, and removable memory +cards. The diversity of software vendors and delivery channels requires a +sophisticated system for managing installed software.

    +

    The Symbian Software Installer uses digital signatures and certificates to +authenticate that the application being installed on a mobile device is from +a known vendor. The signature can be obtained through the Symbian +Signed process, and the default certificates installed in the mobile +device act as root certificates. During installation the signature is validated +against the certificates. If they match, the application is installed and +the requested capabilities are +stored in the executable, assuming that the root certificate can grant the +capabilities. Only user capabilities can be granted to unsigned or +self-signed applications, and these are always confirmed by the user.

    + +

    The end users have an option to cancel the installation if they detect +that the vendor of the software package and certificate authority are not +trustworthy. This is especially important when installing security-related +components (for example, VPN clients, firewalls and virus scanners) or other +business-related software.

    +     +

    The Software Installer ensures that no two applications have the same SID value +on a particular target device. The Software Installer has the TCB capability +to read and modify content in the \sys folder +and all its subfolders, which means that you can write to third-party application +executables in the \sys\bin folder when they are installed +through the Software Installer.

    +

    For more information on the Software Installer, see Secure +Software Install Tools.

    +

    The following figure illustrates the steps of software installation:

    +Installation process for signed packages +

    The Software Installer can install the following types of packages:

    +
      +

    • signed sis packages

      • +

    • Java archives (JAR) run by a Java virtual machine

      +
      • +

    • Web Runtime widgets

      • +
    +

    The Software Installer recognizes different devices, which allows you +to define the platforms and devices to which the software can be installed.

    + +

    If you receive an error message when using the Software Installer, see Troubleshooting +Installation Errors at the Symbian Foundation.

     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-12C9C36B-8AD4-544E-A6A3-54A799EF0280.dita --- a/Symbian3/SDK/Source/GUID-12C9C36B-8AD4-544E-A6A3-54A799EF0280.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-12C9C36B-8AD4-544E-A6A3-54A799EF0280.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,252 +1,252 @@ - - - - - -Socket -Server ReferenceThis topic provides a summary of related documentation for the -ESock APIs. - -

    Socket Server APIs:

    - - - - -Server session APIs - -Header -Description - - - - - -

    RSocketServ

    -

     -

    ES_SOCK.H

    -

    RSocketServ establishes and reserves resources for the base communication -session to the socket server. All other client interfaces require a valid -session to be opened

    -     - - -

    RSocketServ Subsession APIs

    -     - -

    RSocket

    -

    ES_SOCK.H

    -

    End point for all socket-based communications.

    -     - -

    RHostResolver

    -

    ES_SOCK.H

    -

    Makes host name resolution queries.

    -     - -

    RConnection

    -

    ES_SOCK.H

    -

    Used to startup and manage active connections. It is possible to -start a connection either implicitly, via the RSocket or RHostResolver APIs, -or explicitly via the RConnection API. The RConnection creates a default subconnection.

    RConnection API Reference

    -     - -

    RSubConnection

    -

    ES_SOCK.H

    -

    Used to organise channels within a connection and manage Quality -of Service. Multihoming-aware applications must use this API. Only valid in -the context of an RConnection.

    -     - -

    RNetDatabase

    -

    ES_SOCK.H

    -

    Interface for network database access.

    -     - -

    RServiceResolver

    -

    ES_SOCK.H

    -

    Provides an interface to resolve service names and ports.

    -     - -

    RConnectionServ

    - -

    ES_SOCK.H

    -

    Provides access to the Comms Management Plane, including Access -Point queries.

    -     - - -
    - -

    Bearer Mobility APIs

    - - - - -Bearer mobility APIs -Header -Description - - - - -

    CActiveCommsMobilityApiExt

    -

    es_mobility_apiext.h

    -

    Comms Mobility API extension for application client running an Active -Scheduler.

    -     - -

    RCommsMobilityApiExt

    -

    es_mobility_apiext.h

    -

    Comms Mobility API extension for application client not running -an Active Scheduler.

    -     - -

    MMobilityProtocolResp

    -

    es_mobility_apiext.h

    -

    Interface to be implemented by the application client to support -mobility API extension. See Bearer -Mobility Client.

    -     - - -
    - -

    How APIs related to the 3-Plane Comms Architecture.

    - Figure 1 - How ESock APIs related to the 3-Plane Comms Architecture - - -

    The Sockets Client API also defines a number of support classes -used in conjunction with the above interfaces. These encapsulate:

      -

    • Addresses: a -base address class TSockAddr is defined. Specific protocol -address classes are derived from this. Each address can be identified by its -Protocol Family, an integer which identifies protocol suites from others.

      • -

    • Resolution queries: -queries made through RHostResolver objects are packaged -in TNameEntry descriptors. These are packages for TNameRecord objects -that contain TSockAddr objects to pass in addresses.

      • -

    • Protocol information: -a comprehensive description of a protocol’s capabilities and properties can -be dynamically obtained through the TProtocolDesc class. -Capabilities are identified by constants.

      • -

    • Endian issues: BigEndian, LittleEndian, -and ByteOrder can be used to order integers to and from -network order.

      • -
    -
    RSubConnection -Events

    CSubConGenEventDataClientJoined, CSubConGenEventDataClientLeft

    These -two events derive from CSubConGenEventDataClientBase, which -provides the functionality for both. The source and destination end points -of the data client are presented with this event, along with the IAP ID of -the connection on which it was created.

    CSubConNotificationEvent

    Both -generic and extension sub-connection events derive from this class. The rules -for generic and extension events are the same as for parameter sets. That -is, a generic event MUST be able to be understood by all technologies.

    The IsGeneric() method -identifies whether the event is generic.

    The GroupId() method -returns the UID of the factory that contains the event, and Id() returns -the class type Id within that factory. These two pieces of information comprise -the STypeId of the event.

    CSubConGenEventParamsGranted

    Notification -of this event occurs after a request to SetParameters() has -been made and negotiation with the network has been completed. A notification -will be received for each family contained in the parameter bundle that was -negotiated successfully. This event presents a generic set and zero or more -extension sets (providing they are supported by the underlying sub-connection -provider technology) of the parameter family identified by the Id returned -from GetFamily().

    CSubConGenEventParamsRejected

    Notification -of this event occurs after a request to SetParameters() has -been made and negotiation with the network has failed for some reason. It -could be an error within the handset software/configuration, or that the network -could not provide the acceptable (minimum) level of QoS. The reason for failure -and the parameter family are presented by the accessor methods Error() and FamilyId(). -Like the CSubConGenEventParamsGranted event, a notification -for CSubConGenEventParamsRejected is received for each -family in the parameter bundle that could not be negotiated successfully.

    CSubConGenEventParamsChanged

    This -event occurs when the properties of a parameter family has been renegotiated -due to some event on the network. It is not sent in response to a request -to change the properties. The change could be the result of an error or just -that the level of QoS has improved/worsened. If a new set of parameters are -available they’ll be presented as with the CSubConGenEventParamsGranted event. -The error status is presented via the Error() method.

    CSubConGenEventSubConDown

    This -event occurs when the underlying sub-connection has been lost. This could -be due to request for it to be closed, or some error on the network. The error -status is presented via the Error() method.

    -
    RSubConnection -QoS Parameters

    CSubConQosGenericParamSet

    - - - - Parameter - Description -Directions - - - - -

    Bandwidth

    -

    Bandwidth the client requires

    -

    Uplink / Downlink

    -     - -

    Maximum Burst Size

    -

    Maximum size of a burst of data the client can handle

    -

    Uplink / Downlink

    -     - -

    Average Packet Size

    -

    Average packet size required (e.g. codec use)

    -

    Uplink / Downlink

    -     - -

    Maximum Packet Size

    -

    Maximum packet size the client can handle

    -

    Uplink / Downlink

    -     - -

    Delay

    -

    Acceptable Delay/Latency

    -

    Uplink / Downlink

    -     - -

    Delay Variation

    -

    Acceptable variation in delay (also known as jitter)

    -

    Uplink / Downlink

    -     - -

    Priority

    -

    Relative priority the client expects to give this channel compared -to it’s other channels

    -

    Uplink / Downlink

    -     - -

    Header mode

    -

    Specify whether the header size should be calculated by the QoS -module or specified by the client. Default is to let the QoS module calculate -it.

    -

    N/A

    -     - -

    Name

    -

    Identity of a “well known” set of QoS Parameters.

    -

    N/A

    -     - - -

    If an extension parameter set is added to the family that contains -conceptually identical parameters to those in the generic set, it is recommended -that you set both instances (generic and extension) of those parameters.

    CSubConQosIPLinkR99ParamSet / CSubConQosR99ParamSet

    Getter and setter methods are provided for each parameter.

    Note: The -constants used for it are KSubConIPParamsUid and KSubConQosIPLinkR99ParamsType.

    The -following parameter sets are available in Symbian platform.

    CSubConQosR5ParamSet

    It -inherits from the release 4/99 set CSubConQosR99ParamSet. -Although it is possible to add both this parameter set and the R4/R99 one, -it is not necessary and should not be done.

    CSubConIMSExtParamSet

    This -class contains the IM CN Signalling Indicator flag.

    - -
    Test programs

    None

    - + + + + + +Socket +Server ReferenceThis topic provides a summary of related documentation for the +ESock APIs. + +

    Socket Server APIs:

    + + + + +Server session APIs + +Header +Description + + + + + +

    RSocketServ

    +

     +

    ES_SOCK.H

    +

    RSocketServ establishes and reserves resources for the base communication +session to the socket server. All other client interfaces require a valid +session to be opened

    +     + + +

    RSocketServ Subsession APIs

    +     + +

    RSocket

    +

    ES_SOCK.H

    +

    End point for all socket-based communications.

    +     + +

    RHostResolver

    +

    ES_SOCK.H

    +

    Makes host name resolution queries.

    +     + +

    RConnection

    +

    ES_SOCK.H

    +

    Used to startup and manage active connections. It is possible to +start a connection either implicitly, via the RSocket or RHostResolver APIs, +or explicitly via the RConnection API. The RConnection creates a default subconnection.

    RConnection API Reference

    +     + +

    RSubConnection

    +

    ES_SOCK.H

    +

    Used to organise channels within a connection and manage Quality +of Service. Multihoming-aware applications must use this API. Only valid in +the context of an RConnection.

    +     + +

    RNetDatabase

    +

    ES_SOCK.H

    +

    Interface for network database access.

    +     + +

    RServiceResolver

    +

    ES_SOCK.H

    +

    Provides an interface to resolve service names and ports.

    +     + +

    RConnectionServ

    + +

    ES_SOCK.H

    +

    Provides access to the Comms Management Plane, including Access +Point queries.

    +     + + +
    + +

    Bearer Mobility APIs

    + + + + +Bearer mobility APIs +Header +Description + + + + +

    CActiveCommsMobilityApiExt

    +

    es_mobility_apiext.h

    +

    Comms Mobility API extension for application client running an Active +Scheduler.

    +     + +

    RCommsMobilityApiExt

    +

    es_mobility_apiext.h

    +

    Comms Mobility API extension for application client not running +an Active Scheduler.

    +     + +

    MMobilityProtocolResp

    +

    es_mobility_apiext.h

    +

    Interface to be implemented by the application client to support +mobility API extension. See Bearer +Mobility Client.

    +     + + +
    + +

    How APIs related to the 3-Plane Comms Architecture.

    + Figure 1 - How ESock APIs related to the 3-Plane Comms Architecture + + +

    The Sockets Client API also defines a number of support classes +used in conjunction with the above interfaces. These encapsulate:

      +

    • Addresses: a +base address class TSockAddr is defined. Specific protocol +address classes are derived from this. Each address can be identified by its +Protocol Family, an integer which identifies protocol suites from others.

      • +

    • Resolution queries: +queries made through RHostResolver objects are packaged +in TNameEntry descriptors. These are packages for TNameRecord objects +that contain TSockAddr objects to pass in addresses.

      • +

    • Protocol information: +a comprehensive description of a protocol’s capabilities and properties can +be dynamically obtained through the TProtocolDesc class. +Capabilities are identified by constants.

      • +

    • Endian issues: BigEndian, LittleEndian, +and ByteOrder can be used to order integers to and from +network order.

      • +
    +
    RSubConnection +Events

    CSubConGenEventDataClientJoined, CSubConGenEventDataClientLeft

    These +two events derive from CSubConGenEventDataClientBase, which +provides the functionality for both. The source and destination end points +of the data client are presented with this event, along with the IAP ID of +the connection on which it was created.

    CSubConNotificationEvent

    Both +generic and extension sub-connection events derive from this class. The rules +for generic and extension events are the same as for parameter sets. That +is, a generic event MUST be able to be understood by all technologies.

    The IsGeneric() method +identifies whether the event is generic.

    The GroupId() method +returns the UID of the factory that contains the event, and Id() returns +the class type Id within that factory. These two pieces of information comprise +the STypeId of the event.

    CSubConGenEventParamsGranted

    Notification +of this event occurs after a request to SetParameters() has +been made and negotiation with the network has been completed. A notification +will be received for each family contained in the parameter bundle that was +negotiated successfully. This event presents a generic set and zero or more +extension sets (providing they are supported by the underlying sub-connection +provider technology) of the parameter family identified by the Id returned +from GetFamily().

    CSubConGenEventParamsRejected

    Notification +of this event occurs after a request to SetParameters() has +been made and negotiation with the network has failed for some reason. It +could be an error within the handset software/configuration, or that the network +could not provide the acceptable (minimum) level of QoS. The reason for failure +and the parameter family are presented by the accessor methods Error() and FamilyId(). +Like the CSubConGenEventParamsGranted event, a notification +for CSubConGenEventParamsRejected is received for each +family in the parameter bundle that could not be negotiated successfully.

    CSubConGenEventParamsChanged

    This +event occurs when the properties of a parameter family has been renegotiated +due to some event on the network. It is not sent in response to a request +to change the properties. The change could be the result of an error or just +that the level of QoS has improved/worsened. If a new set of parameters are +available they’ll be presented as with the CSubConGenEventParamsGranted event. +The error status is presented via the Error() method.

    CSubConGenEventSubConDown

    This +event occurs when the underlying sub-connection has been lost. This could +be due to request for it to be closed, or some error on the network. The error +status is presented via the Error() method.

    +
    RSubConnection +QoS Parameters

    CSubConQosGenericParamSet

    + + + + Parameter + Description +Directions + + + + +

    Bandwidth

    +

    Bandwidth the client requires

    +

    Uplink / Downlink

    +     + +

    Maximum Burst Size

    +

    Maximum size of a burst of data the client can handle

    +

    Uplink / Downlink

    +     + +

    Average Packet Size

    +

    Average packet size required (e.g. codec use)

    +

    Uplink / Downlink

    +     + +

    Maximum Packet Size

    +

    Maximum packet size the client can handle

    +

    Uplink / Downlink

    +     + +

    Delay

    +

    Acceptable Delay/Latency

    +

    Uplink / Downlink

    +     + +

    Delay Variation

    +

    Acceptable variation in delay (also known as jitter)

    +

    Uplink / Downlink

    +     + +

    Priority

    +

    Relative priority the client expects to give this channel compared +to it’s other channels

    +

    Uplink / Downlink

    +     + +

    Header mode

    +

    Specify whether the header size should be calculated by the QoS +module or specified by the client. Default is to let the QoS module calculate +it.

    +

    N/A

    +     + +

    Name

    +

    Identity of a “well known” set of QoS Parameters.

    +

    N/A

    +     + + +

    If an extension parameter set is added to the family that contains +conceptually identical parameters to those in the generic set, it is recommended +that you set both instances (generic and extension) of those parameters.

    CSubConQosIPLinkR99ParamSet / CSubConQosR99ParamSet

    Getter and setter methods are provided for each parameter.

    Note: The +constants used for it are KSubConIPParamsUid and KSubConQosIPLinkR99ParamsType.

    The +following parameter sets are available in Symbian platform.

    CSubConQosR5ParamSet

    It +inherits from the release 4/99 set CSubConQosR99ParamSet. +Although it is possible to add both this parameter set and the R4/R99 one, +it is not necessary and should not be done.

    CSubConIMSExtParamSet

    This +class contains the IM CN Signalling Indicator flag.

    + +
    Test programs

    None

    +     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-130C21D7-0A39-5A54-8545-C82B2ED4398C.dita --- a/Symbian3/SDK/Source/GUID-130C21D7-0A39-5A54-8545-C82B2ED4398C.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-130C21D7-0A39-5A54-8545-C82B2ED4398C.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,120 +1,120 @@ - - - - - -Simultaneous -Call TutorialThis tutorial describes how to handle two call with the telephony -API for applications. -

    This state diagram shows how to dial or answer one or two calls -at a time.

    - Simultaneous Call State Diagram - -

    The boxes are states. The enumeration value in each box is the status -of the voice line. Voice -line status describes these states and their meaning. The arrows show -events that trigger a change of state. In these events, a word in bold indicates -a CTelephony method that you can call.

    - - - - - -check the Voice -line status for other calls -
      -

    • if the line is Idle (CTelephony::EStatusIdle) -then no calls are in progress

      • -

    • if the line is on -hold (CTelephony::EStatusHold) then there is another -call in progress, but it is on hold and you can still dial or answer a second -call. Now go to point four below

      • -

    • if another call is active, -you must wait until it completes before you can dial or receive a call.

      • -
     -     - - Dial a call -while no calls are in progress, the line's status is CTelephony::EStatusIdle. -To dial a call, use CTelephony::DialNewCall(). If dialling -was successful and the remote party answers the call then the line's status -will become CTelephony::EStatusConnected. - - - Answer a call -while no calls are in progress, the line's status is CTelephony::EStatusIdle. -When a remote party calls your phone, the voice line's status will change -to CTelephony::EStatusRinging. -When the status is CTelephony::EStatusRinging, use CTelephony::AnswerIncomingCall() to -answer the call. The status will change to CTelephony::EStatusConnected and -the phone user can talk to the remote party. - - - Terminate the -call - - -detect Remote -Termination of a call - - - Hold a Call - - - Resume a call - - - Send DTMF tones -down the line - - - Line and call -information - - - Answer -a second call -at some point, a remote party might try to ring your phone. It is answered -in the same way as the first -The voice line state will change to CTelephony::EStatusRinging. -You can receive notification when this occurs; see Detect -an incoming call. Before answering the second call, you must put the -original call on hold. This is shown in the diagram above. - - - Dial -a second call -you can also dial a second call in the same way as the first. Once again, -you must put your original call on hold before dialling the second call - - -a CTelephony::TCallId will be given to you when you -successfully connect a second call. You will also have a CTelephony::TCallId from -the first call. Now you will be the owner of two calls: at any one time, one -will always be active and one will always be on hold. -Now you can: -
      -

    • Terminate -either call. If you terminate the active call then you will -be left with a call on hold. If you terminate the on-hold call then -you will be left with an active call.

      • -

    • Detect -remote party terminating either call. Once again, if the active call -ends then you will be left with a call on hold and vice versa.

      • -

    • Swap -held and active calls.

      • -
     -     -     -     -     -     -Single Call - Tutorial + + + + + +Simultaneous +Call TutorialThis tutorial describes how to handle two call with the telephony +API for applications. +

    This state diagram shows how to dial or answer one or two calls +at a time.

    + Simultaneous Call State Diagram + +

    The boxes are states. The enumeration value in each box is the status +of the voice line. Voice +line status describes these states and their meaning. The arrows show +events that trigger a change of state. In these events, a word in bold indicates +a CTelephony method that you can call.

    + + + + + +check the Voice +line status for other calls +
      +

    • if the line is Idle (CTelephony::EStatusIdle) +then no calls are in progress

      • +

    • if the line is on +hold (CTelephony::EStatusHold) then there is another +call in progress, but it is on hold and you can still dial or answer a second +call. Now go to point four below

      • +

    • if another call is active, +you must wait until it completes before you can dial or receive a call.

      • +
     +     + + Dial a call +while no calls are in progress, the line's status is CTelephony::EStatusIdle. +To dial a call, use CTelephony::DialNewCall(). If dialling +was successful and the remote party answers the call then the line's status +will become CTelephony::EStatusConnected. + + + Answer a call +while no calls are in progress, the line's status is CTelephony::EStatusIdle. +When a remote party calls your phone, the voice line's status will change +to CTelephony::EStatusRinging. +When the status is CTelephony::EStatusRinging, use CTelephony::AnswerIncomingCall() to +answer the call. The status will change to CTelephony::EStatusConnected and +the phone user can talk to the remote party. + + + Terminate the +call + + +detect Remote +Termination of a call + + + Hold a Call + + + Resume a call + + + Send DTMF tones +down the line + + + Line and call +information + + + Answer +a second call +at some point, a remote party might try to ring your phone. It is answered +in the same way as the first +The voice line state will change to CTelephony::EStatusRinging. +You can receive notification when this occurs; see Detect +an incoming call. Before answering the second call, you must put the +original call on hold. This is shown in the diagram above. + + + Dial +a second call +you can also dial a second call in the same way as the first. Once again, +you must put your original call on hold before dialling the second call + + +a CTelephony::TCallId will be given to you when you +successfully connect a second call. You will also have a CTelephony::TCallId from +the first call. Now you will be the owner of two calls: at any one time, one +will always be active and one will always be on hold. +Now you can: +
      +

    • Terminate +either call. If you terminate the active call then you will +be left with a call on hold. If you terminate the on-hold call then +you will be left with an active call.

      • +

    • Detect +remote party terminating either call. Once again, if the active call +ends then you will be left with a call on hold and vice versa.

      • +

    • Swap +held and active calls.

      • +
     +     +     +     +     +     +Single Call + Tutorial     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1319CEA4-56D7-45DF-9C22-45291017992E_d0e3434_href.png Binary file Symbian3/SDK/Source/GUID-1319CEA4-56D7-45DF-9C22-45291017992E_d0e3434_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1319CEA4-56D7-45DF-9C22-45291017992E_d0e4709_href.png Binary file Symbian3/SDK/Source/GUID-1319CEA4-56D7-45DF-9C22-45291017992E_d0e4709_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1376F42B-1B1E-431E-8E60-4FDBAD34EA15.ditamap --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-1376F42B-1B1E-431E-8E60-4FDBAD34EA15.ditamap Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,7136 @@ + + + + +Symbian Developer Library for Application +Developers +Symbian Developer Library for Application Developers + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Touch UI support +From S60 5th Edition, all GUI applications must work with +devices that have touch screens. This section describes how to use +UI components with touch support, and how applications can receive +touch related events. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +API specifications +This section provides information on using the touch UI +component and tactile feedback APIs. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +API Specifications + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-13987218-9427-455E-AC77-ADE6B0E9CD7E.dita --- a/Symbian3/SDK/Source/GUID-13987218-9427-455E-AC77-ADE6B0E9CD7E.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-13987218-9427-455E-AC77-ADE6B0E9CD7E.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,64 +1,65 @@ - - - - - -Introduction -to Symbian^3The Symbian platform, is a comprehensive open-source software platform -for Symbian-based devices. The platform is used by device manufactures to -build devices, and by third-party developers to create after-market applications -for installation onto devices. -
    Overview

    The -Symbian platform includes a customizable user interface, a rich set of applications, -common user interface components (AVKON, UIKON) and development tools for -implementing new applications. It also includes tools and documentation that -enables device creators and application developers to create feature-rich -devices and applications.

    The Symbian platform architecture is divided -into different layers:

      -

    • The Applications Layer consists of application specific UI and -engine components. It uses the services provided by Middleware and OS layers.

      • -

    • The Middleware Layer consists of domains which provide services -to the application layer; for example, Multimedia, Networking and Location -services.

      • -

    • The Operating System (OS) Layer provides all higher-level -OS services across a full range of technology domains such as communications, -networking, graphics, multimedia and so on. It also includes low-level OS -services such as frameworks, libraries and utilities, which turn the abstracted -hardware and OS mechanisms into a programmable interface.

      • -

    • The Adaptation layer integrates the generic platform software -with the phone’s cellular platform. It is implemented by the device creators -though reference implementations are provided with the platform.

      Give link to the adaptation documentation.
      • -

    • The Cellular Platform is the device-specific hardware and cellular -software that performs the services required by the Symbian platform.

      • -

    For more information about layers of the Symbian platform and the -packages contained within it, see the Package view of the current Symbian Foundation platform.

    -Architecture of the Symbian platform - -

    A layer can have packages from any technology -domain. Technology domains are a group of packages, each of which is -a collection of components. To understand more about the architecture, what -the platform offers, see Introduction -to Symbian Developer Community.

    -
    Platform UID

    The -platform UID for Symbian^3 is 0x20022E6D.

    -
    Download
      -

    • You can download the Application Development Toolkit and Product Development -Toolkit from the Symbian Developer Website.

      • - -
    -     - -What's new -in Symbian^3 -New C++ APIs -in Symbian^3 -Porting applications -to Symbian^3 - + + + + + +Introduction to Symbian^3The Symbian platform, is a comprehensive open-source software +platform for Symbian-based devices. The platform is used by device +manufactures to build devices, and by third-party developers to create +after-market applications for installation onto devices. +
    Overview

    The Symbian platform includes a customizable user interface, a +rich set of applications, common user interface components (AVKON, +UIKON) and development tools for implementing new applications. It +also includes tools and documentation that enables device creators +and application developers to create feature-rich devices and applications.

    The Symbian platform architecture is divided into different layers:

      +

    • The Applications Layer consists of application specific +UI and engine components. It uses the services provided by Middleware +and OS layers.

      • +

    • The Middleware Layer consists of domains which provide +services to the application layer; for example, Multimedia, Networking +and Location services.

      • +

    • The Operating System (OS) Layer provides all higher-level +OS services across a full range of technology domains such as communications, +networking, graphics, multimedia and so on. It also includes low-level +OS services such as frameworks, libraries and utilities, which turn +the abstracted hardware and OS mechanisms into a programmable interface.

      • +

    • The Adaptation layer integrates the generic platform +software with the phone’s cellular platform. It is implemented by +the device creators though reference implementations are provided +with the platform.

      Give +link to the adaptation documentation.
      • +

    • The Cellular Platform is the device-specific hardware +and cellular software that performs the services required by the Symbian +platform.

      • +

    For more information about layers of the Symbian platform +and the packages contained within it, see the Package view of the current Symbian Foundation platform.

    +Architecture of the Symbian platform + +

    A layer can have packages from any technology domain. Technology domains are +a group of packages, each of which is a collection of components. +To understand more about the architecture, what the platform offers, +see Introduction to Symbian Developer Community.

    +
    Platform +UID

    The platform UID for Symbian^3 is 0x20022E6D.

    +
    Download
      +

    • You can download the Symbian Foundation Application Development +Toolkit and Product Development Toolkit from the Symbian Developer Website.

      • + +
    +     + +What's +new in Symbian^3 +New +C++ APIs in Symbian^3 + +Porting applications from S60 5th Edition to Symbian^3 + +     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-13C95985-D16F-5A9E-A7F8-CAB637C4C6ED.dita --- a/Symbian3/SDK/Source/GUID-13C95985-D16F-5A9E-A7F8-CAB637C4C6ED.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-13C95985-D16F-5A9E-A7F8-CAB637C4C6ED.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,121 +1,121 @@ - - - - - -DBMS -OverviewProvides an interface to relational databases. -
    Purpose

    The -DBMS component provides an interface to relational databases. It enables you -to create and access databases either from a single client or from multiple -clients sharing access over a server.

    -
    Required background

    To use DBMS you need a knowledge -of relational databases and the SQL query language.

    -
    Key concepts and terms
    - -
    Store database
    -

    A client-side single client database stored in permanent file stores, -implemented by RDbStoreDatabase

    -     - -
    Named database
    -

    A database allowing simultaneous read/write access by multiple clients, -implemented by RDbNamedDatabase

    -     -
    -
    Architecture

    DBMS defines a general relational -database access API, and allows different database implementations to be provided -of which there are two: a small and relatively lightweight client-side implementation; -and, for when multiple clients must have write access to a database, a client-server -implementation.

    When multiple clients can access the same database, -transactions ensure that only one client can change data at a time.

    The File Stores API defines -a sophisticated file storage, called permanent file stores, that allows individual -entries in a file to be modified. The database implementations use these stores -for the underlying data storage.

    - DBMS Class Diagrams - -
    -
    DBMS Summary

    DBMS provides the following:

      -

    • Database Management -System Library

      edbms.dll

      • -

    • Database Management -System Server

      edbsrv.exe

      • -
    -
    APIs - - - -API -Description - - - - -

    RDbDatabase

    -

    Abstract database class.

    -     - -

    RDbStoreDatabase

    -

    Implements RDbDatabase as a store database.

    -     - -

    RDbNamedDatabase

    -

    Implements a named database.

    -     - -

    RDbRowSet

    -

    The base class for all rowset types.

    -     - -

    RDbTable

    -

    Provides access to table data as a rowset.

    -     - -

    RDbView

    -

    Generates rowsets from an SQL query.

    -     - -

    TDbQuery

    -

    A wrapper for an SQL string combined with a text comparison mode.

    -     - -

    TDbWindow

    -

    Describes the desired shape of a view's pre-evaluation window.

    -     - -

    RDbNotifier

    -

    Provides notification of database changes to clients.

    -     - - -
    -
    Typical uses

    DBMS is very well suited to applications -with small to medium-sized datasets, where the total record count is less -than 10,000 and the database size is less than 512KB. It scales reasonably -well to larger datasets with total record counts less than 100,000 and database -sizes less than 10MB.

    DBMS is a suitable database engine for applications -such as:

      -

    • address books

      • -

    • call logs

      • -

    • message stores.

      • -
    -     -Persistent -Storage Overview -DBMS -rowsets overview -DBMS columns, -column sets, and keys overview -DBMS sharing -databases overview -DBMS incremental -operations overview -File stores -overview + + + + + +DBMS +OverviewProvides an interface to relational databases. +
    Purpose

    The +DBMS component provides an interface to relational databases. It enables you +to create and access databases either from a single client or from multiple +clients sharing access over a server.

    +
    Required background

    To use DBMS you need a knowledge +of relational databases and the SQL query language.

    +
    Key concepts and terms
    + +
    Store database
    +

    A client-side single client database stored in permanent file stores, +implemented by RDbStoreDatabase

    +     + +
    Named database
    +

    A database allowing simultaneous read/write access by multiple clients, +implemented by RDbNamedDatabase

    +     +
    +
    Architecture

    DBMS defines a general relational +database access API, and allows different database implementations to be provided +of which there are two: a small and relatively lightweight client-side implementation; +and, for when multiple clients must have write access to a database, a client-server +implementation.

    When multiple clients can access the same database, +transactions ensure that only one client can change data at a time.

    The File Stores API defines +a sophisticated file storage, called permanent file stores, that allows individual +entries in a file to be modified. The database implementations use these stores +for the underlying data storage.

    + DBMS Class Diagrams + +
    +
    DBMS Summary

    DBMS provides the following:

      +

    • Database Management +System Library

      edbms.dll

      • +

    • Database Management +System Server

      edbsrv.exe

      • +
    +
    APIs + + + +API +Description + + + + +

    RDbDatabase

    +

    Abstract database class.

    +     + +

    RDbStoreDatabase

    +

    Implements RDbDatabase as a store database.

    +     + +

    RDbNamedDatabase

    +

    Implements a named database.

    +     + +

    RDbRowSet

    +

    The base class for all rowset types.

    +     + +

    RDbTable

    +

    Provides access to table data as a rowset.

    +     + +

    RDbView

    +

    Generates rowsets from an SQL query.

    +     + +

    TDbQuery

    +

    A wrapper for an SQL string combined with a text comparison mode.

    +     + +

    TDbWindow

    +

    Describes the desired shape of a view's pre-evaluation window.

    +     + +

    RDbNotifier

    +

    Provides notification of database changes to clients.

    +     + + +
    +
    Typical uses

    DBMS is very well suited to applications +with small to medium-sized datasets, where the total record count is less +than 10,000 and the database size is less than 512KB. It scales reasonably +well to larger datasets with total record counts less than 100,000 and database +sizes less than 10MB.

    DBMS is a suitable database engine for applications +such as:

      +

    • address books

      • +

    • call logs

      • +

    • message stores.

      • +
    +     +Persistent +Storage Overview +DBMS +rowsets overview +DBMS columns, +column sets, and keys overview +DBMS sharing +databases overview +DBMS incremental +operations overview +File stores +overview     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-13D48922-4DEF-56A6-8ADE-DD1DB280627B_d0e396107_href.png Binary file Symbian3/SDK/Source/GUID-13D48922-4DEF-56A6-8ADE-DD1DB280627B_d0e396107_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-13D48922-4DEF-56A6-8ADE-DD1DB280627B_d0e396269_href.png Binary file Symbian3/SDK/Source/GUID-13D48922-4DEF-56A6-8ADE-DD1DB280627B_d0e396269_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-13DEE42F-3EAB-4EB7-9CE1-C4930BCACE01.dita --- a/Symbian3/SDK/Source/GUID-13DEE42F-3EAB-4EB7-9CE1-C4930BCACE01.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-13DEE42F-3EAB-4EB7-9CE1-C4930BCACE01.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,31 +1,33 @@ - - - - - -List query -

    A List query offers a list of predefined choices for the user. It can be -used when more than two options must be offered to the user. There is a prompt -text (optional) on top of the window, and a list of options to choose from.

    -

    The list in a List query is a menu list: the user can select an item or -dismiss the query; the Options menu is not available. The default softkey -labels are OK on the left and Cancel on the right, the actual texts can be -specific to the context. The Selection key causes the same action as the left -softkey.

    -

    Any list item layout suitable for menu lists can be used; see List -layouts.

    - -List query - - -

    The number of items in the list should be kept low, so that all items can -be seen without scrolling.

    -
    Using list queries in -C++ applications

    For implementation information, see Queries.

    + + + + + +List +query +

    A List query offers a list of predefined choices for the user. It can be +used when more than two options must be offered to the user. There is a prompt +text (optional) on top of the window, and a list of options to choose from.

    +

    The list in a List query is a menu list: the user can select an item or +dismiss the query; the Options menu is not available. The default softkey +labels are OK on the left and Cancel on the right, the actual texts can be +specific to the context. The Selection key causes the same action as the left +softkey.

    +

    Any list item layout suitable for menu lists can be used; see List +layouts.

    + +List query + + +

    The number of items in the list should be kept low, so that all items can +be seen without scrolling.

    +
    Using +list queries in applications

    For implementation information, +see Queries.

     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-13F10D4C-BA0C-5B46-804D-191A70C36324_d0e287313_href.png Binary file Symbian3/SDK/Source/GUID-13F10D4C-BA0C-5B46-804D-191A70C36324_d0e287313_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-13F10D4C-BA0C-5B46-804D-191A70C36324_d0e290946_href.png Binary file Symbian3/SDK/Source/GUID-13F10D4C-BA0C-5B46-804D-191A70C36324_d0e290946_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-141D8786-9987-4E5E-9395-484C87B323FB_d0e290621_href.png Binary file Symbian3/SDK/Source/GUID-141D8786-9987-4E5E-9395-484C87B323FB_d0e290621_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-141D8786-9987-4E5E-9395-484C87B323FB_d0e294116_href.png Binary file Symbian3/SDK/Source/GUID-141D8786-9987-4E5E-9395-484C87B323FB_d0e294116_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-14FAE656-7CDE-56ED-ACB2-7853276C24E9.dita --- a/Symbian3/SDK/Source/GUID-14FAE656-7CDE-56ED-ACB2-7853276C24E9.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-14FAE656-7CDE-56ED-ACB2-7853276C24E9.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,23 +1,21 @@ - - - - - -S60 Platform: -Descriptor ExampleExamples that explains how to use descriptors. -

    This C++ code example demonstrates how to use descriptors (Symbian OS strings) -and related APIs. The example is an S60 application that is used to run one -example method or all of them. The methods write a log on the screen or into -a file that demonstrates the results of different statements. The example -has been updated to support S60 5th Edition and touch UI. Important classes: -TBuf, HBufC, RBuf.

    -

    For more details, click on this link : Descriptors example..

    -

    Download

    Click on the following link to download -the example: DescriptorExample .zip .

    View the example code: browse .

    + + + + + +Descriptor +ExampleExamples that explains how to use descriptors. +

    This C++ code example demonstrates how to use descriptors and related APIs. +The example is an S60 application that is used to run one example method or +all of them. The methods write a log on the screen or into a file that demonstrates +the results of different statements.

    +

    Download

    Click +on the following link to download the example: DescriptorExample .zip .

    View the example code: browse .

    +
    Class Summary

    TBuf

    TBufC

    TPtr

    TPtrC

    HBufC

    RBuf

     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-15591211-58D3-56B6-868F-D34C30ED7A7A_d0e176040_href.png Binary file Symbian3/SDK/Source/GUID-15591211-58D3-56B6-868F-D34C30ED7A7A_d0e176040_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-15591211-58D3-56B6-868F-D34C30ED7A7A_d0e182634_href.png Binary file Symbian3/SDK/Source/GUID-15591211-58D3-56B6-868F-D34C30ED7A7A_d0e182634_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-155C5B39-CB9B-5405-B9BB-EB34CA7C43BC_d0e338662_href.png Binary file Symbian3/SDK/Source/GUID-155C5B39-CB9B-5405-B9BB-EB34CA7C43BC_d0e338662_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-155C5B39-CB9B-5405-B9BB-EB34CA7C43BC_d0e344859_href.png Binary file Symbian3/SDK/Source/GUID-155C5B39-CB9B-5405-B9BB-EB34CA7C43BC_d0e344859_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-15CAB5AF-CAA5-5D1B-9236-7874BF944484_d0e333212_href.png Binary file Symbian3/SDK/Source/GUID-15CAB5AF-CAA5-5D1B-9236-7874BF944484_d0e333212_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-15CAB5AF-CAA5-5D1B-9236-7874BF944484_d0e339369_href.png Binary file Symbian3/SDK/Source/GUID-15CAB5AF-CAA5-5D1B-9236-7874BF944484_d0e339369_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-15D5E0D3-B643-5C72-A3D4-03E2480890EF_d0e15332_href.png Binary file Symbian3/SDK/Source/GUID-15D5E0D3-B643-5C72-A3D4-03E2480890EF_d0e15332_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-15D5E0D3-B643-5C72-A3D4-03E2480890EF_d0e20914_href.png Binary file Symbian3/SDK/Source/GUID-15D5E0D3-B643-5C72-A3D4-03E2480890EF_d0e20914_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-15F209D1-6BC6-5207-B443-25306C232CFC_d0e109780_href.png Binary file Symbian3/SDK/Source/GUID-15F209D1-6BC6-5207-B443-25306C232CFC_d0e109780_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-15F209D1-6BC6-5207-B443-25306C232CFC_d0e116318_href.png Binary file Symbian3/SDK/Source/GUID-15F209D1-6BC6-5207-B443-25306C232CFC_d0e116318_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1635E243-BDC9-55D8-8913-0D2DB622B22C_d0e186764_href.png Binary file Symbian3/SDK/Source/GUID-1635E243-BDC9-55D8-8913-0D2DB622B22C_d0e186764_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1635E243-BDC9-55D8-8913-0D2DB622B22C_d0e192309_href.png Binary file Symbian3/SDK/Source/GUID-1635E243-BDC9-55D8-8913-0D2DB622B22C_d0e192309_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-165EE4DD-C9CA-430B-8377-068A4194716E.dita --- a/Symbian3/SDK/Source/GUID-165EE4DD-C9CA-430B-8377-068A4194716E.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-165EE4DD-C9CA-430B-8377-068A4194716E.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,74 +1,73 @@ - - - - - -Modifying -applications to support single-tap Symbian^3 enhances the touch interaction by providing support -for single-tap. -

    S60 5th Edition -introduced touch support feature with double-tap to maintain binary and source -code compatibility with the existing S60 3.x applications. The UI was focus -driven, with the first tap for object selection (the corresponding event forwarded -to the application) and the second tap for activation.

    Symbian^3 enhances -the touch support with single tap for achieving better usability and development -of platform and 3rd party applications. The supporting UI is based on direct -manipulation and is not focus driven, which means that a single-tap on the -device selects and activates an event. This change modifies the touch behavior -of certain UI components as listed below:

      -

    • By default, none of the menu items are highlighted.

      • -

    • Item specific options are displayed in stylus menus rather than in -options menus.

      • -

    • The side toolbar is hidden in the landscape layout view except in specific -applications like the message viewer and editor.

      • -

    It is highly recommended that you migrate your applications to -single-tap to complement the platform UI behavior. However, if you do not -migrate your applications to single-tap, they work the same way as in S60 -5th Edition (touch support with double-tap). The UI components can be -used in hybrid devices for both touch and non-touch events. For details, see Designing application UIs -for touch and non-touch devices.

    - -Include the EAknTouchCompatible and EAknSingleClickCompatible flags in your application's UI (CAknAppUi ) constructor. -

    For example,

    void CFileBrowseBaseView::ConstructL() //Called from framework (CEikDocument) -{ - ... - BaseConstructL(EAknEnableSkin | EAknEnableMSK | EAknTouchCompatible | EAknSingleClickCompatible); - ... -}     -

    The EAknTouchCompatible flag enables touch functionality. -The EAknSingleClickCompatible flag enables single-click -functionality on the Symbian device.

     -

    The following illustrations show how applications behave before -and after the single-tap changes are made:

    -Double-tap enabled: By default, UI component is highlighted. - - -Single-tap enabled: By default, no UI component is highlighted. - -     -     -Hide item-specific -commands from the application's menus, submenus and toolbars. Item-specific -commands are functions that are specific to an item. For example, Edit is -an item-specific command for an existing contact in the Phone book. -

    As a result, all item-specific options are hidden in menus, -submenus and toolbars and are displayed in the stylus -popup menus.

    -     -Activate -items in a list on single-tap. - -Disable -stylus popup menu in AVKON lists. - -Disable -hardware key shortcuts. - -     + + + + + +Modifying applications to support single-tap Symbian^3 enhances the touch interaction by providing +support for single-tap. +

    S60 5th +Edition introduced touch support feature with double-tap to maintain +binary and source code compatibility with the existing S60 3.x applications. +The UI was focus driven, with the first tap for object selection (the +corresponding event forwarded to the application) and the second tap +for activation.

    Symbian^3 enhances the touch support with single +tap for achieving better usability and development of platform and +3rd party applications. The supporting UI is based on direct manipulation +and is not focus driven, which means that a single-tap on the device +selects and activates an event. This change modifies the touch behavior +of certain UI components as listed below:

      +

    • By default, none of the menu items are highlighted.

      • +

    • Item specific options are displayed in stylus menus rather +than in options menus.

      • +

    • The side toolbar is hidden in the landscape layout view except +in specific applications like the message viewer and editor.

      • +

    It is highly recommended that you migrate your applications +to single-tap to complement the platform UI behavior. However, if +you do not migrate your applications to single-tap, they work the +same way as in S60 5th Edition (touch support with double-tap).

    + +Include +the EAknTouchCompatible and EAknSingleClickCompatible flags in your application's UI (CAknAppUi ) constructor. +

    For example,

    void CFileBrowseBaseView::ConstructL() //Called from framework (CEikDocument) +{ + ... + BaseConstructL(EAknEnableSkin | EAknEnableMSK | EAknTouchCompatible | EAknSingleClickCompatible); + ... +}     +

    The EAknTouchCompatible flag enables touch +functionality. The EAknSingleClickCompatible flag +enables single-click functionality on the Symbian device.

     +

    The following illustrations show how applications behave +before and after the single-tap changes are made:

    +Double-tap enabled: By default, UI component is highlighted. + + +Single-tap enabled: By default, no UI component is highlighted. + +     +     +Hide item-specific +commands from the application's menus, submenus and toolbars. +Item-specific commands are functions that are specific to an item. +For example, Edit is an item-specific command for an existing +contact in the Phone book. +

    As a result, all item-specific options are hidden in +menus, submenus and toolbars and are displayed in the stylus popup menus.

    +     +Activate items in +a list on single-tap. + +Disable stylus popup +menu in AVKON lists. + +Disable hardware +key shortcuts. + +         \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-16950F22-F5DE-4D52-8414-544105BA3200.dita --- a/Symbian3/SDK/Source/GUID-16950F22-F5DE-4D52-8414-544105BA3200.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-16950F22-F5DE-4D52-8414-544105BA3200.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,138 +1,135 @@ - - - - - -Hierarchical -list -

    The hierarchical list component (a "tree list") is available for use in -dialogs that deal with moving items to and from (or copying them) from one -folder to another. The main use situation for the component is the File Manager -folder and file browsing, when the actual data is being showed in the same -view. The hierarchical list component allows users to browse through their -folder content by having a list and its content available simultaneously: -the user can simply expand a listed item (folder) to show its content.

    -

    Unlike the other Symbian list types, the hierarchical list component is -not structured on the A D column structure. Visually, the hierarchical levels -are connected with vertical lines (see the figure below), and the folders -in each hierarchy level are shown before files on that same level. Scroll -bars function as usual (vertical bar is always present, horizontal bar is -available when necessary), and the list does not loop by default, although -it is possible to enable looping. Marquee scrolling is supported, but if not -used, the names of folders and files are truncated where necessary. The height -and the vertical distribution of the folder/file texts on the list is the -same as in normal lists. Hierarchical lists can be used both in the main pane -and as pop-ups.

    - -Hierarchical list component - - -

    Owing to the need for horizontal scrolling, it is not possible to use tabs -in the Navi pane. Typically the hierarchical list component is capable of -showing three hierarchy levels in portrait orientation, but this may vary -according to the display sizes and resolutions as well as the display orientation. -The order of folders (sorting order) on each level is defined by the application.

    -

    General navigation:

    -
      -

    • Arrow keys either expand collapsed folders (Arrow right, the focus -does not move yet), collapse expanded folders (Arrow left: one press to move -the focus onto the parent folder when there is one, second press to collapse -the contents), or move the focus into the direction of scrolling.

      • -

    • The Selection key expands collapsed (or vice versa) folders or opens -files under focus.

      • -

    • Commands for expanding, collapsing and opening folders or files are -also available in the Options menu.

      • -
    -Default touch -events for hierarchical list items - - - - - - -

    User action

     -

    State change

     -

    Feedback

     -     - - - -

    Touch down on collapsed folder

     -

    No change

     -

    Highlight is shown.

    Tactile: Basic list effect and audio feedback -is provided with touch down event.

     -     - -

    Touch release on collapsed folder

     -

    Item is expanded. If the folder is empty, the only action performed -is that the icon is changed to expanded folder indication.

     -

    Highlight disappears.

    Tactile: Basic list effect is provided -with touch release event.

     -     - -

    Touch down on expanded folder

     -

    No change

     -

    Highlight is shown.

    Tactile: Basic list effect and audio -feedback is provided with touch release event.

     -     - -

    Touch release on expanded folder

     -

    Item is collapsed.

    If the folder is empty, only action is -that the icon is changed to collapsed folder indication.

     -

    Highlight disappears.

    Tactile: Basic list effect is provided -with touch release event.

     -     - -

    Touch down and hold on folder

     -

    Stylus pop-up menu opens.

     -

    Highlight is shown. Animation is shown to indicate the opening pop-up.

    Tactile: -If activates a long touch, then increasing long touch effect given with hold -event and pop-up effect is provided when the pop-up is opened.

     -     - -

    Touch down on file

     -

    No change

     -

    Highlight is shown.

    Tactile: Sensitive list effect and audio -feedback is provided with touch down event.

     -     - -

    Touch release on file

     -

    Item is activated.

     -

    Highlight disappears.

    Tactile: Sensitive list effect is provided -with touch down and release event.

     -     - -

    Touch down and hold on file

     -

    Stylus pop-up menu is opened.

     -

    Highlight is shown. Animation is shown to indicate the opening pop-up.

    Tactile: -If activates a long touch, then increasing long touch effect given with hold -event and pop-up effect given when the pop-up is opened.

     -     - -

    Touch down on item and move

     -

    Refer to Dragging -and flicking events

    Expand and collapse functions are not done -while dragging.

     -

    Tactile: Refer to Dragging -and flicking events.

     -     - -

    Touch down on item and move horizontally

     -

    Inactive

     -

    Tactile: No effect

     -     - - -
    -
    Using -hierarchical lists in C++ applications

    The API to use for hierarchical -lists is the Hierarchical lists API. For implementation information, -see Using the Hierarchical lists API.

    + + + + + +Hierarchical +list +

    The hierarchical list component (a "tree list") is available for use in +dialogs that deal with moving items to and from (or copying them) from one +folder to another. The main use situation for the component is the File Manager +folder and file browsing, when the actual data is being showed in the same +view. The hierarchical list component allows users to browse through their +folder content by having a list and its content available simultaneously: +the user can simply expand a listed item (folder) to show its content.

    +

    Unlike the other Symbian list types, the hierarchical list component is +not structured on the A D column structure. Visually, the hierarchical levels +are connected with vertical lines (see the figure below), and the folders +in each hierarchy level are shown before files on that same level. Scroll +bars function as usual (vertical bar is always present, horizontal bar is +available when necessary), and the list does not loop by default, although +it is possible to enable looping. Marquee scrolling is supported, but if not +used, the names of folders and files are truncated where necessary. The height +and the vertical distribution of the folder/file texts on the list is the +same as in normal lists. Hierarchical lists can be used both in the main pane +and as pop-ups.

    + +Hierarchical list component + + +

    Owing to the need for horizontal scrolling, it is not possible to use tabs +in the Navi pane. Typically the hierarchical list component is capable of +showing three hierarchy levels in portrait orientation, but this may vary +according to the display sizes and resolutions as well as the display orientation. +The order of folders (sorting order) on each level is defined by the application.

    +

    General navigation:

    +
      +

    • Arrow keys either expand collapsed folders (Arrow right, the focus +does not move yet), collapse expanded folders (Arrow left: one press to move +the focus onto the parent folder when there is one, second press to collapse +the contents), or move the focus into the direction of scrolling.

      • +

    • The Selection key expands collapsed (or vice versa) folders or opens +files under focus.

      • +

    • Commands for expanding, collapsing and opening folders or files are +also available in the Options menu.

      • +
    +Default touch +events for hierarchical list items + + + +

    User action

     +

    State change

     +

    Feedback

     +     + + + +

    Touch down on collapsed folder

     +

    No change

     +

    Highlight is shown.

    Tactile: Basic list effect and audio feedback +is provided with touch down event.

     +     + +

    Touch release on collapsed folder

     +

    Item is expanded. If the folder is empty, the only action performed +is that the icon is changed to expanded folder indication.

     +

    Highlight disappears.

    Tactile: Basic list effect is provided +with touch release event.

     +     + +

    Touch down on expanded folder

     +

    No change

     +

    Highlight is shown.

    Tactile: Basic list effect and audio +feedback is provided with touch release event.

     +     + +

    Touch release on expanded folder

     +

    Item is collapsed.

    If the folder is empty, only action is +that the icon is changed to collapsed folder indication.

     +

    Highlight disappears.

    Tactile: Basic list effect is provided +with touch release event.

     +     + +

    Touch down and hold on folder

     +

    Stylus pop-up menu opens.

     +

    Highlight is shown. Animation is shown to indicate the opening pop-up.

    Tactile: +If activates a long touch, then increasing long touch effect given with hold +event and pop-up effect is provided when the pop-up is opened.

     +     + +

    Touch down on file

     +

    No change

     +

    Highlight is shown.

    Tactile: Sensitive list effect and audio +feedback is provided with touch down event.

     +     + +

    Touch release on file

     +

    Item is activated.

     +

    Highlight disappears.

    Tactile: Sensitive list effect is provided +with touch down and release event.

     +     + +

    Touch down and hold on file

     +

    Stylus pop-up menu is opened.

     +

    Highlight is shown. Animation is shown to indicate the opening pop-up.

    Tactile: +If activates a long touch, then increasing long touch effect given with hold +event and pop-up effect given when the pop-up is opened.

     +     + +

    Touch down on item and move

     +

    Refer to Dragging +and flicking events

    Expand and collapse functions are not done +while dragging.

     +

    Tactile: Refer to Dragging +and flicking events.

     +     + +

    Touch down on item and move horizontally

     +

    Inactive

     +

    Tactile: No effect

     +     + + +
    +
    Using +hierarchical lists in applications

    The API to use for hierarchical +lists is the Hierarchical lists API. For implementation information, +see Using the Hierarchical lists API.

     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-16B42854-F27D-5CB3-BCFE-8F711793EE60_d0e375093_href.png Binary file Symbian3/SDK/Source/GUID-16B42854-F27D-5CB3-BCFE-8F711793EE60_d0e375093_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-16B42854-F27D-5CB3-BCFE-8F711793EE60_d0e381172_href.png Binary file Symbian3/SDK/Source/GUID-16B42854-F27D-5CB3-BCFE-8F711793EE60_d0e381172_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-16BA7B80-DC75-512C-AAEC-F571B5B73F09.dita --- a/Symbian3/SDK/Source/GUID-16BA7B80-DC75-512C-AAEC-F571B5B73F09.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,12 +0,0 @@ - - - - - -Cryptography API guide

    The cryptography API provides cryptographic services to the user software through a standard Symbian platform interface.

    Note: The strong cryptography API guide is not publically available.

    \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-16C323DC-B43F-5621-B617-C31FBB25379B_d0e371844_href.png Binary file Symbian3/SDK/Source/GUID-16C323DC-B43F-5621-B617-C31FBB25379B_d0e371844_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-16C323DC-B43F-5621-B617-C31FBB25379B_d0e377914_href.png Binary file Symbian3/SDK/Source/GUID-16C323DC-B43F-5621-B617-C31FBB25379B_d0e377914_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-16D0854D-55EF-4E22-B7D2-72603699BC59.dita --- a/Symbian3/SDK/Source/GUID-16D0854D-55EF-4E22-B7D2-72603699BC59.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-16D0854D-55EF-4E22-B7D2-72603699BC59.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,29 +1,28 @@ - - - - - -Empty -lists and grids -

    If there are no items to be displayed in a list or grid, the pane contains -a text informing the user about the empty list. The information displayed -in the list should be designed to provide as much help and guidance to the -user as possible. Instead of merely stating that a list is empty, the text -should point the user to some useful direction in the application in order -to add content.

    - -Empty list: the primary font used for informing of an empty list (left), -the secondary font (right) used in addition to provide the user with further -information (used only in cases when genuinely useful additional information -is available) - - -

    Depending on the case, the text may be aligned to prompt the user to create -the first item for an empty list.

    + + + + + +Empty +lists and grids +

    If there are no items to be displayed in a list or grid, the pane contains +a text informing the user about the empty list. The information displayed +in the list should be designed to provide as much help and guidance to the +user as possible. Instead of merely stating that a list is empty, the text +should point the user to some useful direction in the application in order +to add content.

    + +Empty list: the primary font is used to inform about an empty list +and provide the user with further information (used only in cases when genuinely +useful additional information is available). + + +

    Depending on the case, the text may be aligned to prompt the user to create +the first item for an empty list.

     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-16E7CF5D-4364-5F42-94FF-9F79BB52523D-GENID-1-8-1-3-1-1-4-1.dita --- a/Symbian3/SDK/Source/GUID-16E7CF5D-4364-5F42-94FF-9F79BB52523D-GENID-1-8-1-3-1-1-4-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,13 +0,0 @@ - - - - - -AnimationThis section explains how to create basic client-side animation -and server-side sprite animation using the Animation framework. \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-16E7CF5D-4364-5F42-94FF-9F79BB52523D-GENID-1-8-1-6-1-1-4-1-3-1.dita --- a/Symbian3/SDK/Source/GUID-16E7CF5D-4364-5F42-94FF-9F79BB52523D-GENID-1-8-1-6-1-1-4-1-3-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,13 +0,0 @@ - - - - - -AnimationThis section explains how to create basic client-side animation -and server-side sprite animation using the Animation framework. \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-16E7CF5D-4364-5F42-94FF-9F79BB52523D.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-16E7CF5D-4364-5F42-94FF-9F79BB52523D.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,13 @@ + + + + + +AnimationThis section explains how to create basic client-side animation +and server-side sprite animation using the Animation framework. \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1704898B-7836-53C2-8743-F733836EDE7B_d0e332834_href.png Binary file Symbian3/SDK/Source/GUID-1704898B-7836-53C2-8743-F733836EDE7B_d0e332834_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1704898B-7836-53C2-8743-F733836EDE7B_d0e338991_href.png Binary file Symbian3/SDK/Source/GUID-1704898B-7836-53C2-8743-F733836EDE7B_d0e338991_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-170EDC68-77C7-4FD9-A81E-C9F75698F7A3.dita --- a/Symbian3/SDK/Source/GUID-170EDC68-77C7-4FD9-A81E-C9F75698F7A3.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-170EDC68-77C7-4FD9-A81E-C9F75698F7A3.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,35 +1,35 @@ - - - - - -Implementing -support for scalable UIFor the correct control to receive touch events, you must implement -support for scalable UI. -

    In Touch UI devices, supporting scalable UI is even more crucial than before. -Traditionally, the problem was that the application did not scale to fit the -screen size correctly.

    -

    For more information on scalable UI, see Scalability section.

    -

    In Touch UI, there is also another consideration, the Symbian platform -may not receive touch events, or it may receive touch events for the incorrect -control, because there is a problem with knowing the correct location of the -touch event.

    -

    The following figures illustrate code required for handling scalable UI -events.

    - -Scalable UI implementation in control - - - -Scalable UI implementation in UI controller - - -

    For further implementation information, see Handling -layout change events.

    + + + + + +Implementing +support for scalable UIFor the correct control to receive touch events, you must implement +support for scalable UI. +

    In Touch UI devices, supporting scalable UI is even more crucial than before. +Traditionally, the problem was that the application did not scale to fit the +screen size correctly.

    +

    For more information on scalable UI, see Scalability section.

    +

    In Touch UI, there is also another consideration, the Symbian platform +may not receive touch events, or it may receive touch events for the incorrect +control, because there is a problem with knowing the correct location of the +touch event.

    +

    The following figures illustrate code required for handling scalable UI +events.

    + +Scalable UI implementation in control + + + +Scalable UI implementation in UI controller + + +

    For further implementation information, see Handling +layout change events.

     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-173D7E50-92FA-42D7-A01B-47A39216E98D-master.png Binary file Symbian3/SDK/Source/GUID-173D7E50-92FA-42D7-A01B-47A39216E98D-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-173D7E50-92FA-42D7-A01B-47A39216E98D_d0e62371_href.png Binary file Symbian3/SDK/Source/GUID-173D7E50-92FA-42D7-A01B-47A39216E98D_d0e62371_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-173D7E50-92FA-42D7-A01B-47A39216E98D_d0e63892_href.png Binary file Symbian3/SDK/Source/GUID-173D7E50-92FA-42D7-A01B-47A39216E98D_d0e63892_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-173D7E50-92FA-42D7-A01B-47A39216E98D_d0e67482_href.png Binary file Symbian3/SDK/Source/GUID-173D7E50-92FA-42D7-A01B-47A39216E98D_d0e67482_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-173D7E50-92FA-42D7-A01B-47A39216E98D_d0e69123_href.png Binary file Symbian3/SDK/Source/GUID-173D7E50-92FA-42D7-A01B-47A39216E98D_d0e69123_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1742B2A1-6EC1-5368-919B-362516A5D452_d0e368182_href.png Binary file Symbian3/SDK/Source/GUID-1742B2A1-6EC1-5368-919B-362516A5D452_d0e368182_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1742B2A1-6EC1-5368-919B-362516A5D452_d0e374252_href.png Binary file Symbian3/SDK/Source/GUID-1742B2A1-6EC1-5368-919B-362516A5D452_d0e374252_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1747534D-063A-45B0-8636-E7767F984BB0.dita --- a/Symbian3/SDK/Source/GUID-1747534D-063A-45B0-8636-E7767F984BB0.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-1747534D-063A-45B0-8636-E7767F984BB0.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,30 +1,30 @@ - - - - - -Generating -a Certificate Request -

    Create a private key and a self signed certificate as explained -in the Creating a Private -Key and Self Signed Certificate.

    - -Run MakeKeys at -the command prompt using the -req option. -

    The following is the syntax:

    > makekeys -req [-v] [-password <password>] -dname <distinguished-name-string> <private-key-file> <public-key-cert><cert-request-file>The <cert-request-file> must specify -a name for the output certificate request file with .p10 extension.     -

    For example,

    > makekeys -req -dname "CN=Symbian Foundation Developer O=Symbian Foundation C=GB" HelloWorld.key HelloWorld.cer HelloWorldreq.p10 -

    Here, the -dname provides a simple distinguished -name string to the MakeKeys tool. HelloWorld.key is the private -key file and HelloWorld.cer is the public key self-signed -certificate file that were created previously using MakeKeys. Helloworldreq.p10 is -the name of the output certificate request file.

    -     -     + + + + + +Generating +a Certificate Request +

    Create a private key and a self signed certificate as explained +in the Creating a Private +Key and Self Signed Certificate.

    + +Run MakeKeys at +the command prompt using the -req option. +

    The following is the syntax:

    > makekeys -req [-v] [-password <password>] -dname <distinguished-name-string> <private-key-file> <public-key-cert><cert-request-file>The <cert-request-file> must specify +a name for the output certificate request file with .p10 extension.     +

    For example,

    > makekeys -req -dname "CN=Symbian Foundation Developer O=Symbian Foundation C=GB" HelloWorld.key HelloWorld.cer HelloWorldreq.p10 +

    Here, the -dname provides a simple distinguished +name string to the MakeKeys tool. HelloWorld.key is the private +key file and HelloWorld.cer is the public key self-signed +certificate file that were created previously using MakeKeys. Helloworldreq.p10 is +the name of the output certificate request file.

    +     +         \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-176913BA-3877-58E2-9E12-3606EE697813.dita --- a/Symbian3/SDK/Source/GUID-176913BA-3877-58E2-9E12-3606EE697813.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-176913BA-3877-58E2-9E12-3606EE697813.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,12 +1,77 @@ - - - - - - Overview

    This document introduces to the Advanced Camera Settings library in Ecam. The Advanced Camera Settings library is used by application developers to enable camera users to configure camera settings and by device creators to define default and mandatory software and hardware configuration settings.

    Purpose

    Advanced Camera Settings provides domain specific getters and setters for well known camera hardware settings. Image or video format, sizes and video frame rates are already well defined in the general Ccamera API.

    Advanced Camera Settings Library Details

    The DLL that provides the functionality and the library to which your code must link is identified below.

    DLL LIB Short Description

    ecamadvsettings.dll

    ecam.lib

    These files are used for implementing the Advanced Settings.

    Architectural Relationship

    The Advanced Settings is a part of the camera component.

    Description

    The advanced settings class, CCamera::CCameraAdvancedSettings, provides access to common camera hardware settings related to image acquisition for still images and video.

    To allow the settings to be both flexible and rich enough to work with different camera hardware, settings are identified by UID values. You can get a list of UIDs of the supported and currently active settings, so that a user interface of the available options can be updated accordingly. The class also allows the range of possible values for a setting to be obtained.

    Key Advanced Settings API Classes

    The key classes that make up the Advanced Settings are as follows:

    • MCameraPresets

    • MCameraAdvancedSettings

    • CCamera::CCameraAdvancedSettings

    Using Advanced Camera Settings

    Clients can use the Advanced Settings to:

    • Build up a configuration set for a camera including:

      • Camera type. CCamera::CCameraAdvancedSettings::TCameraType

      • Stabilization mode. CCamera::CCameraAdvancedSettings::TStabilizationMode

      • Focus Mode. CCamera::CCameraAdvancedSettings::TFocusMode

      • plus several other configuration specifiers such as TDriveMode, TBracketMode, TPictureOrientation and several others.

    • List the UIDs of the supported and currently active settings, so that the user interface can be updated accordingly.

    • Support the continuous digital zooming functionality.

    See also

    Overview of Camera Framework

    Advanced Settings for Focus, Drive Modes, and Bracket Modes

    Continuous Digital Zooming

    \ No newline at end of file + + + + + + Overview +

    This document introduces to the Advanced Camera Settings library in Ecam. +The Advanced Camera Settings library is used by application developers to +enable camera users to configure camera settings and by device creators to +define default and mandatory software and hardware configuration settings.

    +
    Purpose

    Advanced Camera Settings provides domain +specific getters and setters for well known camera hardware settings. Image +or video format, sizes and video frame rates are already well defined in the +general CCamera API.

    Advanced +Camera Settings Library Details

    The DLL that provides the functionality +and the library to which your code must link is identified below.

    + + + +DLL +LIB +Short Description + + + + +ecamadvsettings.dll +ecam.lib +

    These files are used for implementing the Advanced Settings.

    +     + + +
    +
    Architectural Relationship

    The Advanced Settings +is a part of the camera component.

    +
    Description

    The advanced settings class, CCamera::CCameraAdvancedSettings, +provides access to common camera hardware settings related to image acquisition +for still images and video.

    To allow the settings to be both flexible +and rich enough to work with different camera hardware, settings are identified +by UID values. You can get a list of UIDs of the supported and currently active +settings, so that a user interface of the available options can be updated +accordingly. The class also allows the range of possible values for a setting +to be obtained.

    +
    Key Advanced Settings API Classes

    The key classes +that make up the Advanced Settings are as follows:

      +

    • MCameraPresets

      • +

    • MCameraAdvancedSettings

      • +

    • CCamera::CCameraAdvancedSettings

      • +
    +
    Using Advanced Camera Settings

    Clients can use +the Advanced Settings to:

      +

    • Build up a configuration +set for a camera including:

        +

      • Camera type. CCamera::CCameraAdvancedSettings::TCameraType

        • +

      • Stabilization mode. CCamera::CCameraAdvancedSettings::TStabilizationMode

        • +

      • Focus Mode. CCamera::CCameraAdvancedSettings::TFocusMode

        • +

      • plus several other configuration +specifiers such as TDriveMode, TBracketMode, TPictureOrientation and +several others.

        • +
      • +

    • List the UIDs of the +supported and currently active settings, so that the user interface can be +updated accordingly.

      • +

    • Support the continuous +digital zooming functionality.

      • +
    +
    See also

    Overview of +Camera Framework

    Advanced +Settings for Focus, Drive Modes, and Bracket Modes

    Continuous +Digital Zooming

    +     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-17C64C2F-9426-4B41-9F0A-23060289D644.dita --- a/Symbian3/SDK/Source/GUID-17C64C2F-9426-4B41-9F0A-23060289D644.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-17C64C2F-9426-4B41-9F0A-23060289D644.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,80 +1,88 @@ - - - - - -Multi-touch -

    Multi-touch is an enhancement to the touch screen, which provides the user -with the ability to apply elaborate finger gestures onto the display as commands -to the device.

    -

    Multi-touch is implemented based on the size and type of interfaces. When -a finger or an object touches the display causing the light to scatter, the -reflection is caught by the sensors. The response for the touch is sent back -based on the type of reflection measured.

    -

    Only the devices with multi-touch support have 'Pinch Stroke' as a touch -stroke.

    -
    Pinch StrokePinch -stroke is invoked by two separate but simultaneously active touch down events -and dragging movements along the line that goes through both touch down points. -On release, the pinch in or pinch out state is maintained. Pinch stroke can -be utilized, for example, in Photo viewer to zoom in and zoom out. - -

    The following table lists the default touch-events for pinch-stroke:

    Default touch events -for pinch-stroke - - - -

    User action

     -

    State change

     -

    Feedback

     -     - - - -

    First touch down

     -

    No action.

     -

    Tactile:

      -

    • First touch down tactile feedback follows the context-based feedback.

      • -

    • Audio feedback is provided with touch down.

      • -

     -     - -

    Second simultaneous touch down

     -

    Activates multi-touch mode for the content defined.

     -

    Tactile:

      -

    • When second finger is touched down multi-touch recognition, two sensitive -pulses effect is provided.

      • -

    • Audio feedback is provided with touch down.

      • -

     -     - -

    Pinch in

     -

    Moving the touch points (directly) closer to each other is recognized -as pinch in. Application can use it, for example, for zooming out a picture. -The behavior should be in relation to the speed and size of the stroke.

     -

    Tactile: Smooth pinch effect is provided while moving the fingers.

    No -audio feedback is provided.

     -     - -

    Pinch out

     -

    Moving the touch points (directly) away from each other is recognized -as pinch out. Application can use it, for example, for zooming in a picture. -The behavior should be in relation to the speed and size of the stroke.

     -

    Tactile: Smooth pinch effect is provided while moving the fingers.

    No -audio feedback is provided.

     -     - -

    Touch release

     -

    Releasing one or both fingers stops the pinch.

     -

    No tactile or audio feedback given.

     -     - - -
    + + + + + +Multi-touch +

    Multi-touch is an enhancement to the touch screen, which provides +the user with the ability to apply elaborate finger gestures onto +the display as commands to the device.

    +

    Multi-touch is implemented based on the size and type of interfaces. +When a finger or an object touches the display causing the light to +scatter, the reflection is caught by the sensors. The response for +the touch is sent back based on the type of reflection measured.

    +

    Only the devices with multi-touch support have 'Pinch Stroke' as +a touch stroke.

    +
    Pinch +StrokePinch stroke is invoked by two separate but simultaneously +active touch down events and dragging movements along the line that +goes through both touch down points. On release, the pinch in or pinch +out state is maintained. Pinch stroke can be utilized, for example, +in Photo viewer to zoom in and zoom out. + +

    The following table lists the default touch-events for pinch-stroke:

    Default +touch events for pinch-stroke + + + +

    User action

     +

    State change

     +

    Feedback

     +     + + + +

    First touch down

     +

    No action.

     +

    Tactile:

      +

    • First touch down tactile feedback follows the context-based +feedback.

      • +

    • Audio feedback is provided with touch down.

      • +

     +     + +

    Second simultaneous touch down

     +

    Activates multi-touch mode for the content defined.

     +

    Tactile:

      +

    • When second finger is touched down multi-touch recognition, +two sensitive pulses effect is provided.

      • +

    • Audio feedback is provided with touch down.

      • +

     +     + +

    Pinch in

     +

    Moving the touch points (directly) closer to each other +is recognized as pinch in. Application can use it, for example, for +zooming out a picture. The behavior should be in relation to the speed +and size of the stroke.

     +

    Tactile: Smooth pinch effect is provided while moving the +fingers.

    No audio feedback is provided.

     +     + +

    Pinch out

     +

    Moving the touch points (directly) away from each other +is recognized as pinch out. Application can use it, for example, for +zooming in a picture. The behavior should be in relation to the speed +and size of the stroke.

     +

    Tactile: Smooth pinch effect is provided while moving the +fingers.

    No audio feedback is provided.

     +     + +

    Touch release

     +

    Releasing one or both fingers stops the pinch.

     +

    No tactile or audio feedback given.

     +     + + +
    +
    Using multi-touch in applicationsFor multi-touch, +use classes TRawEvent and TAdvancedPointerEvent (which extends TPointerEvent). For more information, +see Advanced +pointers section.
     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-17D1489B-F7F7-5CA7-9F81-850AA9ACEFEB_d0e332498_href.png Binary file Symbian3/SDK/Source/GUID-17D1489B-F7F7-5CA7-9F81-850AA9ACEFEB_d0e332498_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-17D1489B-F7F7-5CA7-9F81-850AA9ACEFEB_d0e338655_href.png Binary file Symbian3/SDK/Source/GUID-17D1489B-F7F7-5CA7-9F81-850AA9ACEFEB_d0e338655_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-17DE7D55-00C9-5D40-8AE4-39BDB20FCC5B.dita --- a/Symbian3/SDK/Source/GUID-17DE7D55-00C9-5D40-8AE4-39BDB20FCC5B.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-17DE7D55-00C9-5D40-8AE4-39BDB20FCC5B.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,117 +1,117 @@ - - - - - -BIO -Messaging Framework Overview -

    The BIO Messaging Framework provides a framework supports plug-ins which -receive, parse and process BIO messages

    -

    Bearer Independent Objects (BIO) messages contain data that can be received -and interpreted by the device. Unlike conventional messages—such as, SMS and -email, BIO messages does not depend on the type of transport over which it -is received. not intended to be read by the user in their raw form. BIO messages -can be received over a number of bearers: IR, Bluetooth, SMS and WAP Push.

    -
    Purpose

    Plug-ins supported by the framework handle -incoming BIO messages received by a phone. BIO messages are sent to the system -to update attributes on the system.

    Examples of BIO messages are vCards -vCals, device settings, ringtones, graphical logos and icons, Internet access -point setup messages and Over the Air (OTA) configuration messages. vCards -are parsed and then displayed to the user, and when accepted they modify the -user’s contact database. OTA configuration messages are parsed before they -are displayed to the user, and if accepted they create email accounts or internet -access points.

    -
    Key terms
    - -
    vCard
    -

    An electronic business card, which is a collection of properties. Properties -can be a property name, one or more property parameters. and a property value.

    -     - -
    vCal
    -

    An electronic calendar entry, which consists of a collection of properties.

    -     -
    -
    Architecture

    BIO Messaging Framework comprises -of three main components—BIO -MTM, BIO -database and BIO -parser.

    BIO messages are not received by the BIO Message Framework -directly. They come over other subsystems to the BIO database. For example, -the SMS watchers receive BIO messages from the SMS stack and use BIO Messaging -Framework to tag the messages with the correct BIO ID.

    The following -figure illustrates the BIO Messaging Framework architecture:

    - BIO Messaging Framework architecture - -

    BIO database

    The -BIO database is used to identify the type of BIO messages. It maps message -attributes, such as port number, MIME type, or leading string to a BIO type. -These attributes are then used by clients of the BIO Message Framework to -determine what ports to listen for messages. For example, SMS messages which -start with that string and, when storing these messages in the inbox, tag -them with the BIO ID associated with that leading string.

    BIO watcher

    BIO -watcher is part of the Watcher -Framework, which handles BIO messages that come from the SMS and WAP -stack. It firsts identifies the type of BIO message using the BIO database, -and then creates a BIO message in a Message Store using the messaging APIs.

    BIF -files and utilities

    BIO Information Files (BIF) are resource files -that are read by the BIO database to provide registration information of BIO -message types. There is one BIF file for every BIO message type. They encapsulate -the information required for identifying BIO messages. The information may -include the expected port number, MIME type or leading string. Different BIO -watchers use different information.

    BIF files can be one of two formats. -The first format is a resource file and the second format is a custom binary -format for representing the data fields in the BIF file. The BIF utilities -(bifu.dll) provide the functionality to read information -in BIF files of both formats.

    BIO -MTM

    The BIO Client MTM is responsible for loading the BIO database -and BIO utilities to handle parse or process requests from messaging clients. -It is called by a messaging client to parse or process a BIO message that -is saved in a Message Store. If the client is trusted with the correct capabilities, -the BIO parser DLLs are loaded successfully. Without the right capabilities, -the DLLs will not run. A BIO watcher saves the BIO message with the BIO flag -and the appropriate BIO type set.

    The BIO MTM does not support sending -messages and therefore does not support reply or forward of BIO messages. -Forwarding and replying to BIO messages is supported by the MTM that the message -is sent over, for example SMS.

    BIO -parser and utilities

    BIO parsers are plug-ins (DLLs) that provide -parsing and processing functionality for incoming BIO messages. The parser -uses BIO utilities to provide base functionality. BIO utilities that load -the BIO parser use the DLL filename and load the DLLs from the \sys\bin location.

    Each -BIO parser implements the ParseL and ProcessL functions. -The level of functionality varies between parsers. Some parsers update the -final repository with the received data. For example, the WAP parser updates -the CommDb with the received settings. Some parsers save -data in an unparsed state for processing by another component. This secondary -parsing is not part of BIO Messaging Framework and must be initiated by a -messaging client. For example, when generic file parser (GFP) saves a vCard -data as a file to update the contact database, the UI must then invoke the -Versit parser to parse the vCard and commit it to the contact database.

    It -is possible to add new BIO parsers to provide support for different types -of BIO message. The following are the types of parsers provided by Symbian:

      -

    • Generic file parser -(GFP): The generic file parser can be used to identify and save a variety -of BIO data types, for example, vCards and vCals. The generic file parser -does not process the data, it saves it in the message store for processing -by another component. The file is saved as an attachment of the message entry -that is parsed.

      • -

    • OTA parser (WAPP): The -WAPP parser decodes Nokia OTA messages and updates CommDb to reflect the received -settings.

      • -

    • Internet Access -Parser (IACP): The IACP parser decodes Nokia smart messages and updates -the CommDb and messaging settings where appropriate.

      • -
    -
    API summary

    CBIOClientMtm, CBIODatabase and CBaseScriptParser2 are the main APIs of BIO Message Framework.

    -     -Watcher Framework - -Example code - + + + + + +BIO +Messaging Framework Overview +

    The BIO Messaging Framework provides a framework supports plug-ins which +receive, parse and process BIO messages

    +

    Bearer Independent Objects (BIO) messages contain data that can be received +and interpreted by the device. Unlike conventional messages—such as, SMS and +email, BIO messages does not depend on the type of transport over which it +is received. not intended to be read by the user in their raw form. BIO messages +can be received over a number of bearers: IR, Bluetooth, SMS and WAP Push.

    +
    Purpose

    Plug-ins supported by the framework handle +incoming BIO messages received by a phone. BIO messages are sent to the system +to update attributes on the system.

    Examples of BIO messages are vCards +vCals, device settings, ringtones, graphical logos and icons, Internet access +point setup messages and Over the Air (OTA) configuration messages. vCards +are parsed and then displayed to the user, and when accepted they modify the +user’s contact database. OTA configuration messages are parsed before they +are displayed to the user, and if accepted they create email accounts or internet +access points.

    +
    Key terms
    + +
    vCard
    +

    An electronic business card, which is a collection of properties. Properties +can be a property name, one or more property parameters. and a property value.

    +     + +
    vCal
    +

    An electronic calendar entry, which consists of a collection of properties.

    +     +
    +
    Architecture

    BIO Messaging Framework comprises +of three main components—BIO +MTM, BIO +database and BIO +parser.

    BIO messages are not received by the BIO Message Framework +directly. They come over other subsystems to the BIO database. For example, +the SMS watchers receive BIO messages from the SMS stack and use BIO Messaging +Framework to tag the messages with the correct BIO ID.

    The following +figure illustrates the BIO Messaging Framework architecture:

    + BIO Messaging Framework architecture + +

    BIO database

    The +BIO database is used to identify the type of BIO messages. It maps message +attributes, such as port number, MIME type, or leading string to a BIO type. +These attributes are then used by clients of the BIO Message Framework to +determine what ports to listen for messages. For example, SMS messages which +start with that string and, when storing these messages in the inbox, tag +them with the BIO ID associated with that leading string.

    BIO watcher

    BIO +watcher is part of the Watcher +Framework, which handles BIO messages that come from the SMS and WAP +stack. It firsts identifies the type of BIO message using the BIO database, +and then creates a BIO message in a Message Store using the messaging APIs.

    BIF +files and utilities

    BIO Information Files (BIF) are resource files +that are read by the BIO database to provide registration information of BIO +message types. There is one BIF file for every BIO message type. They encapsulate +the information required for identifying BIO messages. The information may +include the expected port number, MIME type or leading string. Different BIO +watchers use different information.

    BIF files can be one of two formats. +The first format is a resource file and the second format is a custom binary +format for representing the data fields in the BIF file. The BIF utilities +(bifu.dll) provide the functionality to read information +in BIF files of both formats.

    BIO +MTM

    The BIO Client MTM is responsible for loading the BIO database +and BIO utilities to handle parse or process requests from messaging clients. +It is called by a messaging client to parse or process a BIO message that +is saved in a Message Store. If the client is trusted with the correct capabilities, +the BIO parser DLLs are loaded successfully. Without the right capabilities, +the DLLs will not run. A BIO watcher saves the BIO message with the BIO flag +and the appropriate BIO type set.

    The BIO MTM does not support sending +messages and therefore does not support reply or forward of BIO messages. +Forwarding and replying to BIO messages is supported by the MTM that the message +is sent over, for example SMS.

    BIO +parser and utilities

    BIO parsers are plug-ins (DLLs) that provide +parsing and processing functionality for incoming BIO messages. The parser +uses BIO utilities to provide base functionality. BIO utilities that load +the BIO parser use the DLL filename and load the DLLs from the \sys\bin location.

    Each +BIO parser implements the ParseL and ProcessL functions. +The level of functionality varies between parsers. Some parsers update the +final repository with the received data. For example, the WAP parser updates +the CommDb with the received settings. Some parsers save +data in an unparsed state for processing by another component. This secondary +parsing is not part of BIO Messaging Framework and must be initiated by a +messaging client. For example, when generic file parser (GFP) saves a vCard +data as a file to update the contact database, the UI must then invoke the +Versit parser to parse the vCard and commit it to the contact database.

    It +is possible to add new BIO parsers to provide support for different types +of BIO message. The following are the types of parsers provided by Symbian:

      +

    • Generic file parser +(GFP): The generic file parser can be used to identify and save a variety +of BIO data types, for example, vCards and vCals. The generic file parser +does not process the data, it saves it in the message store for processing +by another component. The file is saved as an attachment of the message entry +that is parsed.

      • +

    • OTA parser (WAPP): The +WAPP parser decodes Nokia OTA messages and updates CommDb to reflect the received +settings.

      • +

    • Internet Access +Parser (IACP): The IACP parser decodes Nokia smart messages and updates +the CommDb and messaging settings where appropriate.

      • +
    +
    API summary

    CBIOClientMtm, CBIODatabase and CBaseScriptParser2 are the main APIs of BIO Message Framework.

    +     +Watcher Framework + +Example code +     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-182326EB-E818-4146-82D9-494D59E430B8-master.png Binary file Symbian3/SDK/Source/GUID-182326EB-E818-4146-82D9-494D59E430B8-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-182326EB-E818-4146-82D9-494D59E430B8_d0e81983_href.png Binary file Symbian3/SDK/Source/GUID-182326EB-E818-4146-82D9-494D59E430B8_d0e81983_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-18358882-A4DD-5010-BED7-4ACAE021495D.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-18358882-A4DD-5010-BED7-4ACAE021495D.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,12 @@ + + + + + +Example code \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-184E301D-78BF-5324-98F6-AD583A875D6E_d0e403005_href.png Binary file Symbian3/SDK/Source/GUID-184E301D-78BF-5324-98F6-AD583A875D6E_d0e403005_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-184E301D-78BF-5324-98F6-AD583A875D6E_d0e403167_href.png Binary file Symbian3/SDK/Source/GUID-184E301D-78BF-5324-98F6-AD583A875D6E_d0e403167_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-18547A2C-7425-5478-8235-EC6D3848B404_d0e207449_href.png Binary file Symbian3/SDK/Source/GUID-18547A2C-7425-5478-8235-EC6D3848B404_d0e207449_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-18547A2C-7425-5478-8235-EC6D3848B404_d0e212244_href.png Binary file Symbian3/SDK/Source/GUID-18547A2C-7425-5478-8235-EC6D3848B404_d0e212244_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-18D7228F-A1E5-594A-B654-EF5D74CE17D2.dita --- a/Symbian3/SDK/Source/GUID-18D7228F-A1E5-594A-B654-EF5D74CE17D2.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-18D7228F-A1E5-594A-B654-EF5D74CE17D2.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,27 +1,27 @@ - - - - - -Recording Video Data

    This tutorial describes how to record video data.

    Purpose

    The purpose of this tutorial is to show you how to use the video recorder to control video recording.

    Required Background

    The Video Client Overview introduces the video client utilities.

    Introduction

    The video recorder utility is used to record video clips to files, descriptors or URLs and manipulate embedded meta data. This functionality is implemented by the CVideoRecorderUtility class.

    The sequence diagram below explains the different functionalities of the video recorder utility:

    - Video recorder sequence diagram -
    Using Video Recording

    The following tasks will be covered in this tutorial:

    • Record Video Data

    Basic Procedure

    The high level steps to record video data are shown here:

    1. If you are using an audio clip, the recording gain must be set using the CVideoRecorderUtility::SetGainL() function before recording because the initial gain is undefined or may also have been modified by another client application.

    2. The specific functions to record and perform related tasks are as follows:

      • To start recording video data to the specified file, descriptor or URL, use the CVideoRecorderUtility::Record() function.

        void CRecordVideo::Record() - { - iVideoRecordUtility->Record(); - }

      • To pause recording, use the CVideoRecorderUtility::PauseL() function. The position within the video clip is maintained in case a subsequent CVideoRecorderUtility::Record() is called.

        void CRecordVideo::PauseL() - { - iVideoRecordUtility->PauseL(); - }

      • To stop recording, use the CVideoRecorderUtility::Stop() function. If the video format supports audio tracks and if audio is enabled, this function also stops recording the audio data.

        TInt CRecordVideo::Stop() - { - TInt err = iVideoRecordUtility->Stop(); - return err; - }

      • To close all related video and audio controllers, use the CVideoRecorderUtility::Close() function.

        void CRecordVideo::Close() - { - iVideoRecordUtility->Close(); + + + + + +Recording Video Data

        This tutorial describes how to record video data.

        Purpose

        The purpose of this tutorial is to show you how to use the video recorder to control video recording.

        Required Background

        The Video Client Overview introduces the video client utilities.

        Introduction

        The video recorder utility is used to record video clips to files, descriptors or URLs and manipulate embedded meta data. This functionality is implemented by the CVideoRecorderUtility class.

        The sequence diagram below explains the different functionalities of the video recorder utility:

        + Video recorder sequence diagram +
        Using Video Recording

        The following tasks will be covered in this tutorial:

        • Record Video Data

        Basic Procedure

        The high level steps to record video data are shown here:

        1. If you are using an audio clip, the recording gain must be set using the CVideoRecorderUtility::SetGainL() function before recording because the initial gain is undefined or may also have been modified by another client application.

        2. The specific functions to record and perform related tasks are as follows:

          • To start recording video data to the specified file, descriptor or URL, use the CVideoRecorderUtility::Record() function.

            void CRecordVideo::Record() + { + iVideoRecordUtility->Record(); + }

          • To pause recording, use the CVideoRecorderUtility::PauseL() function. The position within the video clip is maintained in case a subsequent CVideoRecorderUtility::Record() is called.

            void CRecordVideo::PauseL() + { + iVideoRecordUtility->PauseL(); + }

          • To stop recording, use the CVideoRecorderUtility::Stop() function. If the video format supports audio tracks and if audio is enabled, this function also stops recording the audio data.

            TInt CRecordVideo::Stop() + { + TInt err = iVideoRecordUtility->Stop(); + return err; + }

          • To close all related video and audio controllers, use the CVideoRecorderUtility::Close() function.

            void CRecordVideo::Close() + { + iVideoRecordUtility->Close(); }
        See Also

        Creating and Preparing a Video Recorder

        Configuring the Video Recorder

        Enabling/Disabling Video Recording

        Controlling Video Recording Quality

        Setting Video Metadata

        Controlling the Video Plugin

        \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-18D92465-3F62-55CF-8229-EE811FD5F568.dita --- a/Symbian3/SDK/Source/GUID-18D92465-3F62-55CF-8229-EE811FD5F568.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-18D92465-3F62-55CF-8229-EE811FD5F568.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,12 +1,12 @@ - - - - - -Stream networks

        When a store stream is created, a stream ID is generated. This ID can be used to open the stream later. Stream IDs can be externalised into another stream, and this allows streams in a store to be built into a network.

        An object that is saved to a store may use a network of streams, typically starting with a single head stream.

        An object stores itself using a function of the form:

        streamId=object.StoreL(store);

        Given the correct stream ID, the object may be restored using a function of the form:

        object.RestoreL(store,streamId)

        where store is a reference or pointer to a store.

        The function names StoreL() and RestoreL() are conventional for this purpose.

        The following diagram shows the idea of stream networks:

         \ No newline at end of file + + + + + +Stream networks

        When a store stream is created, a stream ID is generated. This ID can be used to open the stream later. Stream IDs can be externalised into another stream, and this allows streams in a store to be built into a network.

        An object that is saved to a store may use a network of streams, typically starting with a single head stream.

        An object stores itself using a function of the form:

        streamId=object.StoreL(store);

        Given the correct stream ID, the object may be restored using a function of the form:

        object.RestoreL(store,streamId)

        where store is a reference or pointer to a store.

        The function names StoreL() and RestoreL() are conventional for this purpose.

        The following diagram shows the idea of stream networks:

         \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1910C54E-44E0-4D36-820A-BCD5FFCDA719.dita --- a/Symbian3/SDK/Source/GUID-1910C54E-44E0-4D36-820A-BCD5FFCDA719.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-1910C54E-44E0-4D36-820A-BCD5FFCDA719.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,44 +1,44 @@ - - - - - -Migrating -from STLport v4 to v5If you are using STLport v4, it is recommended that you migrate -to the latest version of Standard C++ Library (STLport v5 ) available from -Symbian^3 to make use of it's latest features. -

        To migrate -to STLport v5, application developers can retain the existing sources, but -must make changes to the MMP files. More than just linking against STLport -v5, application developers can make use of latest features available from -STLport v5 onwards and also make use of tools support added in Symbian^3.

        -         -

        To migrate -from STLport v4 to v5, perform the following steps:

         - - -

        Replace the LIBRARY entry in the .MMP file -from libstdcpp.lib to libstdcppv5.lib.

         -         - -

        Replace the SYSTEMINCLUDE path in the .MMP file -from \epoc32\include\stdapis\stlport to \epoc32\include\stdapis\stlportv5.

         -         - -

        Add the STDCPP keyword to the .MMP file, -if you are using the global operator new and your target -type is not an STD target type.

        -

        As Carbide currently has a defect associated with the STDCPP keyword, -it is recommended that you build code from command line instead of using Carbide.

        -         -         -

        Note: For -more information about using STLport v5 on Symbian platform, see Standard -C++ Support on Symbian Platform.

         + + + + + +Migrating +from STLport v4 to v5If you are using STLport v4, it is recommended that you migrate +to the latest version of Standard C++ Library (STLport v5 ) available from +Symbian^3 to make use of it's latest features. +

        To migrate +to STLport v5, application developers can retain the existing sources, but +must make changes to the MMP files. More than just linking against STLport +v5, application developers can make use of latest features available from +STLport v5 onwards and also make use of tools support added in Symbian^3.

        +         +

        To migrate +from STLport v4 to v5, perform the following steps:

         + + +

        Replace the LIBRARY entry in the .MMP file +from libstdcpp.lib to libstdcppv5.lib.

         +         + +

        Replace the SYSTEMINCLUDE path in the .MMP file +from \epoc32\include\stdapis\stlport to \epoc32\include\stdapis\stlportv5.

         +         + +

        Add the STDCPP keyword to the .MMP file, +if you are using the global operator new and your target +type is not an STD target type.

        +

        As Carbide currently has a defect associated with the STDCPP keyword, +it is recommended that you build code from command line instead of using Carbide.

        +         +         +

        Note: For +more information about using STLport v5 on Symbian platform, see Standard +C++ Support on Symbian Platform.

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-192C7AC8-DCBD-5AA8-984A-35D9602C0ADB_d0e272145_href.jpg Binary file Symbian3/SDK/Source/GUID-192C7AC8-DCBD-5AA8-984A-35D9602C0ADB_d0e272145_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-192C7AC8-DCBD-5AA8-984A-35D9602C0ADB_d0e275826_href.jpg Binary file Symbian3/SDK/Source/GUID-192C7AC8-DCBD-5AA8-984A-35D9602C0ADB_d0e275826_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1955F591-2D2C-42EE-AF03-7BBBEE1A4005.dita --- a/Symbian3/SDK/Source/GUID-1955F591-2D2C-42EE-AF03-7BBBEE1A4005.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-1955F591-2D2C-42EE-AF03-7BBBEE1A4005.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,135 +1,140 @@ - - - - - -Grid -types -

        Grids are in many ways analogous to lists. However, there are some things -worth noticing:

        -
          -
        • In grids, the Arrow left and Arrow right keys are always used for moving -the focus; they cannot be used in any other way that may be possible with -lists.

          • -

        • Grid layouts are not as standardized as lists; the layouts must be -designed case by case for the applications. Typically, grid items occupy less -screen space than list items. This results in grid items having fewer elements -than list items. A grid item may in general have one text, or one graphic, -or a text and a graphic.

          • -
        -

        The following grid types can be used, and they are analogous to the corresponding -list types:

        -Grid types - - - -Grid -Description - - - - -

        Menu grid

         -

        For selecting one item; no Options menu.

         -         - -

        Selection grid

         -

        Permanent state; can be left pending, the Options menu is available.

         -         - -

        Markable grid

         -

        A selection grid with the marking function.

         -         - - -
        -

        There are no grid types corresponding to a multi-selection list, a setting -list or a form.

        -Default touch -events in grids. - - - -

        User action

         -

        State change

         -

        Feedback

         -         - - - -

        Touch down

         -

        No effect

         -

        Highlight is shown.

        Tactile: Basic list effect and audio feedback -is provided with touch down event.

         -         - -

        Touch release

         -

        Item is activated

         -

        Highlight disappears.

        Tactile: Basic list effect is provided -with touch release event.

         -         - -

        Touch down and move outside the grid without releasing the touch -down.

         -

        Refer to Dragging -and flicking events

         -

        Tactile: Refer to Dragging -and flicking events.

         -         - -

        Touch down, move outside and back.

         -

        Refer to Dragging -and flicking events

         -

        Tactile: Refer to Dragging -and flicking events.

         -         - -

        Touch down and move vertically

         -

        Refer to Dragging -and flicking events

         -

        Tactile: Refer to Dragging -and flicking events.

         -         - -

        Touch down and move horizontally

         -

        Refer to Dragging -and flicking events

         -Highlight stays on the item while it is touched and disappears when -moving outside of it.

        Tactile: Refer to Dragging -and flicking events.

         -         - - -
        -
        Using -grids in C++ applications

        The APIs to use for grids are the Grids API and the Lists API. For implementation information, see Using the Grids API and Using the Lists API.

        The CAknGrid class is used to set up the basic parameters of -a layout in terms of number of columns and rows, cell size, and orientation. -After this, AknListBoxLayouts is -used to set up detailed parameters for graphics and text in the cell. The -following cell parameters can be set:

          -

        • Location and size of bitmaps

          • -

        • Location and size of text string

          • -

        • Font and its color

          • -

        • Text align in the allocated space

          • -

        Bitmaps are loaded manually, as an icon array.

        Other parameters -of visual elements (for example, highlighted text color) are used from the -Symbian Developer Platform standard look and feel module; these should not -be overridden unless you've instantiated your own class.

        Several specialized grid classes can be found in AVKON.

        Use -the class CAknCaleMonthStyleGrid to show a month view. The first row shows the day and the first column shows -the week number. The following data can be set for an item:

          -

        • Outlined icon to show border, dimension 21 x 9 pixels

          • -

        • Marking icon in the bottom right corner of a cell, dimension 5 x 5 -pixels

          • -

        • Two-digit number

          • -

        Use the class CAknPinbStyleGrid to show application shortcuts in a 5 x 5 cells grid. For every item, an -icon is specified that is displayed in the center of a cell. In addition, -two small icons, 13 x 13 pixels, can be specified. The first one is displayed -in the top-right corner for marking. The second one is displayed in the bottom-left -corner to show the target application.

        + + + + + +Grid +types +

        Grids are in many ways analogous to lists. However, there are some things +worth noticing:

        +
          +
        • In grids, the Arrow left and Arrow right keys are always used for moving +the focus; they cannot be used in any other way that may be possible with +lists.

          • +

        • Grid layouts are not as standardized as lists; the layouts must be +designed case by case for the applications. Typically, grid items occupy less +screen space than list items. This results in grid items having fewer elements +than list items. A grid item may in general have one text, or one graphic, +or a text and a graphic.

          • +
        +

        The following grid types can be used, and they are analogous to the corresponding +list types:

        +Grid types + + + + + +Grid +Description + + + + +

        Menu grid

         +

        For selecting one item; no Options menu.

         +         + +

        Selection grid

         +

        Permanent state; can be left pending, the Options menu is available.

         +         + +

        Markable grid

         +

        A selection grid with the marking function.

         +         + + +
        +

        There are no grid types corresponding to a multi-selection list, a setting +list or a form.

        +Default touch +events in grids. + + + +

        User action

         +

        State change

         +

        Feedback

         +         + + + +

        Touch down

         +

        No effect

         +

        Highlight is shown.

        Tactile: Basic list effect and audio feedback +is provided with touch down event.

         +         + +

        Touch release

         +

        Item is activated

         +

        Highlight disappears.

        Tactile: Basic list effect is provided +with touch release event.

         +         + +

        Touch down and move outside the grid without releasing the touch +down.

         +

        Refer to Dragging +and flicking events

         +

        Tactile: Refer to Dragging +and flicking events.

         +         + +

        Touch down, move outside and back.

         +

        Refer to Dragging +and flicking events

         +

        Tactile: Refer to Dragging +and flicking events.

         +         + +

        Touch down and move vertically

         +

        Refer to Dragging +and flicking events

         +

        Tactile: Refer to Dragging +and flicking events.

         +         + +

        Touch down and move horizontally

         +

        Refer to Dragging +and flicking events

         +Highlight stays on the item while it is touched and disappears when +moving outside of it.

        Tactile: Refer to Dragging +and flicking events.

         +         + + +
        +
        Using +grids in applications

        The APIs to use for grids are +the Grids API and the Lists API. For implementation information, see Using the Grids API and Using the Lists API.

        The CAknGrid class +is used to set up the basic parameters of a layout in terms of number of columns +and rows, cell size, and orientation. After this, AknListBoxLayouts is +used to set up detailed parameters for graphics and text in the cell. The +following cell parameters can be set:

          +

        • Location and size of bitmaps

          • +

        • Location and size of text string

          • +

        • Font and its color

          • +

        • Text align in the allocated space

          • +

        Bitmaps are loaded manually, as an icon array.

        Other parameters +of visual elements (for example, highlighted text color) are used from the +Symbian Developer Platform standard look and feel module; these should not +be overridden unless you've instantiated your own class.

        Several specialized grid classes can be found in AVKON.

        Use +the class CAknCaleMonthStyleGrid to show a month view. +The first row shows the day and the first column shows the week number. The +following data can be set for an item:

          +

        • Outlined icon to show border, dimension 21 x 9 pixels

          • +

        • Marking icon in the bottom right corner of a cell, dimension 5 x 5 +pixels

          • +

        • Two-digit number

          • +

        Use the class CAknPinbStyleGrid to show application +shortcuts in a 5 x 5 cells grid. For every item, an icon is specified that +is displayed in the center of a cell. In addition, two small icons, 13 x 13 +pixels, can be specified. The first one is displayed in the top-right corner +for marking. The second one is displayed in the bottom-left corner to show +the target application.

        \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1969956D-CDA0-5DA0-ACF8-69AFBBEC1408.dita --- a/Symbian3/SDK/Source/GUID-1969956D-CDA0-5DA0-ACF8-69AFBBEC1408.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-1969956D-CDA0-5DA0-ACF8-69AFBBEC1408.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,14 +1,14 @@ - - - - - -Light APILight API is a library API that provides the ability to control various light targets of the device. It also provides methods to retrieve the current light status and the supported light targets of the device.

        It uses synchronous method calls which block the client application until a response is received from the plug-in. The API consists of CHWRMLight and MHWRMLightObserver classes.

        - Light API Interfaces -

        The client creates an instance of CHWRMLight using NewL(). If the client requires status information, it must also provide a callback pointer of the MHWRMLightObserver implementing class for the NewL() method.

        Usually HWRM Light interface supports restoring the previous or default light state (ON/OFF/BLINK). The already supported (reservation controller) functionality in existing HWRM light APIs is extended to restore the previous or default color of the LED as well.

        HWRM also supports automatic reserve and release the targets depends on the client application foreground observer notification through an UI plugin. During these states the light state with color value would be stored and restored automatically. This means if the client application window comes on the foreground then the reserved target’s state will be restored.

        Definitions

        Term

        Description

        Light target

        A separate entity that can be lighted in the device. For example, the primary display of the device is a light target.

        Lights frozen state

        Whenever lights are released, their current state is stored as frozen state. On next reserve, the user can specify that frozen state be restored.

        Lights default state

        Lights default state is determined by device inactivity time and relevant general settings.

        Lights base state

        It is the state of the light target set for infinite duration (after all the time-based operation is completed).

        Light API Tutorial         \ No newline at end of file + + + + + +Light APILight API is a library API that provides the ability to control various light targets of the device. It also provides methods to retrieve the current light status and the supported light targets of the device.

        It uses synchronous method calls which block the client application until a response is received from the plug-in. The API consists of CHWRMLight and MHWRMLightObserver classes.

        + Light API Interfaces +

        The client creates an instance of CHWRMLight using NewL(). If the client requires status information, it must also provide a callback pointer of the MHWRMLightObserver implementing class for the NewL() method.

        Usually HWRM Light interface supports restoring the previous or default light state (ON/OFF/BLINK). The already supported (reservation controller) functionality in existing HWRM light APIs is extended to restore the previous or default color of the LED as well.

        HWRM also supports automatic reserve and release the targets depends on the client application foreground observer notification through an UI plugin. During these states the light state with color value would be stored and restored automatically. This means if the client application window comes on the foreground then the reserved target’s state will be restored.

        Definitions

        Term

        Description

        Light target

        A separate entity that can be lighted in the device. For example, the primary display of the device is a light target.

        Lights frozen state

        Whenever lights are released, their current state is stored as frozen state. On next reserve, the user can specify that frozen state be restored.

        Lights default state

        Lights default state is determined by device inactivity time and relevant general settings.

        Lights base state

        It is the state of the light target set for infinite duration (after all the time-based operation is completed).

        Light API Tutorial         \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-19B2E0BF-9766-55C6-A37F-188A9EDAFF39_d0e277923_href.png Binary file Symbian3/SDK/Source/GUID-19B2E0BF-9766-55C6-A37F-188A9EDAFF39_d0e277923_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-19B2E0BF-9766-55C6-A37F-188A9EDAFF39_d0e281609_href.png Binary file Symbian3/SDK/Source/GUID-19B2E0BF-9766-55C6-A37F-188A9EDAFF39_d0e281609_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-19CF4B7B-EA55-566D-B68C-0A25DCADCA6C-GENID-1-8-1-3-1-1-7-1-7-1-8-1.dita --- a/Symbian3/SDK/Source/GUID-19CF4B7B-EA55-566D-B68C-0A25DCADCA6C-GENID-1-8-1-3-1-1-7-1-7-1-8-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,69 +0,0 @@ - - - - - -Control -contexts -

        Prior to Symbian OS v9.1 controls were able to share a graphics context -using the MCoeControlContext API. This was used primarily -in compound controls to achieve a common solid background color and was necessary -because controls were required to clear and redraw their own rectangles. Now, -with improvements to flicker free drawing and improved framework mechanisms -for drawing patterned (skinned) backgrounds, parents and containers are able -to provide backgrounds.

        -

        The MCoeControlContext API is now deprecated for UIQ. A description -of the migration process is described below.

        -

        S60 and MOAP do not use the new background framework.

        -
        <p><b>Control -Contexts </b> </p> <p>Control contexts allow a group of controls to share -graphics context settings for drawing. Each control may use a control context, -a class derived from <xref href="GUID-298C4B9D-4DB7-322A-99AB-15816C0F0247.dita"><apiname>MCoeControlContext</apiname></xref>. By using the same -control context a group of controls can share common settings. A typical use -is for components of a compound control to use the same control context to -ensure that they use the same background color settings. </p> <p>Functions -defined by <xref href="GUID-298C4B9D-4DB7-322A-99AB-15816C0F0247.dita"><apiname>MCoeControlContext</apiname></xref> are called from within the -control framework when a control is about to be drawn. These functions can -be implemented to initialize graphics settings to common values. By using -the same control context a group of controls can all be made to use the same -graphics settings. </p> <p>The context is set for all controls that wish to -use it by setting their <codeph>iContext</codeph> members, either directly, -by using <codeph>CCoeControl::SetControlContext(),</codeph> or by copying -with <codeph>CCoeControl::CopyControlContextFrom()</codeph>. Whenever a control -is about to be drawn the control framework checks if the control has its <codeph>iContext</codeph> member -set and, if so, calls <codeph>MCoeControlContext::ActivateContext()</codeph>. -This function has a default implementation that calls <codeph>MCoeControlContext::PrepareContext()</codeph>, -which should have been implemented to initialize the graphics settings. </p> <p>The -control framework provides one concrete control context class, <codeph>CCoeBrushAndPenContext</codeph>, -which sets graphics context brush and pen settings. Applications derive other -control context classes as required. </p> <p>The control framework automatically -propagates a compound control’s context to all of its components when the -components set their container with <codeph>CCoeControl::SetContainerWindowL()</codeph>. </p> <p> </p> <p><b>The -following section describes how code written for older versions of Symbian -platform must be updated. </b> </p> <p>The following changes need to be made -to existing code: </p> <ul> -<li id="GUID-71F1C167-CD12-5D00-9F16-73732BD698CB-GENID-1-8-1-3-1-1-7-1-7-1-8-1-2-4-11-1"><p>Remove all code referring -to the <codeph>CCoeControl::iContext</codeph> variable. </p> </li> -<li id="GUID-3B13DB08-A7B9-5B2D-9A6D-FBA8D9B3A6B0-GENID-1-8-1-3-1-1-7-1-7-1-8-1-2-4-11-2"><p>Remove all calls to <codeph>CCoeControl’s - SetControlContext()</codeph>, <codeph>CopyControlContextFrom()</codeph> and <codeph>ControlContext()</codeph>. </p> </li> -<li id="GUID-4CD48156-C053-5DF0-9ACC-9AF5415C3104-GENID-1-8-1-3-1-1-7-1-7-1-8-1-2-4-11-3"><p>Remove all implementations -of the <codeph>MCoeControlContext</codeph> from all custom controls, i.e. -remove all <codeph>ActivateContext()</codeph>, <codeph>ResetContext()</codeph> and <codeph>PrepareContext()</codeph> implementations -from custom controls. </p> </li> -<li id="GUID-AD956F60-78C0-5A77-AE7E-FED2FAA096E8-GENID-1-8-1-3-1-1-7-1-7-1-8-1-2-4-11-4"><p>Remove all use of the <codeph>CCoeBrushAndPenContext</codeph> and <codeph>MCoeControlBrushContext</codeph> APIs. </p> </li> -<li id="GUID-8519E952-7A86-5CE5-BE18-2DA081AA16B9-GENID-1-8-1-3-1-1-7-1-7-1-8-1-2-4-11-5"><p>Remove all calls to <codeph>MCoeControlContext</codeph> ’s <codeph>ActivateContext()</codeph>, <codeph>ResetContext()</codeph> and <codeph>PrepareContext()</codeph>. </p> </li> -<li id="GUID-C27D37C8-7E49-5A62-B7F9-966D66FF1DB5-GENID-1-8-1-3-1-1-7-1-7-1-8-1-2-4-11-6"><p>Remove all code that -clears the area surrounding the controls’ actual graphical representation. </p> </li> -<li id="GUID-1A5941C7-74BC-584C-9733-609EF79CEC19-GENID-1-8-1-3-1-1-7-1-7-1-8-1-2-4-11-7"><p>Change -the draw code of compound controls so that the parent of children correctly -updates the area behind the children. </p> </li> -</ul> <p>This stage 7 will not work for window-owning controls as the Window -Server will prevent the parent from drawing behind the child's window. See <xref href="GUID-88936D48-B801-3D9C-8A9D-3498807937CE.dita"><apiname>MCoeControlBackground</apiname></xref> and <xref href="GUID-B84FA223-3DFD-58C5-8CEF-C5AA73AA6290-GENID-1-8-1-3-1-1-7-1-9-1.dita#GUID-B84FA223-3DFD-58C5-8CEF-C5AA73AA6290-GENID-1-8-1-3-1-1-7-1-9-1/GUID-FF7DB067-24AD-50C3-BF52-952F836609B0-GENID-1-8-1-3-1-1-7-1-9-1-2-18">how -to write a control</xref>. </p> </section> -</conbody></concept> \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-19CF4B7B-EA55-566D-B68C-0A25DCADCA6C-GENID-1-8-1-6-1-1-4-1-6-1-7-1-8-1.dita --- a/Symbian3/SDK/Source/GUID-19CF4B7B-EA55-566D-B68C-0A25DCADCA6C-GENID-1-8-1-6-1-1-4-1-6-1-7-1-8-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,69 +0,0 @@ -<?xml version="1.0" encoding="utf-8"?> -<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> -<!-- This component and the accompanying materials are made available under the terms of the License -"Eclipse Public License v1.0" which accompanies this distribution, -and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> -<!-- Initial Contributors: - Nokia Corporation - initial contribution. -Contributors: ---> -<!DOCTYPE concept - PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> -<concept id="GUID-19CF4B7B-EA55-566D-B68C-0A25DCADCA6C-GENID-1-8-1-6-1-1-4-1-6-1-7-1-8-1" xml:lang="en"><title>Control -contexts -

        Prior to Symbian OS v9.1 controls were able to share a graphics context -using the MCoeControlContext API. This was used primarily -in compound controls to achieve a common solid background color and was necessary -because controls were required to clear and redraw their own rectangles. Now, -with improvements to flicker free drawing and improved framework mechanisms -for drawing patterned (skinned) backgrounds, parents and containers are able -to provide backgrounds.

        -

        The MCoeControlContext API is now deprecated for UIQ. A description -of the migration process is described below.

        -

        S60 and MOAP do not use the new background framework.

        -
        <p><b>Control -Contexts </b> </p> <p>Control contexts allow a group of controls to share -graphics context settings for drawing. Each control may use a control context, -a class derived from <xref href="GUID-298C4B9D-4DB7-322A-99AB-15816C0F0247.dita"><apiname>MCoeControlContext</apiname></xref>. By using the same -control context a group of controls can share common settings. A typical use -is for components of a compound control to use the same control context to -ensure that they use the same background color settings. </p> <p>Functions -defined by <xref href="GUID-298C4B9D-4DB7-322A-99AB-15816C0F0247.dita"><apiname>MCoeControlContext</apiname></xref> are called from within the -control framework when a control is about to be drawn. These functions can -be implemented to initialize graphics settings to common values. By using -the same control context a group of controls can all be made to use the same -graphics settings. </p> <p>The context is set for all controls that wish to -use it by setting their <codeph>iContext</codeph> members, either directly, -by using <codeph>CCoeControl::SetControlContext(),</codeph> or by copying -with <codeph>CCoeControl::CopyControlContextFrom()</codeph>. Whenever a control -is about to be drawn the control framework checks if the control has its <codeph>iContext</codeph> member -set and, if so, calls <codeph>MCoeControlContext::ActivateContext()</codeph>. -This function has a default implementation that calls <codeph>MCoeControlContext::PrepareContext()</codeph>, -which should have been implemented to initialize the graphics settings. </p> <p>The -control framework provides one concrete control context class, <codeph>CCoeBrushAndPenContext</codeph>, -which sets graphics context brush and pen settings. Applications derive other -control context classes as required. </p> <p>The control framework automatically -propagates a compound control’s context to all of its components when the -components set their container with <codeph>CCoeControl::SetContainerWindowL()</codeph>. </p> <p> </p> <p><b>The -following section describes how code written for older versions of Symbian -platform must be updated. </b> </p> <p>The following changes need to be made -to existing code: </p> <ul> -<li id="GUID-71F1C167-CD12-5D00-9F16-73732BD698CB-GENID-1-8-1-6-1-1-4-1-6-1-7-1-8-1-2-4-11-1"><p>Remove all code referring -to the <codeph>CCoeControl::iContext</codeph> variable. </p> </li> -<li id="GUID-3B13DB08-A7B9-5B2D-9A6D-FBA8D9B3A6B0-GENID-1-8-1-6-1-1-4-1-6-1-7-1-8-1-2-4-11-2"><p>Remove all calls to <codeph>CCoeControl’s - SetControlContext()</codeph>, <codeph>CopyControlContextFrom()</codeph> and <codeph>ControlContext()</codeph>. </p> </li> -<li id="GUID-4CD48156-C053-5DF0-9ACC-9AF5415C3104-GENID-1-8-1-6-1-1-4-1-6-1-7-1-8-1-2-4-11-3"><p>Remove all implementations -of the <codeph>MCoeControlContext</codeph> from all custom controls, i.e. -remove all <codeph>ActivateContext()</codeph>, <codeph>ResetContext()</codeph> and <codeph>PrepareContext()</codeph> implementations -from custom controls. </p> </li> -<li id="GUID-AD956F60-78C0-5A77-AE7E-FED2FAA096E8-GENID-1-8-1-6-1-1-4-1-6-1-7-1-8-1-2-4-11-4"><p>Remove all use of the <codeph>CCoeBrushAndPenContext</codeph> and <codeph>MCoeControlBrushContext</codeph> APIs. </p> </li> -<li id="GUID-8519E952-7A86-5CE5-BE18-2DA081AA16B9-GENID-1-8-1-6-1-1-4-1-6-1-7-1-8-1-2-4-11-5"><p>Remove all calls to <codeph>MCoeControlContext</codeph> ’s <codeph>ActivateContext()</codeph>, <codeph>ResetContext()</codeph> and <codeph>PrepareContext()</codeph>. </p> </li> -<li id="GUID-C27D37C8-7E49-5A62-B7F9-966D66FF1DB5-GENID-1-8-1-6-1-1-4-1-6-1-7-1-8-1-2-4-11-6"><p>Remove all code that -clears the area surrounding the controls’ actual graphical representation. </p> </li> -<li id="GUID-1A5941C7-74BC-584C-9733-609EF79CEC19-GENID-1-8-1-6-1-1-4-1-6-1-7-1-8-1-2-4-11-7"><p>Change -the draw code of compound controls so that the parent of children correctly -updates the area behind the children. </p> </li> -</ul> <p>This stage 7 will not work for window-owning controls as the Window -Server will prevent the parent from drawing behind the child's window. See <xref href="GUID-88936D48-B801-3D9C-8A9D-3498807937CE.dita"><apiname>MCoeControlBackground</apiname></xref> and <xref href="GUID-B84FA223-3DFD-58C5-8CEF-C5AA73AA6290-GENID-1-8-1-3-1-1-7-1-9-1.dita#GUID-B84FA223-3DFD-58C5-8CEF-C5AA73AA6290-GENID-1-8-1-3-1-1-7-1-9-1/GUID-FF7DB067-24AD-50C3-BF52-952F836609B0-GENID-1-8-1-3-1-1-7-1-9-1-2-18">how -to write a control</xref>. </p> </section> -</conbody></concept> \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-19CF4B7B-EA55-566D-B68C-0A25DCADCA6C.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-19CF4B7B-EA55-566D-B68C-0A25DCADCA6C.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,69 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> +<!-- This component and the accompanying materials are made available under the terms of the License +"Eclipse Public License v1.0" which accompanies this distribution, +and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> +<!-- Initial Contributors: + Nokia Corporation - initial contribution. +Contributors: +--> +<!DOCTYPE concept + PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> +<concept id="GUID-19CF4B7B-EA55-566D-B68C-0A25DCADCA6C" xml:lang="en"><title>Control +contexts +

        Prior to Symbian OS v9.1 controls were able to share a graphics context +using the MCoeControlContext API. This was used primarily +in compound controls to achieve a common solid background color and was necessary +because controls were required to clear and redraw their own rectangles. Now, +with improvements to flicker free drawing and improved framework mechanisms +for drawing patterned (skinned) backgrounds, parents and containers are able +to provide backgrounds.

        +

        The MCoeControlContext API is now deprecated for UIQ. A description +of the migration process is described below.

        +

        S60 and MOAP do not use the new background framework.

        +
        <p><b>Control +Contexts </b> </p> <p>Control contexts allow a group of controls to share +graphics context settings for drawing. Each control may use a control context, +a class derived from <xref href="GUID-298C4B9D-4DB7-322A-99AB-15816C0F0247.dita"><apiname>MCoeControlContext</apiname></xref>. By using the same +control context a group of controls can share common settings. A typical use +is for components of a compound control to use the same control context to +ensure that they use the same background color settings. </p> <p>Functions +defined by <xref href="GUID-298C4B9D-4DB7-322A-99AB-15816C0F0247.dita"><apiname>MCoeControlContext</apiname></xref> are called from within the +control framework when a control is about to be drawn. These functions can +be implemented to initialize graphics settings to common values. By using +the same control context a group of controls can all be made to use the same +graphics settings. </p> <p>The context is set for all controls that wish to +use it by setting their <codeph>iContext</codeph> members, either directly, +by using <codeph>CCoeControl::SetControlContext(),</codeph> or by copying +with <codeph>CCoeControl::CopyControlContextFrom()</codeph>. Whenever a control +is about to be drawn the control framework checks if the control has its <codeph>iContext</codeph> member +set and, if so, calls <codeph>MCoeControlContext::ActivateContext()</codeph>. +This function has a default implementation that calls <codeph>MCoeControlContext::PrepareContext()</codeph>, +which should have been implemented to initialize the graphics settings. </p> <p>The +control framework provides one concrete control context class, <codeph>CCoeBrushAndPenContext</codeph>, +which sets graphics context brush and pen settings. Applications derive other +control context classes as required. </p> <p>The control framework automatically +propagates a compound control’s context to all of its components when the +components set their container with <codeph>CCoeControl::SetContainerWindowL()</codeph>. </p> <p> </p> <p><b>The +following section describes how code written for older versions of Symbian +platform must be updated. </b> </p> <p>The following changes need to be made +to existing code: </p> <ul> +<li id="GUID-71F1C167-CD12-5D00-9F16-73732BD698CB"><p>Remove all code referring +to the <codeph>CCoeControl::iContext</codeph> variable. </p> </li> +<li id="GUID-3B13DB08-A7B9-5B2D-9A6D-FBA8D9B3A6B0"><p>Remove all calls to <codeph>CCoeControl’s + SetControlContext()</codeph>, <codeph>CopyControlContextFrom()</codeph> and <codeph>ControlContext()</codeph>. </p> </li> +<li id="GUID-4CD48156-C053-5DF0-9ACC-9AF5415C3104"><p>Remove all implementations +of the <codeph>MCoeControlContext</codeph> from all custom controls, i.e. +remove all <codeph>ActivateContext()</codeph>, <codeph>ResetContext()</codeph> and <codeph>PrepareContext()</codeph> implementations +from custom controls. </p> </li> +<li id="GUID-AD956F60-78C0-5A77-AE7E-FED2FAA096E8"><p>Remove all use of the <codeph>CCoeBrushAndPenContext</codeph> and <codeph>MCoeControlBrushContext</codeph> APIs. </p> </li> +<li id="GUID-8519E952-7A86-5CE5-BE18-2DA081AA16B9"><p>Remove all calls to <codeph>MCoeControlContext</codeph> ’s <codeph>ActivateContext()</codeph>, <codeph>ResetContext()</codeph> and <codeph>PrepareContext()</codeph>. </p> </li> +<li id="GUID-C27D37C8-7E49-5A62-B7F9-966D66FF1DB5"><p>Remove all code that +clears the area surrounding the controls’ actual graphical representation. </p> </li> +<li id="GUID-1A5941C7-74BC-584C-9733-609EF79CEC19"><p>Change +the draw code of compound controls so that the parent of children correctly +updates the area behind the children. </p> </li> +</ul> <p>This stage 7 will not work for window-owning controls as the Window +Server will prevent the parent from drawing behind the child's window. See <xref href="GUID-88936D48-B801-3D9C-8A9D-3498807937CE.dita"><apiname>MCoeControlBackground</apiname></xref> and <xref href="GUID-B84FA223-3DFD-58C5-8CEF-C5AA73AA6290.dita#GUID-B84FA223-3DFD-58C5-8CEF-C5AA73AA6290/GUID-FF7DB067-24AD-50C3-BF52-952F836609B0">how +to write a control</xref>. </p> </section> +</conbody></concept> \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-19E5720A-2B50-4515-AE90-A40C1BEDF4BA-master.png Binary file Symbian3/SDK/Source/GUID-19E5720A-2B50-4515-AE90-A40C1BEDF4BA-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-19E5720A-2B50-4515-AE90-A40C1BEDF4BA_d0e60568_href.png Binary file Symbian3/SDK/Source/GUID-19E5720A-2B50-4515-AE90-A40C1BEDF4BA_d0e60568_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1A0FB98B-8DB3-5067-9B71-FF838F6AE402_d0e192246_href.png Binary file Symbian3/SDK/Source/GUID-1A0FB98B-8DB3-5067-9B71-FF838F6AE402_d0e192246_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1A0FB98B-8DB3-5067-9B71-FF838F6AE402_d0e193926_href.png Binary file Symbian3/SDK/Source/GUID-1A0FB98B-8DB3-5067-9B71-FF838F6AE402_d0e193926_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1A0FB98B-8DB3-5067-9B71-FF838F6AE402_d0e197254_href.png Binary file Symbian3/SDK/Source/GUID-1A0FB98B-8DB3-5067-9B71-FF838F6AE402_d0e197254_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1A0FB98B-8DB3-5067-9B71-FF838F6AE402_d0e198934_href.png Binary file Symbian3/SDK/Source/GUID-1A0FB98B-8DB3-5067-9B71-FF838F6AE402_d0e198934_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1A488C86-C0D7-49DE-A32B-6AFEDDC9E89F_d0e70772_href.png Binary file Symbian3/SDK/Source/GUID-1A488C86-C0D7-49DE-A32B-6AFEDDC9E89F_d0e70772_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1A488C86-C0D7-49DE-A32B-6AFEDDC9E89F_d0e75806_href.png Binary file Symbian3/SDK/Source/GUID-1A488C86-C0D7-49DE-A32B-6AFEDDC9E89F_d0e75806_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1A5C7320-B017-5CD9-B3EA-1301CC08A762.dita --- a/Symbian3/SDK/Source/GUID-1A5C7320-B017-5CD9-B3EA-1301CC08A762.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-1A5C7320-B017-5CD9-B3EA-1301CC08A762.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,18 +1,18 @@ -<?xml version="1.0" encoding="utf-8"?> -<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> -<!-- This component and the accompanying materials are made available under the terms of the License -"Eclipse Public License v1.0" which accompanies this distribution, -and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> -<!-- Initial Contributors: - Nokia Corporation - initial contribution. -Contributors: ---> -<!DOCTYPE concept - PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> -<concept xml:lang="en" id="GUID-1A5C7320-B017-5CD9-B3EA-1301CC08A762"><title>User Prompt Service Overview

        User Prompt Service (UPS) allows device creators to specify whether requests made by applications to access services, such as a request to make a telephone call, are processed silently or whether they require the user to be prompted.

        Purpose

        An application requests a service. The service provider (a system server) requests a decision from the UPS. The UPS searches for a matching policy file and policy. Based on the policy for the service, the service request may be immediately accepted or denied or it may need to receive a decision from the user, in which case it is accepted or denied after several further steps are carried out.

        Device creators can customize the circumstances under which prompts are generated by configuring policies. Policies are made up of details about the service being requested as well as information about whether to accept or deny silently or to ask the user. They are defined in policy lists. Each service has one policy list defining any number of policies. In cases where the policy specifies that a user prompt is required, ECom plug-ins called Policy Evaluators and Dialog Creators, written by device creators.

        Key concepts

        The component has the following key concepts:

        Policy

        Policies specify whether application requests to access services should be processed silently or whether the user should be prompted for a decision. Policies may be general or specific – for example a policy may be specific to a single application, a group of applications or a class of applications (For example, those with unprotected secure ids). Policies are defined in policy lists. Device creators define policies.

        UPS policy file

        A UPS policy file is a compiled resource file containing all of the policies for a given service. The policies are ordered from most specific to least specific.

        Because policies are matched in order, each service may have only one policy file. To define a policy safely, you need to know which other policies have been defined. If you place a general policy near the beginning of the list of policies, you prevent other policies from being evaluated.

        Policy evaluator

        Policy evaluators are Ecom plug-ins, which are responsible for generating fingerprints (see below) used to locate previous decision records related to the request. Device creators define policy evaluators.

        Dialog creator

        Dialog creators are Ecom plug-ins, which display and generate dialog prompts. Device creators define dialog creators.

        Fingerprint

        A fingerprint is a collection of data to do with the service being requested. The fingerprint usually includes the destination string supplied by the service that is matched to the destination string of a policy in the policy file. It might be a phone number, domain name, access point etc. A fingerprint is used to search the decision database for a match and to add a record to the decision database if a match was not found in the initial search. Device creators define the GenerateFingerprints() function in the Policy Evaluator plug-in.

        A fingerprint serves two purposes:

        • The UPS uses it to search the decision database for a match.

        • If the UPS finds no record of a previous user decision and the user selects "always" or "never" in response to the UPS prompt, it uses the fingerprint to create a new record in the decision database.

        It is possible to specify one or many policy evaluators. It is also possible not to specify a policy evaluator and to depend on the default policy evaluator.

        Decision database

        A decision database stores the phone user's choice of whether a request is always granted or never granted. Decisions stored in the decision database persist across reboots of the device. The decision database is provided by Symbian.

        The decision database may not be accessed directly. However, records may be retrieved and deleted via the management APIs. This might be used by a control-panel application.

        Architectural relationships

        The UPS provides CDialogCreator and CPolicyEvaluator interfaces for device creators to implement.

        - UPS components -
        API summary

        The following diagram shows the relationships between some of the key classes in the UPS.

        - Class diagram of key classes in UPS - Class Name Description

        UserPromptService::CClientEntity

        Class representing an entity executing within a client process. For example, a script.

        UserPromptService::CDialogCreator

        Abstract base class for dialog creator Ecom plug-ins. Dialog creators are responsible for generating and displaying prompt dialogs.

        UserPromptService::CFingerprint

        Class that represents the fingerprint data for a stored decision.

        UserPromptService::CPolicy

        Class for a single policy record.

        UserPromptService::CPolicyEvaluator

        Abstract base class for a policy evaluator Ecom plug-in. Policy evaluators are primarily responsible for generating the fingerprints used to locate previous decision records related to the current request.

        Typical uses

        The following diagram shows the sequence of activities performed by the UPS after it receives a request from a server:

        - Diagram showing activities for a single request -

        As is shown in the above diagram, the UPS returns a decision to the system server as in the following use cases:

        • processing silently

        • finding a stored decision in the decision database

        • prompting the user in a dialog and resulting in a "one-shot" or "session" (non-persistent) decision by the user

        • prompting the user in a dialog and resulting in an "always" or "never" (persistent) decision by the user

        The Policy Evaluator allows device creators to customize the behaviour of the UPS at run-time. Policy Evaluators may:

        • Allow security decisions to be specific to the data on which the service acts instead of simply granting full access to the service, for example "Allow application X to send SMS messages to 01234567". This is supported via the fingerprint functionality.

        • Allow a security decision to be specific to an individual script executing within a scripting host. This is supported via the client entity field.

        • Allow a prompt to be displayed even if the user selected "Always" or "Never". This could be based on a usage threshold or simply as additional confirmation if the user selected "Never". This is supported via the force prompt functionality.

        Typical uses

        The UPS component provides interfaces to perform the following tasks:

        • Integrating a System Server with UPS

        • Writing a UPS Policy File

        • Writing a UPS Policy Evaluator

        • Writing a UPS Dialog Creator

        • Using UPS management APIs

        • Example code at \sf\os\security\authorisation\userpromptservice\examples\ location.

        See also

        For related information, see UPS Configuration.

        \ No newline at end of file + + + + + +User Prompt Service Overview

        User Prompt Service (UPS) allows device creators to specify whether requests made by applications to access services, such as a request to make a telephone call, are processed silently or whether they require the user to be prompted.

        Purpose

        An application requests a service. The service provider (a system server) requests a decision from the UPS. The UPS searches for a matching policy file and policy. Based on the policy for the service, the service request may be immediately accepted or denied or it may need to receive a decision from the user, in which case it is accepted or denied after several further steps are carried out.

        Device creators can customize the circumstances under which prompts are generated by configuring policies. Policies are made up of details about the service being requested as well as information about whether to accept or deny silently or to ask the user. They are defined in policy lists. Each service has one policy list defining any number of policies. In cases where the policy specifies that a user prompt is required, ECom plug-ins called Policy Evaluators and Dialog Creators, written by device creators.

        Key concepts

        The component has the following key concepts:

        Policy

        Policies specify whether application requests to access services should be processed silently or whether the user should be prompted for a decision. Policies may be general or specific – for example a policy may be specific to a single application, a group of applications or a class of applications (For example, those with unprotected secure ids). Policies are defined in policy lists. Device creators define policies.

        UPS policy file

        A UPS policy file is a compiled resource file containing all of the policies for a given service. The policies are ordered from most specific to least specific.

        Because policies are matched in order, each service may have only one policy file. To define a policy safely, you need to know which other policies have been defined. If you place a general policy near the beginning of the list of policies, you prevent other policies from being evaluated.

        Policy evaluator

        Policy evaluators are Ecom plug-ins, which are responsible for generating fingerprints (see below) used to locate previous decision records related to the request. Device creators define policy evaluators.

        Dialog creator

        Dialog creators are Ecom plug-ins, which display and generate dialog prompts. Device creators define dialog creators.

        Fingerprint

        A fingerprint is a collection of data to do with the service being requested. The fingerprint usually includes the destination string supplied by the service that is matched to the destination string of a policy in the policy file. It might be a phone number, domain name, access point etc. A fingerprint is used to search the decision database for a match and to add a record to the decision database if a match was not found in the initial search. Device creators define the GenerateFingerprints() function in the Policy Evaluator plug-in.

        A fingerprint serves two purposes:

        • The UPS uses it to search the decision database for a match.

        • If the UPS finds no record of a previous user decision and the user selects "always" or "never" in response to the UPS prompt, it uses the fingerprint to create a new record in the decision database.

        It is possible to specify one or many policy evaluators. It is also possible not to specify a policy evaluator and to depend on the default policy evaluator.

        Decision database

        A decision database stores the phone user's choice of whether a request is always granted or never granted. Decisions stored in the decision database persist across reboots of the device. The decision database is provided by Symbian.

        The decision database may not be accessed directly. However, records may be retrieved and deleted via the management APIs. This might be used by a control-panel application.

        Architectural relationships

        The UPS provides CDialogCreator and CPolicyEvaluator interfaces for device creators to implement.

        + UPS components +
        API summary

        The following diagram shows the relationships between some of the key classes in the UPS.

        + Class diagram of key classes in UPS + Class Name Description

        UserPromptService::CClientEntity

        Class representing an entity executing within a client process. For example, a script.

        UserPromptService::CDialogCreator

        Abstract base class for dialog creator Ecom plug-ins. Dialog creators are responsible for generating and displaying prompt dialogs.

        UserPromptService::CFingerprint

        Class that represents the fingerprint data for a stored decision.

        UserPromptService::CPolicy

        Class for a single policy record.

        UserPromptService::CPolicyEvaluator

        Abstract base class for a policy evaluator Ecom plug-in. Policy evaluators are primarily responsible for generating the fingerprints used to locate previous decision records related to the current request.

        Typical uses

        The following diagram shows the sequence of activities performed by the UPS after it receives a request from a server:

        + Diagram showing activities for a single request +

        As is shown in the above diagram, the UPS returns a decision to the system server as in the following use cases:

        • processing silently

        • finding a stored decision in the decision database

        • prompting the user in a dialog and resulting in a "one-shot" or "session" (non-persistent) decision by the user

        • prompting the user in a dialog and resulting in an "always" or "never" (persistent) decision by the user

        The Policy Evaluator allows device creators to customize the behaviour of the UPS at run-time. Policy Evaluators may:

        • Allow security decisions to be specific to the data on which the service acts instead of simply granting full access to the service, for example "Allow application X to send SMS messages to 01234567". This is supported via the fingerprint functionality.

        • Allow a security decision to be specific to an individual script executing within a scripting host. This is supported via the client entity field.

        • Allow a prompt to be displayed even if the user selected "Always" or "Never". This could be based on a usage threshold or simply as additional confirmation if the user selected "Never". This is supported via the force prompt functionality.

        Typical uses

        The UPS component provides interfaces to perform the following tasks:

        • Integrating a System Server with UPS

        • Writing a UPS Policy File

        • Writing a UPS Policy Evaluator

        • Writing a UPS Dialog Creator

        • Using UPS management APIs

        • Example code at \sf\os\security\authorisation\userpromptservice\examples\ location.

        See also

        For related information, see UPS Configuration.

        \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1A7183EC-B55E-5B61-8965-89C939ECB395_d0e240382_href.png Binary file Symbian3/SDK/Source/GUID-1A7183EC-B55E-5B61-8965-89C939ECB395_d0e240382_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1A7183EC-B55E-5B61-8965-89C939ECB395_d0e244119_href.png Binary file Symbian3/SDK/Source/GUID-1A7183EC-B55E-5B61-8965-89C939ECB395_d0e244119_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1A8ED0EB-B3B7-553F-95E3-2120D877966B.dita --- a/Symbian3/SDK/Source/GUID-1A8ED0EB-B3B7-553F-95E3-2120D877966B.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-1A8ED0EB-B3B7-553F-95E3-2120D877966B.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,15 +1,15 @@ - - - - - -OpenVG Collection OverviewOpenVG is a royalty-free, cross-platform API that provides a low-level hardware acceleration interface for vector graphics libraries such as Flash and SVG. OpenVG is targeted primarily at handheld devices that require portable acceleration of high-quality vector graphics for user interfaces and text on small screen devices—while enabling hardware acceleration to provide fluidly interactive performance at very low power levels.

        Variant: ScreenPlay and non-ScreenPlay.

        OpenVG is an open standard developed by the Khronos Group (www.khronos.org). OpenVG features include:

        • Coordinate systems and transformations (image drawing uses a 3x3 perspective transformation matrix)

        • Viewport clipping, scissoring and alpha masking

        • Paths

        • Images and image filters

        • Paint (gradient and pattern)

        • Blending.

        In addition, the associated VGU utility library provides features such as higher-level geometric primitives and image warping.

        Architecture

        OpenVG only defines rendering functionality and therefore cannot be used in isolation. It requires EGL to establish an environment in which OpenVG can be used. For example, EGL tells OpenVG where its rendered output should go. OpenVG depends on a standalone implementation of EGL.

        The following diagram shows the direct use of OpenVG by an application through the public OpenVG interface together with EGL. On the Symbian platform, both OpenVG and EGL have a component (shown in blue) that declares the interface, and both require an implementation that implements that interface (shown in green).

        - OpenVG external relationships -

        It is possible for the OpenVG and EGL implementations to communicate through a private interface that is not standardized by Symbian.

        The OpenVG Interface provides a consistent interface to OpenVG on the Symbian platform, enabling cross-device compatibility. The component includes the Khronos-released header files (which incorporate some minor changes, such as to the comments). It also provides some Symbian-specific header files and some other files (such as LIB, DEF and MMP files) and UIDs. It does not provide any implementations of the APIs.

        Description

        OpenVG is designed to be the primary 2D and vector graphics API for use by mobile devices. By providing a consistent interface to OpenVG, the Symbian platform allows OpenVG applications and middleware (such as an SVG engine) to automatically benefit from hardware acceleration when it is present without losing compatibility when it is not available. In addition device and hardware manufacturers benefit from a standard Hardware Adaptation Interface (HAI) to plug into. This means that OpenVG has the potential to provide end users with improved quality and responsiveness of graphics features.

        OpenVG Collection EGL + + + + + +OpenVG Collection OverviewOpenVG is a royalty-free, cross-platform API that provides a low-level hardware acceleration interface for vector graphics libraries such as Flash and SVG. OpenVG is targeted primarily at handheld devices that require portable acceleration of high-quality vector graphics for user interfaces and text on small screen devices—while enabling hardware acceleration to provide fluidly interactive performance at very low power levels.

        Variant: ScreenPlay and non-ScreenPlay.

        OpenVG is an open standard developed by the Khronos Group (www.khronos.org). OpenVG features include:

        • Coordinate systems and transformations (image drawing uses a 3x3 perspective transformation matrix)

        • Viewport clipping, scissoring and alpha masking

        • Paths

        • Images and image filters

        • Paint (gradient and pattern)

        • Blending.

        In addition, the associated VGU utility library provides features such as higher-level geometric primitives and image warping.

        Architecture

        OpenVG only defines rendering functionality and therefore cannot be used in isolation. It requires EGL to establish an environment in which OpenVG can be used. For example, EGL tells OpenVG where its rendered output should go. OpenVG depends on a standalone implementation of EGL.

        The following diagram shows the direct use of OpenVG by an application through the public OpenVG interface together with EGL. On the Symbian platform, both OpenVG and EGL have a component (shown in blue) that declares the interface, and both require an implementation that implements that interface (shown in green).

        + OpenVG external relationships +

        It is possible for the OpenVG and EGL implementations to communicate through a private interface that is not standardized by Symbian.

        The OpenVG Interface provides a consistent interface to OpenVG on the Symbian platform, enabling cross-device compatibility. The component includes the Khronos-released header files (which incorporate some minor changes, such as to the comments). It also provides some Symbian-specific header files and some other files (such as LIB, DEF and MMP files) and UIDs. It does not provide any implementations of the APIs.

        Description

        OpenVG is designed to be the primary 2D and vector graphics API for use by mobile devices. By providing a consistent interface to OpenVG, the Symbian platform allows OpenVG applications and middleware (such as an SVG engine) to automatically benefit from hardware acceleration when it is present without losing compatibility when it is not available. In addition device and hardware manufacturers benefit from a standard Hardware Adaptation Interface (HAI) to plug into. This means that OpenVG has the potential to provide end users with improved quality and responsiveness of graphics features.

        OpenVG Collection EGL Collection         \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1A905563-EF60-4A01-BC55-5B35904F96AB-master.png Binary file Symbian3/SDK/Source/GUID-1A905563-EF60-4A01-BC55-5B35904F96AB-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1A905563-EF60-4A01-BC55-5B35904F96AB_d0e63486_href.png Binary file Symbian3/SDK/Source/GUID-1A905563-EF60-4A01-BC55-5B35904F96AB_d0e63486_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1AA32C40-CDE0-4627-A634-7C07BB1ED67B.dita --- a/Symbian3/SDK/Source/GUID-1AA32C40-CDE0-4627-A634-7C07BB1ED67B.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-1AA32C40-CDE0-4627-A634-7C07BB1ED67B.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,164 +1,154 @@ - - - - - -Forms -

        A form is a specific kind of selection list, where all items (fields) have -some editable content.

        -

        A form can be in the View state or in the Edit state. The item layouts -and functionality are different in these states:

        -
          -

        • In the View state, the items are not editable. The form functions and -looks exactly like a similar selection list. Items can be selected to perform -an application-specific function.

          • -

        • In the Edit state, the user can edit all the fields. Forms can contain -text fields (alphanumeric or numeric content), pop-up fields and sliders.

          • -
        -

        Forms work with single click. The view state of the form follows list behavior. -Edit state works with single click but it has the highlight always visible -to indicate the active form item. Note that the entire form component item -should be touch sensitive in normal state. This means that even if the user -does not touch the edit field but instead the field header, the item is still -activated.

        -

        The user can switch from the View state to the Edit state using the Edit -command in the Options menu. In the Edit state, the contents of the form can -be accepted using the right softkey labeled as Done. The form then returns -to the View state.

        - -An example form - - -

        The following table lists the default touch events for forms:

        -Default touch -events for forms - - - - - - -

        User action

         -

        State change

         -

        Feedback

         -         - - - - -

        In Edit State

         -         - -

        Touch down on item

         -

        No change

         -

        Highlight is shown on the item and focus shifts to the item.

        Tactile: -Basic list effect and audio feedback is provided with touch down event.

        Only -form-specific feedback is provided. No sensitive edit feedback provided on -editor item in the form.         -         - -

        Touch release on item

         -

        Item is activated.

        When the user moves a cursor to a text -field, the cursor is placed at the end of the text in the field. If the field -is empty, the cursor is placed at the beginning of the field.

        Touch -release on a radio button list item selects the item and closes the pop-up.

         -

        Highlight remains on the item.

        In case of a radio button list, -highlight stays on the full list, and not on any single selection item.

        Tactile: -Basic list effect provided with release event.

         -         - -

        Touch down and hold on item

         -

        Inactive

         -

        Tactile: No effect

         -         - -

        Touch down and move inside form

         -

        Refer to Dragging -and flicking events

         -

        Highlight remains on the item that is currently active, when the -user starts to move.

        Tactile: Refer to Dragging -and flicking events.

         -         - -

        Touch down and move outside the form without releasing touch.

         -

        Refer to Dragging -and flicking events

         -

        Tactile: Refer to Dragging -and flicking events.

         -         - -

        Touch down and release outside the radio button list

         -

        Radio button list is closed.

         -

        Tactile: Pop-up effect is provided with touch down event.

         -         - - - - -

        In View State

         -         - -

        Touch down on item

         -

        No effect

         -

        Highlight is shown.

        Tactile: Basic list effect and audio feedback -is provided with the touch down event.

         -         - -

        Touch release

         -

        One of the following occurs:

          -

        • Item is activated.

          • -

        • Item get editable.

          • -

        • Item opens context specific Options menu.

          • -

         -

        Highlight disappears.

        Tactile: Basic list effect is provided -with touch release event.

        If the touch release opens a pop-up, the pop-up -open effect is provided with the touch release. If theme effects are ON, then -increasing long touch effect with touch release is provided.

         -         - -

        Touch down and hold

         -

        Inactive

         -

        Tactile: No effect

         -         - -

        Touch down and move inside form

         -

        Refer to Dragging -and flicking events

         -

        Tactile: Refer to Dragging -and flicking events.

         -         - -

        Touch down and move outside the form without releasing touch.

         -

        Refer to Dragging -and flicking events

         -

        Tactile: Refer to Dragging -and flicking events.

         -         - - -
        -
        Using -forms in C++ applications

        The API to use for creating forms is the Form API. For implementation information, see Using the Form API.

        Typically, a form will be derived -from the class CAknForm and -the methods SaveFormDataL() and DoNotSaveFormData() will be implemented by the developer. These are called when users -switch from edit mode to view mode and are prompted by the form as to whether -they wish to save their modifications.

        For customization, the class CAknForm provides -a single-line or double-line layout and it is possible to use icons on forms.

        In -the following example, the form is pushed on the cleanup stack before ConstructL() (a -potentially leaving method) is called, and popped off before ExecuteLD().

        CAknExFormAdd* form = new(ELeave) CAknExFormAdd; -CleanupStack::PushL(form); -form->ConstructL(); -CleanupStack::Pop(); -form->ExecuteLD(R_AKNEXFORM_TEXT_FIELD_DIALOG); -
        -         -Related APIs -Dialogs API - + + + + + +Forms +

        A form is a specific kind of selection list, where all items (fields) +have some editable content.

        +

        A form can be in the View state or in the Edit state. The item +layouts and functionality are different in these states:

        +
          +

        • In the View state, the items are not editable. The form functions +and looks exactly like a similar selection list. Items can be selected +to perform an application-specific function.

          • +

        • In the Edit state, the user can edit all the fields. Forms +can contain text fields (alphanumeric or numeric content), pop-up +fields and sliders.

          • +
        +

        Forms work with single tap. The view state of the form follows +list behavior. Edit state works with single tap but it has the highlight +always visible to indicate the active form item. Note that the entire +form component item should be touch sensitive in normal state. This +means that even if the user does not touch the edit field but instead +the field header, the item is still activated.

        +

        The user can switch from the View state to the Edit state using +the Edit command in the Options menu. In the Edit state, the contents +of the form can be accepted using the right softkey labeled as Done. +The form then returns to the View state.

        + +An example form + + +

        The following table lists the default touch events for forms:

        +Default +touch events for forms + + + +

        User action

         +

        State change

         +

        Feedback

         +         + + + +

        In Edit State

         +         + +

        Touch down on item

         +

        No change

         +

        Highlight is shown on the item and focus shifts to the item.

        Tactile: Basic list effect and audio feedback is provided with +touch down event.

        Only form-specific feedback is provided. +No sensitive edit feedback provided on editor item in the form.         +         + +

        Touch release on item

         +

        Item is activated.

        When the user moves a cursor to +a text field, the cursor is placed at the end of the text in the field. +If the field is empty, the cursor is placed at the beginning of the +field.

        Touch release on a radio button list item selects the +item and closes the pop-up.

         +

        Highlight remains on the item.

        In case of a radio +button list, highlight stays on the full list, and not on any single +selection item.

        Tactile: Basic list effect provided with release +event.

         +         + +

        Touch down and hold on item

         +

        Inactive

         +

        Tactile: No effect

         +         + +

        Touch down and move inside form

         +

        Refer to Dragging and flicking events

         +

        Highlight remains on the item that is currently active, +when the user starts to move.

        Tactile: Refer to Dragging and flicking events.

         +         + +

        Touch down and move outside the form without releasing touch.

         +

        Refer to Dragging and flicking events

         +

        Tactile: Refer to Dragging and flicking events.

         +         + +

        Touch down and release outside the radio button list

         +

        Radio button list is closed.

         +

        Tactile: Pop-up effect is provided with touch down event.

         +         + + + + +

        In View State

         +         + +

        Touch down on item

         +

        No effect

         +

        Highlight is shown.

        Tactile: Basic list effect and +audio feedback is provided with the touch down event.

         +         + +

        Touch release

         +

        One of the following occurs:

          +

        • Item is activated.

          • +

        • Item get editable.

          • +

        • Item opens context specific Options menu.

          • +

         +

        Highlight disappears.

        Tactile: Basic list effect is +provided with touch release event.

        If the touch release opens +a pop-up, the pop-up open effect is provided with the touch release. +If theme effects are ON, then increasing long touch effect with touch +release is provided.

         +         + +

        Touch down and hold

         +

        Inactive

         +

        Tactile: No effect

         +         + +

        Touch down and move inside form

         +

        Refer to Dragging and flicking events

         +

        Tactile: Refer to Dragging and flicking events.

         +         + +

        Touch down and move outside the form without releasing touch.

         +

        Refer to Dragging and flicking events

         +

        Tactile: Refer to Dragging and flicking events.

         +         + + +
        +
        Using forms in applications

        The API to use for creating forms is the Form API. For implementation information, see Using the Form API.

        Typically, a form will +be derived from the class CAknForm and the methods SaveFormDataL() and DoNotSaveFormData() will be implemented by +the developer. These are called when users switch from edit mode to +view mode and are prompted by the form as to whether they wish to +save their modifications.

        For customization, the class CAknForm provides a single-line or double-line layout and +it is possible to use icons on forms.

        In the following example, +the form is pushed on the cleanup stack before ConstructL() (a potentially leaving method) +is called, and popped off before ExecuteLD().

        CAknExFormAdd* form = new(ELeave) CAknExFormAdd; +CleanupStack::PushL(form); +form->ConstructL(); +CleanupStack::Pop(); +form->ExecuteLD(R_AKNEXFORM_TEXT_FIELD_DIALOG); +
        +         +Related APIs +Dialogs API +         \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1AA392CB-F638-5D35-993E-4A26D67A7C98.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-1AA392CB-F638-5D35-993E-4A26D67A7C98.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,147 @@ + + + + + +How +to retrieve characteristics +

        The following example demonstrates the use of the legacy selector to retrieve +the characteristics of an asymmetric cipher object. In the example, an implementation +object is constructed (making use of an RSA Key Pair also generated by the +framework) and returned. The plug-in characteristics and extended characteristics +associated with the object are then accessed.

        +#include <cryptoasymmetriccipherapi.h> +#include <cryptokeypairgeneratorapi.h> +#include <cryptospidef.h> +#include <plugincharacteristics.h> +#include <extendedcharacteristics.h> +#include <keypair.h> + +// Constant definition for the RSA key pair generator exponent value +const TInt KKeyExponent = 65537; + +using namespace CryptoSpi; + +// Create a new CCryptoParams instance to contain the RSA Key Pair initialization data +CCryptoParams* keyParams = CCryptoParams::NewLC(); + +// Create an RSA Key Pair and Key Pair Generator object pointers +CKeyPair* keyPair = NULL; +CKeyPairGenerator * keypairImpl = NULL; + +// Set the RSA Key Pair Generator initialization parameters reate an RSA key pair +keyParams->AddL(KKeyExponent, KRsaKeyParameterEUid); +keyParams->AddL(KRsaPrivateKeyStandard, KRsaKeyTypeUid); + +// Retrieve an instance of an RSA Key Pair Generator implementation from the framework +CKeyPairGeneratorFactory::CreateKeyPairGeneratorL( keypairImpl, + KRSAKeyPairGeneratorUid, + keyParams); + +CleanupStack::PushL(keypairImpl); + +// Create an RSA Key Pair +keypairImpl->GenerateKeyPairL(1024, *keyParams, keyPair); + +CleanupStack::PushL(keyPair); + +// Create and initialize a pointer for the asymmetric cipher implementation object +CAsymmetricCipher* asymmetricCipherImpl = NULL; + +// If successful, the 'CreateAsymmetricCipherL' method returns KErrNone and sets the +// asymmetricCipherImpl pointer to point to the constructed implementation +TRAPD(err, CAsymmetricCipherFactory::CreateAsymmetricCipherL(asymmetricCipherImpl, + KRsaCipherUid, + keyPair->PrivateKey(), + KCryptoModeEncryptUid, + KPaddingModeNoneUid, + NULL)); + +// Having successfully constructed the asymmetric cipher implementation object, +// it is possible to retrieve the plug-in characteristics associated with it +if (asymmetricCipherImpl && (err == KErrNone)) + { + CleanupStack::PushL(asymmetricCipherImpl); + + // Retrieving common and algorithm-specific characteristics + // Create a constant pointer of type TCharacteristics used to access the + // asymmetric cipher plug-in's common and algorithm-specific characteristics + const TCharacteristics* chars(NULL); + + // Retrieve the common and algorithm-specific characteristics by calling the + // 'GetCharacteristicsL' method passing in TCharacteristics pointer + asymmetricCipherImpl->GetCharacteristicsL(chars); + + // Static cast the characteristics to type TAsymmetricCipherCharacteristics + const TAsymmetricCipherCharacteristics* asymmetricChars = + static_cast<const TAsymmetricCipherCharacteristics*>(chars); + + // Retrieve the common characteristics from the TASymmetricCipherCharacteristics + // object + const TCommonCharacteristics* asymmetricCommonChars = &asymmetricChars->cmn; + + TUid implementationId; + TBool hardwareSupported; + TRomLitC16 creatorName; + TInt maximumKeyLength; + TInt32 supportedPaddingModes; + + // Example of extracting asymmetric common characteristics + implementationId.iUid = asymmetricCommonChars->iImplementationUID; + hardwareSupported = asymmetricCommonChars->iIsHardwareSupported; + creatorName = *(asymmetricCommonChars->iCreatorName); + + // Example of extracting asymmetric algorithm specific characteristics + maximumKeyLength = asymmetricChars->iMaximumKeyLength; + supportedPaddingModes = *(asymmetricChars->iSupportedPaddingModes); + + //Retrieving extended characteristics + + // Create a constant pointer of type CExtendedCharacteristics used to store and + // access the asymmetric cipher plug-in extended characteristics. Retrieve + // the data by calling the 'GetExtendedCharacteristicsL' method and store the + // returned pointer + const CExtendedCharacteristics* extendedChars = + asymmetricCipherImpl->GetExtendedCharacteristicsL(); + + // Const casting the pointer to the CExtendedCharacteristics object allows it to + // be pushed onto the cleanup stack + CExtendedCharacteristics* ncExtendedChars = + const_cast<CExtendedCharacteristics*>(extendedChars); + CleanupStack::PushL(ncExtendedChars); + + TInt concurrency; + + // Each of the extended characteristics for the particular cryptographic + // implementation can then be accessed by passing the UID value into the + // appropriate 'Get' method + concurrency = extendedChars->GetTIntCharacteristicL(KConcurrencyTypeUid); + // Alternatively, extended characteristic retrieval can be achieved via the + // ListExtendedCharacteristics() method of the CExtendedCharacteristics Object. + // Using the 'ListExtendedCharacteristics' function returns a pointer to a + // CCryptoParams object, that contains a list of all associated extended + // characteristics + const CCryptoParams* extendedCryptoParams = + extendedChars->ListExtendedCharacteristics(); + + TBool exclusiveUse; + + // The extended characteristics can then be accessed in much the same way as + // before, making a call to the appropriate 'Get' method with the UID value of the + // required type + exclusiveUse = extendedCryptoParams->GetTIntL(KExclusiveUseTypeUid); + + CleanupStack::PopAndDestroy(2, asymmetricCipherImpl); + } + +// Pop and destroy the remaining items on the cleanup stack +CleanupStack::PopAndDestroy(3,keyParams); + + +         \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1AAA88BB-19AD-5B8E-993C-11F4B7CD90EB.dita --- a/Symbian3/SDK/Source/GUID-1AAA88BB-19AD-5B8E-993C-11F4B7CD90EB.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-1AAA88BB-19AD-5B8E-993C-11F4B7CD90EB.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,179 +1,179 @@ - - - - - -Writing -a MIME Recognizer

        The Mime Recognizers provide the implementation for data type -(MIME Type) recognition using the MIME recognition framework.

        Each -MIME recognizer specifies the MIME type it supports along with the priority -and confidence of recognition. A MIME recognizer reads a small piece of data -and identifies the data type. Once the data type is identified, it is passed -to the Application -Architecture (AppArc). AppArc launches the application -that best handles the identified data type.

        -

        Symbian OS v9.1 -and onwards, MIME recognizers are ECOM plug-ins. -They are located in \sys\bin\.

        Each MIME recognizer is loaded -by the Application -Architecture (AppArc) during the startup sequence.

        - - -Create a project file (.mmp) for the MIME recognizer -and ensure the following parameters are set. - - - - -

        Variable Name

        -

        Value

        -

        Description

        -         - -

        TargetType

        -

        plugin

        -

        Specifies the type of binary.

        -         - -

        Resource

        -

        Use the block start resource ... end

        -

        The variable Resource is set to the registration -resource file (.rss))of the MIME recognizer.

        -         - -

        UID

        -

        0x10009D8D and the DLL UID

        -

        The variable UID requires two values. The first -value is 0x10009D8D and is constant for all MIME recognizers. The second value -is the UID of the DLL.

        -         - -

        Capability

        -

        Protserv

        -

        The AppArc server has protserv capability.The MIME -recognizers are loaded by the AppArc server on requirement. The MIME recognizers -must have protserv capability to be loaded by the AppArc -server.

        -         - - -
         -For more details, refer Creating -a Project File. -The code below shows a sample .mmp file with the -above parameters set. -target exampleRecognizer.dll - -capability Protserv -targettype plugin -uid 0x10009d8d 0x1d1f75ed -vendorid 0x70000001 - -sourcepath . -source exampleRecognizer.cpp -systeminclude \EPOC32\INCLUDE -systeminclude \EPOC32\INCLUDE\ECOM - -library EUSER.LIB APMIME.LIB - -start resource 1d1f75ed.rss -target exampleRecognizer.rsc -end -         - -Export the factory code function of the MIME recognizer as shown below. -This is required to create an instance of the MIME recognizer. -The class CExampleRecognizer is derived from CApaDataRecognizerType. -const TInt KImplementationUID = 0x101F7DA1; - -CApaDataRecognizerType* CExampleRecognizer::CreateRecognizerL() - { - return new (ELeave) CExampleRecognizer; - } - -const TImplementationProxy ImplementationTable[] = - { - IMPLEMENTATION_PROXY_ENTRY(KImplementationUID,CExampleRecognizer::CreateRecognizerL); - } - -EXPORT_C const TImplementationProxy* ImplementationGroupProxy(TInt& aTableCount) - { - aTableCount = sizeof(ImplementationTable) / sizeof(TImplementationProxy); - return ImplementationTable; - } - -For more details refer Exporting -Implementation Factories. - - -Implement CApaDataRecognizerType polymorphic interface. - - -The code below shows a sample constructor implementation. -const TUid KExampleUid = {0x1d1f75ed}; - -const TInt KNumDataTypes = 1; - -CExampleRecognizer::CExampleRecognizer() : CApaDataRecognizerType(KExampleUid,CApaDataRecognizerType::EHigh) - - { - iCountDataTypes = KNumDataTypes; - - } - - -Specify a UID (the DLL UID as specified in the plug-in -project definition file) and a priority in -the constructor. -The iCountDataTypes variable, represents the number -of data types supported by the recognizer can also be set in the constructor. -The value set for this variable should match the implementation of CApaDataRecognizerType::SupportedDataTypeL(). - - -Implement the pure virtual function CApaDataRecognizerType::SupportedDataTypeL(). -It returns the MIME types that the recognizer is capable of recognizing. -The code below shows a sample implementation of SupportedDataTypeL() for -supporting MIME type/ subtype "text/example". - -_LIT8(KExampleTextMimeType, "text/example"); - - -TDataType CExampleRecognizer::SupportedDataTypeL(TInt aIndex) const - - { - return TDataType(KExampleTextMimeType); - - } - - -Implement CApaDataRecognizerType::DoRecognizeL(). -This function executes data type recognition. -The code below shows a sample implementation of DoRecognizeL() for -recognizing the MIME type "/text/example" contained in files -with .example extension with maximum confidence. -void CExampleRecognizer::DoRecognizeL(const TDesC& aName, const TDesC8& aBuffer) - { - _LIT8(KExampleData, "example"); - _LIT(KDotExample, ".Example"); - - TParse parse; - parse.Set(aName,NULL,NULL); - TPtrC ext=parse.Ext(); // extract the extension from the filename - - if (ext.CompareF(KDotExample)==0 && aBuffer.FindF(KExampleData)!=KErrNotFound) - { - iConfidence=ECertain; - iDataType=TDataType(KExampleTextMimeType); - } - } - - - -         + + + + + +Writing +a MIME Recognizer

        The Mime Recognizers provide the implementation for data type +(MIME Type) recognition using the MIME recognition framework.

        Each +MIME recognizer specifies the MIME type it supports along with the priority +and confidence of recognition. A MIME recognizer reads a small piece of data +and identifies the data type. Once the data type is identified, it is passed +to the Application +Architecture (AppArc). AppArc launches the application +that best handles the identified data type.

        +

        Symbian OS v9.1 +and onwards, MIME recognizers are ECOM plug-ins. +They are located in \sys\bin\.

        Each MIME recognizer is loaded +by the Application +Architecture (AppArc) during the startup sequence.

        + + +Create a project file (.mmp) for the MIME recognizer +and ensure the following parameters are set. + + + + +

        Variable Name

        +

        Value

        +

        Description

        +         + +

        TargetType

        +

        plugin

        +

        Specifies the type of binary.

        +         + +

        Resource

        +

        Use the block start resource ... end

        +

        The variable Resource is set to the registration +resource file (.rss))of the MIME recognizer.

        +         + +

        UID

        +

        0x10009D8D and the DLL UID

        +

        The variable UID requires two values. The first +value is 0x10009D8D and is constant for all MIME recognizers. The second value +is the UID of the DLL.

        +         + +

        Capability

        +

        Protserv

        +

        The AppArc server has protserv capability.The MIME +recognizers are loaded by the AppArc server on requirement. The MIME recognizers +must have protserv capability to be loaded by the AppArc +server.

        +         + + +
         +For more details, refer Creating +a Project File. +The code below shows a sample .mmp file with the +above parameters set. +target exampleRecognizer.dll + +capability Protserv +targettype plugin +uid 0x10009d8d 0x1d1f75ed +vendorid 0x70000001 + +sourcepath . +source exampleRecognizer.cpp +systeminclude \EPOC32\INCLUDE +systeminclude \EPOC32\INCLUDE\ECOM + +library EUSER.LIB APMIME.LIB + +start resource 1d1f75ed.rss +target exampleRecognizer.rsc +end +         + +Export the factory code function of the MIME recognizer as shown below. +This is required to create an instance of the MIME recognizer. +The class CExampleRecognizer is derived from CApaDataRecognizerType. +const TInt KImplementationUID = 0x101F7DA1; + +CApaDataRecognizerType* CExampleRecognizer::CreateRecognizerL() + { + return new (ELeave) CExampleRecognizer; + } + +const TImplementationProxy ImplementationTable[] = + { + IMPLEMENTATION_PROXY_ENTRY(KImplementationUID,CExampleRecognizer::CreateRecognizerL); + } + +EXPORT_C const TImplementationProxy* ImplementationGroupProxy(TInt& aTableCount) + { + aTableCount = sizeof(ImplementationTable) / sizeof(TImplementationProxy); + return ImplementationTable; + } + +For more details refer Exporting +Implementation Factories. + + +Implement CApaDataRecognizerType polymorphic interface. + + +The code below shows a sample constructor implementation. +const TUid KExampleUid = {0x1d1f75ed}; + +const TInt KNumDataTypes = 1; + +CExampleRecognizer::CExampleRecognizer() : CApaDataRecognizerType(KExampleUid,CApaDataRecognizerType::EHigh) + + { + iCountDataTypes = KNumDataTypes; + + } + + +Specify a UID (the DLL UID as specified in the plug-in +project definition file) and a priority in +the constructor. +The iCountDataTypes variable, represents the number +of data types supported by the recognizer can also be set in the constructor. +The value set for this variable should match the implementation of CApaDataRecognizerType::SupportedDataTypeL(). + + +Implement the pure virtual function CApaDataRecognizerType::SupportedDataTypeL(). +It returns the MIME types that the recognizer is capable of recognizing. +The code below shows a sample implementation of SupportedDataTypeL() for +supporting MIME type/ subtype "text/example". + +_LIT8(KExampleTextMimeType, "text/example"); + + +TDataType CExampleRecognizer::SupportedDataTypeL(TInt aIndex) const + + { + return TDataType(KExampleTextMimeType); + + } + + +Implement CApaDataRecognizerType::DoRecognizeL(). +This function executes data type recognition. +The code below shows a sample implementation of DoRecognizeL() for +recognizing the MIME type "/text/example" contained in files +with .example extension with maximum confidence. +void CExampleRecognizer::DoRecognizeL(const TDesC& aName, const TDesC8& aBuffer) + { + _LIT8(KExampleData, "example"); + _LIT(KDotExample, ".Example"); + + TParse parse; + parse.Set(aName,NULL,NULL); + TPtrC ext=parse.Ext(); // extract the extension from the filename + + if (ext.CompareF(KDotExample)==0 && aBuffer.FindF(KExampleData)!=KErrNotFound) + { + iConfidence=ECertain; + iDataType=TDataType(KExampleTextMimeType); + } + } + + + +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1AF99DF6-C5BE-5713-940D-5E9FBD43F123.dita --- a/Symbian3/SDK/Source/GUID-1AF99DF6-C5BE-5713-940D-5E9FBD43F123.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-1AF99DF6-C5BE-5713-940D-5E9FBD43F123.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,59 +1,59 @@ - - - - - -Animation -example -
        Description

        This example is a UI application, which -demonstrates how to create and play basic and sprite animations. It implements -all the standard classes required by any application using UI controls such -as an application, a document, an application UI and a view.

        The application -provides UI controls to create a sprite animation and a basic client-side -animation. It also provides UI controls to control the behavior -of an animation such as, start, stop, pause, resume and move.

        The -application plays an animated .gif file both as a basic -client-side animation and a server-side sprite animation. It performs the -following tasks in the order they are listed to create the basic and sprite -animations:

          -

        1. Creates an object of -the CICLAnimationDataProvider class.

          2. -

        2. Loads the animated .gif file -into the object.

          3. -

        3. Configures the animation -to play in an infinite loop using TAnimationConfig.

          4. -

        4. Creates objects of CBasicAnimation and CSpriteAnimation classes by passing the data provider object as an argument.

          5. -

        5. Starts animations with -the TAnimationConfig object as an argument.

          6. -

        Once both the animations are started, the window server will automatically -draw the animations onto the window by calling the Draw() method.

        -
        Download

        Click on the following link to download -the example: AnimExample.zip

        Click: browse to view the example code.

        -
        Class summary
          -

        • CEikApplication

          • -

        • CEikDocument

          • -

        • CEikAppUi

          • -

        • CCoeControl

          • -

        • CActive

          • -

        • CBasicAnimation

          • -

        • CSpriteAnimation

          • -

        • CICLAnimationDataProvider

          • -

        • TAnimationConfig

          • -
        -
        Build

        The Symbian -platform build process describes how to build an application. But, -use abld export command before abld build to -copy the animated .gif file to RAM (C:\ drive) -of the target platform.

        The AnimExample builds an executable called AnimExample.exe in -the standard location (\epoc32\release\winscw\ udeb -or urel for CodeWarrior). Either launch the executable or launch the emulator -and then select the AnimExample application from the Emulator's extras bar.

        -
        See also

        Using -Animation

        + + + + + +Animation +example +
        Description

        This example is a UI application, which +demonstrates how to create and play basic and sprite animations. It implements +all the standard classes required by any application using UI controls such +as an application, a document, an application UI and a view.

        The application +provides UI controls to create a sprite animation and a basic client-side +animation. It also provides UI controls to control the behavior +of an animation such as, start, stop, pause, resume and move.

        The +application plays an animated .gif file both as a basic +client-side animation and a server-side sprite animation. It performs the +following tasks in the order they are listed to create the basic and sprite +animations:

          +

        1. Creates an object of +the CICLAnimationDataProvider class.

          2. +

        2. Loads the animated .gif file +into the object.

          3. +

        3. Configures the animation +to play in an infinite loop using TAnimationConfig.

          4. +

        4. Creates objects of CBasicAnimation and CSpriteAnimation classes by passing the data provider object as an argument.

          5. +

        5. Starts animations with +the TAnimationConfig object as an argument.

          6. +

        Once both the animations are started, the window server will automatically +draw the animations onto the window by calling the Draw() method.

        +
        Download

        Click on the following link to download +the example: AnimExample.zip

        Click: browse to view the example code.

        +
        Class summary
          +

        • CEikApplication

          • +

        • CEikDocument

          • +

        • CEikAppUi

          • +

        • CCoeControl

          • +

        • CActive

          • +

        • CBasicAnimation

          • +

        • CSpriteAnimation

          • +

        • CICLAnimationDataProvider

          • +

        • TAnimationConfig

          • +
        +
        Build

        The Symbian +platform build process describes how to build an application. But, +use abld export command before abld build to +copy the animated .gif file to RAM (C:\ drive) +of the target platform.

        The AnimExample builds an executable called AnimExample.exe in +the standard location (\epoc32\release\winscw\ udeb +or urel for CodeWarrior). Either launch the executable or launch the emulator +and then select the AnimExample application from the Emulator's extras bar.

        +
        See also

        Using +Animation

        \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1AFDDD6F-CB99-587D-A0B5-D3F5B27F7135.dita --- a/Symbian3/SDK/Source/GUID-1AFDDD6F-CB99-587D-A0B5-D3F5B27F7135.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-1AFDDD6F-CB99-587D-A0B5-D3F5B27F7135.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,40 +1,40 @@ - - - - - -Concepts -

        This section describes the ideas that underly the Comms Database.

        -

        The Comms Database provides system wide storage for communications related -settings. The Comms Database holds information about Internet Access Providers -(IAPs), Internet Service Providers (ISPs), GPRS, modems, locations, charge-cards, -proxies, WAP settings etc. The Comms Database holds this information as a -set of related tables.

        -

        Symbian platform defines the format of this information, but the Comms -Database can also contain user-defined data. Symbian support for user-defined -data is limited to backup and security.

        -

        Tools and applications that manage voice and data transmissions use the -Comms Database.

        -

        The Comms Database is a persistent store. Tools and applications use the -CommsDat API to access the data in the Comms Database. The CommsDat API hides -the structure of the data on the database. The CommsDat API also hides the -implementation of the database, and allows the implementation to change in -future versions of Symbian platform without a change to client code.

        -

        The current version of Symbian platform implements the Comms -Database in the Central Repository.

        -

        The Comms Database is available on all Symbian platforms.

        - - - -         -Configuring -comms database using CED -Comms database -configuration file format + + + + + +Concepts +

        This section describes the ideas that underly the Comms Database.

        +

        The Comms Database provides system wide storage for communications related +settings. The Comms Database holds information about Internet Access Providers +(IAPs), Internet Service Providers (ISPs), GPRS, modems, locations, charge-cards, +proxies, WAP settings etc. The Comms Database holds this information as a +set of related tables.

        +

        Symbian platform defines the format of this information, but the Comms +Database can also contain user-defined data. Symbian support for user-defined +data is limited to backup and security.

        +

        Tools and applications that manage voice and data transmissions use the +Comms Database.

        +

        The Comms Database is a persistent store. Tools and applications use the +CommsDat API to access the data in the Comms Database. The CommsDat API hides +the structure of the data on the database. The CommsDat API also hides the +implementation of the database, and allows the implementation to change in +future versions of Symbian platform without a change to client code.

        +

        The current version of Symbian platform implements the Comms +Database in the Central Repository.

        +

        The Comms Database is available on all Symbian platforms.

        + + + +         +Configuring +comms database using CED +Comms database +configuration file format         \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1B64E1D9-33AB-4C28-A471-22D4C51FEC43.dita --- a/Symbian3/SDK/Source/GUID-1B64E1D9-33AB-4C28-A471-22D4C51FEC43.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-1B64E1D9-33AB-4C28-A471-22D4C51FEC43.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,31 +1,44 @@ - - - - - -Tooltips -

        Tooltip is used for providing brief hint about an item, to explain the -user’s tasks for the item selected by the user.

        -

        An information pop-up is -used to display the tooltip.

        -

        Design recommendation: Tooltips must not be used for items that -might open a stylus pop-up menu with touch down and hold.

        -

        It is an application's responsibility to design all required texts -for their tooltips.

        - -Example tooltip - - -

        Tooltip appears when the user touches down and holds on an item, that has -a tooltip designed, for at least 0.3 seconds. It also appears from a dimmed -icon, as it would be displayed in “normal” situation. Tooltip disappears with -touch release, when the focus is moved to another item or when the user touches -down some other item that does not have a tooltip.

        -

        There is no touch interaction with the tooltip item.

        + + + + + +Tooltips +

        Tooltip is used for providing brief hint about an item, to explain the +user’s tasks for the item selected by the user.

        +

        An information pop-up is +used to display the tooltip.

        +

        Information pop-up notes are used to provide additional information to +the user, most typically regarding a focused item. Although the Information +pop-up can be used in various applications and components, it should not be +used too frequently as constantly appearing and disappearing notes may disturb +smooth user experience.

        +

        The Information pop-up does not have focus, its content cannot be scrolled, +and the control always remains in the main pane. The maximum number of rows +in the Information pop-up is four. In a typical case, the pop-up emerges one +second after the user has taken the focus on an item but has not made any +further actions. The pop-up is timed so that it (typically) remains visible +for ten seconds or until some event interrupts it. Time-outs are application-specific +and variation is possible.

        +

        The API to use for the information pop-up is the Info pop-up API.

        + +Example of tooltip + + +

        Design recommendation: Tooltips must not be used for items that +might open a stylus pop-up menu with touch down and hold.

        +

        It is an application's responsibility to design all required texts +for their tooltips.

        +

        Tooltip appears when the user touches down and holds on an item, that has +a tooltip designed, for at least 0.3 seconds. It also appears from a dimmed +icon, as it would be displayed in “normal” situation. Tooltip disappears with +touch release, when the focus is moved to another item or when the user touches +down some other item that does not have a tooltip.

        +

        There is no touch interaction with the tooltip item.

         \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1BAF17A9-B71B-5003-AEB5-4631F019C6AC-GENID-1-8-1-3-1-1-9-1-4-1-5-1.dita --- a/Symbian3/SDK/Source/GUID-1BAF17A9-B71B-5003-AEB5-4631F019C6AC-GENID-1-8-1-3-1-1-9-1-4-1-5-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,21 +0,0 @@ - - - - - -Fixed -and Floating WindowsThis section explains the fixed and floating FEP windows. -
        The fixed window

        The -FEP architecture does not enable FEP to negotiate with the application beneath -them for division of screen area.

        -
        The floating -window

        To make the control of FEP window float above the application, -and even above any dialogs or pop-up windows that the application launches, -use the following code in the construction of control routine:

        DrawableWindow()->SetOrdinalPosition(0, ECoeWinPriorityFep);
        -         \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1BAF17A9-B71B-5003-AEB5-4631F019C6AC-GENID-1-8-1-6-1-1-4-1-8-1-4-1-5-1.dita --- a/Symbian3/SDK/Source/GUID-1BAF17A9-B71B-5003-AEB5-4631F019C6AC-GENID-1-8-1-6-1-1-4-1-8-1-4-1-5-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,21 +0,0 @@ - - - - - -Fixed -and Floating WindowsThis section explains the fixed and floating FEP windows. -
        The fixed window

        The -FEP architecture does not enable FEP to negotiate with the application beneath -them for division of screen area.

        -
        The floating -window

        To make the control of FEP window float above the application, -and even above any dialogs or pop-up windows that the application launches, -use the following code in the construction of control routine:

        DrawableWindow()->SetOrdinalPosition(0, ECoeWinPriorityFep);
        -         \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1BAF17A9-B71B-5003-AEB5-4631F019C6AC.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-1BAF17A9-B71B-5003-AEB5-4631F019C6AC.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,21 @@ + + + + + +Fixed +and Floating WindowsThis section explains the fixed and floating FEP windows. +
        The fixed window

        The +FEP architecture does not enable FEP to negotiate with the application beneath +them for division of screen area.

        +
        The floating +window

        To make the control of FEP window float above the application, +and even above any dialogs or pop-up windows that the application launches, +use the following code in the construction of control routine:

        DrawableWindow()->SetOrdinalPosition(0, ECoeWinPriorityFep);
        +         \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1BB546C1-2795-55D9-97B6-AC3F6AB79389-GENID-1-8-1-3-1-1-7-1-7-1.dita --- a/Symbian3/SDK/Source/GUID-1BB546C1-2795-55D9-97B6-AC3F6AB79389-GENID-1-8-1-3-1-1-7-1-7-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,22 +0,0 @@ - - - - - -Controls -

        In the Symbian platform UI Control Framework, all UI elements (with a few -exceptions) are controls. A control is a rectangular area -of the screen that may respond to user input events. Buttons, menus, text -input boxes and application views displaying application-specific data are -all examples of controls.

        -

        All controls are implemented by deriving from the CCoeControl class. -Concrete implementations of controls are provided by a user interface library, -or by the application programmer. The control framework itself provides no -concrete controls.

        -         \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1BB546C1-2795-55D9-97B6-AC3F6AB79389-GENID-1-8-1-6-1-1-4-1-6-1-7-1.dita --- a/Symbian3/SDK/Source/GUID-1BB546C1-2795-55D9-97B6-AC3F6AB79389-GENID-1-8-1-6-1-1-4-1-6-1-7-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,22 +0,0 @@ - - - - - -Controls -

        In the Symbian platform UI Control Framework, all UI elements (with a few -exceptions) are controls. A control is a rectangular area -of the screen that may respond to user input events. Buttons, menus, text -input boxes and application views displaying application-specific data are -all examples of controls.

        -

        All controls are implemented by deriving from the CCoeControl class. -Concrete implementations of controls are provided by a user interface library, -or by the application programmer. The control framework itself provides no -concrete controls.

        -         \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1BB546C1-2795-55D9-97B6-AC3F6AB79389.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-1BB546C1-2795-55D9-97B6-AC3F6AB79389.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,22 @@ + + + + + +Controls +

        In the Symbian platform UI Control Framework, all UI elements (with a few +exceptions) are controls. A control is a rectangular area +of the screen that may respond to user input events. Buttons, menus, text +input boxes and application views displaying application-specific data are +all examples of controls.

        +

        All controls are implemented by deriving from the CCoeControl class. +Concrete implementations of controls are provided by a user interface library, +or by the application programmer. The control framework itself provides no +concrete controls.

        +         \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1BDADA7A-D517-49F4-AF46-AFC2B7758571.dita --- a/Symbian3/SDK/Source/GUID-1BDADA7A-D517-49F4-AF46-AFC2B7758571.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-1BDADA7A-D517-49F4-AF46-AFC2B7758571.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,87 +1,84 @@ - - - - - -Slider -setting item -

        A slider setting item has a value (numeric or textual) that can be adjusted -using an interface with a slider appearance. The control area is the same -as for scrollbar.

        - -Slider setting item - - -

        The actual slider item usage is specified in applications.

        -Default touch -events for slider setting item - - - - - - -

        User action

         -

        State change

         -

        Feedback

         -         - - - -

        Touch down (on slider)

         -

        Slider thumb is moved to the nearest slider step position on the -slider.

        Value is changed accordingly.

        If touch down event is -performed in the middle of two slider step positions, the slider thumb is -moved towards the greater (larger) value.

         -

        Tactile: No touch down effect. Sensitive slider effect and audio -given when thumb moves.

         -         - -

        Touch down (on slider thumb)

         -

        Slider thumb is activated and can be moved.

         -

        Tactile: Sensitive slider effect and audio given with touch down.

         -         - -

        Touch release

         -

        No effect

         -

        Tactile: Sensitive slider effect given with touch release (on slider -thumb).

         -         - -

        Touch down and hold (on slider)

         -

        Moves the thumb step by step to the place where touched down.

         -

        Tactile: Hold slider effect is given with long touch on slider. -Effect is tied to the steps. If there are more than 15 steps, then smooth -slider effect is given instead.

         -         - -

        Touch down and hold (on slider thumb)

         -

        Inactive

         -

        Tactile: No effect

         -         - -

        Touch down and move

         -

        Slider thumb is moved along with the touch event.

        It moves -step by step via its possible positions.

        Value is changing accordingly.

        If -touch release in the middle of two slider step positions, the slider thumb -is moved towards the greater (larger) value.

        The slider control area -is the entire main pane area.

         -

        Tactile: Smooth slider effect is provided when dragging from thumb.

        Smooth -feedback can be increasing and decreasing when there is a meaning to use this -kind of feature (e.g., in volume and zoom slider).

         -         - -

        Touch down and cancel (slider thumb)

         -

        Slider thumb is moved to the nearest slider step position where -it was when the touch left the slider control area.

         -

        Tactile: No feedback given with touch release after drag outside.

         -         - - + + + + + +Slider +setting item +

        A slider setting item has a value (numeric or textual) that can be adjusted +using an interface with a slider appearance. The control area for slider setting +item is same as that of the scrollbar.

        + +Slider setting item + + +

        The actual slider item usage is specified in applications.

        +
        Default touch +events for slider setting item + + + +

        User action

         +

        State change

         +

        Feedback

         +         + + + +

        Touch down (on slider)

         +

        Slider thumb is moved to the nearest slider step position on the +slider.

        Value is changed accordingly.

        If touch down event is +performed in the middle of two slider step positions, the slider thumb is +moved towards the greater (larger) value.

         +

        Tactile: No touch down effect. Sensitive slider effect and audio +given when thumb moves.

         +         + +

        Touch down (on slider thumb)

         +

        Slider thumb is activated and can be moved.

         +

        Tactile: Sensitive slider effect and audio given with touch down.

         +         + +

        Touch release

         +

        No effect

         +

        Tactile: Sensitive slider effect given with touch release (on slider +thumb).

         +         + +

        Touch down and hold (on slider)

         +

        Moves the thumb step by step to the place where touched down.

         +

        Tactile: Hold slider effect is given with long touch on slider. +Effect is tied to the steps. If there are more than 15 steps, then smooth +slider effect is given instead.

         +         + +

        Touch down and hold (on slider thumb)

         +

        Inactive

         +

        Tactile: No effect

         +         + +

        Touch down and move

         +

        Slider thumb is moved along with the touch event.

        It moves +step by step via its possible positions.

        Value is changing accordingly.

        If +touch release in the middle of two slider step positions, the slider thumb +is moved towards the greater (larger) value.

        The slider control area +is the entire main pane area.

         +

        Tactile: Smooth slider effect is provided when dragging from thumb.

        Smooth +feedback can be increasing and decreasing when there is a meaning to use this +kind of feature (e.g., in volume and zoom slider).

         +         + +

        Touch down and cancel (slider thumb)

         +

        Slider thumb is moved to the nearest slider step position where +it was when the touch left the slider control area.

         +

        Tactile: No feedback given with touch release after drag outside.

         +         + +
         \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1BDBFC07-A8E8-5150-953D-CA9CFE1CBF16_d0e249822_href.jpg Binary file Symbian3/SDK/Source/GUID-1BDBFC07-A8E8-5150-953D-CA9CFE1CBF16_d0e249822_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1BDBFC07-A8E8-5150-953D-CA9CFE1CBF16_d0e253554_href.jpg Binary file Symbian3/SDK/Source/GUID-1BDBFC07-A8E8-5150-953D-CA9CFE1CBF16_d0e253554_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1BEA00A2-7934-5CF6-A838-44CCA4A28F35.dita --- a/Symbian3/SDK/Source/GUID-1BEA00A2-7934-5CF6-A838-44CCA4A28F35.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-1BEA00A2-7934-5CF6-A838-44CCA4A28F35.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,14 +1,14 @@ - - - - - -Application registration files
        Introduction

        An application registration file defines information about an application that is required by the application launcher or system shell. This includes the application’s name, UID and properties. Other information required by the shell, for instance the icons and captions, is defined separately; the location of the icon/caption definitions is provided in the registration file. Before v8.1, all of this information was provided by aif files. In v8.1, both aif files and registration files are supported, but from v9.0 onwards, only registration files are supported.

        - Registration files -

        This diagram shows:

        A registration file is required by every application, even if it has default properties, icons and caption. Minimally, it must specify the application's UID and the name of the application’s executable.

        For an example, see An example registration file and icon/caption file.

        Registration information

        A registration file defines the following non-localisable application information; in other words, information that never varies according to the phone’s language setting:

        • the application’s properties, such as whether it is embeddable or hidden,

        • a group name; this may be used to categorize applications. Note that a group name may also be defined in the localisable file. If so, the localisable version will take precedence.

        • a number which identifies the screen on which the application is displayed (if the phone has multiple screens).

        • the MIME types supported by the application, and the priority of support for each,

        • a list of files owned by the application,

        • a flag that identifies non-standard types of application,

        • for server applications only, a list of the services provided.

        All of these properties are defined using an APP_REGISTRATION_INFO resource struct. See its declaration in AppInfo.rh for the default values. For more information about these properties, see Defining application icons, captions and properties.

        Most applications also need to define localisable information, for instance non-default captions and icons and possibly a group name (described above). The registration file specifies its location. This can be done in one of two ways:

        • as the name and path (excluding drive letter and extension) of a localisable icon/caption definition file,

        • as the ID of a LOCALISABLE_APP_INFO resource struct defined in the application’s UI resource file. In this case, the name and path of the application’s UI resource file (excluding drive letter and extension) must also be provided.

        \ No newline at end of file + + + + + +Application registration files
        Introduction

        An application registration file defines information about an application that is required by the application launcher or system shell. This includes the application’s name, UID and properties. Other information required by the shell, for instance the icons and captions, is defined separately; the location of the icon/caption definitions is provided in the registration file. Before v8.1, all of this information was provided by aif files. In v8.1, both aif files and registration files are supported, but from v9.0 onwards, only registration files are supported.

        + Registration files +

        This diagram shows:

        A registration file is required by every application, even if it has default properties, icons and caption. Minimally, it must specify the application's UID and the name of the application’s executable.

        For an example, see An example registration file and icon/caption file.

        Registration information

        A registration file defines the following non-localisable application information; in other words, information that never varies according to the phone’s language setting:

        • the application’s properties, such as whether it is embeddable or hidden,

        • a group name; this may be used to categorize applications. Note that a group name may also be defined in the localisable file. If so, the localisable version will take precedence.

        • a number which identifies the screen on which the application is displayed (if the phone has multiple screens).

        • the MIME types supported by the application, and the priority of support for each,

        • a list of files owned by the application,

        • a flag that identifies non-standard types of application,

        • for server applications only, a list of the services provided.

        All of these properties are defined using an APP_REGISTRATION_INFO resource struct. See its declaration in AppInfo.rh for the default values. For more information about these properties, see Defining application icons, captions and properties.

        Most applications also need to define localisable information, for instance non-default captions and icons and possibly a group name (described above). The registration file specifies its location. This can be done in one of two ways:

        • as the name and path (excluding drive letter and extension) of a localisable icon/caption definition file,

        • as the ID of a LOCALISABLE_APP_INFO resource struct defined in the application’s UI resource file. In this case, the name and path of the application’s UI resource file (excluding drive letter and extension) must also be provided.

        \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1C14ECA4-057B-5591-A8E3-F7DB0325E5AE_d0e215643_href.png Binary file Symbian3/SDK/Source/GUID-1C14ECA4-057B-5591-A8E3-F7DB0325E5AE_d0e215643_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1C14ECA4-057B-5591-A8E3-F7DB0325E5AE_d0e219380_href.png Binary file Symbian3/SDK/Source/GUID-1C14ECA4-057B-5591-A8E3-F7DB0325E5AE_d0e219380_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1C499E7D-8099-5BE4-AE46-6143388E6ACB.dita --- a/Symbian3/SDK/Source/GUID-1C499E7D-8099-5BE4-AE46-6143388E6ACB.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-1C499E7D-8099-5BE4-AE46-6143388E6ACB.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,56 +1,56 @@ - - - - - -Audio Input Streaming Tutorial

        This tutorial describes how to use Audio Input Streaming.

        Purpose

        The purpose of this tutorial is to show you how to open, read and then close an audio input stream.

        Required Background

        The Audio Input Streaming Overview provides an introduction to Audio Input Streaming.

        Introduction

        The audio input stream interface class, CMdaAudioInputStream, enables MMF client applications to:

        • stream audio data from the low level audio controller (which has collected it from a hardware device, such as a microphone) to specified buffers (record audio).

        • specify the priority of the audio stream relative to other clients trying to use the same audio hardware

        • set the sample rate and the number of channels to use for recording.

        • change the gain and channel balance of the input stream.

        The low level audio controller stores the audio data in buffers. CMdaAudioInputStream reads these buffers incrementally and does not have to wait until capture is complete.

        Using Audio Input Streaming

        Typically, using an audio input stream involves the following steps as shown in the sequence diagram below:

        The following tasks will be covered in this tutorial:

        • Constructing an audio input stream

        • Opening an audio input stream

        • Getting and setting the stream properties

        • Reading an audio input stream

        • Stopping an audio input stream

        Basic Procedure to Construct an Audio Input Stream

        The high level step to construct an audio input stream is shown here:

        • The client application creates an audio input stream object using the static function CMdaAudioInputStream::NewL(). The input stream class provides two versions of the constructor: one with the default priority and preferences, and another with specified priority and preferences. The client application must also implement the observer class MMdaAudioInputStreamCallback to notify it about audio input streaming progress.

          The following code constructs an audio input stream:

          CMdaAudioInputStream* aInputStream; -aInputStream = CMdaAudioInputStream::NewL(aCallback, EMdaPriorityNormal, EMdaPriorityPreferenceTimeAndQuality);

          where, aCallback is an MMdaAudioInputStreamCallback object.

        Basic Procedure to Open an Audio Input Stream

        The high level steps to open an audio input stream are shown here:

        1. To open an input stream, use the Open() member function, which provides a pointer to the TMdaPackage object with the required audio settings. You can also open the stream without the audio settings. For example:

          aInputStream->Open(NULL);

        2. Once the stream is open, a MMdaAudioInputStreamCallback::MaiscOpenComplete() is issued to indicate that the stream is ready for use.

          void CIOStreamAudio::MaiscOpenComplete(TInt aError) - { - ASSERT(iState==EStateOpeningInput); - if (aError!=KErrNone) - { - Complete(aError); - } - else - { - iMainBuffer.Zero(); - iState = EStateReading; - ReadNextBlock(KNullDesC8); // kick off a new read - KNullDesC8 for first buffer - } - }

        Basic Procedure to Get and Set Stream Properties

        The high level steps to get and set stream properties are shown here:

        1. To set the sampling rate and number of audio channels, use the SetAudioPropertiesL() member function. You can do this only if the stream is open and if data is not being streamed. Values must be specified as enum values. For example, TMdaAudioDataSettings::ESampleRate8000Hz and not 8000 (Hz). The following code sets the sampling rate to 8000Hz and audio channel to mono:

          aInputStream->SetAudioPropertiesL(TMdaAudioDataSettings::ESampleRate8000Hz,TMdaAudioDataSettings::EChannelsMono));

        2. The Gain() and GetBalanceL() member functions let you determine the current gain and balance settings.

        3. The SetGain() and SetBalanceL() member functions let you set the gain and balance respectively. You can use them while the stream is open, with the new settings taking immediate effect.

        Basic Procedure to Read an Audio Input Stream

        The high level steps to read an audio input stream are shown here:

        1. To record the audio stream, use the ReadL() member function, specifying the buffer to use. The first ReadL() after a successful Open(), starts audio recording. Once the buffer is successfully recorded, a pointer to it is returned by MMdaAudioInputStreamCallback::MaiscBufferCopied() callback.

          void CIOStreamAudio::MaiscBufferCopied(TInt aError, const TDesC8& aBuffer) - { - ASSERT(iState==EStateReading); - if (aError!=KErrNone) - { - if (aError!=KErrAbort) // aborts happen on Stop as buffers are recovered, need to ignore - { - Complete(aError); - } - } - else - { - ReadNextBlock(aBuffer); - } - }

        2. The following code reads the next audio block into the buffer in an array of descriptors:

          void CIOStreamAudio::ReadNextBlock(const TDesC8& aBuffer) - { - ASSERT(iState==EStateReading); - // buffer will be tail of iMainBuffer. Shift latter's length and get the next bit - TInt lengthRecorded = iMainBuffer.Length()+aBuffer.Length(); - iMainBuffer.SetLength(lengthRecorded); - iBufferPtr.Set(const_cast<TUint8*>(iMainBuffer.Ptr())+lengthRecorded, 0, iMainBuffer.MaxLength()-lengthRecorded); - TRAPD(error, iInputStream->ReadL(iBufferPtr)); - if (error!=KErrNone) - { - Complete(error); - } - }

        Basic Procedure to Stop an Audio Input Stream

        The high level steps to stop an audio input stream are shown here:

        • To stop recording the audio stream, use the Stop() member function. Two callbacks are issued after a Stop().

          1. An MMdaAudioInputStreamCallback::MaiscBufferCopied() pointing to a buffer that contains the last of the recorded audio data (and an aError value of KErrAbort).

          2. An MMdaAudioInputStreamCallback::MaiscRecordComplete(), indicating successful closure of the audio stream.

            void CIOStreamAudio::MaiscRecordComplete(TInt aError) - { - ASSERT(iState==EStateReading && aError!=KErrNone); - Complete(aError); + + + + + +Audio Input Streaming Tutorial

            This tutorial describes how to use Audio Input Streaming.

            Purpose

            The purpose of this tutorial is to show you how to open, read and then close an audio input stream.

            Required Background

            The Audio Input Streaming Overview provides an introduction to Audio Input Streaming.

            Introduction

            The audio input stream interface class, CMdaAudioInputStream, enables MMF client applications to:

            • stream audio data from the low level audio controller (which has collected it from a hardware device, such as a microphone) to specified buffers (record audio).

            • specify the priority of the audio stream relative to other clients trying to use the same audio hardware

            • set the sample rate and the number of channels to use for recording.

            • change the gain and channel balance of the input stream.

            The low level audio controller stores the audio data in buffers. CMdaAudioInputStream reads these buffers incrementally and does not have to wait until capture is complete.

            Using Audio Input Streaming

            Typically, using an audio input stream involves the following steps as shown in the sequence diagram below:

            The following tasks will be covered in this tutorial:

            • Constructing an audio input stream

            • Opening an audio input stream

            • Getting and setting the stream properties

            • Reading an audio input stream

            • Stopping an audio input stream

            Basic Procedure to Construct an Audio Input Stream

            The high level step to construct an audio input stream is shown here:

            • The client application creates an audio input stream object using the static function CMdaAudioInputStream::NewL(). The input stream class provides two versions of the constructor: one with the default priority and preferences, and another with specified priority and preferences. The client application must also implement the observer class MMdaAudioInputStreamCallback to notify it about audio input streaming progress.

              The following code constructs an audio input stream:

              CMdaAudioInputStream* aInputStream; +aInputStream = CMdaAudioInputStream::NewL(aCallback, EMdaPriorityNormal, EMdaPriorityPreferenceTimeAndQuality);

              where, aCallback is an MMdaAudioInputStreamCallback object.

            Basic Procedure to Open an Audio Input Stream

            The high level steps to open an audio input stream are shown here:

            1. To open an input stream, use the Open() member function, which provides a pointer to the TMdaPackage object with the required audio settings. You can also open the stream without the audio settings. For example:

              aInputStream->Open(NULL);

            2. Once the stream is open, a MMdaAudioInputStreamCallback::MaiscOpenComplete() is issued to indicate that the stream is ready for use.

              void CIOStreamAudio::MaiscOpenComplete(TInt aError) + { + ASSERT(iState==EStateOpeningInput); + if (aError!=KErrNone) + { + Complete(aError); + } + else + { + iMainBuffer.Zero(); + iState = EStateReading; + ReadNextBlock(KNullDesC8); // kick off a new read - KNullDesC8 for first buffer + } + }

            Basic Procedure to Get and Set Stream Properties

            The high level steps to get and set stream properties are shown here:

            1. To set the sampling rate and number of audio channels, use the SetAudioPropertiesL() member function. You can do this only if the stream is open and if data is not being streamed. Values must be specified as enum values. For example, TMdaAudioDataSettings::ESampleRate8000Hz and not 8000 (Hz). The following code sets the sampling rate to 8000Hz and audio channel to mono:

              aInputStream->SetAudioPropertiesL(TMdaAudioDataSettings::ESampleRate8000Hz,TMdaAudioDataSettings::EChannelsMono));

            2. The Gain() and GetBalanceL() member functions let you determine the current gain and balance settings.

            3. The SetGain() and SetBalanceL() member functions let you set the gain and balance respectively. You can use them while the stream is open, with the new settings taking immediate effect.

            Basic Procedure to Read an Audio Input Stream

            The high level steps to read an audio input stream are shown here:

            1. To record the audio stream, use the ReadL() member function, specifying the buffer to use. The first ReadL() after a successful Open(), starts audio recording. Once the buffer is successfully recorded, a pointer to it is returned by MMdaAudioInputStreamCallback::MaiscBufferCopied() callback.

              void CIOStreamAudio::MaiscBufferCopied(TInt aError, const TDesC8& aBuffer) + { + ASSERT(iState==EStateReading); + if (aError!=KErrNone) + { + if (aError!=KErrAbort) // aborts happen on Stop as buffers are recovered, need to ignore + { + Complete(aError); + } + } + else + { + ReadNextBlock(aBuffer); + } + }

            2. The following code reads the next audio block into the buffer in an array of descriptors:

              void CIOStreamAudio::ReadNextBlock(const TDesC8& aBuffer) + { + ASSERT(iState==EStateReading); + // buffer will be tail of iMainBuffer. Shift latter's length and get the next bit + TInt lengthRecorded = iMainBuffer.Length()+aBuffer.Length(); + iMainBuffer.SetLength(lengthRecorded); + iBufferPtr.Set(const_cast<TUint8*>(iMainBuffer.Ptr())+lengthRecorded, 0, iMainBuffer.MaxLength()-lengthRecorded); + TRAPD(error, iInputStream->ReadL(iBufferPtr)); + if (error!=KErrNone) + { + Complete(error); + } + }

            Basic Procedure to Stop an Audio Input Stream

            The high level steps to stop an audio input stream are shown here:

            • To stop recording the audio stream, use the Stop() member function. Two callbacks are issued after a Stop().

              1. An MMdaAudioInputStreamCallback::MaiscBufferCopied() pointing to a buffer that contains the last of the recorded audio data (and an aError value of KErrAbort).

              2. An MMdaAudioInputStreamCallback::MaiscRecordComplete(), indicating successful closure of the audio stream.

                void CIOStreamAudio::MaiscRecordComplete(TInt aError) + { + ASSERT(iState==EStateReading && aError!=KErrNone); + Complete(aError); }
            See Also

            Audio Output Streaming Tutorial

            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1C802DBD-1453-5C69-94D5-FB0229C544D6.dita --- a/Symbian3/SDK/Source/GUID-1C802DBD-1453-5C69-94D5-FB0229C544D6.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-1C802DBD-1453-5C69-94D5-FB0229C544D6.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,58 +1,58 @@ - - - - - -Uikon -Overview -
            Purpose

            Provides a framework for applications. -The framework is fundamental to all GUI applications.

            -
            Architectural relationships

            Uikon provides a UI -library layer. It was designed to allow further higher level UI libraries -to be added that can include controls that derive from the ones provided by -Uikon. Avkon provides these higher level UI libraries in Symbian^3 and historically -in the S60 platform. Application developers can use the Uikon APIs directly, -though they should check that there is not a more appropriate Avkon API.

            The -Uikon application framework extends two lower frameworks:

              -

            • the Application Architecture -Framework: handles application start-up and accessing the application data -(its document).

              • -

            • UI Control Framework: -provides the framework for drawing and handling input to screen controls

              • -

            Uikon ties these two frameworks together to provide the framework -for the standard application design.

            Uikon's framework classes are -extended in turn by:

              -

            • applications, to implement -appropriate behaviour for their type of data, and for their types of command

              • -

            • possibly by UI variant-specific -libraries, to add UI variant-specific behaviour to the application framework

              • -
            -
            Description

            The API has five key concepts: application -(CEikApplication), document (CEikDocument), -app UI (CEikAppUi), UI Environment (CEikonEnv), -and utilities (EikFileUtils).

            Application

            The application class defines properties of the application, such as UID -and caption, and creates a new document.

            The application base class -is provided by CEikApplication.

            Document

            The document class represents the data model for -the application. In file-based applications, it stores and restores the application's -data. It handles requests to edit a document by creating an app UI.

            The -document base class is provided by CEikDocument.

            App UI

            The app UI is the central user interface class. It -creates and owns controls to display the application data, and centralises -handling of command input from standard controls such as menus and toolbars.

            The -app UI base class is provided by CEikAppUi, which can be -customised by using the resource structure EIK_APP_INFO.

            UI Environment

            The UI Environment provides a large number -of assorted UI functionality, particularly simple access to information and -query dialogs, and access to standard system UI resources (bitmaps and fonts). -Every object in a GUI application can access a UI Environment (through CEikonEnv::Static()), -as a pointer to it is stored in thread-local storage.

            The UI Environment -is provided by CEikonEnv.

            Utilities

            Utility classes provide easy access for applications -to frequently-used functionality. Notable are EikFileUtils for -file access, and EikResourceUtils for resource access.

            -
            See also

            UI -Control Framework Overview

            + + + + + +Uikon +Overview +
            Purpose

            Provides a framework for applications. +The framework is fundamental to all GUI applications.

            +
            Architectural relationships

            Uikon provides a UI +library layer. It was designed to allow further higher level UI libraries +to be added that can include controls that derive from the ones provided by +Uikon. Avkon provides these higher level UI libraries in Symbian^3 and historically +in the S60 platform. Application developers can use the Uikon APIs directly, +though they should check that there is not a more appropriate Avkon API.

            The +Uikon application framework extends two lower frameworks:

              +

            • the Application Architecture +Framework: handles application start-up and accessing the application data +(its document).

              • +

            • UI Control Framework: +provides the framework for drawing and handling input to screen controls

              • +

            Uikon ties these two frameworks together to provide the framework +for the standard application design.

            Uikon's framework classes are +extended in turn by:

              +

            • applications, to implement +appropriate behaviour for their type of data, and for their types of command

              • +

            • possibly by UI variant-specific +libraries, to add UI variant-specific behaviour to the application framework

              • +
            +
            Description

            The API has five key concepts: application +(CEikApplication), document (CEikDocument), +app UI (CEikAppUi), UI Environment (CEikonEnv), +and utilities (EikFileUtils).

            Application

            The application class defines properties of the application, such as UID +and caption, and creates a new document.

            The application base class +is provided by CEikApplication.

            Document

            The document class represents the data model for +the application. In file-based applications, it stores and restores the application's +data. It handles requests to edit a document by creating an app UI.

            The +document base class is provided by CEikDocument.

            App UI

            The app UI is the central user interface class. It +creates and owns controls to display the application data, and centralises +handling of command input from standard controls such as menus and toolbars.

            The +app UI base class is provided by CEikAppUi, which can be +customised by using the resource structure EIK_APP_INFO.

            UI Environment

            The UI Environment provides a large number +of assorted UI functionality, particularly simple access to information and +query dialogs, and access to standard system UI resources (bitmaps and fonts). +Every object in a GUI application can access a UI Environment (through CEikonEnv::Static()), +as a pointer to it is stored in thread-local storage.

            The UI Environment +is provided by CEikonEnv.

            Utilities

            Utility classes provide easy access for applications +to frequently-used functionality. Notable are EikFileUtils for +file access, and EikResourceUtils for resource access.

            +
            See also

            UI +Control Framework Overview

            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1CB7491C-1207-5C2E-979F-8ABEB95EE9D9.dita --- a/Symbian3/SDK/Source/GUID-1CB7491C-1207-5C2E-979F-8ABEB95EE9D9.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-1CB7491C-1207-5C2E-979F-8ABEB95EE9D9.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,41 +1,41 @@ - - - - - -XML -DOM Engine Node ReferenceThis topic lists the node classes of the XML DOM Engine. -

            The following diagram describes all the node classes of the XML -DOM Engine. Refer to the links below for more information about each class.

            - XML DOM Engine classes - -
              -

            • RXmlEngDocument

              • -

            • TXmlEngElement

              • -

            • TXmlEngAttr

              • -

            • TTextXmlEngNode

              • -

            • TXmlEngComment

              • -

            • TXmlEngEntityReference

              • -

            • TXmlEngCharacterData

              • -

            • TXmlEngProcessingInstruction

              • -

            • TXmlEngCDATASection

              • -

            • TXmlEngDocumentFragment

              • -

            • TXmlEngNamespace

              • -

            • RXmlEngNodeList <T>

              • -

            • RXmlEngDOMImplementation

              • -

            • TXmlEngDataContainer

              • -

            • TXmlEngFileContainer

              • -

            • TXmlEngChunkContainer

              • -
            -             -XML DOM Engine -Overview -Implementation -of W3C Types + + + + + +XML +DOM Engine Node ReferenceThis topic lists the node classes of the XML DOM Engine. +

            The following diagram describes all the node classes of the XML +DOM Engine. Refer to the links below for more information about each class.

            + XML DOM Engine classes + +
              +

            • RXmlEngDocument

              • +

            • TXmlEngElement

              • +

            • TXmlEngAttr

              • +

            • TTextXmlEngNode

              • +

            • TXmlEngComment

              • +

            • TXmlEngEntityReference

              • +

            • TXmlEngCharacterData

              • +

            • TXmlEngProcessingInstruction

              • +

            • TXmlEngCDATASection

              • +

            • TXmlEngDocumentFragment

              • +

            • TXmlEngNamespace

              • +

            • RXmlEngNodeList <T>

              • +

            • RXmlEngDOMImplementation

              • +

            • TXmlEngDataContainer

              • +

            • TXmlEngFileContainer

              • +

            • TXmlEngChunkContainer

              • +
            +             +XML DOM Engine +Overview +Implementation +of W3C Types             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1CC6FEF0-7D1E-5329-8276-22ACFE3DE362.dita --- a/Symbian3/SDK/Source/GUID-1CC6FEF0-7D1E-5329-8276-22ACFE3DE362.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-1CC6FEF0-7D1E-5329-8276-22ACFE3DE362.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,60 +1,60 @@ - - - - - -Subsessions -within a sessionDescribes subsessions within a session. -

            Once a client has established a session with a server, it can then establish -a number of subsessions with that server. Each subsession represents an independent -channel of communication within the current session.

            -

            Subsessions are useful if a single client needs to establish many channels -of communication with the server. This is because subsessions have a much -lower overhead than a full session. The main cost of a subsession is slightly -increased programming complexity on the server side.

            -

            The main points are:

            -
              -

            • the client has an RSubSessionBase handle -to the subsession

              • -

            • the server uses a CObject derived -class to represent the subsession.

              • -
            -

            As a subsession is always referenced by a handle on the client side, the -corresponding subsession object on the server side must generate a handle.

            -

            For ordinary sessions, the generation of handles is done by the server -framework.

            -

            For subsessions, server side code must be explicitly written to do this. -The CObject class and its associated container (CObjectCon) -and index (CObjectIx) classes provide the behaviour to achieve -this.

            -
            Server side requirements

            Each subsession is represented -by an instance of a CObject derived class.

            Subsession -objects must be held in an object container, an instance of CObjectCon. -This means that the server 's CServer2 derived class must -construct and maintain a CObjectCon object.

            Object -containers are constructed by and held in an object container index, an instance -of a CObjectConIx. This means that the server 's CServer2 derived -class must construct and maintain a CObjectConIx object.

            A -unique handle number for a subsession object is generated when the subsession -object is added to an object index, an instance of a CObjectIx. -This means that the server's CServer2 derived class must -construct and maintain a CObjectIx object.

            The handle -number is a combination of a unique id assigned to the object's container -and a number generated by the object index.

            - -

            Subsession within a session

            -
            -
            Note
              -

            • Depending on the purpose -of the server, more than one object container (a CObjectCon) -and more than one object index (a CObjectIx) may be used. -However, the server must have one and only one object container index -(a CObjectConIx) from which all object containers are generated.

              • -
            + + + + + +Subsessions +within a sessionDescribes subsessions within a session. +

            Once a client has established a session with a server, it can then establish +a number of subsessions with that server. Each subsession represents an independent +channel of communication within the current session.

            +

            Subsessions are useful if a single client needs to establish many channels +of communication with the server. This is because subsessions have a much +lower overhead than a full session. The main cost of a subsession is slightly +increased programming complexity on the server side.

            +

            The main points are:

            +
              +

            • the client has an RSubSessionBase handle +to the subsession

              • +

            • the server uses a CObject derived +class to represent the subsession.

              • +
            +

            As a subsession is always referenced by a handle on the client side, the +corresponding subsession object on the server side must generate a handle.

            +

            For ordinary sessions, the generation of handles is done by the server +framework.

            +

            For subsessions, server side code must be explicitly written to do this. +The CObject class and its associated container (CObjectCon) +and index (CObjectIx) classes provide the behaviour to achieve +this.

            +
            Server side requirements

            Each subsession is represented +by an instance of a CObject derived class.

            Subsession +objects must be held in an object container, an instance of CObjectCon. +This means that the server 's CServer2 derived class must +construct and maintain a CObjectCon object.

            Object +containers are constructed by and held in an object container index, an instance +of a CObjectConIx. This means that the server 's CServer2 derived +class must construct and maintain a CObjectConIx object.

            A +unique handle number for a subsession object is generated when the subsession +object is added to an object index, an instance of a CObjectIx. +This means that the server's CServer2 derived class must +construct and maintain a CObjectIx object.

            The handle +number is a combination of a unique id assigned to the object's container +and a number generated by the object index.

            + +

            Subsession within a session

            +
            +
            Note
              +

            • Depending on the purpose +of the server, more than one object container (a CObjectCon) +and more than one object index (a CObjectIx) may be used. +However, the server must have one and only one object container index +(a CObjectConIx) from which all object containers are generated.

              • +
             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1D35F788-A470-5269-93E0-7C33A0013489.dita --- a/Symbian3/SDK/Source/GUID-1D35F788-A470-5269-93E0-7C33A0013489.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-1D35F788-A470-5269-93E0-7C33A0013489.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,23 +1,23 @@ - - - - - -Creating a Table This tutorial shows you how to create a Symbian SQL table.

            This tutorial uses code from the Basic SQL example application.

            Assumptions

            You have a database. The database has no tables and therefore no data.

            SQL statements

            The following SQL statements are used for this example:

            CREATE TABLE Pets( person TEXT, cat SMALLINT, dog SMALLINT, rodent SMALLINT, bird SMALLINT)

            The RSqlDatabase::Exec function provides a mechanism for executing Symbian SQL statements.

            Create a table The steps required to create a table are shown here: Declare a constant to hold the table handle: _LIT(KTabCreate,"CREATE TABLE Pets( person TEXT, cat SMALLINT, dog SMALLINT, rodent SMALLINT, bird SMALLINT);"); KTabCreate will be used later by the SQL EXECUTE command. Instantiate the required objects: RSqlDatabase db; -CConsoleBase* iConsole; This creates an RSqlDatabase object, which is needed to execute the SQL statement. Execute the SQL statement: db.Exec(KTabCreate) This will execute the SQL statement to create the table. The table now exists and you can begin adding data to it.

            Your database now has at least one table. You can begin to add data to the table and you can query and edit it.

            Create table example

            The following code snippet is from the example used for this tutorial:

            _LIT(KTabCreate,"CREATE TABLE Pets( person TEXT, cat SMALLINT, dog SMALLINT, rodent SMALLINT, bird SMALLINT);"); -_LIT(KCreateTable,"\nCreating a table\n"); -... -CConsoleBase* iConsole; -... -RSqlDatabase db; -iConsole->Printf(KCreateTable); -... -User::LeaveIfError(db.Exec(KTabCreate)); -...

            Now that you have created a table you need to populate it with some data. The following tasks will show you how to populate a table:

            • Querying Databases: Basic

            • Inserting Data into a Table

            • Writing from a Data Stream

            SQL Overview Basic SQL Example + + + + + +Creating a Table This tutorial shows you how to create a Symbian SQL table.

            This tutorial uses code from the Basic SQL example application.

            Assumptions

            You have a database. The database has no tables and therefore no data.

            SQL statements

            The following SQL statements are used for this example:

            CREATE TABLE Pets( person TEXT, cat SMALLINT, dog SMALLINT, rodent SMALLINT, bird SMALLINT)

            The RSqlDatabase::Exec function provides a mechanism for executing Symbian SQL statements.

            Create a table The steps required to create a table are shown here: Declare a constant to hold the table handle: _LIT(KTabCreate,"CREATE TABLE Pets( person TEXT, cat SMALLINT, dog SMALLINT, rodent SMALLINT, bird SMALLINT);"); KTabCreate will be used later by the SQL EXECUTE command. Instantiate the required objects: RSqlDatabase db; +CConsoleBase* iConsole; This creates an RSqlDatabase object, which is needed to execute the SQL statement. Execute the SQL statement: db.Exec(KTabCreate) This will execute the SQL statement to create the table. The table now exists and you can begin adding data to it.

            Your database now has at least one table. You can begin to add data to the table and you can query and edit it.

            Create table example

            The following code snippet is from the example used for this tutorial:

            _LIT(KTabCreate,"CREATE TABLE Pets( person TEXT, cat SMALLINT, dog SMALLINT, rodent SMALLINT, bird SMALLINT);"); +_LIT(KCreateTable,"\nCreating a table\n"); +... +CConsoleBase* iConsole; +... +RSqlDatabase db; +iConsole->Printf(KCreateTable); +... +User::LeaveIfError(db.Exec(KTabCreate)); +...

            Now that you have created a table you need to populate it with some data. The following tasks will show you how to populate a table:

            • Querying Databases: Basic

            • Inserting Data into a Table

            • Writing from a Data Stream

            SQL Overview Basic SQL Example Application             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1D399C05-6CC0-4781-A6E1-1C94CFF8995B-master.png Binary file Symbian3/SDK/Source/GUID-1D399C05-6CC0-4781-A6E1-1C94CFF8995B-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1D399C05-6CC0-4781-A6E1-1C94CFF8995B_d0e63101_href.png Binary file Symbian3/SDK/Source/GUID-1D399C05-6CC0-4781-A6E1-1C94CFF8995B_d0e63101_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1D399C05-6CC0-4781-A6E1-1C94CFF8995B_d0e67264_href.png Binary file Symbian3/SDK/Source/GUID-1D399C05-6CC0-4781-A6E1-1C94CFF8995B_d0e67264_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1D60BB43-4FF8-5632-A597-0DF00234F93E.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-1D60BB43-4FF8-5632-A597-0DF00234F93E.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,36 @@ + + + + + +Finding +the cryptographic strength +

            The TCrypto class enables the user software to find +out the strength of a Cryptography library. The example below illustrates +how:

            + +// 1. Get the cryptography strength. + +TCrypto::TStrength strength = TCrypto::Strength(); + + +// 2. Determine the cryptographic strength. + +switch (strength) + { + case TCrypto::EWeak: + // Using 56 bit key strength. + break; + case TCrypto::EStrong: + // Using 512 bit key strength. + break; + default: + } + +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1DDFFB60-BBA8-500E-A9B1-F048EE5BFBD0_d0e189660_href.png Binary file Symbian3/SDK/Source/GUID-1DDFFB60-BBA8-500E-A9B1-F048EE5BFBD0_d0e189660_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1DDFFB60-BBA8-500E-A9B1-F048EE5BFBD0_d0e194717_href.png Binary file Symbian3/SDK/Source/GUID-1DDFFB60-BBA8-500E-A9B1-F048EE5BFBD0_d0e194717_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1E1B040A-1C18-4F62-95F9-CE0ECE39C430.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-1E1B040A-1C18-4F62-95F9-CE0ECE39C430.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,13 @@ + + + + + +Cryptography ConceptsThis section provides all the conceptual information about +the Crypto and the different features supported by Crypto. \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1E25EE44-9421-549C-B79E-AEFE87308011_d0e311449_href.png Binary file Symbian3/SDK/Source/GUID-1E25EE44-9421-549C-B79E-AEFE87308011_d0e311449_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1E25EE44-9421-549C-B79E-AEFE87308011_d0e317843_href.png Binary file Symbian3/SDK/Source/GUID-1E25EE44-9421-549C-B79E-AEFE87308011_d0e317843_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1E446762-AFE2-4198-8CD7-8C4466392543.dita --- a/Symbian3/SDK/Source/GUID-1E446762-AFE2-4198-8CD7-8C4466392543.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-1E446762-AFE2-4198-8CD7-8C4466392543.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,30 +1,30 @@ - - - - - -Choice -list API class structure -

            The class structure for the Choice list API consists of the class CAknChoiceList and -observer interface McoeControlObserver. The class structure -is depicted in the figure below.

            - -Choice list API classes - - -

            The CAknChoiceList class provides an interface for controlling -the choice list. You need to create separate instances of this class for each -choice list.

            -

            When you use the choice list component in your application, you must implement -the McoeControlObserver interface. This interface is used -as a callback hook between the client application and the actual choice list. -The client application receives a notification through this interface when -the choice list is closed. This enables you to determine what to do with the -changed selection from the choice list in your client application.

            + + + + + +Choice +list API class structure +

            The class structure for the Choice list API consists of the class CAknChoiceList and +observer interface McoeControlObserver. The class structure +is depicted in the figure below.

            + +Choice list API classes + + +

            The CAknChoiceList class provides an interface for controlling +the choice list. You need to create separate instances of this class for each +choice list.

            +

            When you use the choice list component in your application, you must implement +the McoeControlObserver interface. This interface is used +as a callback hook between the client application and the actual choice list. +The client application receives a notification through this interface when +the choice list is closed. This enables you to determine what to do with the +changed selection from the choice list in your client application.

             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1E4FFC56-8473-4E0A-B2E2-4E8DE8B1D00F.dita --- a/Symbian3/SDK/Source/GUID-1E4FFC56-8473-4E0A-B2E2-4E8DE8B1D00F.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-1E4FFC56-8473-4E0A-B2E2-4E8DE8B1D00F.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,47 +1,47 @@ - - - - - -Increasing -the Priority of a Third-Party ApplicationThis section describes how a third-party application can increase -its OOM priority by using OOM Monitor APIs. -

            Third-party applications -that needs to be running all the time can increase their priority to High from -the default level (Normal). By increasing the priority, applications -can protect itself from being closed by the OOM Monitor. For example:

              -

            • IP Phone application receiving IP calls

              • -

            • Instant Messaging application receiving messages

              • -

            are applications which listens for events from the network all the -time.

             - -Create an OOM Monitor -session -ROomMonitorSession ioomMonitorSession; -CleanUpClosePushL(ioomMonitorSession); -User::LeaveIfError(ioomMonitorSession.Connect()); - - -Set the priority -for the application to High . -iOomMonitorSession.SetOomPriority(ROomMonitorSession::EOomPriorityHigh); -DoCriticalBackgroundProcessingL(); - - -Close the session. -iOomMonitorSession.Close(); - - - -             -OOM Monitor -Priority -OOM Monitor -Reference + + + + + +Increasing +the Priority of a Third-Party ApplicationThis section describes how a third-party application can increase +its OOM priority by using OOM Monitor APIs. +

            Third-party applications +that needs to be running all the time can increase their priority to High from +the default level (Normal). By increasing the priority, applications +can protect itself from being closed by the OOM Monitor. For example:

              +

            • IP Phone application receiving IP calls

              • +

            • Instant Messaging application receiving messages

              • +

            are applications which listens for events from the network all the +time.

             + +Create an OOM Monitor +session +ROomMonitorSession ioomMonitorSession; +CleanUpClosePushL(ioomMonitorSession); +User::LeaveIfError(ioomMonitorSession.Connect()); + + +Set the priority +for the application to High . +iOomMonitorSession.SetOomPriority(ROomMonitorSession::EOomPriorityHigh); +DoCriticalBackgroundProcessingL(); + + +Close the session. +iOomMonitorSession.Close(); + + + +             +OOM Monitor +Priority +OOM Monitor +Reference             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1E87CA7A-9733-58A1-A747-F5F3DE9B64D7.dita --- a/Symbian3/SDK/Source/GUID-1E87CA7A-9733-58A1-A747-F5F3DE9B64D7.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-1E87CA7A-9733-58A1-A747-F5F3DE9B64D7.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,38 +1,40 @@ - - - - - -ControlFramework: -A UI application with a toolbar -
            Description

            This example program creates an application -that uses a single view. It implements the standard classes required by any -application using UI controls. That is, an application, a document, an application -UI and a view.

            A view is a control (derived from CCoeControl) -that displays the application's data on the screen and handles user input. -The pointer and key input is handled by printing to the screen a description -of the key event, or the x,y coordinates of the pointer event.

            The -application and document are implemented minimally. The application UI handles -commands by overriding the CEikAppUi::HandleCommandL() method. -In this example, commands are generated by the toolbar buttons, and are handled -by changing the formatting of the text. The text that is initially displayed -is read from a resource file.

            -
            Download

            Click on the following link to download -the example: ControlFramework.zip

            Click: browse to view the example code.

            -
            Class Summary

            CEikApplication

            CEikDocument

            CEikAppUi

            CCoeControl

            -
            Build

            The Symbian -build process describes how to build an application.

            The ControlFramework -example builds an executable called ControlFramework.exe in -the standard location (\epoc32\release\winscw\ <build_variant> for -CodeWarrior). Either launch the executable itself, or launch the emulator -and then select the ControlFramework application from the Emulator's extras -bar.

            -
            See also

            Using -UI Control Framework (CONE)

            + + + + + +ControlFramework: A UI application with a toolbar +
            Description

            This example program creates an application that uses a single +view. It implements the standard classes required by any application +using UI controls. That is, an application, a document, an application +UI and a view.

            A view is a control (derived from CCoeControl) that displays the application's data on the +screen and handles user input. The pointer and key input is handled +by printing to the screen a description of the key event, or the x,y +coordinates of the pointer event.

            The application and document +are implemented minimally. The application UI handles commands by +overriding the CEikAppUi::HandleCommandL() method. +In this example, commands are generated by the toolbar buttons, and +are handled by changing the formatting of the text. The text that +is initially displayed is read from a resource file.

            +
            Download

            Click on the following link to download the example: ControlFramework.zip

            Click: browse to view the example code.

            +
            Class +Summary
              +

            • CEikApplication

              • +

            • CEikDocument

              • +

            • CEikAppUi

              • +

            • CCoeControl

              • +
            +
            Build

            The Symbian +build process describes how to build an application.

            The ControlFramework example builds an executable called ControlFramework.exe in the standard location (\epoc32\release\winscw\ <build_variant> for +CodeWarrior). Either launch the executable itself, or launch the emulator +and then select the ControlFramework application from the Emulator's +extras bar.

            +
            See +also

            Using UI Control Framework (CONE)

            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1EB9BF25-DFF4-42CA-926C-D26409A2868E_d0e64452_href.png Binary file Symbian3/SDK/Source/GUID-1EB9BF25-DFF4-42CA-926C-D26409A2868E_d0e64452_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1EB9BF25-DFF4-42CA-926C-D26409A2868E_d0e65079_href.png Binary file Symbian3/SDK/Source/GUID-1EB9BF25-DFF4-42CA-926C-D26409A2868E_d0e65079_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1EC68F99-C383-5D3A-BAE9-52AF530F8445_d0e184889_href.png Binary file Symbian3/SDK/Source/GUID-1EC68F99-C383-5D3A-BAE9-52AF530F8445_d0e184889_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1EC68F99-C383-5D3A-BAE9-52AF530F8445_d0e191485_href.png Binary file Symbian3/SDK/Source/GUID-1EC68F99-C383-5D3A-BAE9-52AF530F8445_d0e191485_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1ECCCAA0-2E27-5E46-968D-4EBC4E5CE259.dita --- a/Symbian3/SDK/Source/GUID-1ECCCAA0-2E27-5E46-968D-4EBC4E5CE259.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,13 +0,0 @@ - - - - - -Application -Framework Example CodeExample code for Application Framework. \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1F7B0EB9-50E9-4C11-B620-18054596F5AD.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-1F7B0EB9-50E9-4C11-B620-18054596F5AD.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,166 @@ + + + + + +Deprecated APIsAll the deprecated APIs in Symbian^3 are listed with the +alternatives provided. These deprecated APIs will be removed from +the future Symbian platform release, so it is recommended to avoid +using these APIs. +

            The following table summarizes the deprecated APIs:

            + + + + +API +Affected headers and libraries +Description + + + + +AVKON UI framework and the following dependant APIs:
              +

            • Phonebook Data Add Edit UI API

              • +

            • Phonebook Data Management API

              • +

            • Speed Dial Utility Control API

              • +

            • Phonebook vCard Import Export API

              • +

            • Phonebook UI Utilities API

              • +

            • Phonebook Thumbnail operation API

              • +

            • Phonebook Fetch UI API

              • +

            • Screensaver API

              • +

            • SendUI API

              • +

            • Notepad Library API

              • +

            • Connection Settings UI API

              • +

            • Landmarks UI Add_Edit API

              • +

            • Landmarks UI selector API

              • +

            • Location Center Registration API

              • +
             +The avkon.lib, commondialogs.lib, and eikcoctl.lib libraries of AVKON UI framework +are affected by this change.

            The following dependant libraries are +also affected by this change:

              +

            • pbkview.lib

              • +

            • pbkeng.lib

              • +

            • bcardeng.lib

              • +

            • spdctrl.lib

              • +

            • sendui.lib

              • +

            • npdlib.lib

              • +

            • cmmanager.lib

              • +

            • eikdlg.lib

              • +

            • commonui.lib

              • +

            • eikctl.lib

              • +

            • uiklaf.lib

              • +

            • eikdlg.lib

              • +

            • aknnotify.lib

              • +

            • lmkcommonui.lib

              • +
             +AVKON UI framework and its dependant APIs have been deprecated. +This is the first step to move to Qt UI framework in the future releases. +It is recommended to start migrating all the existing applications +from AVKON to Qt, so that these applications continue to work on the +future Symbian platform releases. For more information on migrating +to Qt, refer to Qt for Symbian +             + +KLinkLayerOpen and KLinkLayerClosed +nifvar.h and nifman.dll +These constants have been deprecated. The existing applications +will continue to work, but it is recommended that the new applications +use KConnectionUp or KConnectionDown constants (es_sock.h) to indicate the connection +status. + + +KCDCurrentVersion and KCDLatestVersion +commsdat.h, metadatabase.h and commsdat.dll. +These constants were used to retrieve the version information +of a database schema in Comms Database. They have been deprecated +from Symbian^3 onwards as there are two database schemas in Comms +Database. To identify each of these schemas separately, use KCDVersion1_1 and KCDVersion1_2 instead +of the deprecated constants. The existing applications using these +deprecated constants will continue to work on Symbian^3 without any +change. + + +RConnection::DataTransferredRequest(), RConnection::DataTransferredCancel(), RConnection::GetDataSentNotificationRequest(), RConnection::DataSentNotificationCancel(), RConnection::DataReceivedNotificationRequest(), and RConnection::DataReceivedNotificationCancel(). +es_sock.h and esock.dll +All these APIs has been deprecated. To monitor data and handle +data sent/received notifications, use the RSubConnection API instead. All the existing applications continue to work on Symbian^3 +without any changes. For more information on using RSubConnection API, refer to Socket-Server documentation. + + +

            Sub-connection management and monitoring APIs:

              +

            • RConnection::Stop(TSubConnectionUniqueId)

              • +

            • RConnection::Stop(TSubConnectionUniqueId, TConnStopType)

              • +

            • RConnection::ProgressNotification(TSubConnectionUniqueId, +TNifProgressBuf&, TRequestStatus&, TUint)

              • +

            • RConnection::CancelProgressNotification(TSubConnectionUniqueId)

              • +

            • RConnection::Progress(TSubConnectionUniqueId, TNifProgress&)

              • +

            • RConnection::IsSubConnectionActiveRequest()

              • +

            • RConnection::IsSubConnectionActiveCancel()

              • +

            Connection settings access APIs in RConnection:

              +

            • RConnection::GetIntSetting(const TDesC&, TUint32&)

              • +

            • RConnection::GetBoolSetting(const TDesC&, TBool&)

              • +

            • RConnection::GetDesSetting(const TDesC&, TDes8&)

              • +

            • RConnection::GetDesSetting(const TDesC&, TDes16&)

              • +

            • RConnection::GetLongDesSetting(const TDesC& aSettingName, +TDes& aValue)

              • +

            System wide connection management and monitoring APIs:

              +

            • RConnection::EnumerateConnections(TUint& aCount)

              • +

            • RConnection::AllInterfaceNotification(TDes8& aNotification, +TRequestStatus& aStatus)

              • +

            • RConnection::CancelAllInterfaceNotification()

              • +
             +es_sock.h and esocksvr.dll +

            All the sub-connection management and monitoring APIs in +RConnection have been deprecated. Instead of these deprecated APIs, +use the following RSubConnection APIs:

              +

            • RSubConnection::EventNotification(TNotificationEventBuf& +aEventBuffer, TBool aGenericEventsOnly, TRequestStatus& aStatus)

              • +

            • RSubConnection::EventNotification(TNotificationEventBuf& +aEventBuffer, TEventFilter aEventFilterList[], TUint aEventListLength, +TRequestStatus& aStatus)

              • +

            • RSubConnection::CancelEventNotification()

              • +

            • RSubConnection::Stop()

              • +

            For more information on these RSubConnection APIs, refer to Registering for Sub-Connection events: Tutorial

            The +connection settings access APIs in RConnection are +deprecated so you can use RConnection::GetParameters(ESock::CCommsDataObjectBase& +aDataObject) to retrieve the connection settings.

            The system-wide connection management APIs are deprecated so avoid +using it. Instead, use the following RConnectionServ APIs:

              +

            • RConnectionServ::AccessPointStatusQuery(const CConnectionServParameterBundle& +aQuery, CConnectionServParameterBundle& aResult, TRequestStatus& +aStatus)

              • +

            • RConnectionServ::AccessPointNotification(const CConnectionServParameterBundle& +aQuery, MAccessPointNotificationObserver& aObserver)

              • +

            • RConnectionServ::CancelAccessPointNotification()

              • +

            For more information on how to use these APIs, refer to Using a Management +Plane session to receive Access Point notifications: Tutorial.

             +             + +CFbsDevice::CancelSprite(), CFbsDevice::HideSprite(),CFbsDevice::HideSprite(const TRect&, const TRegion*), CFbsDevice::ShowSprite(TSpriteBase*), CFbsDevice::ShowSprite(TSpriteBase*, const TRect&,const TRegion*), CFbsScreenDevice::DrawSpriteBegin(), CFbsScreenDevice::DrawSpriteEnd(), CFbsScreenDevice::CancelSprite(), CFbsScreenDevice::HideSprite(), CFbsScreenDevice::HideSprite(const TRect&,const TRegion*), CFbsScreenDevice::ShowSprite(TSpriteBase*), and CFbsScreenDevice::ShowSprite(TSpriteBase*, const TRect&,const +TRegion*). +bitdev.h +These CFbsDevice and CFbsScreenDevice APIs, which were used internally by the Window Server +for implementing sprites, are deprecated from Symbian^3 onwards. + + + +Flash Viewer Framework API +flash_ui.h and flash2ui.dll +This framework API is deprecated so remove all references to +it. + + +Browser Control API, Browser Plugin API, Download Manager Client +API, Download Manager UI API, Favourites Engine API, and Settings +API +browserengine.lib, browserengine.lib, downloadmgr.lib, downloadmgruilib.lib, and favouritesengine.lib. +All these browser APIs are deprecated, so start using the QTWebKit module instead. + + + +
             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1FC88405-616F-5ED1-A136-9FE1E9226F0E.dita --- a/Symbian3/SDK/Source/GUID-1FC88405-616F-5ED1-A136-9FE1E9226F0E.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-1FC88405-616F-5ED1-A136-9FE1E9226F0E.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,179 +1,179 @@ - - - - - -Exif Utility Library Guide

            Exif (Exchangeable image file format) is a standard specifying rules for storing metadata in digital image files, mainly those using JPEG compression.

            Purpose

            Exif enhances the JPEG and TIFF specifications with the addition of metadata tags to hold information such as the camera settings used to take the picture.

            Exif Overview

            The Exif standard defines a wide range of metadata tags, some of which are listed below:

            • Date and time information of the image captured.

            • Camera settings like camera model and make, and information that varies with each image such as orientation, aperture, shutter speed, focal length, metering mode, and film speed information.

            • A thumbnail for previewing the picture on camera LCD.

            • Copyright information.

            Accessing Exif Metadata

            Access to Exif metadata is provided through an abstract interface available in all the main ICL APIs. This interface can be implemented and managed through an ICL plugin, exhibiting the functionality to the client through the plugin extension mechanism.

            The MExifMetaData class is a generic interface for accessing the Exif metadata. To access a specific item of a metadata, both tag ID and the primary Image File Directory [IFD] number must be provided in the MExifMetaData access method, as some tags may appear in more than one IFD. The primary IFD number may either be 0 or 1. The main image tags are grouped together under IFD 0 and the tags for the thumbnail images are grouped under IFD 1 in the Exif metadata. The tags under these IFD can be further classified into sub IFD:

            For example : Tags related to the GPS can be sorted to form a group.

            The MExifMetaData is compounded by two classes as mentioned below:

            • MExifMetadataReader : This provides more generic functionalitites to read the tags from the Exif Metadata. The user is expected to provide the tag id and the primary IFD for the tags that needs to be read.

            • MExifMetadataWriter : This is a generic way to write or set the tags of the Exif metadata. Here also the user is expected to render the key inputs like tag id and IFD for the data that needs to be written or modified.

            The access provided by MExifMetaData is quite low level. The users are expected to know the tag IDs defined in the Exif specification in order to use it. Hence more user friendly classes as listed below are made available to access these tags.

            Examples

            This section contains code snippets showing how Exif metadata is accessed in several situations.

            JPEG Exif Plugin

            • TExifReaderUtility : This class provides a user friendly interface for reading the metadata in Exif encoded image files. The following example code illustrates its use:

              void CIclExample::AccessToEXIFMetadataL(const TDesC& aFileName) - { - HBufC8* buffer8Bit=NULL; - - // If the image is not recognised or valid then the call will leave with an error - CJPEGExifDecoder* exifdecoder = static_cast<CJPEGExifDecoder*>(CJPEGExifDecoder::FileNewL(iFs, aFileName/*,CImageDecoder::EOptionNone, KNullUid, KNullUid, KUidICLJpegEXIFInterface*/)); - CleanupStack::PushL(exifdecoder); - - // Create a MExifMetadata object and Initializes to metadata associated with the CJPEGExifDecoder - MExifMetadata* metaData=exifdecoder->ExifMetadata(); - - // Create a TExifReaderUtility object and pass the metadata to read it - if(metaData != NULL) - { - TExifReaderUtility reader(metaData); - User::LeaveIfError(reader.GetImageDescription(buffer8Bit)); - } - - delete buffer8Bit; - CleanupStack::PopAndDestroy(exifdecoder); - }

            • TExifWriterUtility : This class provides a user friendly interface for writing the metadata in Exif encoded image files. The following example code illustrates its use:

              void CIclExample::AddEXIFDataToJPEGFileL() -{ - TInt err = KErrNone; - - HBufC8 *encodedImageDescriptor = NULL; - - // Create the encoder, passing a buffer to store the encoded image - CJPEGExifEncoder* exifencoder = static_cast<CJPEGExifEncoder*>(CImageEncoder::DataNewL(encodedImageDescriptor,CImageEncoder::EOptionNone,KImageTypeJPGUid)); - - // Create a MExifMetadata object and initializes to metadata associated with CJPEGExifEncoder - MExifMetadataWriter* metaData=exifencoder->ExifMetadata(); - CleanupStack::PushL(exifencoder); - - // Create a TExifWriterUtility object to write the metadata in to the image - TExifWriterUtility exifWriteUtility(metaData); - - HBufC8* buf8ParamWriteVersion=KBuf8ParamWriteVersion().Alloc(); - - User::LeaveIfError(exifWriteUtility.SetImageDescription(buf8ParamWriteVersion)); - - delete encodedImageDescriptor; - encodedImageDescriptor = NULL; - - delete buf8ParamWriteVersion; - buf8ParamWriteVersion = NULL; - - CleanupStack::PopAndDestroy(exifencoder); - - }

            The access to the Exif metadata in image decoder/encoder will be provided through the MExifMetadata interface. The extended object CJPEGExifDecoder of the public class CImageDecoder provides the mechanism to access the custom Exif interface, by allowing the client to request a reference to the MExifMetadata interface. Once the source image has been set, and the client has acquired a reference to MExifMetadata, the data associated with the Exif tags can be accessed at any time before or after a decoding process has taken place.

            The client can request the main image or the thumbnail image as the source for the decode operation using the function SetImageTypeL(). These are the only arguments SetImageTypeL() will accept. Any other argument provided will cause the function to leave with error KErrArgument. The plugin assumes the main image to be the source unless otherwise specified. The plugin will ignore the function call if the image requested is unavailable.

            imageDecoder->SetImageTypeL(CImageDecoder::EImageTypeThumbnail);

            Unlike decoding, encoding is a one step procedure that requires all the Exif data to be set before the event is initiated. Any unspecified parameters must be populated by the default values. The call to the SetImageTypeL() determines whether an embedded image will be included in the encoded image or not. The client must furnish an optional parameter EImageTypeThumbnail along with the EImageTypeMain included in the bitfield to denote the inclusion of a thumbnail in the encoded image. Any other parameter specified aberrant from this specification will result in the function leaving with KErrArgument error. The thumbnail generated will conform to the DCF standards.

            Exif support in CImageDisplay

            In this scenario, the ExifMetadata() returns a pointer to the object that implements the MExifMetadata interface. The Exif metadata can be extracted, once the source image has been set. This provides a read only access to the metadata. It is illustrated as follows:

            void CIclExample::AccessToEXIFMetadataL(const TDesC& aFileName) - { - HBufC8* buffer8Bit=NULL; - - // Create the decoder, passing in the image memory. The image is recognised by the - // Image Conversion Library, an appropriate codec plugin loaded and the image - // headers parsed. - // If the image is not recognised or valid then the call will leave with an error - CJPEGExifDecoder* exifdecoder = static_cast<CJPEGExifDecoder*>(CJPEGExifDecoder::FileNewL(iFs, aFileName/*,CImageDecoder::EOptionNone, KNullUid, KNullUid, KUidICLJpegEXIFInterface*/)); - CleanupStack::PushL(exifdecoder); - - // Create a MExifMetadata object and Initializes to metadata associated with the CJPEGExifDecoder - MExifMetadata* metaData=exifdecoder->ExifMetadata(); - - // Create a TExifReaderUtility object and pass the metadata to read it - if(metaData != NULL) - { - TExifReaderUtility reader(metaData); - User::LeaveIfError(reader.GetImageDescription(buffer8Bit)); - } - - delete buffer8Bit; - CleanupStack::PopAndDestroy(exifdecoder); - }

            Exif support in CimageTransform

            In this scenario, the ExifMetadata() returns a pointer to the object that implements the MExifMetadata interface. It is illustrated as follows:

            void CIclExample::AddEXIFDataToJPEGFileL() -{ - TInt err = KErrNone; - - HBufC8 *encodedImageDescriptor = NULL; - - // Create the encoder, passing a buffer to store the encoded image - CJPEGExifEncoder* exifencoder = static_cast<CJPEGExifEncoder*>(CImageEncoder::DataNewL(encodedImageDescriptor,CImageEncoder::EOptionNone,KImageTypeJPGUid)); - - // Create a MExifMetadata object and initializes to metadata associated with CJPEGExifEncoder - MExifMetadataWriter* metaData=exifencoder->ExifMetadata(); - CleanupStack::PushL(exifencoder); - - // Create a TExifWriterUtility object to write the metadata in to the image - TExifWriterUtility exifWriteUtility(metaData); - - HBufC8* buf8ParamWriteVersion=KBuf8ParamWriteVersion().Alloc(); - - User::LeaveIfError(exifWriteUtility.SetImageDescription(buf8ParamWriteVersion)); - - delete encodedImageDescriptor; - encodedImageDescriptor = NULL; - - delete buf8ParamWriteVersion; - buf8ParamWriteVersion = NULL; - - CleanupStack::PopAndDestroy(exifencoder); - - }

            The ExifMetadata() provides functions to scale still images. Additionally, it has the ability to scale only a subset of the original image by setting a clipping rectangle. This acts as if the source image outside the region does not exist causing the clipped image to be resized to the size specified.

            Furthermore, a thumbnail can be added to the JPEG file as shown in the code below:

            void CIclExample::AddThumbnailToJPEGFileL(const TDesC& aFileName) - { - TInt err = KErrNone; - TInt soiOffset=0; - TInt thumbnailLength = 0; - TInt size = 0; - Const TInt KConstStartOffset = 12; - HBufC8 *desData= NULL; - - TPtr8 imageFromFilePtr = LoadImageIntoMemoryL(aFileName); - - // Create a CImageTransform object and push it on to the cleanup stack - CImageTransform* imageTransform=CImageTransform::NewL(iFs); - CleanupStack::PushL(imageTransform); - - // Call SetSourceFilenameL() function of CImageTransform to set the source to file - imageTransform->SetSourceFilenameL(aFileName); - - // Call SetDestDataL() function of CImageTransform to set the destination size in pixels - imageTransform->SetDestDataL(desData); - - // Call SetDestSizeInPixelsL() function of CImageTransform to set the destination size in pixels - imageTransform->SetDestSizeInPixelsL(TSize(160, 120), ETrue); - - // Call SetOptionsL() to add the thumbnail - imageTransform->SetOptionsL(CImageTransform::EThumbnail); - - //Call SetupL() to setup the ImageTransform - imageTransform->SetupL(); - - // encode the image - CActiveListener* activeListener = CreateAndInitializeActiveListenerLC(); - imageTransform->Transform(activeListener->iStatus); - CActiveScheduler::Start(); - User::LeaveIfError(activeListener -> iStatus.Int()); - - // Create a CJPEGExifDecoder - CJPEGExifDecoder* exifdecoder = static_cast<CJPEGExifDecoder*>(CJPEGExifDecoder::DataNewL(iFs, imageFromFilePtr)); - CleanupStack::PushL(exifdecoder); - - // Get the thumbnail from the image - MExifMetadata* metaData=exifdecoder->ExifMetadata(); - - // Get the offset to the thumbnail image (i.e. the value of tag 0x0201) - metaData->GetIntegerParam(0x0201, 1, soiOffset); - - // Get the length of the thumbnail image (i.e. the value of tag 0x0202) - metaData->GetIntegerParam(0x0202, 1, thumbnailLength); - - // Add thumbnail to image - RFile file; - file.Open(iFs,KbitmapFile,EFileShareReadersOnly|EFileStream|EFileRead); - CleanupClosePushL(file); - file.Size(size); - - HBufC8* buffer = HBufC8::NewMaxLC(size); - TPtr8 bufferDes(buffer->Des()); - file.Read(bufferDes); - - TPtrC8 thumbnailData = bufferDes.Mid(KConstStartOffset + soiOffset,thumbnailLength); - - // Write thumbnail data to image - User::LeaveIfError(file.Write(thumbnailData)); - - file.Close(); - delete desData; - - CleanupStack::PopAndDestroy(6);// buffer,exifdecoder,activeListener,imageTransform,desData,iImageInMemory + + + + + +Exif Utility Library Guide

            Exif (Exchangeable image file format) is a standard specifying rules for storing metadata in digital image files, mainly those using JPEG compression.

            Purpose

            Exif enhances the JPEG and TIFF specifications with the addition of metadata tags to hold information such as the camera settings used to take the picture.

            Exif Overview

            The Exif standard defines a wide range of metadata tags, some of which are listed below:

            • Date and time information of the image captured.

            • Camera settings like camera model and make, and information that varies with each image such as orientation, aperture, shutter speed, focal length, metering mode, and film speed information.

            • A thumbnail for previewing the picture on camera LCD.

            • Copyright information.

            Accessing Exif Metadata

            Access to Exif metadata is provided through an abstract interface available in all the main ICL APIs. This interface can be implemented and managed through an ICL plugin, exhibiting the functionality to the client through the plugin extension mechanism.

            The MExifMetaData class is a generic interface for accessing the Exif metadata. To access a specific item of a metadata, both tag ID and the primary Image File Directory [IFD] number must be provided in the MExifMetaData access method, as some tags may appear in more than one IFD. The primary IFD number may either be 0 or 1. The main image tags are grouped together under IFD 0 and the tags for the thumbnail images are grouped under IFD 1 in the Exif metadata. The tags under these IFD can be further classified into sub IFD:

            For example : Tags related to the GPS can be sorted to form a group.

            The MExifMetaData is compounded by two classes as mentioned below:

            • MExifMetadataReader : This provides more generic functionalitites to read the tags from the Exif Metadata. The user is expected to provide the tag id and the primary IFD for the tags that needs to be read.

            • MExifMetadataWriter : This is a generic way to write or set the tags of the Exif metadata. Here also the user is expected to render the key inputs like tag id and IFD for the data that needs to be written or modified.

            The access provided by MExifMetaData is quite low level. The users are expected to know the tag IDs defined in the Exif specification in order to use it. Hence more user friendly classes as listed below are made available to access these tags.

            Examples

            This section contains code snippets showing how Exif metadata is accessed in several situations.

            JPEG Exif Plugin

            • TExifReaderUtility : This class provides a user friendly interface for reading the metadata in Exif encoded image files. The following example code illustrates its use:

              void CIclExample::AccessToEXIFMetadataL(const TDesC& aFileName) + { + HBufC8* buffer8Bit=NULL; + + // If the image is not recognised or valid then the call will leave with an error + CJPEGExifDecoder* exifdecoder = static_cast<CJPEGExifDecoder*>(CJPEGExifDecoder::FileNewL(iFs, aFileName/*,CImageDecoder::EOptionNone, KNullUid, KNullUid, KUidICLJpegEXIFInterface*/)); + CleanupStack::PushL(exifdecoder); + + // Create a MExifMetadata object and Initializes to metadata associated with the CJPEGExifDecoder + MExifMetadata* metaData=exifdecoder->ExifMetadata(); + + // Create a TExifReaderUtility object and pass the metadata to read it + if(metaData != NULL) + { + TExifReaderUtility reader(metaData); + User::LeaveIfError(reader.GetImageDescription(buffer8Bit)); + } + + delete buffer8Bit; + CleanupStack::PopAndDestroy(exifdecoder); + }

            • TExifWriterUtility : This class provides a user friendly interface for writing the metadata in Exif encoded image files. The following example code illustrates its use:

              void CIclExample::AddEXIFDataToJPEGFileL() +{ + TInt err = KErrNone; + + HBufC8 *encodedImageDescriptor = NULL; + + // Create the encoder, passing a buffer to store the encoded image + CJPEGExifEncoder* exifencoder = static_cast<CJPEGExifEncoder*>(CImageEncoder::DataNewL(encodedImageDescriptor,CImageEncoder::EOptionNone,KImageTypeJPGUid)); + + // Create a MExifMetadata object and initializes to metadata associated with CJPEGExifEncoder + MExifMetadataWriter* metaData=exifencoder->ExifMetadata(); + CleanupStack::PushL(exifencoder); + + // Create a TExifWriterUtility object to write the metadata in to the image + TExifWriterUtility exifWriteUtility(metaData); + + HBufC8* buf8ParamWriteVersion=KBuf8ParamWriteVersion().Alloc(); + + User::LeaveIfError(exifWriteUtility.SetImageDescription(buf8ParamWriteVersion)); + + delete encodedImageDescriptor; + encodedImageDescriptor = NULL; + + delete buf8ParamWriteVersion; + buf8ParamWriteVersion = NULL; + + CleanupStack::PopAndDestroy(exifencoder); + + }

            The access to the Exif metadata in image decoder/encoder will be provided through the MExifMetadata interface. The extended object CJPEGExifDecoder of the public class CImageDecoder provides the mechanism to access the custom Exif interface, by allowing the client to request a reference to the MExifMetadata interface. Once the source image has been set, and the client has acquired a reference to MExifMetadata, the data associated with the Exif tags can be accessed at any time before or after a decoding process has taken place.

            The client can request the main image or the thumbnail image as the source for the decode operation using the function SetImageTypeL(). These are the only arguments SetImageTypeL() will accept. Any other argument provided will cause the function to leave with error KErrArgument. The plugin assumes the main image to be the source unless otherwise specified. The plugin will ignore the function call if the image requested is unavailable.

            imageDecoder->SetImageTypeL(CImageDecoder::EImageTypeThumbnail);

            Unlike decoding, encoding is a one step procedure that requires all the Exif data to be set before the event is initiated. Any unspecified parameters must be populated by the default values. The call to the SetImageTypeL() determines whether an embedded image will be included in the encoded image or not. The client must furnish an optional parameter EImageTypeThumbnail along with the EImageTypeMain included in the bitfield to denote the inclusion of a thumbnail in the encoded image. Any other parameter specified aberrant from this specification will result in the function leaving with KErrArgument error. The thumbnail generated will conform to the DCF standards.

            Exif support in CImageDisplay

            In this scenario, the ExifMetadata() returns a pointer to the object that implements the MExifMetadata interface. The Exif metadata can be extracted, once the source image has been set. This provides a read only access to the metadata. It is illustrated as follows:

            void CIclExample::AccessToEXIFMetadataL(const TDesC& aFileName) + { + HBufC8* buffer8Bit=NULL; + + // Create the decoder, passing in the image memory. The image is recognised by the + // Image Conversion Library, an appropriate codec plugin loaded and the image + // headers parsed. + // If the image is not recognised or valid then the call will leave with an error + CJPEGExifDecoder* exifdecoder = static_cast<CJPEGExifDecoder*>(CJPEGExifDecoder::FileNewL(iFs, aFileName/*,CImageDecoder::EOptionNone, KNullUid, KNullUid, KUidICLJpegEXIFInterface*/)); + CleanupStack::PushL(exifdecoder); + + // Create a MExifMetadata object and Initializes to metadata associated with the CJPEGExifDecoder + MExifMetadata* metaData=exifdecoder->ExifMetadata(); + + // Create a TExifReaderUtility object and pass the metadata to read it + if(metaData != NULL) + { + TExifReaderUtility reader(metaData); + User::LeaveIfError(reader.GetImageDescription(buffer8Bit)); + } + + delete buffer8Bit; + CleanupStack::PopAndDestroy(exifdecoder); + }

            Exif support in CimageTransform

            In this scenario, the ExifMetadata() returns a pointer to the object that implements the MExifMetadata interface. It is illustrated as follows:

            void CIclExample::AddEXIFDataToJPEGFileL() +{ + TInt err = KErrNone; + + HBufC8 *encodedImageDescriptor = NULL; + + // Create the encoder, passing a buffer to store the encoded image + CJPEGExifEncoder* exifencoder = static_cast<CJPEGExifEncoder*>(CImageEncoder::DataNewL(encodedImageDescriptor,CImageEncoder::EOptionNone,KImageTypeJPGUid)); + + // Create a MExifMetadata object and initializes to metadata associated with CJPEGExifEncoder + MExifMetadataWriter* metaData=exifencoder->ExifMetadata(); + CleanupStack::PushL(exifencoder); + + // Create a TExifWriterUtility object to write the metadata in to the image + TExifWriterUtility exifWriteUtility(metaData); + + HBufC8* buf8ParamWriteVersion=KBuf8ParamWriteVersion().Alloc(); + + User::LeaveIfError(exifWriteUtility.SetImageDescription(buf8ParamWriteVersion)); + + delete encodedImageDescriptor; + encodedImageDescriptor = NULL; + + delete buf8ParamWriteVersion; + buf8ParamWriteVersion = NULL; + + CleanupStack::PopAndDestroy(exifencoder); + + }

            The ExifMetadata() provides functions to scale still images. Additionally, it has the ability to scale only a subset of the original image by setting a clipping rectangle. This acts as if the source image outside the region does not exist causing the clipped image to be resized to the size specified.

            Furthermore, a thumbnail can be added to the JPEG file as shown in the code below:

            void CIclExample::AddThumbnailToJPEGFileL(const TDesC& aFileName) + { + TInt err = KErrNone; + TInt soiOffset=0; + TInt thumbnailLength = 0; + TInt size = 0; + Const TInt KConstStartOffset = 12; + HBufC8 *desData= NULL; + + TPtr8 imageFromFilePtr = LoadImageIntoMemoryL(aFileName); + + // Create a CImageTransform object and push it on to the cleanup stack + CImageTransform* imageTransform=CImageTransform::NewL(iFs); + CleanupStack::PushL(imageTransform); + + // Call SetSourceFilenameL() function of CImageTransform to set the source to file + imageTransform->SetSourceFilenameL(aFileName); + + // Call SetDestDataL() function of CImageTransform to set the destination size in pixels + imageTransform->SetDestDataL(desData); + + // Call SetDestSizeInPixelsL() function of CImageTransform to set the destination size in pixels + imageTransform->SetDestSizeInPixelsL(TSize(160, 120), ETrue); + + // Call SetOptionsL() to add the thumbnail + imageTransform->SetOptionsL(CImageTransform::EThumbnail); + + //Call SetupL() to setup the ImageTransform + imageTransform->SetupL(); + + // encode the image + CActiveListener* activeListener = CreateAndInitializeActiveListenerLC(); + imageTransform->Transform(activeListener->iStatus); + CActiveScheduler::Start(); + User::LeaveIfError(activeListener -> iStatus.Int()); + + // Create a CJPEGExifDecoder + CJPEGExifDecoder* exifdecoder = static_cast<CJPEGExifDecoder*>(CJPEGExifDecoder::DataNewL(iFs, imageFromFilePtr)); + CleanupStack::PushL(exifdecoder); + + // Get the thumbnail from the image + MExifMetadata* metaData=exifdecoder->ExifMetadata(); + + // Get the offset to the thumbnail image (i.e. the value of tag 0x0201) + metaData->GetIntegerParam(0x0201, 1, soiOffset); + + // Get the length of the thumbnail image (i.e. the value of tag 0x0202) + metaData->GetIntegerParam(0x0202, 1, thumbnailLength); + + // Add thumbnail to image + RFile file; + file.Open(iFs,KbitmapFile,EFileShareReadersOnly|EFileStream|EFileRead); + CleanupClosePushL(file); + file.Size(size); + + HBufC8* buffer = HBufC8::NewMaxLC(size); + TPtr8 bufferDes(buffer->Des()); + file.Read(bufferDes); + + TPtrC8 thumbnailData = bufferDes.Mid(KConstStartOffset + soiOffset,thumbnailLength); + + // Write thumbnail data to image + User::LeaveIfError(file.Write(thumbnailData)); + + file.Close(); + delete desData; + + CleanupStack::PopAndDestroy(6);// buffer,exifdecoder,activeListener,imageTransform,desData,iImageInMemory }

            Exif extension to support YUV image format

            An extension to Exif is provided in the ICL to support encoding and decoding uncompressed YUV data images to and from the JPEG data format. The advantage of YUV format over RGB is that it reduces the amount of information required to reproduce a satisfactory video image. This is achieved by some of the components in YUV corresponding to more than one pixel.

            For example, the pixel does not necessarily have its own set of Y,U,V components, but may share the U and V components with other pixels as shown below:

            • YUV 4:4:4 - Each pixel has a Y, U, and V component.

            • YUV 4:2:2 - Each horizontal pair of pixels has a Y component per pixel but only one U and V component per pair.

            • YUV 4:2:0 - Each 2*2 block of pixels has a Y component per pixel but only one U and one V component per block.

            Note: The YUV bitmap layout may differ from the RGB bitmap layout in the sense that the RGB pixel components are rendered in the same buffer as opposed to YUV bitmaps which may have different layouts.

            The conversion between RGB and 4:4:4 YUV is pretty straight forward. The CFbsBitmaps are capable of encapsulating YUV data presented in its basic 4:4:4 YUV interleaved format. However, the existing CFbsBitmap does not support all possible YUV bitmap formats and layouts. This limitation is overcome by the CImageFrame class which allows the image data to be stored in the memory in any format or layout as long as it is uniquely identified. This is achieved by using format code UID's.

            CImageFrame* imageFrame= CImageFrame::NewL(&chunk, imageSizeInBytes, KRChunkSize);
            Exif Utility Overview JPEG Exif Plugin Image Display Image Transformation             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1FCD0312-7B28-47F9-BE54-822B74A8934C.dita --- a/Symbian3/SDK/Source/GUID-1FCD0312-7B28-47F9-BE54-822B74A8934C.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-1FCD0312-7B28-47F9-BE54-822B74A8934C.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,78 +1,78 @@ - - - - - -Designing -applications for touch UI -

            Both touch screens and hybrid devices are supported by Symbian platform. -Touch screen enables direct manipulation of content and objects, allowing -for far more natural interaction with the device. This means a completely -different user experience and interaction style compared to using a hardware -keypad.

            - - - -

            All applications must be touch-enabled, which means that they can be used -with the touch screen alone, regardless of the presence of a keypad. There -are only three mandatory hardware keys in touch devices based -on the Symbian platform - Send, End, and Multi-tasking key.

            -

            The application features must follow the platform support for different -hardware. When designing a touch-enabled Symbian application, the UI must -be designed so that everything can be accomplished by using the touch screen -interface, as the potential target devices may or may not have a hardware -keyboard.

            -

            The touch UI in the Symbian platform is based on the use of resistive and -capacitive touch screens. In resistive touch screen technology, two -conductive and resistive layers are separated by a thin space. When an object -touches this kind of touch panel, the layers are connected at a certain point, -and a touch event is registered. This allows efficient stylus control, in -addition to finger touch - unlike capacitive panels, which usually register -only finger touch. Additionally, resistive touch screen offers a higher resolution -and more durability. In capacitive touch screen technology, the panel -consists of an insulator such as glass, coated with a transparent conductor -(such as indium tin oxide (ITO)). When an object touches the surface of the -screen, it results in a distortion of the local electrostatic field, measurable -as a change in capacitance. Then a touch controller measures the frequency -variations to ascertain the co-ordinates of the object's touch. Capacitive -touch screen supports multi-touch.

            -

            The hardware is supported by various:

            -
              -

            • touch-specific components (see Touch -support for common UI components)

              • -

            • component and UI behavior changes

              • -

            • layout changes, and

              • -

            • additions to the interaction style.

              • -
            -

            The touch UI is designed to enable full task flow with touch, with minimal -need to switch to hardware keys. Thus, the design ensures that users can complete -a task with the chosen interaction method from start to finish.

            -

            While designing and implementing applications for touch screen devices -based on the Symbian platform, consider interactions that benefit the most -from the touch UI.

            -

            If you can apply direct manipulation of the UI, for example when moving -items from one place to another, or scrolling a page, do not confine the user -with unnecessary scrollbars or have the user resort to options list commands.

            -

            Instead, enable the user to view pages larger than a screen by panning -them directly, and dragging and dropping items rather than marking them and -using menu options.

            -
              -

            • Remember that the most intuitive touch screen interactions that can -be performed using a finger are tapping, stroking up/down/left/right, and -the long tap.

              • -

            • Utilize strokes that are easily discovered to the users in the given -context. It should be explicit to the user where strokes can be performed.

              • -

            • Design to ensure that users can complete a task with the same interaction -method from start to finish - touch or hardware keys, stylus, or finger, and -using one hand or both hands.

              • -

            • Aim to optimize system performance and battery consumption to provide -a fluid and reliable touch user experience.

              • -
            -

            See Also:

            + + + + + +Designing +applications for touch UI +

            Both touch screens and hybrid devices are supported by Symbian platform. +Touch screen enables direct manipulation of content and objects, allowing +for far more natural interaction with the device. This means a completely +different user experience and interaction style compared to using a hardware +keypad.

            + + + +

            All applications must be touch-enabled, which means that they can be used +with the touch screen alone, regardless of the presence of a keypad. In Symbian +platform-based touch devices, the important hardware keys are Send, End, Multi-tasking +and Power key.

            +

            The application features must follow the platform support for different +hardware. When designing a touch-enabled Symbian application, the UI must +be designed so that everything can be accomplished by using the touch screen +interface, as the potential target devices may or may not have a hardware +keyboard.

            +

            The touch UI in the Symbian platform is based on the use of resistive and +capacitive touch screens. In resistive touch screen technology, two +conductive and resistive layers are separated by a thin space. When an object +touches this kind of touch panel, the layers are connected at a certain point, +and a touch event is registered. This allows efficient stylus control, in +addition to finger touch - unlike capacitive panels, which usually register +only finger touch. Additionally, resistive touch screen offers a higher resolution +and more durability. In capacitive touch screen technology, the panel +consists of an insulator such as glass, coated with a transparent conductor +(such as indium tin oxide (ITO)). When an object touches the surface of the +screen, it results in a distortion of the local electrostatic field, measurable +as a change in capacitance. Then a touch controller measures the frequency +variations to ascertain the co-ordinates of the object's touch. Capacitive +touch screen supports multi-touch.

            +

            The hardware is supported by various:

            +
              +

            • touch-specific components (see Touch +support for common UI components)

              • +

            • component and UI behavior changes

              • +

            • layout changes, and

              • +

            • additions to the interaction style.

              • +
            +

            The touch UI is designed to enable full task flow with touch, with minimal +need to switch to hardware keys. Thus, the design ensures that users can complete +a task with the chosen interaction method from start to finish.

            +

            While designing and implementing applications for touch screen devices +based on the Symbian platform, consider interactions that benefit the most +from the touch UI.

            +

            If you can apply direct manipulation of the UI, for example when moving +items from one place to another, or scrolling a page, do not confine the user +with unnecessary scrollbars or have the user resort to options list commands.

            +

            Instead, enable the user to view pages larger than a screen by panning +them directly, and dragging and dropping items rather than marking them and +using menu options.

            +
              +

            • Remember that the most intuitive touch screen interactions that can +be performed using a finger are tapping, stroking up/down/left/right, and +the long tap.

              • +

            • Utilize strokes that are easily discovered to the users in the given +context. It should be explicit to the user where strokes can be performed.

              • +

            • Design to ensure that users can complete a task with the same interaction +method from start to finish - touch or hardware keys, stylus, or finger, and +using one hand or both hands.

              • +

            • Aim to optimize system performance and battery consumption to provide +a fluid and reliable touch user experience.

              • +
            +

            See Also:

             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-1FE5D4D5-B2BF-4090-9F69-D538B2220DA3.dita --- a/Symbian3/SDK/Source/GUID-1FE5D4D5-B2BF-4090-9F69-D538B2220DA3.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-1FE5D4D5-B2BF-4090-9F69-D538B2220DA3.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,36 +1,36 @@ - - - - - -Handle -Global Variable ExampleThis example demonstrates: -

            How to handle global variables within the library code

            -

            How to use WSD (Writable Static Data) in dll

            -
            Download

            Click -on the following link to download the example: handleglobalvar.zip

            Click: browse to view the example code.

            -
            Design and -Implementation

            The following sections provide information about -the implementation of the example.

            Capabilities

            The -program capabilities are defined in globalvarex.mmp: CAPABILITY -NONE. Libwsddll library capabilities are defined inlibwsddll.mmp file: CAPABILITY -ALL -TCB.

            Application Launching

            The application can -be launched by executing globalvarex from eshell.

            libwsd library

            This -library is used to get/set dll global Data. It demonstrates how to handle -WSD (Writable Static Data).

            How to handle WSD in dll

            Collect all -global variables within the structure TWsdData and creat the instance whenever -it's required. For target release, use global variables and add EPOCALLOWDLLDATA -in the library mmp file. wsddll.h and wsddll.cpp implement the concept of -how to handle WSD data in Dll.
            -
            Building and -Using To build the handleglobalvar example application, go to the -handleglobalvar\group directory and build the application. The definition -for the whole application can be found in the bld.inf file in the group subdirectory -of the applications main directory.
            + + + + + +Handle +Global Variable ExampleThis example demonstrates: +

            How to handle global variables within the library code

            +

            How to use WSD (Writable Static Data) in dll

            +
            Download

            Click +on the following link to download the example: handleglobalvar.zip

            Click: browse to view the example code.

            +
            Design and +Implementation

            The following sections provide information about +the implementation of the example.

            Capabilities

            The +program capabilities are defined in globalvarex.mmp: CAPABILITY +NONE. Libwsddll library capabilities are defined inlibwsddll.mmp file: CAPABILITY +ALL -TCB.

            Application Launching

            The application can +be launched by executing globalvarex from eshell.

            libwsd library

            This +library is used to get/set dll global Data. It demonstrates how to handle +WSD (Writable Static Data).

            How to handle WSD in dll

            Collect all +global variables within the structure TWsdData and creat the instance whenever +it's required. For target release, use global variables and add EPOCALLOWDLLDATA +in the library mmp file. wsddll.h and wsddll.cpp implement the concept of +how to handle WSD data in Dll.
            +
            Building and +Using To build the handleglobalvar example application, go to the +handleglobalvar\group directory and build the application. The definition +for the whole application can be found in the bld.inf file in the group subdirectory +of the applications main directory.
            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2022F702-9899-5798-8932-D70119C7177D.dita --- a/Symbian3/SDK/Source/GUID-2022F702-9899-5798-8932-D70119C7177D.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-2022F702-9899-5798-8932-D70119C7177D.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,90 +1,90 @@ - - - - - -Setting -Up A Log Engine Client This tutorial describes how to set up a Log Engine client. -
            Introduction

            If -you are certain that you are coding for a platform with logging functionality -you create a custom class with some such name as CMyLogEngine. -It should have members of the classes CLogClient, CLogViewEvent, CLogViewRecent and CLogFilter and an observer of some kind. The functions of your -custom class will use the functionality of these classes by calls to the member -objects.

            If you are not certain that your platform will provide logging -functionality you must use a log wrapper framework. Write a custom class to -use the log wrapper functionality with some such name as myLogWrapper. -It should have two members which own CLogWrapper and CLogClient objects. -In the constructor function of myLogWrapper call the ClientAvailable() function -of CLogWrapper to determine whether logging functionality -is present. If so, construct the CLogClient member: if -not, leave. The effect of this is that calls to the log client functionality -of myLogWrapper will access an actual log client if the functionality -is available. However, if the functionality is not available calls to the -log client functionality will either have no effect or else leave as in this -example code.

            -
            Procedure
              -

            1. Create a custom class CMyLogEngine

              2. -

            2. Declare the members CLogClient, CLogViewEvent, CLogViewRecent and CLogFilter in the header -file of the client application

              3. -

            3. Declare ConstrucL() function -in the header file of the client application

              4. -

            4. Implement ConstructL() function

                -

              1. Establish a connection -to the Log Engine

                iLogClient = CLogClient::NewL(iFs);

                2. -

              2. get the log events using CLogViewEvent

                iLogViewEvent = CLogViewEvent::NewL(*iLogClient);

                3. -

              3. get the log of recent -events using CLogViewRecent

                iLogViewRecent = CLogViewRecent::NewL(*iLogClient);

                4. -

              4. add a log filter using ClogFilter

                iLogFilter = CLogFilter::NewL();

                5. -
              5. -
            -
            Result

            The client applications can use the log -events to be displayed to the user or for other used as a data for further -processing.

            -Log engine -client example

            Example code for a Log Engine client on a platform -with logging functionality

            void CMyLogEngine::ConstructL() - { - - // Establish connection to log engine - iLogClient = CLogClient::NewL(iFs); - - // Log view and view for recent events with standard priority - iLogViewEvent = CLogViewEvent::NewL(*iLogClient); - iLogViewRecent = CLogViewRecent::NewL(*iLogClient); - - // Filter for events - iLogFilter = CLogFilter::NewL(); -

            Example code for a Log Engine client using a wrapper framework

            void CMyLogWrapper::ConstructL(RFs& aFs) - { - - // create the CLogWrapper to forward requests to. - iLogWrapper = CLogWrapper::NewL(aFs); - - if (iLogWrapper->ClientAvailable()) - { - iLogClient = static_cast<CLogClient*>(&iLogWrapper->Log()); - } - else - { - User::Leave(KErrNotSupported); - } - } - -

            You can now use myLogWrapper as if it was -a log client.

            -             -Maintaining -Log Events -Requesting -Log Engine Notifications -Displaying -Log Events -Configuring -Log Engine + + + + + +Setting +Up A Log Engine Client This tutorial describes how to set up a Log Engine client. +
            Introduction

            If +you are certain that you are coding for a platform with logging functionality +you create a custom class with some such name as CMyLogEngine. +It should have members of the classes CLogClient, CLogViewEvent, CLogViewRecent and CLogFilter and an observer of some kind. The functions of your +custom class will use the functionality of these classes by calls to the member +objects.

            If you are not certain that your platform will provide logging +functionality you must use a log wrapper framework. Write a custom class to +use the log wrapper functionality with some such name as myLogWrapper. +It should have two members which own CLogWrapper and CLogClient objects. +In the constructor function of myLogWrapper call the ClientAvailable() function +of CLogWrapper to determine whether logging functionality +is present. If so, construct the CLogClient member: if +not, leave. The effect of this is that calls to the log client functionality +of myLogWrapper will access an actual log client if the functionality +is available. However, if the functionality is not available calls to the +log client functionality will either have no effect or else leave as in this +example code.

            +
            Procedure
              +

            1. Create a custom class CMyLogEngine

              2. +

            2. Declare the members CLogClient, CLogViewEvent, CLogViewRecent and CLogFilter in the header +file of the client application

              3. +

            3. Declare ConstrucL() function +in the header file of the client application

              4. +

            4. Implement ConstructL() function

                +

              1. Establish a connection +to the Log Engine

                iLogClient = CLogClient::NewL(iFs);

                2. +

              2. get the log events using CLogViewEvent

                iLogViewEvent = CLogViewEvent::NewL(*iLogClient);

                3. +

              3. get the log of recent +events using CLogViewRecent

                iLogViewRecent = CLogViewRecent::NewL(*iLogClient);

                4. +

              4. add a log filter using CLogFilter

                iLogFilter = CLogFilter::NewL();

                5. +
              5. +
            +
            Result

            The +client applications can use the log events to be displayed to the user or +for other used as a data for further processing.

            +Log engine +client example

            Example code for a Log Engine client on a platform +with logging functionality

            void CMyLogEngine::ConstructL() + { + + // Establish connection to log engine + iLogClient = CLogClient::NewL(iFs); + + // Log view and view for recent events with standard priority + iLogViewEvent = CLogViewEvent::NewL(*iLogClient); + iLogViewRecent = CLogViewRecent::NewL(*iLogClient); + + // Filter for events + iLogFilter = CLogFilter::NewL(); +

            Example code for a Log Engine client using a wrapper framework

            void CMyLogWrapper::ConstructL(RFs& aFs) + { + + // create the CLogWrapper to forward requests to. + iLogWrapper = CLogWrapper::NewL(aFs); + + if (iLogWrapper->ClientAvailable()) + { + iLogClient = static_cast<CLogClient*>(&iLogWrapper->Log()); + } + else + { + User::Leave(KErrNotSupported); + } + } + +

            You can now use myLogWrapper as if it was +a log client.

            +             +Maintaining +Log Events +Requesting +Log Engine Notifications +Displaying +Log Events +Configuring +Log Engine             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2045A3D6-88DB-41ED-905B-079A8DC35E24.dita --- a/Symbian3/SDK/Source/GUID-2045A3D6-88DB-41ED-905B-079A8DC35E24.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,18 +0,0 @@ - - - - - -Handling -user command selection -

            Use the method HandleControlEventL() in the class CAknStylusPopUpMenu to handle events that occur when user -selects a menu item.

            -

            Add sample code on handling user -command selection here.

            -             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-20B2C96A-9742-4CB0-A37F-19B65765E826.dita --- a/Symbian3/SDK/Source/GUID-20B2C96A-9742-4CB0-A37F-19B65765E826.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-20B2C96A-9742-4CB0-A37F-19B65765E826.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,58 +1,58 @@ - - - - - -Implementing -the MHTTPDataOptimiser Interface -

            To enable support for Web Acceleration, you must implement your own custom -encoding and decoding mechanisms by implementing the functions of the interface MHTTPDataOptimiser. -The following code illustrates the MHTTPDataOptimiser interface -that consists of the EncodeL() and DecodeL() methods:

            -class MHTTPDataOptimiser -{ - -public: - -virtual void EncodeL(const TDesC8& aHTTPData, HBufC8*& aEncodedData) = 0; - -virtual void DecodeL(const TDesC8& aData, HBufC8*& aHTTPData, TBool& aTransFail) = 0; - -}; -
            The EncodeL() -method

            This method converts HTTP request data (to your selected -network optimisation protocol format) before it is sent across the TCP connection. -This method has the following parameters:

              -

            • aHTTPData: Contains -HTTP request data in standard HTTP format.

              • -

            • aEncodedData: On -return contains encoded HTTP request data in a network optimisation protocol -format.

              • -

            Note: It is assumed that you define a custom optimisation -mechanism to encode the HTTP request data by implementing the EncodeL() method.

            -
            The DecodeL() -method

            This method converts the HTTP response data in your selected -network optimisation protocol format back to the standard HTTP response data -format. This method has the following parameters:

              -

            • aData: Contains -the raw data in a network optimisation protocol format received over the TCP -connection.

              • -

            • aHTTPData: On -return of this method the aHTTPData parameter contains the -HTTP response data.

              • -

            • aTransFail: When -you set this parameter value to ETrue it sends the KErrHTTPOptimiserFailsTrans event -to the mobile browser application.

              • -

            Note: In a scenario where the HTTP response data is split -across various packets (for example, when the network bandwidth is low), the MHTTPDataOptimiser::DecodeL() method -is called for every data packet received. In this scenario, to ensure successful -parsing of the HTTP response data, the aTransFail parameter -must be set to EFalse for every call made to MHTTPDataOptimiser::DecodeL(), -until the final transaction is encountered.

            + + + + + +Implementing +the MHTTPDataOptimiser Interface +

            To enable support for Web Acceleration, you must implement your own custom +encoding and decoding mechanisms by implementing the functions of the interface MHTTPDataOptimiser. +The following code illustrates the MHTTPDataOptimiser interface +that consists of the EncodeL() and DecodeL() methods:

            +class MHTTPDataOptimiser +{ + +public: + +virtual void EncodeL(const TDesC8& aHTTPData, HBufC8*& aEncodedData) = 0; + +virtual void DecodeL(const TDesC8& aData, HBufC8*& aHTTPData, TBool& aTransFail) = 0; + +}; +
            The EncodeL() +method

            This method converts HTTP request data (to your selected +network optimisation protocol format) before it is sent across the TCP connection. +This method has the following parameters:

              +

            • aHTTPData: Contains +HTTP request data in standard HTTP format.

              • +

            • aEncodedData: On +return contains encoded HTTP request data in a network optimisation protocol +format.

              • +

            Note: It is assumed that you define a custom optimisation +mechanism to encode the HTTP request data by implementing the EncodeL() method.

            +
            The DecodeL() +method

            This method converts the HTTP response data in your selected +network optimisation protocol format back to the standard HTTP response data +format. This method has the following parameters:

              +

            • aData: Contains +the raw data in a network optimisation protocol format received over the TCP +connection.

              • +

            • aHTTPData: On +return of this method the aHTTPData parameter contains the +HTTP response data.

              • +

            • aTransFail: When +you set this parameter value to ETrue it sends the KErrHTTPOptimiserFailsTrans event +to the mobile browser application.

              • +

            Note: In a scenario where the HTTP response data is split +across various packets (for example, when the network bandwidth is low), the MHTTPDataOptimiser::DecodeL() method +is called for every data packet received. In this scenario, to ensure successful +parsing of the HTTP response data, the aTransFail parameter +must be set to EFalse for every call made to MHTTPDataOptimiser::DecodeL(), +until the final transaction is encountered.

            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-20B364FB-FC12-5EF1-B0EC-1A845693EFFD_d0e202333_href.png Binary file Symbian3/SDK/Source/GUID-20B364FB-FC12-5EF1-B0EC-1A845693EFFD_d0e202333_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-20B364FB-FC12-5EF1-B0EC-1A845693EFFD_d0e207341_href.png Binary file Symbian3/SDK/Source/GUID-20B364FB-FC12-5EF1-B0EC-1A845693EFFD_d0e207341_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-20FECB77-2E1D-4104-948F-8E878DAFE1B8-master.png Binary file Symbian3/SDK/Source/GUID-20FECB77-2E1D-4104-948F-8E878DAFE1B8-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-20FECB77-2E1D-4104-948F-8E878DAFE1B8_d0e67767_href.png Binary file Symbian3/SDK/Source/GUID-20FECB77-2E1D-4104-948F-8E878DAFE1B8_d0e67767_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-20FECB77-2E1D-4104-948F-8E878DAFE1B8_d0e72920_href.png Binary file Symbian3/SDK/Source/GUID-20FECB77-2E1D-4104-948F-8E878DAFE1B8_d0e72920_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-20FEEF54-23CB-4D30-B846-11B4ACE8E772_d0e4552_href.png Binary file Symbian3/SDK/Source/GUID-20FEEF54-23CB-4D30-B846-11B4ACE8E772_d0e4552_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-20FEEF54-23CB-4D30-B846-11B4ACE8E772_d0e5827_href.png Binary file Symbian3/SDK/Source/GUID-20FEEF54-23CB-4D30-B846-11B4ACE8E772_d0e5827_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2105B5F0-2D00-5ECA-8859-A8A432423327_d0e237328_href.png Binary file Symbian3/SDK/Source/GUID-2105B5F0-2D00-5ECA-8859-A8A432423327_d0e237328_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2105B5F0-2D00-5ECA-8859-A8A432423327_d0e241065_href.png Binary file Symbian3/SDK/Source/GUID-2105B5F0-2D00-5ECA-8859-A8A432423327_d0e241065_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2161BD64-889B-5EAB-B023-1162FE9619DB.dita --- a/Symbian3/SDK/Source/GUID-2161BD64-889B-5EAB-B023-1162FE9619DB.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-2161BD64-889B-5EAB-B023-1162FE9619DB.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,160 +1,160 @@ - - - - - -How -to use multiple active objectsThis document illustrates how to use one active object to control -another. -

            The following example code fragments show how to construct a program with -two active objects, where one controls the initiation and cancellation of -the other.

            -

            In these examples:

            -

            CActiveConsole is an active object and contains a pointer -to a CConsoleBase object which is a service provider. Through -this service provider, the active object provides the facility to request -a character from the keyboard.

            -

            RunL() delegates the handling of completed requests to -the pure virtual function ProcessKeyPress(), which must be -provided by a derived class.

            -

            CMessageKeyProcessor is further derived from CActiveConsole and -contains a pointer to another active object CExampleActiveObject, -which requires input from the keyboard.

            -

            Depending on the input character, the CMessageKeyProcessor active -object does one of the following:

            -
              -

            • issues a request to -the CExampleActiveObject active object

              • -

            • cancels any outstanding -request to the CExampleActiveObject active object

              • -

            • does nothing

              • -
            -

            The implementation of the CExampleActiveObject active -object is not relevant to the example and is not shown.

            -

            The following diagram shows the relationship between the classes.

            - - - -
            Encapsulating the service provider

            The class CActiveConsole encapsulates -the provision of basic keyboard services. Its iConsole data -member is a pointer to the service provider, the CConsoleBase object.

            The -active object class is defined as:

            class CActiveConsole : public CActive - { -public: - CActiveConsole(CConsoleBase* aConsole); - void ConstructL(); - ~CActiveConsole(); - void RequestCharacter(); - void RunL(); - void DoCancel(); - virtual void ProcessKeyPress(TChar aChar)=0; -protected: - CConsoleBase* iConsole; - };

            The class constructor takes a pointer to a CConsoleBase object -as its single argument and initializes its iConsole data -member to this value:

            CActiveConsole::CActiveConsole(CConsoleBase* aConsole) - : iConsole(aConsole) - {}

            The ConstructL() function adds the -active object to the active scheduler:

            void CActiveConsole::ConstructL() - { - CActiveScheduler::Add(this); - }

            The destructor cancels any outstanding request before -destroying the active object:

            CActiveConsole::~CActiveConsole() - { - Cancel(); - }

            DoCancel() is implemented to cancel -the request to iConsole.

            The RequestCharacter() function -makes a request for a key press to the service provider by calling iConsole->Read(iStatus) and -setting the active request flag:

            void CActiveConsole::RequestCharacter() - { - iConsole->Read(iStatus); - SetActive(); - }

            The RunL() function makes a call to -the ProcessKeyPress() function. This is a pure virtual function -that derived classes must implement to handle the key press and to reissue -the request:

            void CActiveConsole::RunL() - { - ProcessKeyPress(TChar(iConsole->KeyCode())); - }
            -
            Further deriving from the active object

            The class CMessageKeyProcessor is -a concrete class, derived from CActiveConsole. It provides -an implementation for theProcessKeyPress() function and can -issue or cancel requests to aCExampleActiveObject active -object.

            This active object class is defined as:

            class CMessageKeyProcessor : public CActiveConsole - { -public: - ... - CMessageKeyProcessor(CConsoleBase* aConsole, CExampleActiveObject* iExampleObject); - void ProcessKeyPress(TChar aChar); -private: - CExampleActiveObject* iExampleObject; - };

            Notes

              -

            • The first constructor -parameter specifies a CConsoleBase which will be used to -provide asynchronous keyboard input.

              • -

            • the second constructor -parameter specifies a CExampleActiveObject which will be -controlled by this CMessageKeyProcessor.

              • -

            The behaviour of the ProcessKeyPress() function -depends on the key code value:

            void CMessageKeyProcessor::ProcessKeyPress(TChar aChar) - { - if (aChar == 'm' || aChar == 'M') - { - iExampleObject->Cancel(); - iExampleObject->IssueRequest(); - } - if (aChar == 'c' || aChar == 'C') - { - iExampleObject->Cancel(); - } - if (aChar != EKeyEscape) - { - RequestCharacter(); - } - else - { - iExampleObject->Cancel(); - CActiveScheduler::Stop(); - } - }
            -
            Enhanced framework

            In the code fragment below, -an active scheduler is created to which both a CMessageKeyProcessor active -object and aCExampleActiveObject active object are added:

            LOCAL_C void doExampleL() - { - CActiveScheduler* exampleScheduler=new (ELeave) CActiveScheduler; - CleanupStack::PushL(exampleScheduler); - CActiveScheduler::Install(exampleScheduler); - - CExampleActiveObject* iExampleObject = - CExampleActiveObject::NewLC(); - CMessageKeyProcessor* keyProcessor= - CMessageKeyProcessor::NewLC(console, iExampleObject); - - keyProcessor->RequestCharacter(); - CActiveScheduler::Start(); - CleanupStack::PopAndDestroy(3); - }

            Notes

              -

            • An instance of the active -scheduler, exampleScheduler is pushed onto the cleanup stack -and installed as the current active scheduler.

              • -

            • An instance of the CExampleActiveObject active -object is created.

              • -

            • An instance of the CMessageKeyProcessor active -object is created and this is in control.

              • -

            • keyProcessor->RequestCharacter() issues -a request for keyboard input.

              • -

            • CActiveScheduler::Start() starts -the active scheduler. At least one outstanding request is necessary before -the wait loop is started, otherwise the thread hangs. All further request -issuing and servicing occurs within this function. The wait loop continues -until one of the active objects’ RunL() callsCActiveScheduler::Stop().

              • -

            • The active objects and -the active scheduler are popped from the cleanup stack and destroyed.

              • -
            + + + + + +How +to use multiple active objectsThis document illustrates how to use one active object to control +another. +

            The following example code fragments show how to construct a program with +two active objects, where one controls the initiation and cancellation of +the other.

            +

            In these examples:

            +

            CActiveConsole is an active object and contains a pointer +to a CConsoleBase object which is a service provider. Through +this service provider, the active object provides the facility to request +a character from the keyboard.

            +

            RunL() delegates the handling of completed requests to +the pure virtual function ProcessKeyPress(), which must be +provided by a derived class.

            +

            CMessageKeyProcessor is further derived from CActiveConsole and +contains a pointer to another active object CExampleActiveObject, +which requires input from the keyboard.

            +

            Depending on the input character, the CMessageKeyProcessor active +object does one of the following:

            +
              +

            • issues a request to +the CExampleActiveObject active object

              • +

            • cancels any outstanding +request to the CExampleActiveObject active object

              • +

            • does nothing

              • +
            +

            The implementation of the CExampleActiveObject active +object is not relevant to the example and is not shown.

            +

            The following diagram shows the relationship between the classes.

            + + + +
            Encapsulating the service provider

            The class CActiveConsole encapsulates +the provision of basic keyboard services. Its iConsole data +member is a pointer to the service provider, the CConsoleBase object.

            The +active object class is defined as:

            class CActiveConsole : public CActive + { +public: + CActiveConsole(CConsoleBase* aConsole); + void ConstructL(); + ~CActiveConsole(); + void RequestCharacter(); + void RunL(); + void DoCancel(); + virtual void ProcessKeyPress(TChar aChar)=0; +protected: + CConsoleBase* iConsole; + };

            The class constructor takes a pointer to a CConsoleBase object +as its single argument and initializes its iConsole data +member to this value:

            CActiveConsole::CActiveConsole(CConsoleBase* aConsole) + : iConsole(aConsole) + {}

            The ConstructL() function adds the +active object to the active scheduler:

            void CActiveConsole::ConstructL() + { + CActiveScheduler::Add(this); + }

            The destructor cancels any outstanding request before +destroying the active object:

            CActiveConsole::~CActiveConsole() + { + Cancel(); + }

            DoCancel() is implemented to cancel +the request to iConsole.

            The RequestCharacter() function +makes a request for a key press to the service provider by calling iConsole->Read(iStatus) and +setting the active request flag:

            void CActiveConsole::RequestCharacter() + { + iConsole->Read(iStatus); + SetActive(); + }

            The RunL() function makes a call to +the ProcessKeyPress() function. This is a pure virtual function +that derived classes must implement to handle the key press and to reissue +the request:

            void CActiveConsole::RunL() + { + ProcessKeyPress(TChar(iConsole->KeyCode())); + }
            +
            Further deriving from the active object

            The class CMessageKeyProcessor is +a concrete class, derived from CActiveConsole. It provides +an implementation for theProcessKeyPress() function and can +issue or cancel requests to aCExampleActiveObject active +object.

            This active object class is defined as:

            class CMessageKeyProcessor : public CActiveConsole + { +public: + ... + CMessageKeyProcessor(CConsoleBase* aConsole, CExampleActiveObject* iExampleObject); + void ProcessKeyPress(TChar aChar); +private: + CExampleActiveObject* iExampleObject; + };

            Notes

              +

            • The first constructor +parameter specifies a CConsoleBase which will be used to +provide asynchronous keyboard input.

              • +

            • the second constructor +parameter specifies a CExampleActiveObject which will be +controlled by this CMessageKeyProcessor.

              • +

            The behaviour of the ProcessKeyPress() function +depends on the key code value:

            void CMessageKeyProcessor::ProcessKeyPress(TChar aChar) + { + if (aChar == 'm' || aChar == 'M') + { + iExampleObject->Cancel(); + iExampleObject->IssueRequest(); + } + if (aChar == 'c' || aChar == 'C') + { + iExampleObject->Cancel(); + } + if (aChar != EKeyEscape) + { + RequestCharacter(); + } + else + { + iExampleObject->Cancel(); + CActiveScheduler::Stop(); + } + }
            +
            Enhanced framework

            In the code fragment below, +an active scheduler is created to which both a CMessageKeyProcessor active +object and aCExampleActiveObject active object are added:

            LOCAL_C void doExampleL() + { + CActiveScheduler* exampleScheduler=new (ELeave) CActiveScheduler; + CleanupStack::PushL(exampleScheduler); + CActiveScheduler::Install(exampleScheduler); + + CExampleActiveObject* iExampleObject = + CExampleActiveObject::NewLC(); + CMessageKeyProcessor* keyProcessor= + CMessageKeyProcessor::NewLC(console, iExampleObject); + + keyProcessor->RequestCharacter(); + CActiveScheduler::Start(); + CleanupStack::PopAndDestroy(3); + }

            Notes

              +

            • An instance of the active +scheduler, exampleScheduler is pushed onto the cleanup stack +and installed as the current active scheduler.

              • +

            • An instance of the CExampleActiveObject active +object is created.

              • +

            • An instance of the CMessageKeyProcessor active +object is created and this is in control.

              • +

            • keyProcessor->RequestCharacter() issues +a request for keyboard input.

              • +

            • CActiveScheduler::Start() starts +the active scheduler. At least one outstanding request is necessary before +the wait loop is started, otherwise the thread hangs. All further request +issuing and servicing occurs within this function. The wait loop continues +until one of the active objects’ RunL() callsCActiveScheduler::Stop().

              • +

            • The active objects and +the active scheduler are popped from the cleanup stack and destroyed.

              • +
             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-217C992B-AC56-42A7-9920-DEC891D233A5.dita --- a/Symbian3/SDK/Source/GUID-217C992B-AC56-42A7-9920-DEC891D233A5.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-217C992B-AC56-42A7-9920-DEC891D233A5.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,47 +1,47 @@ - - - - - -Allowing -Optional RAM AllocationThis section describes how an application can request from OOM -Monitor for optional RAM allocation. -

            An application -can allocate RAM optionally by calling the ROomMonitorSession::RequestFreeMemory() method. -For more information on optional RAM, refer to Optional -RAM Allocation.

            An application can release the optional RAM allocation -as soon as it is not needed anymore. An application can also keep the optional -RAM allocation until OOM Monitor requests to release it.

            -             - -Create an OOM Monitor -session. -ROomMonitorSession ioomMonitorSession; -CleanUpClosePushL(ioomMonitorSession); -User::LeaveIfError(ioomMonitorSession.Connect()); - - -Request for optional -RAM. -iOomMonitorSession.RequestOptionalRam(aBytesRequested,aMinimumBytesNeeded,aPluginId,aBytesAvailable); -

            - -Close the session. -iOomMonitorSession.Close(); - - - - -OOM Monitor -Plug-in -OOM Monitor -Overview -OOM Monitor -Reference + + + + + +Allowing +Optional RAM AllocationThis section describes how an application can request from OOM +Monitor for optional RAM allocation. +

            An application +can allocate RAM optionally by calling the ROomMonitorSession::RequestFreeMemory() method. +For more information on optional RAM, refer to Optional +RAM Allocation.

            An application can release the optional RAM allocation +as soon as it is not needed anymore. An application can also keep the optional +RAM allocation until OOM Monitor requests to release it.

            + + +Create an OOM Monitor +session. +ROomMonitorSession ioomMonitorSession; +CleanUpClosePushL(ioomMonitorSession); +User::LeaveIfError(ioomMonitorSession.Connect()); + + +Request for optional +RAM. +iOomMonitorSession.RequestOptionalRam(aBytesRequested,aMinimumBytesNeeded,aPluginId,aBytesAvailable); +

            + +Close the session. +iOomMonitorSession.Close(); + + + + +OOM Monitor +Plug-in +OOM Monitor +Overview +OOM Monitor +Reference \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-21A1D1D2-524E-560E-88C8-16E2E49E2B7F_d0e252674_href.jpg Binary file Symbian3/SDK/Source/GUID-21A1D1D2-524E-560E-88C8-16E2E49E2B7F_d0e252674_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-21A1D1D2-524E-560E-88C8-16E2E49E2B7F_d0e256382_href.jpg Binary file Symbian3/SDK/Source/GUID-21A1D1D2-524E-560E-88C8-16E2E49E2B7F_d0e256382_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-21D0D9D5-B57F-5F16-A2AF-17BC00DC1B15-GENID-1-8-1-18-1-1-4-1-4-1.dita --- a/Symbian3/SDK/Source/GUID-21D0D9D5-B57F-5F16-A2AF-17BC00DC1B15-GENID-1-8-1-18-1-1-4-1-4-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,26 +0,0 @@ - - - - - -S60 -Platform: Audio Streaming Example -

            Description

            This C++ example application demonstrates -the use of Audio Streaming API, which provides functionality for recording -audio stream into a buffer, and for playback of the audio buffer. Besides -playing, recording, and stopping the audio stream, the recorded audio stream -can be saved into a file, to be played again later. The package includes PCM -and AMR-NB encoded sample files. Audio Streaming API is part of the Symbian -Multimedia Framework (MMF). The updated example has been tested to support -S60 5th Edition and touch UI. Important classes: CMdaAudioInputStream, CMdaAudioOutputStream, -MMdaAudioInputStreamCallback, MMdaAudioOutputStreamCallback. For more details, -click on this link : Audio Streaming Example

            -
            Download

            Click -on the following link to download the example: AudioStreamExample.zip

            Click: browse to view the example code.

            -             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-21D0D9D5-B57F-5F16-A2AF-17BC00DC1B15-GENID-1-8-1-18-1-1-5-1-7-1-6-1-3-1.dita --- a/Symbian3/SDK/Source/GUID-21D0D9D5-B57F-5F16-A2AF-17BC00DC1B15-GENID-1-8-1-18-1-1-5-1-7-1-6-1-3-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,26 +0,0 @@ - - - - - -S60 -Platform: Audio Streaming Example -
            Description

            This C++ example application demonstrates -the use of Audio Streaming API, which provides functionality for recording -audio stream into a buffer, and for playback of the audio buffer. Besides -playing, recording, and stopping the audio stream, the recorded audio stream -can be saved into a file, to be played again later. The package includes PCM -and AMR-NB encoded sample files. Audio Streaming API is part of the Symbian -Multimedia Framework (MMF). The updated example has been tested to support -S60 5th Edition and touch UI. Important classes: CMdaAudioInputStream, CMdaAudioOutputStream, -MMdaAudioInputStreamCallback, MMdaAudioOutputStreamCallback. For more details, -click on this link : Audio Streaming Example

            -
            Download

            Click -on the following link to download the example: AudioStreamExample.zip

            Click: browse to view the example code.

            -             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-21D0D9D5-B57F-5F16-A2AF-17BC00DC1B15.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-21D0D9D5-B57F-5F16-A2AF-17BC00DC1B15.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,24 @@ + + + + + +Audio +Streaming Example +
            Description

            This +C++ example application demonstrates the use of Audio Streaming API, which +provides functionality for recording audio stream into a buffer, and for playback +of the audio buffer. Besides playing, recording, and stopping the audio stream, +the recorded audio stream can be saved into a file, to be played again later. +The package includes PCM and AMR-NB encoded sample files. Audio Streaming +API is part of the Symbian Multimedia Framework (MMF).

            +
            Download

            Click +on the following link to download the example: AudioStreamExample.zip

            Click: browse to view the example code.

            +
            Classes

            CMdaAudioInputStream

            CMdaAudioOutputStream

            MMdaAudioInputStreamCallback

            MMdaAudioOutputStreamCallback

            +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-21DAC50D-7737-42B6-BBDA-E12E8779741B.dita --- a/Symbian3/SDK/Source/GUID-21DAC50D-7737-42B6-BBDA-E12E8779741B.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-21DAC50D-7737-42B6-BBDA-E12E8779741B.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,37 +1,104 @@ - - - - - -Feedback -

            Visual feedback is the most important sensory feedback when entering characters -on screen. Visual feedback can be, for example, button effects, color changes, -status indicators, touch/release state changes, or clearing the screen when -transitioning to next screen.

            -

            With audio feedback, lower clicks and tones are preferred over loud beeps, -though most people turn audio feedback off anyway.

            -

            Vibration is used as tactile feedback for touch screen interaction or input. -Tactile feedback gives the user an immediate response that the touch event -has been registered.

            -

            With the Symbian touch UI, tactile feedback is used in the following situations:

            -
              -

            • Sensors: a tap on the device by hand provides tactile feedback -to the user in case of a successful interaction.

              • -

            • Touch interaction (touch screen): to indicate to the user that -an interaction event has been successful. For example, when the user presses -a button on the touch screen

              • -
            -

            Tactile feedback is included in those common UI components where -it has been seen as beneficial. When creating new applications and designing -custom components, tactile feedback is to be included where found useful. -For example, in any button type of UI component, the tactile feedback is naturally -beneficial.

            -

            For more information, see Tactile -feedback.

            + + + + + +Feedback +

            Visual feedback is the most important sensory feedback when entering characters +on screen. Visual feedback can be, for example, button effects, color changes, +status indicators, touch/release state changes, or clearing the screen when +transitioning to next screen.

            +

            With audio feedback, lower clicks and tones are preferred over loud beeps, +though most people turn audio feedback off anyway.

            +

            Vibration is used as tactile feedback for touch screen interaction or input. +Tactile feedback gives the user an immediate response that the touch event +has been registered.

            +

            With the Symbian touch UI, tactile feedback is used in the following situations:

            +
              +

            • Sensors: a tap on the device by hand provides tactile feedback +to the user in case of a successful interaction.

              • +

            • Touch interaction (touch screen): to indicate to the user that +an interaction event has been successful. For example, when the user presses +a button on the touch screen

              • +
            +

            Tactile feedback is included in those common UI components where +it has been seen as beneficial. When creating new applications and designing +custom components, tactile feedback is to be included where found useful. +For example, in any button type of UI component, the tactile feedback is naturally +beneficial.

            +

            In your application, you can use the following feedback types, defined +in TTouchLogicalFeedback:

            + + + + +

            ETouchFeedbackNone

             +

            Used for disabling feedback in some areas of the application window +while using the area registry.

             +             + +

            ETouchFeedbackBasic

             +

            Used as a default feedback for stylus touch down events. For example, +when the mobile device user taps a button or tab.

             +             + +

            ETouchFeedbackSensitive

             +

            Provides sensitive feedback in situations when:

              +

            • the triggering action is not very important (for example, change of +focus in a list).

              • +

            • there can be a large number of feedback instances within a short time +(for example, text selection which gives feedback on every new selected character).

              • +
            It is also used for scrolling and dragging.

             +             + + +
            +

            To use vibration or audio feedback in your application:

            +
              +

            1. Include touchfeedback.lib in +your .mmp file.

              2. +

            2. Include touchfeedback.h.

              3. +

            3. To enable +tactile feedback for your application, add the following code.

              MTouchFeedback* feedback = MTouchFeedback::Instance(); +feedback->SetFeedbackEnabledForThisApp(ETrue); // enabling feedback is optional

              Do +not delete the pointer in the controller destructor.

              4. +

            4. To use tactile +feedback when a mobile device user points at a control, add the following +code.

              void CMyContainerControl::HandlePointerEventL(const TPointerEvent& aPointerEvent) + { + // Feedback is always played at pointer down event + if(aPointerEvent.iType == TPointerEvent::EButton1Down) + { + MTouchFeedback* feedback = MTouchFeedback::Instance(); + if (feedback) + { + feedback->InstantFeedback(ETouchFeedbackBasic); + } + } + + // Your other pointer event handling code here +
              5. +

            5. To enable +automatic feedback triggering in a specific area of a UI component, add

              feedback->SetFeedbackArea( this, + 1, // area Id + TRect( 0,0,20,20 ), + ETouchFeedbackBasic, + ETouchEventStylusDown ); +
              6. +
            +
              +

            • To use tactile feedback in an application, additional platform security +capabilities are not required.

              • +

            • Applications themselves do not need to generate feedback effects, unless +they are using custom components. The feedback is generated by components +that the applications use.

              • +
             +

            For more information, see Tactile +feedback.

             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-21E43B0E-85C7-536E-83A5-E829820775BF_d0e283471_href.png Binary file Symbian3/SDK/Source/GUID-21E43B0E-85C7-536E-83A5-E829820775BF_d0e283471_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-21E43B0E-85C7-536E-83A5-E829820775BF_d0e287157_href.png Binary file Symbian3/SDK/Source/GUID-21E43B0E-85C7-536E-83A5-E829820775BF_d0e287157_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-21EF9E6F-A0BF-5EB2-9E3F-CA6A011D4C89_d0e190335_href.png Binary file Symbian3/SDK/Source/GUID-21EF9E6F-A0BF-5EB2-9E3F-CA6A011D4C89_d0e190335_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-21EF9E6F-A0BF-5EB2-9E3F-CA6A011D4C89_d0e195343_href.png Binary file Symbian3/SDK/Source/GUID-21EF9E6F-A0BF-5EB2-9E3F-CA6A011D4C89_d0e195343_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-21F0EE0E-6CC6-44E7-9FED-FB8911E3C3A2-master.jpg Binary file Symbian3/SDK/Source/GUID-21F0EE0E-6CC6-44E7-9FED-FB8911E3C3A2-master.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-21F0EE0E-6CC6-44E7-9FED-FB8911E3C3A2_d0e211670_href.jpg Binary file Symbian3/SDK/Source/GUID-21F0EE0E-6CC6-44E7-9FED-FB8911E3C3A2_d0e211670_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-22093E74-EFE7-5642-93DE-1573E18F7C08.dita --- a/Symbian3/SDK/Source/GUID-22093E74-EFE7-5642-93DE-1573E18F7C08.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-22093E74-EFE7-5642-93DE-1573E18F7C08.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,119 +1,119 @@ - - - - - -The -Window Server Rendering LoopThis topic provides a brief introduction to the Window Server's -rendering loop, which takes place in two stages, known as the upper loop and -the lower loop. -

            Variant: ScreenPlay and non-ScreenPlay. Target -audience: Device creators.

            -

            The following diagram provides a simplified representation of the upper -and lower loops.

            - -The Window Server's upper and lower rendering loops - - -

            -

            The upper loop is the process by which the Window Server’s scene -state information is updated based on commands from the client. There are -two types of scene state updates: window tree updates (such as when a window -is moved) and redraw store updates (such as when new drawing operations are -sent for a particular window).

            -

            The lower loop is the process by which updates are made to what -the user sees on the screen. The lower loop runs after the upper loop.

            -

            The two most important APIs on the client side are:

            -
              -

            • RWindow, -which is the class through which a client controls a window. Its main functions -enable a client to create and destroy windows, move and resize them, make -them visible or invisible, and send them to the foreground or background.

              • -

            • CWindowGc, -which is the class through which a client issues draw operations. At any given -time, a CWindowGc is activated on a particular window. The CWindowGc functions -that are used most frequently are DrawBitmap() and BitBlt(), -for drawing a skin bitmap as a background, and DrawText().

              • -
            - -The main participants in the ScreenPlay Window Server rendering loop - - -

            On the client side, RWindow and CWindowGc commands -are converted to opcodes that are stored in a command buffer. When the command -buffer is full, it is automatically flushed, which means that it is -transferred across to a corresponding server-side command buffer. The client -can also explicitly request a flush using RWsSession::Flush().

            -

            On the server side:

            -
              -

            • The upper loop processes -the server-side command buffers. RWindow commands are processed -as updates to the window tree. CWindowGc commands -are processed as updates to the redraw stores.

              • -

            • The lower loop ultimately -causes the updates to be drawn to the UI surface. However, the updates do -not go straight to the UI surface. Instead they go through an additional level -of indirection called render stages. These are replaceable plug-ins -to the Window Server, which enable the customization of the final stages of -the rendering pipeline.

              • -
            -

            The details of the upper and lower loops vary depending on whether dirty-rectangle -tracking or change tracking is in use.

            -

            Dirty-rectangle tracking mode

            -

            Dirty-rectangle tracking mode is always used in the non-ScreenPlay variant -and is the default mode in ScreenPlay.

            -

            Updates to both the window tree and the redraw stores typically mean that -the current contents of the screen become invalid. Therefore, when processing RWindow or CWindowGc commands, -the upper loop adds the affected regions to a list of dirty rectangles that -need to be redrawn. The list includes transparent windows that are on top -of other windows and excludes windows that are obscured. The upper loop then -starts a scheduler, which eventually causes the dirty rectangles to be redrawn.

            -

            Some time later the scheduler runs the lower loop. The task of the lower -loop is to clean any dirty rectangles by playing (or replaying) the drawing -operations from the redraw stores into the first render stage. This is done -for all of the visible windows, starting at the back and working forwards.

            -

            Change tracking mode

            -

            Change tracking mode is only available in ScreenPlay. To enable change -tracking mode, add the CHANGETRACKING parameter to the wsini.ini file. This -parameter is set on a per-screen basis.

            -

            In change tracking mode, the upper loop keeps a list of all of the windows -for which there are new or changed drawing operations, regardless whether -the window is obscured or not. The list does not include transparent windows -that have not changed and which are on top of other windows. As in dirty-rectangle -tracking mode, changes cause the upper loop to start the scheduler which eventually -causes the lower loop to run. This plays the drawing operations for all of -the windows in the list of changed windows into the first render stage.

            -

            Typically you enable change tracking mode only if you are creating a transition -effects (TFX) render stage that is building up its own visuals stores. Visual -stores are replicas of the redraw stores and are often used with a visuals -tree. A visuals tree is a replica of the Window Server's window tree, into -which the render stage may add nodes that the Window Server does not "know" -about. In addition, these render stages typically introduce transition effects -which may change the visibility of windows that the Window Server does know -about. For example, the following diagram shows a transition effect in which -a window slides onto the screen from the top and temporarily obscures an existing -window on the screen.

            - - A transition effect temporarily obscures a window on the screen - - -

            In this and similar scenarios, the Window Server does not know whether -a window is obscured or visible. Therefore dirty-rectangle tracking is not -effective.

            -

            Each screen on the device has a separate render stage chain. -Because you set the CHANGETRACKING parameter on a per-screen -basis, it is possible to have a sophisticated TFX on one screen and a simple -display render stage on another screen.

            -             -Redraw Stores - -Window Server -Internals: Concepts - + + + + + +The +Window Server Rendering LoopThis topic provides a brief introduction to the Window Server's +rendering loop, which takes place in two stages, known as the upper loop and +the lower loop. +

            Variant: ScreenPlay and non-ScreenPlay. Target +audience: Device creators.

            +

            The following diagram provides a simplified representation of the upper +and lower loops.

            + +The Window Server's upper and lower rendering loops + + +

            +

            The upper loop is the process by which the Window Server’s scene +state information is updated based on commands from the client. There are +two types of scene state updates: window tree updates (such as when a window +is moved) and redraw store updates (such as when new drawing operations are +sent for a particular window).

            +

            The lower loop is the process by which updates are made to what +the user sees on the screen. The lower loop runs after the upper loop.

            +

            The two most important APIs on the client side are:

            +
              +

            • RWindow, +which is the class through which a client controls a window. Its main functions +enable a client to create and destroy windows, move and resize them, make +them visible or invisible, and send them to the foreground or background.

              • +

            • CWindowGc, +which is the class through which a client issues draw operations. At any given +time, a CWindowGc is activated on a particular window. The CWindowGc functions +that are used most frequently are DrawBitmap() and BitBlt(), +for drawing a skin bitmap as a background, and DrawText().

              • +
            + +The main participants in the ScreenPlay Window Server rendering loop + + +

            On the client side, RWindow and CWindowGc commands +are converted to opcodes that are stored in a command buffer. When the command +buffer is full, it is automatically flushed, which means that it is +transferred across to a corresponding server-side command buffer. The client +can also explicitly request a flush using RWsSession::Flush().

            +

            On the server side:

            +
              +

            • The upper loop processes +the server-side command buffers. RWindow commands are processed +as updates to the window tree. CWindowGc commands +are processed as updates to the redraw stores.

              • +

            • The lower loop ultimately +causes the updates to be drawn to the UI surface. However, the updates do +not go straight to the UI surface. Instead they go through an additional level +of indirection called render stages. These are replaceable plug-ins +to the Window Server, which enable the customization of the final stages of +the rendering pipeline.

              • +
            +

            The details of the upper and lower loops vary depending on whether dirty-rectangle +tracking or change tracking is in use.

            +

            Dirty-rectangle tracking mode

            +

            Dirty-rectangle tracking mode is always used in the non-ScreenPlay variant +and is the default mode in ScreenPlay.

            +

            Updates to both the window tree and the redraw stores typically mean that +the current contents of the screen become invalid. Therefore, when processing RWindow or CWindowGc commands, +the upper loop adds the affected regions to a list of dirty rectangles that +need to be redrawn. The list includes transparent windows that are on top +of other windows and excludes windows that are obscured. The upper loop then +starts a scheduler, which eventually causes the dirty rectangles to be redrawn.

            +

            Some time later the scheduler runs the lower loop. The task of the lower +loop is to clean any dirty rectangles by playing (or replaying) the drawing +operations from the redraw stores into the first render stage. This is done +for all of the visible windows, starting at the back and working forwards.

            +

            Change tracking mode

            +

            Change tracking mode is only available in ScreenPlay. To enable change +tracking mode, add the CHANGETRACKING parameter to the wsini.ini file. This +parameter is set on a per-screen basis.

            +

            In change tracking mode, the upper loop keeps a list of all of the windows +for which there are new or changed drawing operations, regardless whether +the window is obscured or not. The list does not include transparent windows +that have not changed and which are on top of other windows. As in dirty-rectangle +tracking mode, changes cause the upper loop to start the scheduler which eventually +causes the lower loop to run. This plays the drawing operations for all of +the windows in the list of changed windows into the first render stage.

            +

            Typically you enable change tracking mode only if you are creating a transition +effects (TFX) render stage that is building up its own visuals stores. Visual +stores are replicas of the redraw stores and are often used with a visuals +tree. A visuals tree is a replica of the Window Server's window tree, into +which the render stage may add nodes that the Window Server does not "know" +about. In addition, these render stages typically introduce transition effects +which may change the visibility of windows that the Window Server does know +about. For example, the following diagram shows a transition effect in which +a window slides onto the screen from the top and temporarily obscures an existing +window on the screen.

            + + A transition effect temporarily obscures a window on the screen + + +

            In this and similar scenarios, the Window Server does not know whether +a window is obscured or visible. Therefore dirty-rectangle tracking is not +effective.

            +

            Each screen on the device has a separate render stage chain. +Because you set the CHANGETRACKING parameter on a per-screen +basis, it is possible to have a sophisticated TFX on one screen and a simple +display render stage on another screen.

            +             +Redraw Stores + +Window Server +Internals: Concepts +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-220D3B2F-7A88-55AB-942F-1735A6E9E420_d0e323992_href.png Binary file Symbian3/SDK/Source/GUID-220D3B2F-7A88-55AB-942F-1735A6E9E420_d0e323992_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-220D3B2F-7A88-55AB-942F-1735A6E9E420_d0e330149_href.png Binary file Symbian3/SDK/Source/GUID-220D3B2F-7A88-55AB-942F-1735A6E9E420_d0e330149_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-220D7D10-5571-46C4-BA2B-B4FBAE4153F1-master.png Binary file Symbian3/SDK/Source/GUID-220D7D10-5571-46C4-BA2B-B4FBAE4153F1-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-220D7D10-5571-46C4-BA2B-B4FBAE4153F1_d0e36193_href.png Binary file Symbian3/SDK/Source/GUID-220D7D10-5571-46C4-BA2B-B4FBAE4153F1_d0e36193_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-220D7D10-5571-46C4-BA2B-B4FBAE4153F1_d0e41760_href.png Binary file Symbian3/SDK/Source/GUID-220D7D10-5571-46C4-BA2B-B4FBAE4153F1_d0e41760_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-22446D23-3CF7-5E1B-B479-4DCA6B6A3DA9-GENID-1-8-1-18-1-1-4-1-11-1.dita --- a/Symbian3/SDK/Source/GUID-22446D23-3CF7-5E1B-B479-4DCA6B6A3DA9-GENID-1-8-1-18-1-1-4-1-11-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,31 +0,0 @@ - - - - - -MmfExSinkSource: -Multimedia Framework sink/source plug-ins example -
            Description

            MmfExSinkSource demonstrates -how to implement sink and source plug-ins for the Multimedia Framework. A -sink is an object that can receive multimedia data; a source is an object -that can supply it. This example implements a sink and a source as descriptor -objects.

            Both the sink and source are implemented in a single class, CMMFExDescriptor, -that derives from CMMFClip. CMMFClip represents -a multimedia clip (i.e. not a stream or hardware device), which, in turn, -derives from the ECom sink interface MDataSink, and the source -interface MDataSource.

            Both the example source and -sink are passed on creation a packaged TMMFExDescriptorParams object, -which specifies the descriptor to read/write, and the thread to which the -descriptor belongs.

            Note that the default audio controller only uses -the default sink/sources, and returns "not supported" if you attempt to use -other sink/sources with it.

            -
            Download

            Click -on the following link to download the example: MmfExSinkSource.zip file

            Click:browse to view the example code.

            -
            Class summary

            RThread CMMFClip MDataSink MDataSource CMMFBuffer

            -             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-22446D23-3CF7-5E1B-B479-4DCA6B6A3DA9-GENID-1-8-1-18-1-1-5-1-7-1-6-1-7-1.dita --- a/Symbian3/SDK/Source/GUID-22446D23-3CF7-5E1B-B479-4DCA6B6A3DA9-GENID-1-8-1-18-1-1-5-1-7-1-6-1-7-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,31 +0,0 @@ - - - - - -MmfExSinkSource: -Multimedia Framework sink/source plug-ins example -
            Description

            MmfExSinkSource demonstrates -how to implement sink and source plug-ins for the Multimedia Framework. A -sink is an object that can receive multimedia data; a source is an object -that can supply it. This example implements a sink and a source as descriptor -objects.

            Both the sink and source are implemented in a single class, CMMFExDescriptor, -that derives from CMMFClip. CMMFClip represents -a multimedia clip (i.e. not a stream or hardware device), which, in turn, -derives from the ECom sink interface MDataSink, and the source -interface MDataSource.

            Both the example source and -sink are passed on creation a packaged TMMFExDescriptorParams object, -which specifies the descriptor to read/write, and the thread to which the -descriptor belongs.

            Note that the default audio controller only uses -the default sink/sources, and returns "not supported" if you attempt to use -other sink/sources with it.

            -
            Download

            Click -on the following link to download the example: MmfExSinkSource.zip file

            Click:browse to view the example code.

            -
            Class summary

            RThread CMMFClip MDataSink MDataSource CMMFBuffer

            -             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-22446D23-3CF7-5E1B-B479-4DCA6B6A3DA9.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-22446D23-3CF7-5E1B-B479-4DCA6B6A3DA9.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,31 @@ + + + + + +MmfExSinkSource: +Multimedia Framework sink/source plug-ins example +
            Description

            MmfExSinkSource demonstrates +how to implement sink and source plug-ins for the Multimedia Framework. A +sink is an object that can receive multimedia data; a source is an object +that can supply it. This example implements a sink and a source as descriptor +objects.

            Both the sink and source are implemented in a single class, CMMFExDescriptor, +that derives from CMMFClip. CMMFClip represents +a multimedia clip (i.e. not a stream or hardware device), which, in turn, +derives from the ECom sink interface MDataSink, and the source +interface MDataSource.

            Both the example source and +sink are passed on creation a packaged TMMFExDescriptorParams object, +which specifies the descriptor to read/write, and the thread to which the +descriptor belongs.

            Note that the default audio controller only uses +the default sink/sources, and returns "not supported" if you attempt to use +other sink/sources with it.

            +
            Download

            Click +on the following link to download the example: MmfExSinkSource.zip file

            Click:browse to view the example code.

            +
            Class summary

            RThread CMMFClip MDataSink MDataSource CMMFBuffer

            +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-22498580-E902-4024-921C-F756A8CD58DF_d0e70545_href.png Binary file Symbian3/SDK/Source/GUID-22498580-E902-4024-921C-F756A8CD58DF_d0e70545_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-22498580-E902-4024-921C-F756A8CD58DF_d0e75600_href.png Binary file Symbian3/SDK/Source/GUID-22498580-E902-4024-921C-F756A8CD58DF_d0e75600_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-22699952-D032-5B69-B38A-43347A40A420_d0e355499_href.png Binary file Symbian3/SDK/Source/GUID-22699952-D032-5B69-B38A-43347A40A420_d0e355499_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-22699952-D032-5B69-B38A-43347A40A420_d0e361579_href.png Binary file Symbian3/SDK/Source/GUID-22699952-D032-5B69-B38A-43347A40A420_d0e361579_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-226EDECC-BE24-412C-945D-7EABE566282A.dita --- a/Symbian3/SDK/Source/GUID-226EDECC-BE24-412C-945D-7EABE566282A.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-226EDECC-BE24-412C-945D-7EABE566282A.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,22 +1,22 @@ - - - - - -Editing -indicators in pop-up windows -

            When a pop-up window contains an editor that needs editing indicators, -it is not feasible to use the Navi pane for the indicators. For this purpose, -a specific area in the pop-up window, above the editing field, can be used -for displaying the editing indicators (see Editing -indicators for an example).

            -
            Using -editing indicators in pop-up windows in C++ applications

            The APIs -to use are the Indicators API and the Popups API.

            + + + + + +Editing +indicators in pop-up windows +

            When a pop-up window contains an editor that needs editing indicators, +it is not feasible to use the Navi pane for the indicators. For this purpose, +a specific area in the pop-up window, above the editing field, can be used +for displaying the editing indicators (see Editing +indicators for an example).

            +
            Using +editing indicators in pop-up windows in applications

            The APIs to +use are the Indicators API and the Popups API.

             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2274DE87-8D6B-5376-A9AE-03ABE4DEE495.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-2274DE87-8D6B-5376-A9AE-03ABE4DEE495.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,19 @@ + + + + + +EchoClientUI: +TCP/IP Echo Client UI +
            Download

            Click on the following link to download +the example: EchoClient.zip

            Click browse to view the example code.

            +
            Description

            This project provides the user interface +for the TCP echo client engine example EchoClientEngine.

            +
            Class summary

            CEikConsoleScreen CEikAppUi CEikApplication

            standard Uikon application framework classes

            +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-22844C28-AB5B-5A6F-8863-7269464684B4.dita --- a/Symbian3/SDK/Source/GUID-22844C28-AB5B-5A6F-8863-7269464684B4.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-22844C28-AB5B-5A6F-8863-7269464684B4.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,99 +1,99 @@ - - - - - -Symbian -SQL OverviewThis document introduces you to the Symbian platform implementation -of the Structured Query Language(SQL). -
            Purpose

            SQL is: the syntax for creating, modifying -and deleting databases and the data they contain; an engine or server that -understands that syntax; the commands and operations that allow the SQL engine -to process the syntatical elements. Developers who know one variant of SQL -can easily work in another.

            -
            Required background

            Relational databases, the SQL -query language, database programming fundamentals.

            -
            Key concepts/terms

            The SQL component includes these -key concepts:

              -

            • Relational database

              A -structured collection of data organised as tables (relations).

              • -

            • SQL

              A standard -language for querying relational databases.

              • -

            • Security policy

              A -specification of user permissions on a database.

              • -
            -
            Architectural relationships

            The SQL component is -a free standing component that can be accessed by any application and from -anywhere in Symbian platform.

            It is has a client-server architecture. -Applications interface with the client API. The server side is an executable -running in its own process and is not directly accessible to client applications. -It can only be reached via the client-side interface.

            - This image depicts the client / server nature of Symbian -SQL - -
            -
            API summary

            The SQL component client consists of -three APIs which are used to access, query and secure a database.

            SQL APIs

              -

            • The SQL database API, -which you use to access a database.

              • -

            • The SQL statement API, -which you use to query a database.

              • -

            • The SQL security policy -API, which you use to create a secure database.

              • -
            - - - -API -Description - - - - -

            RSqlDatabase

            -

            The SQL database API

            -             - -

            RSqlStatement

            -

            The SQL statement API

            -             - -

            RSqlSecurityPolicy

            -

            The SQL security policy API

            -             - - -
            -
            Typical uses

            Relational databases and the SQL query -language are fundamentals of application development with numerous uses.

            SQL Users

              -

            • Application developers -needing to access databases.

              • -

            SQL -tasks

            The SQL component is used to:

              -

            • create,

              • -

            • delete,

              • -

            • access,

              • -

            • query, and

              • -

            • modify relational databases.

              • -

            Creating -and deleting a relational database

            The SQL component is used to -create and delete relational databases. They may be secure or insecure.

            Accessing a relational database

            Use the SQL component to open -and close databases and to attach a secondary database to a primary one.

            Querying and modifying a relational database

            Use the SQL component -to query a database using SQL. Queries can read, write, modify and delete -data in a database.

            -             -SQL Overview - -SQL DB Overview - -SQL Server -Guide -Persistent -Storage + + + + + +Symbian +SQL OverviewThis document introduces you to the Symbian platform implementation +of the Structured Query Language(SQL). +
            Purpose

            SQL is: the syntax for creating, modifying +and deleting databases and the data they contain; an engine or server that +understands that syntax; the commands and operations that allow the SQL engine +to process the syntatical elements. Developers who know one variant of SQL +can easily work in another.

            +
            Required background

            Relational databases, the SQL +query language, database programming fundamentals.

            +
            Key concepts/terms

            The SQL component includes these +key concepts:

              +

            • Relational database

              A +structured collection of data organised as tables (relations).

              • +

            • SQL

              A standard +language for querying relational databases.

              • +

            • Security policy

              A +specification of user permissions on a database.

              • +
            +
            Architectural relationships

            The SQL component is +a free standing component that can be accessed by any application and from +anywhere in Symbian platform.

            It is has a client-server architecture. +Applications interface with the client API. The server side is an executable +running in its own process and is not directly accessible to client applications. +It can only be reached via the client-side interface.

            + This image depicts the client / server nature of Symbian +SQL + +
            +
            API summary

            The SQL component client consists of +three APIs which are used to access, query and secure a database.

            SQL APIs

              +

            • The SQL database API, +which you use to access a database.

              • +

            • The SQL statement API, +which you use to query a database.

              • +

            • The SQL security policy +API, which you use to create a secure database.

              • +
            + + + +API +Description + + + + +

            RSqlDatabase

            +

            The SQL database API

            +             + +

            RSqlStatement

            +

            The SQL statement API

            +             + +

            RSqlSecurityPolicy

            +

            The SQL security policy API

            +             + + +
            +
            Typical uses

            Relational databases and the SQL query +language are fundamentals of application development with numerous uses.

            SQL Users

              +

            • Application developers +needing to access databases.

              • +

            SQL +tasks

            The SQL component is used to:

              +

            • create,

              • +

            • delete,

              • +

            • access,

              • +

            • query, and

              • +

            • modify relational databases.

              • +

            Creating +and deleting a relational database

            The SQL component is used to +create and delete relational databases. They may be secure or insecure.

            Accessing a relational database

            Use the SQL component to open +and close databases and to attach a secondary database to a primary one.

            Querying and modifying a relational database

            Use the SQL component +to query a database using SQL. Queries can read, write, modify and delete +data in a database.

            +             +SQL Overview + +SQL DB Overview + +SQL Server +Guide +Persistent +Storage             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-231840A2-255B-5200-8AD1-1D7667FCB448.dita --- a/Symbian3/SDK/Source/GUID-231840A2-255B-5200-8AD1-1D7667FCB448.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-231840A2-255B-5200-8AD1-1D7667FCB448.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,81 +1,81 @@ - - - - - -What -are recordsThis topic describes the structure of record. A record is an item -that can be stored in the Comms Database. -

            A record is a container and an element. A record refers to a set of fields -in a defined order. A set or records that has the same fields in the same -order can be called a recordset or a table. Fields in a given position make -a column. A column is conceptual. The CommsDat API has no C++ item defined -as a column.

            -

            There are two types of record:

            -
              -

            • records defined at system -compile time - these records have named fields and are defined by Symbian -platform.

              • -

            • records defined by the -user - these records are defined at run time - they are not known to Symbian -platform when Symbian platform is built.

              • -
            -
            Records defined at system compile time

            The -class CCDRecordBase represents a Symbian -platform defined record. All Symbian platform defined records inherit from CCDRecordBase. -An individual named record is an instance of a class derived from CCDRecordBase. -Symbian platform creates an individual named record and assigns a unique numeric -Id. Symbian platform defines the class and the unique Id before the system -is built.

            The class defines a schema for the record. A schema is a -pattern for the record that all records of this type follow. The class contains -a set of fields and links to other records.

            - -

            For example, Symbian platform defines the class CCDIAPRecord. -The class represents an Internet Access Point (IAP) record. A set of IAP records -form an IAP table. Symbian platform assigns the unique numeric Id KCDTIdIAPRecord to a record of this type.

            The -public data members of this class are the fields and links that make the record. -The following code shows part of the class definition. Some parts are omitted -- this is not the complete class definition.

            class CCDIAPRecord : public CCDRecordBase - { - public: - CMDBField<TDesC> iServiceType; - CMDBRecordLink<CCDServiceRecordBase> iService; - CMDBField<TDesC> iBearerType; - CMDBRecordLink<CCDBearerRecordBase> iBearer; - CMDBRecordLink<CCDNetworkRecord> iNetwork; - CMDBField<TUint32> iNetworkWeighting; - CMDBRecordLink<CCDLocationRecord> iLocation; - ... - } -

            To create an instance of a Symbian platform defined record -in memory, use the factory function: CommsDat::CCDRecordBase::RecordFactoryL().

            Tools -and applications can also create an instance of a Symbian platform defined -record in memory, and copy it from another record. Use the factory function: CommsDat::CCDRecordBase::CreateCopyRecord().

            Fields -are public data members of a Symbian platform defined record. Tools and applications -access the fields directly.

            Tools and applications can use the CommsDat::CCDRecordBase::GetFieldByNameL() or CommsDat::CCDRecordBase::GetFieldByIdL() functions -to find fields in a Symbian platform defined record. These methods are not recommended. -It is more efficient to access the fields directly.

            -
            Records defined by the user

            The class CMDBGenericRecord represents a user defined record. -All user defined records inherit from CMDBGenericRecord. -User defined records do not have named fields. A tool or application supplies -a schema at run time. The schema defines the structure of the record.

            A -schema is an array of SGenericRecordTypeInfo objects. -Each item in the array defines the fields in the record in order.

            Tools -and applications can use the CommsDat::CMDBGenericRecord::InitializeL() function -to initialise a record in memory. Tools and Applications can also get use -the LoadL() and FindL() functions to get -the the table schema from the Comms Database.

            - -

            You use the same methods to create, store and access user -defined records that Symbian platform defined records use. Symbian platform -backs up user defined data and secures user defined data with Platform Security. -Symbian platform does not maintain user defined data formats.

            Tools -and applications must use the CommsDat::CCDRecordBase::GetFieldByNameL() or CommsDat::CCDRecordBase::GetFieldByIdL() functions -to find fields in a user defined record. It is more efficient to use CommsDat::CCDRecordBase::GetFieldByIdL().

            + + + + + +What +are recordsThis topic describes the structure of record. A record is an item +that can be stored in the Comms Database. +

            A record is a container and an element. A record refers to a set of fields +in a defined order. A set or records that has the same fields in the same +order can be called a recordset or a table. Fields in a given position make +a column. A column is conceptual. The CommsDat API has no C++ item defined +as a column.

            +

            There are two types of record:

            +
              +

            • records defined at system +compile time - these records have named fields and are defined by Symbian +platform.

              • +

            • records defined by the +user - these records are defined at run time - they are not known to Symbian +platform when Symbian platform is built.

              • +
            +
            Records defined at system compile time

            The +class CCDRecordBase represents a Symbian +platform defined record. All Symbian platform defined records inherit from CCDRecordBase. +An individual named record is an instance of a class derived from CCDRecordBase. +Symbian platform creates an individual named record and assigns a unique numeric +Id. Symbian platform defines the class and the unique Id before the system +is built.

            The class defines a schema for the record. A schema is a +pattern for the record that all records of this type follow. The class contains +a set of fields and links to other records.

            + +

            For example, Symbian platform defines the class CCDIAPRecord. +The class represents an Internet Access Point (IAP) record. A set of IAP records +form an IAP table. Symbian platform assigns the unique numeric Id KCDTIdIAPRecord to a record of this type.

            The +public data members of this class are the fields and links that make the record. +The following code shows part of the class definition. Some parts are omitted +- this is not the complete class definition.

            class CCDIAPRecord : public CCDRecordBase + { + public: + CMDBField<TDesC> iServiceType; + CMDBRecordLink<CCDServiceRecordBase> iService; + CMDBField<TDesC> iBearerType; + CMDBRecordLink<CCDBearerRecordBase> iBearer; + CMDBRecordLink<CCDNetworkRecord> iNetwork; + CMDBField<TUint32> iNetworkWeighting; + CMDBRecordLink<CCDLocationRecord> iLocation; + ... + } +

            To create an instance of a Symbian platform defined record +in memory, use the factory function: CommsDat::CCDRecordBase::RecordFactoryL().

            Tools +and applications can also create an instance of a Symbian platform defined +record in memory, and copy it from another record. Use the factory function: CommsDat::CCDRecordBase::CreateCopyRecord().

            Fields +are public data members of a Symbian platform defined record. Tools and applications +access the fields directly.

            Tools and applications can use the CommsDat::CCDRecordBase::GetFieldByNameL() or CommsDat::CCDRecordBase::GetFieldByIdL() functions +to find fields in a Symbian platform defined record. These methods are not recommended. +It is more efficient to access the fields directly.

            +
            Records defined by the user

            The class CMDBGenericRecord represents a user defined record. +All user defined records inherit from CMDBGenericRecord. +User defined records do not have named fields. A tool or application supplies +a schema at run time. The schema defines the structure of the record.

            A +schema is an array of SGenericRecordTypeInfo objects. +Each item in the array defines the fields in the record in order.

            Tools +and applications can use the CommsDat::CMDBGenericRecord::InitializeL() function +to initialise a record in memory. Tools and Applications can also get use +the LoadL() and FindL() functions to get +the the table schema from the Comms Database.

            + +

            You use the same methods to create, store and access user +defined records that Symbian platform defined records use. Symbian platform +backs up user defined data and secures user defined data with Platform Security. +Symbian platform does not maintain user defined data formats.

            Tools +and applications must use the CommsDat::CCDRecordBase::GetFieldByNameL() or CommsDat::CCDRecordBase::GetFieldByIdL() functions +to find fields in a user defined record. It is more efficient to use CommsDat::CCDRecordBase::GetFieldByIdL().

            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-231E58F2-7935-462A-B048-51729D8245D4_d0e11032_href.png Binary file Symbian3/SDK/Source/GUID-231E58F2-7935-462A-B048-51729D8245D4_d0e11032_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-231E58F2-7935-462A-B048-51729D8245D4_d0e12307_href.png Binary file Symbian3/SDK/Source/GUID-231E58F2-7935-462A-B048-51729D8245D4_d0e12307_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-232E2D33-8BC1-5CC3-A4DF-2C99900E1083.dita --- a/Symbian3/SDK/Source/GUID-232E2D33-8BC1-5CC3-A4DF-2C99900E1083.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-232E2D33-8BC1-5CC3-A4DF-2C99900E1083.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,36 +1,38 @@ - - - - - -Client-side -MTM implementation -
            Example Code

            Download

            Click on the -following link to download the example: TextMTM.zip

            Click: browse to view the example code.

            The files reproduced -here are the main files contained in the examples directory. Some extra files -may be needed to run the examples, and these will be found in the appropriate -examples directory.

            The subproject txtc demonstrates -a Client-side MTM. The central class is CTextMtmClient,

            derived -from the Client-side MTM base class CBaseMtm.

            txtc implements -all mandatory Client-side MTM functionality, and the following optional MTM -functionality:

              -

            • find: this searches the body text of a local entry, or its description -or details

              • -

            • message forwarding: this copies a message to another folder

              • -

            • MTM-specific operations: txtc accepts requests for -an asynchronous service Refresh operation, and passes such requests to the -Server-side Text MTM.

              • -

            -
            Class Summary

            CBaseMtm CMTMTxtsetings TMTMTxtSettings

            The -following optional functionality is not implemented:

              -

            • address handling: addresses are not relevant to this MTM

              • -

            • subject field

              • -

            • replying

              • -

            + + + + + +Client-side MTM implementation +
            Example Code

            Download

            Click +on the following link to download the example: TextMTMi.zip

            Click: browse to view the example code.

            The files +reproduced here are the main files contained in the examples directory. +Some extra files may be needed to run the examples, and these will +be found in the appropriate examples directory.

            The subproject txtc demonstrates a Client-side MTM. The central class +is CTextMtmClient,

            derived from the Client-side +MTM base class CBaseMtm.

            txtc implements all mandatory Client-side MTM functionality, and the +following optional MTM functionality:

              +

            • find: this searches the body text of a local entry, or its +description or details

              • +

            • message forwarding: this copies a message to another folder

              • +

            • MTM-specific operations: txtc accepts requests +for an asynchronous service Refresh operation, and passes such requests +to the Server-side Text MTM.

              • +

            +
            Class Summary
              +

            • CBaseMtm

              • +

            • CMTMTxtsetings

              • +

            • TMTMTxtSettings

              • +

            The following optional functionality is not +implemented:

              +

            • address handling: addresses are not relevant to this MTM

              • +

            • subject field

              • +

            • replying

              • +

             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-236C0D1D-AC4C-5C08-9089-1AC59881CD39_d0e169182_href.jpg Binary file Symbian3/SDK/Source/GUID-236C0D1D-AC4C-5C08-9089-1AC59881CD39_d0e169182_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-236C0D1D-AC4C-5C08-9089-1AC59881CD39_d0e175783_href.jpg Binary file Symbian3/SDK/Source/GUID-236C0D1D-AC4C-5C08-9089-1AC59881CD39_d0e175783_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-238D6070-96AC-5D8A-86EA-488C59DF2AE3-GENID-1-8-1-3-1-1-9-1-4-1-9-1.dita --- a/Symbian3/SDK/Source/GUID-238D6070-96AC-5D8A-86EA-488C59DF2AE3-GENID-1-8-1-3-1-1-9-1-4-1-9-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,119 +0,0 @@ - - - - - -Detecting -Changes in the Environment -
            Introduction

            There -are two classes defined in epoc32\include\COEMAIN.H that -enable FEPs to be notified about changes in their environment: MCoeForegroundObserver and MCoeFocusObserver. CCoeFep derives from both of these classes, but does not itself -implement any of their virtual functions.

            -
            Using the MCoeForegroundObserver -class

            MCoeForegroundObserver has two (pure) -virtual functions whose signatures are as follows:

            virtual void HandleGainingForeground()=0; -virtual void HandleLosingForeground()=0;

            The purpose of this -class is to enable notification of when the application (in whose thread the -client of this class is running) goes into the foreground or background. FEPs -that have a window owning control should include the following code at the -start of their implementation of HandleGainingForeground():

            DrawableWindow()->MoveToGroup(iCoeEnv->WsSession().GetFocusWindowGroup());

            This -code switches the FEP to the window group that has gained focus. Doing this -also enables FEPs to work with applications that have more than one window -group. The HandleGainingForeground() and HandleLosingForeground() virtual -functions might also be of use to a FEP if, for example, it is required to -be invisible when the application underneath it is in the background.

            -
            Using the MCoeFocusObserver -class

            MCoeFocusObserver has two (pure) virtual -functions whose signatures are as follows:

            virtual void HandleChangeInFocus()=0; -virtual void HandleDestructionOfFocusedItem()=0;

            The purpose -of this class is to enable notification of when controls under the FEP gain -or lose focus. This notification is useful to FEPs that need to know about -the input capabilities of their target control. See the next section for information -on input capabilities.

            -
            Using the TCoeInputCapabilities -class

            The public parts of TCoeInputCapabilities (which -is defined in epoc32\include\COEINPUT.H) are as follows:

            class TCoeInputCapabilities - { -public: - enum - { - ENone=0, - EWesternNumericIntegerPositive=0x00000001, - EWesternNumericIntegerNegative=0x00000002, - EWesternNumericReal=0x00000004, - EWesternAlphabetic=0x00000008, - EJapaneseHiragana=0x00000010, - EJapaneseKatakanaHalfWidth=0x00000020, - EJapaneseKatakanaFullWidth=0x00000040, - EDialableCharacters=0x00000080, - ESecretText=0x00000100, - EAllText=0x01000000, - ENavigation=0x02000000 - }; - class MCoeFepSpecificExtensions; // to be defined by concrete FEPs, declared here -public: - IMPORT_C TCoeInputCapabilities(TUint aCapabilities); - IMPORT_C TCoeInputCapabilities(TUint aCapabilities, MCoeFepAwareTextEditor* aFepAwareTextEditor, MCoeCaptionRetrieverForFep* aCaptionRetrieverForFep); - IMPORT_C TCoeInputCapabilities(TUint aCapabilities, MCoeFepAwareTextEditor* aFepAwareTextEditor, MCoeCaptionRetrieverForFep* aCaptionRetrieverForFep, TUid aFepUid, MCoeFepSpecificExtensions* aFepSpecificExtensions); - IMPORT_C TCoeInputCapabilities(const TCoeInputCapabilities& aAnother); - IMPORT_C TCoeInputCapabilities& operator=(const TCoeInputCapabilities& aAnother); - IMPORT_C TBool operator==(const TCoeInputCapabilities& aAnother) const; - IMPORT_C TBool operator!=(const TCoeInputCapabilities& aAnother) const; - IMPORT_C void MergeWith(const TCoeInputCapabilities& aAnother); - IMPORT_C void SetCapabilities(TUint aCapabilities); - IMPORT_C TUint Capabilities() const; - IMPORT_C TBool IsNone() const; - IMPORT_C TBool SupportsWesternNumericIntegerPositive() const; - IMPORT_C TBool SupportsWesternNumericIntegerNegative() const; - IMPORT_C TBool SupportsWesternNumericReal() const; - IMPORT_C TBool SupportsWesternAlphabetic() const; - IMPORT_C TBool SupportsJapaneseHiragana() const; - IMPORT_C TBool SupportsJapaneseKatakanaHalfWidth() const; - IMPORT_C TBool SupportsJapaneseKatakanaFullWidth() const; - IMPORT_C TBool SupportsDialableCharacters() const; - IMPORT_C TBool SupportsSecretText() const; - IMPORT_C TBool SupportsAllText() const; - IMPORT_C TBool SupportsNavigation() const; - IMPORT_C MCoeFepAwareTextEditor* FepAwareTextEditor() const; - IMPORT_C MCoeCaptionRetrieverForFep* CaptionRetrieverForFep() const; - IMPORT_C MCoeFepSpecificExtensions* FepSpecificExtensions(TUid aFepUid) const; - IMPORT_C MObjectProvider* ObjectProvider() const; - IMPORT_C void SetObjectProvider(MObjectProvider* aObjectProvider); - };

            The following code initializes inputCapabilities to -the merged input capabilities of all the currently focused controls:

            TCoeInputCapabilities inputCapabilities(STATIC_CAST(CCoeAppUi*, iCoeEnv->AppUi())->InputCapabilities());

            The best place for this code is inside the overrides of MCoeFocusObserver ’s -virtual functions.

            By calling TCoeInputCapabilities's -inquiry functions, the FEP can vary its behaviour according to the input capabilities -of the target control. The Supports Xxxxx () member -functions indicate what sort of key events should be sent by the FEP to the -target control. It is important for the FEP to behave appropriately for the -capabilities of the target control(s). For example, a FEP should not allow -the user to compose a large amount of text, only to pass it on to a control -that does not support it. The FepAwareTextEditor(), CaptionRetrieverForFep() and FepSpecificExtensions() member functions return pointers to objects of the interface classes MCoeFepAwareTextEditor, MCoeCaptionRetrieverForFep and MCoeFepSpecificExtensions respectively. In each case, -a NULL return value indicates that the interface is not supported by any of -the currently focused controls.

            MCoeFepAwareTextEditor (which -is defined in epoc32\include\FEPBASE.H) is an important -and complex class, and is discussed in Close -interaction with text editor controls below.

            MCoeCaptionRetrieverForFep, -which is also defined in epoc32\include\FEPBASE.H, has -a single member function whose signature is as follows:

            virtual void GetCaptionForFep(TDes& aCaption) const=0;

            This sets aCaption to the caption of the target control. -An example of a caption is the non-editable prompt displayed alongside each -item in a dialog.

            MCoeFepSpecificExtensions is -declared in epoc32\include\COEINPUT.H within the scope -of the TCoeInputCapabilities class, although it is not -defined by any component in the Symbian platform. It is to be defined by concrete -FEPs rather than by the FEP architecture. The intention of this is to allow -applications to communicate specialized input capabilities with a particular -FEP that they know about. The concrete FEP would define the class in a public -header file which then can be used by the relevant applications. Note that -the TCoeInputCapabilities constructor which takes a MCoeFepSpecificExtensions pointer, -and also the inquiry function returning a MCoeFepSpecificExtensions pointer -both require the UID of the FEP defining this class to be passed. This is -to ensure that the FEP and the application are both assuming the same definition -of the MCoeFepSpecificExtensions class.

            -             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-238D6070-96AC-5D8A-86EA-488C59DF2AE3-GENID-1-8-1-6-1-1-4-1-8-1-4-1-9-1.dita --- a/Symbian3/SDK/Source/GUID-238D6070-96AC-5D8A-86EA-488C59DF2AE3-GENID-1-8-1-6-1-1-4-1-8-1-4-1-9-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,119 +0,0 @@ - - - - - -Detecting -Changes in the Environment -
            Introduction

            There -are two classes defined in epoc32\include\COEMAIN.H that -enable FEPs to be notified about changes in their environment: MCoeForegroundObserver and MCoeFocusObserver. CCoeFep derives from both of these classes, but does not itself -implement any of their virtual functions.

            -
            Using the MCoeForegroundObserver -class

            MCoeForegroundObserver has two (pure) -virtual functions whose signatures are as follows:

            virtual void HandleGainingForeground()=0; -virtual void HandleLosingForeground()=0;

            The purpose of this -class is to enable notification of when the application (in whose thread the -client of this class is running) goes into the foreground or background. FEPs -that have a window owning control should include the following code at the -start of their implementation of HandleGainingForeground():

            DrawableWindow()->MoveToGroup(iCoeEnv->WsSession().GetFocusWindowGroup());

            This -code switches the FEP to the window group that has gained focus. Doing this -also enables FEPs to work with applications that have more than one window -group. The HandleGainingForeground() and HandleLosingForeground() virtual -functions might also be of use to a FEP if, for example, it is required to -be invisible when the application underneath it is in the background.

            -
            Using the MCoeFocusObserver -class

            MCoeFocusObserver has two (pure) virtual -functions whose signatures are as follows:

            virtual void HandleChangeInFocus()=0; -virtual void HandleDestructionOfFocusedItem()=0;

            The purpose -of this class is to enable notification of when controls under the FEP gain -or lose focus. This notification is useful to FEPs that need to know about -the input capabilities of their target control. See the next section for information -on input capabilities.

            -
            Using the TCoeInputCapabilities -class

            The public parts of TCoeInputCapabilities (which -is defined in epoc32\include\COEINPUT.H) are as follows:

            class TCoeInputCapabilities - { -public: - enum - { - ENone=0, - EWesternNumericIntegerPositive=0x00000001, - EWesternNumericIntegerNegative=0x00000002, - EWesternNumericReal=0x00000004, - EWesternAlphabetic=0x00000008, - EJapaneseHiragana=0x00000010, - EJapaneseKatakanaHalfWidth=0x00000020, - EJapaneseKatakanaFullWidth=0x00000040, - EDialableCharacters=0x00000080, - ESecretText=0x00000100, - EAllText=0x01000000, - ENavigation=0x02000000 - }; - class MCoeFepSpecificExtensions; // to be defined by concrete FEPs, declared here -public: - IMPORT_C TCoeInputCapabilities(TUint aCapabilities); - IMPORT_C TCoeInputCapabilities(TUint aCapabilities, MCoeFepAwareTextEditor* aFepAwareTextEditor, MCoeCaptionRetrieverForFep* aCaptionRetrieverForFep); - IMPORT_C TCoeInputCapabilities(TUint aCapabilities, MCoeFepAwareTextEditor* aFepAwareTextEditor, MCoeCaptionRetrieverForFep* aCaptionRetrieverForFep, TUid aFepUid, MCoeFepSpecificExtensions* aFepSpecificExtensions); - IMPORT_C TCoeInputCapabilities(const TCoeInputCapabilities& aAnother); - IMPORT_C TCoeInputCapabilities& operator=(const TCoeInputCapabilities& aAnother); - IMPORT_C TBool operator==(const TCoeInputCapabilities& aAnother) const; - IMPORT_C TBool operator!=(const TCoeInputCapabilities& aAnother) const; - IMPORT_C void MergeWith(const TCoeInputCapabilities& aAnother); - IMPORT_C void SetCapabilities(TUint aCapabilities); - IMPORT_C TUint Capabilities() const; - IMPORT_C TBool IsNone() const; - IMPORT_C TBool SupportsWesternNumericIntegerPositive() const; - IMPORT_C TBool SupportsWesternNumericIntegerNegative() const; - IMPORT_C TBool SupportsWesternNumericReal() const; - IMPORT_C TBool SupportsWesternAlphabetic() const; - IMPORT_C TBool SupportsJapaneseHiragana() const; - IMPORT_C TBool SupportsJapaneseKatakanaHalfWidth() const; - IMPORT_C TBool SupportsJapaneseKatakanaFullWidth() const; - IMPORT_C TBool SupportsDialableCharacters() const; - IMPORT_C TBool SupportsSecretText() const; - IMPORT_C TBool SupportsAllText() const; - IMPORT_C TBool SupportsNavigation() const; - IMPORT_C MCoeFepAwareTextEditor* FepAwareTextEditor() const; - IMPORT_C MCoeCaptionRetrieverForFep* CaptionRetrieverForFep() const; - IMPORT_C MCoeFepSpecificExtensions* FepSpecificExtensions(TUid aFepUid) const; - IMPORT_C MObjectProvider* ObjectProvider() const; - IMPORT_C void SetObjectProvider(MObjectProvider* aObjectProvider); - };

            The following code initializes inputCapabilities to -the merged input capabilities of all the currently focused controls:

            TCoeInputCapabilities inputCapabilities(STATIC_CAST(CCoeAppUi*, iCoeEnv->AppUi())->InputCapabilities());

            The best place for this code is inside the overrides of MCoeFocusObserver ’s -virtual functions.

            By calling TCoeInputCapabilities's -inquiry functions, the FEP can vary its behaviour according to the input capabilities -of the target control. The Supports Xxxxx () member -functions indicate what sort of key events should be sent by the FEP to the -target control. It is important for the FEP to behave appropriately for the -capabilities of the target control(s). For example, a FEP should not allow -the user to compose a large amount of text, only to pass it on to a control -that does not support it. The FepAwareTextEditor(), CaptionRetrieverForFep() and FepSpecificExtensions() member functions return pointers to objects of the interface classes MCoeFepAwareTextEditor, MCoeCaptionRetrieverForFep and MCoeFepSpecificExtensions respectively. In each case, -a NULL return value indicates that the interface is not supported by any of -the currently focused controls.

            MCoeFepAwareTextEditor (which -is defined in epoc32\include\FEPBASE.H) is an important -and complex class, and is discussed in Close -interaction with text editor controls below.

            MCoeCaptionRetrieverForFep, -which is also defined in epoc32\include\FEPBASE.H, has -a single member function whose signature is as follows:

            virtual void GetCaptionForFep(TDes& aCaption) const=0;

            This sets aCaption to the caption of the target control. -An example of a caption is the non-editable prompt displayed alongside each -item in a dialog.

            MCoeFepSpecificExtensions is -declared in epoc32\include\COEINPUT.H within the scope -of the TCoeInputCapabilities class, although it is not -defined by any component in the Symbian platform. It is to be defined by concrete -FEPs rather than by the FEP architecture. The intention of this is to allow -applications to communicate specialized input capabilities with a particular -FEP that they know about. The concrete FEP would define the class in a public -header file which then can be used by the relevant applications. Note that -the TCoeInputCapabilities constructor which takes a MCoeFepSpecificExtensions pointer, -and also the inquiry function returning a MCoeFepSpecificExtensions pointer -both require the UID of the FEP defining this class to be passed. This is -to ensure that the FEP and the application are both assuming the same definition -of the MCoeFepSpecificExtensions class.

            -             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-238D6070-96AC-5D8A-86EA-488C59DF2AE3.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-238D6070-96AC-5D8A-86EA-488C59DF2AE3.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,119 @@ + + + + + +Detecting +Changes in the Environment +
            Introduction

            There +are two classes defined in epoc32\include\COEMAIN.H that +enable FEPs to be notified about changes in their environment: MCoeForegroundObserver and MCoeFocusObserver. CCoeFep derives from both of these classes, but does not itself +implement any of their virtual functions.

            +
            Using the MCoeForegroundObserver +class

            MCoeForegroundObserver has two (pure) +virtual functions whose signatures are as follows:

            virtual void HandleGainingForeground()=0; +virtual void HandleLosingForeground()=0;

            The purpose of this +class is to enable notification of when the application (in whose thread the +client of this class is running) goes into the foreground or background. FEPs +that have a window owning control should include the following code at the +start of their implementation of HandleGainingForeground():

            DrawableWindow()->MoveToGroup(iCoeEnv->WsSession().GetFocusWindowGroup());

            This +code switches the FEP to the window group that has gained focus. Doing this +also enables FEPs to work with applications that have more than one window +group. The HandleGainingForeground() and HandleLosingForeground() virtual +functions might also be of use to a FEP if, for example, it is required to +be invisible when the application underneath it is in the background.

            +
            Using the MCoeFocusObserver +class

            MCoeFocusObserver has two (pure) virtual +functions whose signatures are as follows:

            virtual void HandleChangeInFocus()=0; +virtual void HandleDestructionOfFocusedItem()=0;

            The purpose +of this class is to enable notification of when controls under the FEP gain +or lose focus. This notification is useful to FEPs that need to know about +the input capabilities of their target control. See the next section for information +on input capabilities.

            +
            Using the TCoeInputCapabilities +class

            The public parts of TCoeInputCapabilities (which +is defined in epoc32\include\COEINPUT.H) are as follows:

            class TCoeInputCapabilities + { +public: + enum + { + ENone=0, + EWesternNumericIntegerPositive=0x00000001, + EWesternNumericIntegerNegative=0x00000002, + EWesternNumericReal=0x00000004, + EWesternAlphabetic=0x00000008, + EJapaneseHiragana=0x00000010, + EJapaneseKatakanaHalfWidth=0x00000020, + EJapaneseKatakanaFullWidth=0x00000040, + EDialableCharacters=0x00000080, + ESecretText=0x00000100, + EAllText=0x01000000, + ENavigation=0x02000000 + }; + class MCoeFepSpecificExtensions; // to be defined by concrete FEPs, declared here +public: + IMPORT_C TCoeInputCapabilities(TUint aCapabilities); + IMPORT_C TCoeInputCapabilities(TUint aCapabilities, MCoeFepAwareTextEditor* aFepAwareTextEditor, MCoeCaptionRetrieverForFep* aCaptionRetrieverForFep); + IMPORT_C TCoeInputCapabilities(TUint aCapabilities, MCoeFepAwareTextEditor* aFepAwareTextEditor, MCoeCaptionRetrieverForFep* aCaptionRetrieverForFep, TUid aFepUid, MCoeFepSpecificExtensions* aFepSpecificExtensions); + IMPORT_C TCoeInputCapabilities(const TCoeInputCapabilities& aAnother); + IMPORT_C TCoeInputCapabilities& operator=(const TCoeInputCapabilities& aAnother); + IMPORT_C TBool operator==(const TCoeInputCapabilities& aAnother) const; + IMPORT_C TBool operator!=(const TCoeInputCapabilities& aAnother) const; + IMPORT_C void MergeWith(const TCoeInputCapabilities& aAnother); + IMPORT_C void SetCapabilities(TUint aCapabilities); + IMPORT_C TUint Capabilities() const; + IMPORT_C TBool IsNone() const; + IMPORT_C TBool SupportsWesternNumericIntegerPositive() const; + IMPORT_C TBool SupportsWesternNumericIntegerNegative() const; + IMPORT_C TBool SupportsWesternNumericReal() const; + IMPORT_C TBool SupportsWesternAlphabetic() const; + IMPORT_C TBool SupportsJapaneseHiragana() const; + IMPORT_C TBool SupportsJapaneseKatakanaHalfWidth() const; + IMPORT_C TBool SupportsJapaneseKatakanaFullWidth() const; + IMPORT_C TBool SupportsDialableCharacters() const; + IMPORT_C TBool SupportsSecretText() const; + IMPORT_C TBool SupportsAllText() const; + IMPORT_C TBool SupportsNavigation() const; + IMPORT_C MCoeFepAwareTextEditor* FepAwareTextEditor() const; + IMPORT_C MCoeCaptionRetrieverForFep* CaptionRetrieverForFep() const; + IMPORT_C MCoeFepSpecificExtensions* FepSpecificExtensions(TUid aFepUid) const; + IMPORT_C MObjectProvider* ObjectProvider() const; + IMPORT_C void SetObjectProvider(MObjectProvider* aObjectProvider); + };

            The following code initializes inputCapabilities to +the merged input capabilities of all the currently focused controls:

            TCoeInputCapabilities inputCapabilities(STATIC_CAST(CCoeAppUi*, iCoeEnv->AppUi())->InputCapabilities());

            The best place for this code is inside the overrides of MCoeFocusObserver ’s +virtual functions.

            By calling TCoeInputCapabilities's +inquiry functions, the FEP can vary its behaviour according to the input capabilities +of the target control. The Supports Xxxxx () member +functions indicate what sort of key events should be sent by the FEP to the +target control. It is important for the FEP to behave appropriately for the +capabilities of the target control(s). For example, a FEP should not allow +the user to compose a large amount of text, only to pass it on to a control +that does not support it. The FepAwareTextEditor(), CaptionRetrieverForFep() and FepSpecificExtensions() member functions return pointers to objects of the interface classes MCoeFepAwareTextEditor, MCoeCaptionRetrieverForFep and MCoeFepSpecificExtensions respectively. In each case, +a NULL return value indicates that the interface is not supported by any of +the currently focused controls.

            MCoeFepAwareTextEditor (which +is defined in epoc32\include\FEPBASE.H) is an important +and complex class, and is discussed in Close +interaction with text editor controls below.

            MCoeCaptionRetrieverForFep, +which is also defined in epoc32\include\FEPBASE.H, has +a single member function whose signature is as follows:

            virtual void GetCaptionForFep(TDes& aCaption) const=0;

            This sets aCaption to the caption of the target control. +An example of a caption is the non-editable prompt displayed alongside each +item in a dialog.

            MCoeFepSpecificExtensions is +declared in epoc32\include\COEINPUT.H within the scope +of the TCoeInputCapabilities class, although it is not +defined by any component in the Symbian platform. It is to be defined by concrete +FEPs rather than by the FEP architecture. The intention of this is to allow +applications to communicate specialized input capabilities with a particular +FEP that they know about. The concrete FEP would define the class in a public +header file which then can be used by the relevant applications. Note that +the TCoeInputCapabilities constructor which takes a MCoeFepSpecificExtensions pointer, +and also the inquiry function returning a MCoeFepSpecificExtensions pointer +both require the UID of the FEP defining this class to be passed. This is +to ensure that the FEP and the application are both assuming the same definition +of the MCoeFepSpecificExtensions class.

            +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-239B8B32-5816-575E-97B1-FF7B68BC7575_d0e114300_href.png Binary file Symbian3/SDK/Source/GUID-239B8B32-5816-575E-97B1-FF7B68BC7575_d0e114300_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-239B8B32-5816-575E-97B1-FF7B68BC7575_d0e120838_href.png Binary file Symbian3/SDK/Source/GUID-239B8B32-5816-575E-97B1-FF7B68BC7575_d0e120838_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-24039DCE-B5C4-46CB-9E02-AB421C64FB87.dita --- a/Symbian3/SDK/Source/GUID-24039DCE-B5C4-46CB-9E02-AB421C64FB87.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-24039DCE-B5C4-46CB-9E02-AB421C64FB87.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,53 +1,53 @@ - - - - - -Relationship -between window controls -

            When a control draws in the window of another control, the position -is relative to that window. If a control owns a window that is a child of -another window, that control's position is relative to the parent window; -however, if that control is a compound control, its child control's coordinates -are relative to its own parent control window position. Top-level window-owning -controls are displayed using a position relative to the display. In other -words, it uses the physical coordinates of the display.

            -

            The following figure illustrates this relationship.

            -Relative positions of three controls where the top-level parent owns -the window -

            Consider three controls, A, B, and C (shown in -the figure above):

            -
              -

            • A is a top-level control and owns a window

              -
              • -

            • Child controls B and C do not create their -own windows in this example.

              • -

            • B, a child control of A, does not create a -window, and it has a child control, C.

              - -

              B's window is set calling the CCoeControl::SetContainerWindowL(A) method -and C's window is set with CCoeControl::SetContainerWindowL(B). -Then C's position (p) is relative to A, since it is the actual -window owner. A's position (m) is relative to the display position.

              -               -
              • -
            -

            However, if B is a child control of A but also has a window -of its own, it is a child window of A's window (as shown in the following -figure). Then if C is a child of B and sets its window by calling CCoeControl::SetContainerWindowL(B), -the position of C (p') is relative to B's window.

            -Relative positions of three controls where a child owns a window -

            As the example illustrates, a control position depends on the window -in which it is drawn. Therefore, you need to know the drawing window for each -control. It is an important issue when designing a UI layout. There are some -common controls that optionally may have their own window, such as menus, -dialogs, and scroll bars. The application framework handles drawing these -controls, as long as the appropriate resources and flags have been set. The CCoeControl::OwnsWindow() call -can be used to detect whether a control owns a window or not.

            + + + + + +Relationship +between window controls +

            When a control draws in the window of another control, the position +is relative to that window. If a control owns a window that is a child of +another window, that control's position is relative to the parent window; +however, if that control is a compound control, its child control's coordinates +are relative to its own parent control window position. Top-level window-owning +controls are displayed using a position relative to the display. In other +words, it uses the physical coordinates of the display.

            +

            The following figure illustrates this relationship.

            +Relative positions of three controls where the top-level parent owns +the window +

            Consider three controls, A, B, and C (shown in +the figure above):

            +
              +

            • A is a top-level control and owns a window

              +
              • +

            • Child controls B and C do not create their +own windows in this example.

              • +

            • B, a child control of A, does not create a +window, and it has a child control, C.

              + +

              B's window is set calling the CCoeControl::SetContainerWindowL(A) method +and C's window is set with CCoeControl::SetContainerWindowL(B). +Then C's position (p) is relative to A, since it is the actual +window owner. A's position (m) is relative to the display position.

              +               +
              • +
            +

            However, if B is a child control of A but also has a window +of its own, it is a child window of A's window (as shown in the following +figure). Then if C is a child of B and sets its window by calling CCoeControl::SetContainerWindowL(B), +the position of C (p') is relative to B's window.

            +Relative positions of three controls where a child owns a window +

            As the example illustrates, a control position depends on the window +in which it is drawn. Therefore, you need to know the drawing window for each +control. It is an important issue when designing a UI layout. There are some +common controls that optionally may have their own window, such as menus, +dialogs, and scroll bars. The application framework handles drawing these +controls, as long as the appropriate resources and flags have been set. The CCoeControl::OwnsWindow() call +can be used to detect whether a control owns a window or not.

             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2418E86F-BF82-4F2A-A056-5F1D0682C410.dita --- a/Symbian3/SDK/Source/GUID-2418E86F-BF82-4F2A-A056-5F1D0682C410.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,16 +0,0 @@ - - - - - -Changes -and release information -

            The Stylus pop-up menu API is an SDK API and first released in S60 5th -Edition.

            -             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-244631CF-03F9-4C48-9802-682A76E9ECCC.dita --- a/Symbian3/SDK/Source/GUID-244631CF-03F9-4C48-9802-682A76E9ECCC.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-244631CF-03F9-4C48-9802-682A76E9ECCC.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,87 +1,87 @@ - - - - - -Hiding -item-specific commands in submenusThis document describes the changes required to your application's -code for hiding item-specific commands in submenus. - -You can hide item-specific -commands in submenus in either of the following ways: - -

            Add the EEikMenuItemSpecific flag to submenu resource -definitions. As a result, the submenu items are displayed in the stylus pop-up -menu at the same level as main menu items.

            RESOURCE MENU_PANE r_calendarapiexample_entries_menu_option - { - items = - { - MENU_ITEM - { - command = ECalendarAPIexampleOption; - txt = qtn_options_option; - cascade = r_calendarapiexample_entries_menu; - // ----Add the following line----- - flags = EEikMenuItemSpecific; - //-------------------------------------- - }, - MENU_ITEM - { - command = ECalendarAPIexampleDeleteAll; - txt = qtn_options_delet_all; - } - }; - } -RESOURCE MENU_PANE r_calendarapiexample_entries_menu - { - items = - { - MENU_ITEM { command = ECalendarAPIexampleCmdDelete; txt = qtn_options_delete;} - }; - }

            For example, the following illustrations show how the -item-specific submenu item (Delete) is hidden in the -options menu and displayed in the stylus pop-up menu by setting the EEikMenuItemSpecific flag.

            - Before setting the EEikMenuItemSpecific flag - - -After setting the EEikMenuItemSpecific flag - -             -

            Add the EEikMenuItemSpecificListQuery flag to -submenu resource definitions. As a result, the submenu items are displayed -in a list query dialog box within stylus pop-up menus.

            RESOURCE MENU_PANE r_calendarapiexample_entries_menu_option - { - items = - { - MENU_ITEM - { - command = ECalendarAPIexampleOption; - txt = qtn_options_option; - cascade = r_calendarapiexample_entries_menu; - //----Add the following line---------- - flags = EEikMenuItemSpecificListQuery; - //--------------------------------------- - }, - MENU_ITEM - { - command = ECalendarAPIexampleDeleteAll; - txt = qtn_options_delet_all; - } - }; - } -

            For example, the following illustration shows how the Delete command -is displayed in the list query dialog box under option by -setting the EEikMenuItemSpecificListQuery flag.

            -After setting the EEikMenuItemSpecificListQuery flag - -             -             -             -             + + + + + +Hiding +item-specific commands in submenusThis document describes the changes required to your application's +code for hiding item-specific commands in submenus. + +You can hide item-specific +commands in submenus in either of the following ways: + +

            Add the EEikMenuItemSpecific flag to submenu resource +definitions. As a result, the submenu items are displayed in the stylus pop-up +menu at the same level as main menu items.

            RESOURCE MENU_PANE r_calendarapiexample_entries_menu_option + { + items = + { + MENU_ITEM + { + command = ECalendarAPIexampleOption; + txt = qtn_options_option; + cascade = r_calendarapiexample_entries_menu; + // ----Add the following line----- + flags = EEikMenuItemSpecific; + //-------------------------------------- + }, + MENU_ITEM + { + command = ECalendarAPIexampleDeleteAll; + txt = qtn_options_delet_all; + } + }; + } +RESOURCE MENU_PANE r_calendarapiexample_entries_menu + { + items = + { + MENU_ITEM { command = ECalendarAPIexampleCmdDelete; txt = qtn_options_delete;} + }; + }

            For example, the following illustrations show how the +item-specific submenu item (Delete) is hidden in the +options menu and displayed in the stylus pop-up menu by setting the EEikMenuItemSpecific flag.

            + Before setting the EEikMenuItemSpecific flag + + +After setting the EEikMenuItemSpecific flag + +             +

            Add the EEikMenuItemSpecificListQuery flag to +submenu resource definitions. As a result, the submenu items are displayed +in a list query dialog box within stylus pop-up menus.

            RESOURCE MENU_PANE r_calendarapiexample_entries_menu_option + { + items = + { + MENU_ITEM + { + command = ECalendarAPIexampleOption; + txt = qtn_options_option; + cascade = r_calendarapiexample_entries_menu; + //----Add the following line---------- + flags = EEikMenuItemSpecificListQuery; + //--------------------------------------- + }, + MENU_ITEM + { + command = ECalendarAPIexampleDeleteAll; + txt = qtn_options_delet_all; + } + }; + } +

            For example, the following illustration shows how the Delete command +is displayed in the list query dialog box under option by +setting the EEikMenuItemSpecificListQuery flag.

            +After setting the EEikMenuItemSpecificListQuery flag + +             +             +             +                         \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-24508C2D-31B9-5CC2-9EB8-F00AD39D8AA0.dita --- a/Symbian3/SDK/Source/GUID-24508C2D-31B9-5CC2-9EB8-F00AD39D8AA0.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-24508C2D-31B9-5CC2-9EB8-F00AD39D8AA0.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,32 +1,32 @@ - - - - - -Notification -Services Overview -
            Purpose

            Provides miscellaneous low-level -services for notifying programs of environment changes and of thread deaths, -and for putting simple messages on screen.

            -
            Description

            The API has three key concepts: change -notifier, thread-death notifier, and simple screen output service.

            Change -notifier

            The change notifier signals the requesting thread's request -semaphore when a change in the environment occurs, such as a switch in locale, -or system time being reset.

            The change notifier interface is provided -by RChangeNotifier.

            Note that the Environment Change -Notifier API provides the same service, wrapped in an active object.

            Thread-death notifier

            The thread-death notifier signals the -requesting thread's request semaphore when a specified other thread terminates.

            The -thread-death notifier interface is provided by RUndertaker.

            Simple screen output service

            The simple screen output service -allows either a single line message or a simple dialog box to be displayed -on the screen. It is typically used for debug messages.

            The simple -screen output service interface is provided by RNotifier, -which also provides access to the UI-specific plug-in notifiers, via the Extended Notifier Framework.

            -
            See also

            Environment -Change Notifier Overview

            + + + + + +Notification +Services Overview +
            Purpose

            Provides miscellaneous low-level +services for notifying programs of environment changes and of thread deaths, +and for putting simple messages on screen.

            +
            Description

            The API has three key concepts: change +notifier, thread-death notifier, and simple screen output service.

            Change +notifier

            The change notifier signals the requesting thread's request +semaphore when a change in the environment occurs, such as a switch in locale, +or system time being reset.

            The change notifier interface is provided +by RChangeNotifier.

            Note that the Environment Change +Notifier API provides the same service, wrapped in an active object.

            Thread-death notifier

            The thread-death notifier signals the +requesting thread's request semaphore when a specified other thread terminates.

            The +thread-death notifier interface is provided by RUndertaker.

            Simple screen output service

            The simple screen output service +allows either a single line message or a simple dialog box to be displayed +on the screen. It is typically used for debug messages.

            The simple +screen output service interface is provided by RNotifier, +which also provides access to the UI-specific plug-in notifiers, via the Extended Notifier Framework.

            +
            See also

            Environment +Change Notifier Overview

            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-245FC4CA-EB57-5745-AD2E-79E33D43D912_d0e220109_href.png Binary file Symbian3/SDK/Source/GUID-245FC4CA-EB57-5745-AD2E-79E33D43D912_d0e220109_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-245FC4CA-EB57-5745-AD2E-79E33D43D912_d0e223846_href.png Binary file Symbian3/SDK/Source/GUID-245FC4CA-EB57-5745-AD2E-79E33D43D912_d0e223846_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2468821F-6C66-5761-AE56-CEC942A2EE95_d0e194954_href.png Binary file Symbian3/SDK/Source/GUID-2468821F-6C66-5761-AE56-CEC942A2EE95_d0e194954_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2468821F-6C66-5761-AE56-CEC942A2EE95_d0e199962_href.png Binary file Symbian3/SDK/Source/GUID-2468821F-6C66-5761-AE56-CEC942A2EE95_d0e199962_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2472E5E0-C33A-51B4-8210-89D7DEFA87C8_d0e215812_href.png Binary file Symbian3/SDK/Source/GUID-2472E5E0-C33A-51B4-8210-89D7DEFA87C8_d0e215812_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2472E5E0-C33A-51B4-8210-89D7DEFA87C8_d0e219549_href.png Binary file Symbian3/SDK/Source/GUID-2472E5E0-C33A-51B4-8210-89D7DEFA87C8_d0e219549_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-24860917-0FE2-5C8F-B436-96928350996E.dita --- a/Symbian3/SDK/Source/GUID-24860917-0FE2-5C8F-B436-96928350996E.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-24860917-0FE2-5C8F-B436-96928350996E.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,150 +1,150 @@ - - - - - -Bearer -Mobility Overview -

            Bearer mobility allows the email Message Type Modules (MTM) to non-seamlessly -switch between networking bearers, such as, GPRS, WiFi, CDMA, GSM, and so -on. Switching between network bearers enables destination networks to connect -without dropping the connection with the remote server.

            -

            The POP3, IMAP4 and SMTP email server MTMs support this functionality.

            -
            Description

            The -bearer mobility must be enabled in the Networking bearer mobility framework -to provide bearer mobility functionality in the Messaging Application module.

            After -the bearer mobility is set for the email server MTMs at the client-side using -the SetBearerMobility function, the bearer mobility manager -registers with the bearer mobility framework in the Networking subsystem. -This informs the bearer mobility manager about any change in the bearers.

            The -bearer mobility plug-in gets the notifications about the change in the bearer. -When the required bearer is available, the server MTMs uses this plug-in to -get notifications. The following illustration shows the architecture of the -bearer mobility implementation in the Messaging Application module.

            - Architecture of Bearer Mobility - -
            -
            Settings

            The email client MTM CEmailAccounts interfaces -are enhanced to configure the email account settings. These settings modify -the behaviour of the relevant server MTMs for the following functionality:

            Non-seamless -bearer mobility

            The IMAP4, POP3, and SMTP server MTMs are extended -to allow messaging applications to use the non-seamless network bearer mobility -when connecting to a destination network using the respective protocols. The -following functions are added to the CImBaseEmailSettings (CImPop3Settings, CImImap4Settings, and CImSmtpSettings) class:

              -

            • SetBearerMobility

              • -

            • BearerMobility()

              • -

            Per bearer-type -configuration for IMAP email accounts

            Specifically for IMAP email -accounts, the CEmailAccounts class enables the following -per bearer-type configuration that affect the behaviour of IMAP accounts:

              -

            • Download rules

              Download -rules specify which parts of message to automatically download (according -to bearer type) when synchronising the contents of an IMAP email account. -You can configure an IMAP email account for IMAP download rules on each bearer -type and for each account using the CImapSyncDownloadRules class.

              When -synchronising an IMAP email account you can do the following:

                -

              • Indicate that a list -of email download rules for each type of bearer must be used during the email -account synchronisations.

                • -

              • Retrieve emails during -the synchronisation using the mail options specified in the list for the bearer -type that is currently in use by the connection to the server.

                • -

              The CImapSyncDownloadRules class is used to store -per IMAP account sync download rules. This class describes the download rules -that provide the ability to automatically get the email content. This is configurable -on a per account and per bearer-type basis.

                -

              • Different download rules -can be specified for different bearers. For example, you can specify that -all text and attachments should be retrieved when connecting through a WiFi -connection; whereas, only text parts should be retrieved when connecting over -GPRS connection.

                • -

              • Synchronisation is performed -in two stages: the email header synchronisation is performed first followed -by the email content retrieval. If the email account settings indicate that -the per-bearer-type list should not be used, or no per-bearer-type list is -defined, or the current bearer type is not listed in the per-bearer-type list, -then during the synchronisation the email headers for inbox and personal folders -are downloaded.

                Note: The per-bearer-type list is a set of -IMAP download and transport buffer size rules defined for each type of bearer.

                • -

              • Messages that are not -previously populated are retrieved using this method. So a message that has -been populated according to GPRS settings will not be retrieved again according -to WiFi settings, if a subsequent connection is made.

                • -

              • Messages that arrive -on the server while IMAP is in the IDLE state are also automatically -downloaded according to the Inbox download rules for the connected bearer -type.

                • -

              • A single instance of -a set of download rules is applicable to multiple bearer types.

                • -
              • -

            • Transport buffer -size

              Transport buffer size specifies the size of the data transferred -from server to client to get email body and attachments from an IMAP server -using a per bearer-type list of transport buffer sizes. You can configure -an IMAP account for IMAP transport buffer size on each bearer type using the CImapTransportBufferSizes class.

              The -per-bearer-type list is a set of IMAP download and transport buffer size rules -defined for each type of bearer.

              This class allows a client to -configure transport buffer sizes of IMAP accounts according to the bearer -type for retrieving large message parts. It is possible to specify in the -following:

                -

              • Maximum retrieve size. -Default is 20480 octets.

                • -

              • Maximum outstanding -retrieve requests. Default is two outstanding requests.

                • -

              Important considerations

                -

              • If there are is no bearer -type specific list defined, or the current bearer type is not listed in the -per-bearer-type list of transport buffer sizes, then the maximum retrieve -request size specified in the email account settings is used. The maximum -and default number of outstanding retrieve requests is two.

                • -

              • The transport buffer -sizes that can be specified are the maximum retrieve request size sent in -IMAP retrieve requests.

                • -

              • Download email body -and attachments from an IMAP server using the retrieve request buffer size -specific to the bearer type that the server connection is using.

                • -

              • Download email body -and attachments from an IMAP server using the maximum number of outstanding -retrieve requests specific to the bearer type that the server connection is -using.

                • -

              • A single instance of -a set of transport buffer sizes is applicable to multiple bearer types.

                • -
              • -

            Bearer mobility policy plug-in

            The bearer mobility -policy plug-in enables you to customise the migration behaviour of email accounts, -the bearer mobility policy plug-in is provided. It consists of an ECOM interface -class (CImMobilityPolicyPlugin) and a call-back class (MImMobilityPolicyHandler),which -allows the plug-in to issue policy decisions on an individual mobility events.

            -
            Important considerations
              -

            • To enable bearer mobility, -you must first enable it at the Networking bearer mobility framework.

              • -

            • Bearer mobility is possible -only on the connections that are established using a SNAP preference list.

              • -

            • To use the bearer mobility, -you must configure the email account settings to specify the SNAP preference -when creating the RConnection notification (events).

              • -

            • Multiple SNAP preferences -for each service entry is not supported.

              • -

            • It is not possible to -specify both IAPs and a SNAP for a single email account. The API for setting -a SNAP preference clears any provisioned IAPs. Likewise, the API for setting -IAPs are updated to clear any SNAP preference that is set.

              • -
            -             -SNAP Preferences - -Configuring -Non-seamless Bearer Mobility -Configuring -TLS or SSL Socket -SMTP Account -Override Settings -IMAP Account -Settings + + + + + +Bearer +Mobility Overview +

            Bearer mobility allows the email Message Type Modules (MTM) to non-seamlessly +switch between networking bearers, such as, GPRS, WiFi, CDMA, GSM, and so +on. Switching between network bearers enables destination networks to connect +without dropping the connection with the remote server.

            +

            The POP3, IMAP4 and SMTP email server MTMs support this functionality.

            +
            Description

            The +bearer mobility must be enabled in the Networking bearer mobility framework +to provide bearer mobility functionality in the Messaging Application module.

            After +the bearer mobility is set for the email server MTMs at the client-side using +the SetBearerMobility function, the bearer mobility manager +registers with the bearer mobility framework in the Networking subsystem. +This informs the bearer mobility manager about any change in the bearers.

            The +bearer mobility plug-in gets the notifications about the change in the bearer. +When the required bearer is available, the server MTMs uses this plug-in to +get notifications. The following illustration shows the architecture of the +bearer mobility implementation in the Messaging Application module.

            + Architecture of Bearer Mobility + +
            +
            Settings

            The email client MTM CEmailAccounts interfaces +are enhanced to configure the email account settings. These settings modify +the behaviour of the relevant server MTMs for the following functionality:

            Non-seamless +bearer mobility

            The IMAP4, POP3, and SMTP server MTMs are extended +to allow messaging applications to use the non-seamless network bearer mobility +when connecting to a destination network using the respective protocols. The +following functions are added to the CImBaseEmailSettings (CImPop3Settings, CImImap4Settings, and CImSmtpSettings) class:

              +

            • SetBearerMobility

              • +

            • BearerMobility()

              • +

            Per bearer-type +configuration for IMAP email accounts

            Specifically for IMAP email +accounts, the CEmailAccounts class enables the following +per bearer-type configuration that affect the behaviour of IMAP accounts:

              +

            • Download rules

              Download +rules specify which parts of message to automatically download (according +to bearer type) when synchronising the contents of an IMAP email account. +You can configure an IMAP email account for IMAP download rules on each bearer +type and for each account using the CImapSyncDownloadRules class.

              When +synchronising an IMAP email account you can do the following:

                +

              • Indicate that a list +of email download rules for each type of bearer must be used during the email +account synchronisations.

                • +

              • Retrieve emails during +the synchronisation using the mail options specified in the list for the bearer +type that is currently in use by the connection to the server.

                • +

              The CImapSyncDownloadRules class is used to store +per IMAP account sync download rules. This class describes the download rules +that provide the ability to automatically get the email content. This is configurable +on a per account and per bearer-type basis.

                +

              • Different download rules +can be specified for different bearers. For example, you can specify that +all text and attachments should be retrieved when connecting through a WiFi +connection; whereas, only text parts should be retrieved when connecting over +GPRS connection.

                • +

              • Synchronisation is performed +in two stages: the email header synchronisation is performed first followed +by the email content retrieval. If the email account settings indicate that +the per-bearer-type list should not be used, or no per-bearer-type list is +defined, or the current bearer type is not listed in the per-bearer-type list, +then during the synchronisation the email headers for inbox and personal folders +are downloaded.

                Note: The per-bearer-type list is a set of +IMAP download and transport buffer size rules defined for each type of bearer.

                • +

              • Messages that are not +previously populated are retrieved using this method. So a message that has +been populated according to GPRS settings will not be retrieved again according +to WiFi settings, if a subsequent connection is made.

                • +

              • Messages that arrive +on the server while IMAP is in the IDLE state are also automatically +downloaded according to the Inbox download rules for the connected bearer +type.

                • +

              • A single instance of +a set of download rules is applicable to multiple bearer types.

                • +
              • +

            • Transport buffer +size

              Transport buffer size specifies the size of the data transferred +from server to client to get email body and attachments from an IMAP server +using a per bearer-type list of transport buffer sizes. You can configure +an IMAP account for IMAP transport buffer size on each bearer type using the CImapTransportBufferSizes class.

              The +per-bearer-type list is a set of IMAP download and transport buffer size rules +defined for each type of bearer.

              This class allows a client to +configure transport buffer sizes of IMAP accounts according to the bearer +type for retrieving large message parts. It is possible to specify in the +following:

                +

              • Maximum retrieve size. +Default is 20480 octets.

                • +

              • Maximum outstanding +retrieve requests. Default is two outstanding requests.

                • +

              Important considerations

                +

              • If there are is no bearer +type specific list defined, or the current bearer type is not listed in the +per-bearer-type list of transport buffer sizes, then the maximum retrieve +request size specified in the email account settings is used. The maximum +and default number of outstanding retrieve requests is two.

                • +

              • The transport buffer +sizes that can be specified are the maximum retrieve request size sent in +IMAP retrieve requests.

                • +

              • Download email body +and attachments from an IMAP server using the retrieve request buffer size +specific to the bearer type that the server connection is using.

                • +

              • Download email body +and attachments from an IMAP server using the maximum number of outstanding +retrieve requests specific to the bearer type that the server connection is +using.

                • +

              • A single instance of +a set of transport buffer sizes is applicable to multiple bearer types.

                • +
              • +

            Bearer mobility policy plug-in

            The bearer mobility +policy plug-in enables you to customise the migration behaviour of email accounts, +the bearer mobility policy plug-in is provided. It consists of an ECOM interface +class (CImMobilityPolicyPlugin) and a call-back class (MImMobilityPolicyHandler),which +allows the plug-in to issue policy decisions on an individual mobility events.

            +
            Important considerations
              +

            • To enable bearer mobility, +you must first enable it at the Networking bearer mobility framework.

              • +

            • Bearer mobility is possible +only on the connections that are established using a SNAP preference list.

              • +

            • To use the bearer mobility, +you must configure the email account settings to specify the SNAP preference +when creating the RConnection notification (events).

              • +

            • Multiple SNAP preferences +for each service entry is not supported.

              • +

            • It is not possible to +specify both IAPs and a SNAP for a single email account. The API for setting +a SNAP preference clears any provisioned IAPs. Likewise, the API for setting +IAPs are updated to clear any SNAP preference that is set.

              • +
            +             +SNAP Preferences + +Configuring +Non-seamless Bearer Mobility +Configuring +TLS or SSL Socket +SMTP Account +Override Settings +IMAP Account +Settings             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-24B8686D-727A-47A8-B01D-1BA1FBC8F771_d0e129360_href.png Binary file Symbian3/SDK/Source/GUID-24B8686D-727A-47A8-B01D-1BA1FBC8F771_d0e129360_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-24B8686D-727A-47A8-B01D-1BA1FBC8F771_d0e135898_href.png Binary file Symbian3/SDK/Source/GUID-24B8686D-727A-47A8-B01D-1BA1FBC8F771_d0e135898_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-24D16BF8-7BF1-5FF2-BCA8-E5200A9E8431.dita --- a/Symbian3/SDK/Source/GUID-24D16BF8-7BF1-5FF2-BCA8-E5200A9E8431.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-24D16BF8-7BF1-5FF2-BCA8-E5200A9E8431.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,74 +1,74 @@ - - - - - -How -to form linksTo be an element of a list, each element needs to contain a link -object. -

            To form a singly linked list of CMyClass objects, include -the link object TSglQueLink as a component of CMyClass:

            -class CMyClass : public CBase - { - ... - TSglQueLink iSlink; - ... - }; - -Two elements in a linked list - - -

            Although any kind of object can be an element of a linked list, most lists -consist of elements which are all of the same type.

            -

            An object can participate in more than one list. For example, to allow CMyClass objects -to participate in two singly linked lists, include two separate TSglQueLink objects -as components of CMyClass:

            -class CMyClass : public CBase - { - ... - TSglQueLink iSlink1; - ... - TSglQueLink iSlink2; - }; - -An example of two elements, in two lists where they are consecutive -elements in both lists - - -

            Elements can also be objects constructed from a variety of classes, all -ultimately derived from the same base class, where that base class includes -the link object as a component. For example, if CBc is a -base class for CDc1 which, in turn, is a base class for CDc2, -then the elements of the list can consist of a mix of CBc or CDc1 or CDc2 objects.

            -class CBc : public CBase - { - ... - TSglQueLink iSlink; - ... - }; -class CDc1 : public CBclass - { - ... - } - -class CDc2 : public CDc1 - { - ... - } - - -Example of a linked list of different element types - - -

            Note that the link object is at the same offset in each element in this -list.

            -

            New link elements can be inserted at the beginning or the end of the list, -but not into the middle of the list. The functionality for this is provided -by the header TSglQue<class T>.

            + + + + + +How +to form linksTo be an element of a list, each element needs to contain a link +object. +

            To form a singly linked list of CMyClass objects, include +the link object TSglQueLink as a component of CMyClass:

            +class CMyClass : public CBase + { + ... + TSglQueLink iSlink; + ... + }; + +Two elements in a linked list + + +

            Although any kind of object can be an element of a linked list, most lists +consist of elements which are all of the same type.

            +

            An object can participate in more than one list. For example, to allow CMyClass objects +to participate in two singly linked lists, include two separate TSglQueLink objects +as components of CMyClass:

            +class CMyClass : public CBase + { + ... + TSglQueLink iSlink1; + ... + TSglQueLink iSlink2; + }; + +An example of two elements, in two lists where they are consecutive +elements in both lists + + +

            Elements can also be objects constructed from a variety of classes, all +ultimately derived from the same base class, where that base class includes +the link object as a component. For example, if CBc is a +base class for CDc1 which, in turn, is a base class for CDc2, +then the elements of the list can consist of a mix of CBc or CDc1 or CDc2 objects.

            +class CBc : public CBase + { + ... + TSglQueLink iSlink; + ... + }; +class CDc1 : public CBclass + { + ... + } + +class CDc2 : public CDc1 + { + ... + } + + +Example of a linked list of different element types + + +

            Note that the link object is at the same offset in each element in this +list.

            +

            New link elements can be inserted at the beginning or the end of the list, +but not into the middle of the list. The functionality for this is provided +by the header TSglQue<class T>.

             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-24D51B0B-7EBE-49AE-84CF-098096BE0A1C.dita --- a/Symbian3/SDK/Source/GUID-24D51B0B-7EBE-49AE-84CF-098096BE0A1C.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-24D51B0B-7EBE-49AE-84CF-098096BE0A1C.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,113 +1,114 @@ - - - - - -Notes -

            A note is a feedback component that informs the user about the current -situation. A note contains a text and possibly a graphical element. The softkey -labels are typically empty (wait and progress notes are an exception to this).

            - - - - -Confirmation -note - - - - - -Information -note - - - - - -Warning note - - - -Error note - - - - - -

            Permanent -note

             - -             - -Wait note - - - - - -Progress note - - - - - - -
            -

            -Default touch events - - - -

            User action

             -

            State change

             -

            Feedback

             -             - - - -

            In Permanent Notes

             -             - -Touch down and release on display -No effect -Tactile: No effect - - - - - -

            In Wait or Progress Notes

             -             - -

            Touch down and release on display

             -

            No effect

             -

            Tactile: No effect

             -             - -

            Touch down and release on Cancel §TEXT_SOFTKEY_CANCEL§

             -

            Cancel or inactivate operation

             -

            Tactile: Basic button effect is provided with touch down and release -event upon Cancel §TEXT_SOFTKEY_CANCEL§ .

             -             - - - - -

            In Non-Interruptible Wait or Progress -Notes

             -             - -

            Touch down and release on display

             -

            No effect

             -

            Tactile: No effect

             -             - - + + + + + +Notes +

            A note is a feedback component that informs the user about the current +situation. A note contains a text and possibly a graphical element. The softkey +labels are typically empty (wait and progress notes are an exception to this).

            +
            + + + +Confirmation +note + + + + + +Information +note + + + + + +Warning note + + + +Error note + + + + + +

            Permanent +note

             + +             + +Wait note + + + + + +Progress note + + + + + + +
            +

            +Default touch +events + + + +

            User action

             +

            State change

             +

            Feedback

             +             + + + +

            In Permanent Notes

             +             + +Touch down and release on display +No effect +Tactile: No effect + + + + + +

            In Wait or Progress Notes

             +             + +

            Touch down and release on display

             +

            No effect

             +

            Tactile: No effect

             +             + +

            Touch down and release on Cancel §TEXT_SOFTKEY_CANCEL§

             +

            Cancel or inactivate operation

             +

            Tactile: Basic button effect is provided with touch down and release +event upon Cancel §TEXT_SOFTKEY_CANCEL§ .

             +             + + + + +

            In Non-Interruptible Wait or Progress +Notes

             +             + +

            Touch down and release on display

             +

            No effect

             +

            Tactile: No effect

             +             + +
            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-24F464D8-36C1-592A-9BDB-673E771A5707_d0e266785_href.png Binary file Symbian3/SDK/Source/GUID-24F464D8-36C1-592A-9BDB-673E771A5707_d0e266785_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-24F464D8-36C1-592A-9BDB-673E771A5707_d0e270493_href.png Binary file Symbian3/SDK/Source/GUID-24F464D8-36C1-592A-9BDB-673E771A5707_d0e270493_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-25035286-5134-51F6-A3B6-C0DF0E802719.dita --- a/Symbian3/SDK/Source/GUID-25035286-5134-51F6-A3B6-C0DF0E802719.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-25035286-5134-51F6-A3B6-C0DF0E802719.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,13 +1,13 @@ - - - - - -The Linear DDA

            Linear Digital Differential Analyzers (DDAs) are used by various functions to construct straight lines and to calculate bitmap stretching and compression.

            Line construction

            The linear DDA constructs a pixel line between the start point and end point, using the straight geometric line between these points.

            In the example below Line A has a start point (3,10) and end point (22,6). The x-delta is therefore 22-3+1=20. The y-delta is 10-6+1=5. 5 goes into 20 exactly four times, so each step of the pixel line has four pixels in it.

            The distribution of pixels is fairly straightforward if the x-delta is an exact multiple of the y-delta, or vice versa. In this case there are the same number of pixels in each pixel line step (as in the case of line A). When the x-delta is not an exact multiple of the y-delta, (or vice versa) the pixels in the pixel line cannot be distributed evenly so the pixel line steps each have differing numbers of pixels (as in the case of line B).

            Scaling bitmaps

            When a bitmap is to be displayed it often has to be stretched or compressed to fit the desired display area.

            The linear DDA constructs an imaginary pixel line between the start point and end point, using the straight geometric line between these points. This is then used to stretch or compress the original bitmap prior to display.

            The example below uses linear DDA to do a 400% horizontal scaling of a bitmapped "6" character. In most situations two linear DDAs would be needed, one for horizontal and one for vertical scaling.

            Drawing + + + + + +The Linear DDA

            Linear Digital Differential Analyzers (DDAs) are used by various functions to construct straight lines and to calculate bitmap stretching and compression.

            Line construction

            The linear DDA constructs a pixel line between the start point and end point, using the straight geometric line between these points.

            In the example below Line A has a start point (3,10) and end point (22,6). The x-delta is therefore 22-3+1=20. The y-delta is 10-6+1=5. 5 goes into 20 exactly four times, so each step of the pixel line has four pixels in it.

            The distribution of pixels is fairly straightforward if the x-delta is an exact multiple of the y-delta, or vice versa. In this case there are the same number of pixels in each pixel line step (as in the case of line A). When the x-delta is not an exact multiple of the y-delta, (or vice versa) the pixels in the pixel line cannot be distributed evenly so the pixel line steps each have differing numbers of pixels (as in the case of line B).

            Scaling bitmaps

            When a bitmap is to be displayed it often has to be stretched or compressed to fit the desired display area.

            The linear DDA constructs an imaginary pixel line between the start point and end point, using the straight geometric line between these points. This is then used to stretch or compress the original bitmap prior to display.

            The example below uses linear DDA to do a 400% horizontal scaling of a bitmapped "6" character. In most situations two linear DDAs would be needed, one for horizontal and one for vertical scaling.

            Drawing to a Graphics Context Tutorials Drawing and Graphics Contexts             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-257212F5-A414-4F17-A786-DB3168218139_d0e67378_href.png Binary file Symbian3/SDK/Source/GUID-257212F5-A414-4F17-A786-DB3168218139_d0e67378_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-257212F5-A414-4F17-A786-DB3168218139_d0e72579_href.png Binary file Symbian3/SDK/Source/GUID-257212F5-A414-4F17-A786-DB3168218139_d0e72579_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-25CBA151-ED8E-5A88-A9FD-F20810371B4D_d0e214312_href.png Binary file Symbian3/SDK/Source/GUID-25CBA151-ED8E-5A88-A9FD-F20810371B4D_d0e214312_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-25CBA151-ED8E-5A88-A9FD-F20810371B4D_d0e218049_href.png Binary file Symbian3/SDK/Source/GUID-25CBA151-ED8E-5A88-A9FD-F20810371B4D_d0e218049_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2610E11C-26FA-538E-A3E1-34AADA35F20B.dita --- a/Symbian3/SDK/Source/GUID-2610E11C-26FA-538E-A3E1-34AADA35F20B.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-2610E11C-26FA-538E-A3E1-34AADA35F20B.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,40 +1,40 @@ - - - - - -Querying Databases: BasicThis tutorial shows you how to create a simple SQL database query.
            Introduction

            This tutorial shows you how to wrap a SQL query statement into an RSqlStatement object to query a database.

            This tutorial uses code from the Basic SQL example application.

            Assumptions

            You have a database. The database has no tables and therefore no data.

            SQL statements

            The following SQL statements are used for this example:

            SELECT person FROM Pets WHERE cat - >= 1

            The (SELECT) results of the query will be the value in the 'name' column FROM the 'countries' table WHERE the value of the 'population' column of the same record is > the value specified.

            Procedure

            1. Prepare the statement:

              The steps to prepare a SQL statement are shown here.

              1. Set up some constants used by the SQL statement object to define the SQL query:

                _LIT(KSelect1,"SELECT person FROM Pets WHERE cat >= 1;");

                This defines the query parameters.

              2. Instantiate the RSqlStatement SQL statement:

                RSqlStatement stmt;

              3. Prepare the statement:

                User::LeaveIfError(stmt.Prepare(iPetDb, aStatement));

                Creates a parameterised SQL statement executable.

              4. Define the indices to be used in the search:

                TInt personIndex = stmt.ColumnIndex(KPerson);

            2. Execute the SQL query:

              The Symbian SQL statement is executed by RSqlStatement::Next().

              1. Search the records until a match is found:

                TInt rc = KErrNone; -while ((rc = stmt.Next()) == KSqlAtRow)

                Next() fires the executable SQL statement and stops at and returns the matched record.

            3. Do something with the results:

              The query is done and you have the results. In this section we look at a simple way to do something with the results and we close the SQL statement object.

              1. Get and use the results of the search:

                ... -{ -TPtrC myData = stmt.ColumnTextL(personIndex); -iConsole->Printf(_L("Person=%S\n"), &myData); -}

              2. Close the SQL search statement:

                err = myStatement.Close();

                When the database search is finished the object should be closed to free up resources.

            Results

            The tutorial has demonstrated how to query a Symbian SQL database. Looking through the example application you can work out how easily the query can be changed to meet specific requirements and how the results can be used in different ways.

            Querying example

            The following code snippet is from the basic example application.

            ... -... -RSqlStatement stmt; -iConsole->Printf(_L("Running Query:\n%S\n"), &aStatement); -user::LeaveIfError(stmt.Prepare(iPetDb, aStatement)); -CleanupClosePushL(stmt); -TInt personIndex = stmt.ColumnIndex(KPerson); -TInt rc = KErrNone; -while ((rc = stmt.Next()) == KSqlAtRow) - { - // Do something with the results - TPtrC myData = stmt.ColumnTextL(personIndex); // read return data - iConsole->Printf(_L("Person=%S\n"), &myData); - } -if (rc != KSqlAtEnd) - { - _LIT(KErrSQLError, "Error %d returned from RSqlStatement::Next()."); - iConsole->Printf(KErrSQLError, rc); - } - ... - CleanupStack::PopAndDestroy(1); -}

            Now that you have performed a basic database query you can start thinking about more advanced querying options. The following will show you how:

            • Reading to a buffer

            • Reading to memory

            • Reading to a data stream

            SQL Overview Basic SQL Example + + + + + +Querying Databases: BasicThis tutorial shows you how to create a simple SQL database query.
            Introduction

            This tutorial shows you how to wrap a SQL query statement into an RSqlStatement object to query a database.

            This tutorial uses code from the Basic SQL example application.

            Assumptions

            You have a database. The database has no tables and therefore no data.

            SQL statements

            The following SQL statements are used for this example:

            SELECT person FROM Pets WHERE cat + >= 1

            The (SELECT) results of the query will be the value in the 'name' column FROM the 'countries' table WHERE the value of the 'population' column of the same record is > the value specified.

            Procedure

            1. Prepare the statement:

              The steps to prepare a SQL statement are shown here.

              1. Set up some constants used by the SQL statement object to define the SQL query:

                _LIT(KSelect1,"SELECT person FROM Pets WHERE cat >= 1;");

                This defines the query parameters.

              2. Instantiate the RSqlStatement SQL statement:

                RSqlStatement stmt;

              3. Prepare the statement:

                User::LeaveIfError(stmt.Prepare(iPetDb, aStatement));

                Creates a parameterised SQL statement executable.

              4. Define the indices to be used in the search:

                TInt personIndex = stmt.ColumnIndex(KPerson);

            2. Execute the SQL query:

              The Symbian SQL statement is executed by RSqlStatement::Next().

              1. Search the records until a match is found:

                TInt rc = KErrNone; +while ((rc = stmt.Next()) == KSqlAtRow)

                Next() fires the executable SQL statement and stops at and returns the matched record.

            3. Do something with the results:

              The query is done and you have the results. In this section we look at a simple way to do something with the results and we close the SQL statement object.

              1. Get and use the results of the search:

                ... +{ +TPtrC myData = stmt.ColumnTextL(personIndex); +iConsole->Printf(_L("Person=%S\n"), &myData); +}

              2. Close the SQL search statement:

                err = myStatement.Close();

                When the database search is finished the object should be closed to free up resources.

            Results

            The tutorial has demonstrated how to query a Symbian SQL database. Looking through the example application you can work out how easily the query can be changed to meet specific requirements and how the results can be used in different ways.

            Querying example

            The following code snippet is from the basic example application.

            ... +... +RSqlStatement stmt; +iConsole->Printf(_L("Running Query:\n%S\n"), &aStatement); +user::LeaveIfError(stmt.Prepare(iPetDb, aStatement)); +CleanupClosePushL(stmt); +TInt personIndex = stmt.ColumnIndex(KPerson); +TInt rc = KErrNone; +while ((rc = stmt.Next()) == KSqlAtRow) + { + // Do something with the results + TPtrC myData = stmt.ColumnTextL(personIndex); // read return data + iConsole->Printf(_L("Person=%S\n"), &myData); + } +if (rc != KSqlAtEnd) + { + _LIT(KErrSQLError, "Error %d returned from RSqlStatement::Next()."); + iConsole->Printf(KErrSQLError, rc); + } + ... + CleanupStack::PopAndDestroy(1); +}

            Now that you have performed a basic database query you can start thinking about more advanced querying options. The following will show you how:

            • Reading to a buffer

            • Reading to memory

            • Reading to a data stream

            SQL Overview Basic SQL Example Application             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-261ADCEC-C8C8-46E3-A7DC-804AC868C233.dita --- a/Symbian3/SDK/Source/GUID-261ADCEC-C8C8-46E3-A7DC-804AC868C233.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-261ADCEC-C8C8-46E3-A7DC-804AC868C233.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,32 +1,32 @@ - - - - - -Descriptors -

            Descriptors are self-describing strings that can be used to store binary -data and text. Each descriptor object holds the length of the string as well -as its type which identifies the underlying memory layout of the data it holds. -For more information on different descriptor classes, see Using -Descriptors.

            -

            There are modifiable and non-modifiable descriptors, the latter type -is identified by a "C" suffix in the class name. The length of a non-modifiable -descriptor is defined when compiling an application, and the length of a modifiable -descriptor can vary within the limits set by iMaxLength. -Nonmodifiable descriptors are more secure, as their length is checked during -compilation. The following figure shows the differences between these types.

            -Differences between modifiable, nonmodifiable, and pointer descriptors -

            When designing applications, avoid using fixed-length buffers as parameters -and use base classes (preferably constant base type TDesC) -instead. Descriptor objects provide a flexible interface for manipulating -the contained string, including size and length checks. Take advantage of -these when possible.

            -

            For more information and examples, see the Descriptors -Overview topic.

            + + + + + +Descriptors +

            Descriptors are self-describing strings that can be used to store binary +data and text. Each descriptor object holds the length of the string as well +as its type which identifies the underlying memory layout of the data it holds. +For more information on different descriptor classes, see Using +Descriptors.

            +

            There are modifiable and non-modifiable descriptors, the latter type +is identified by a "C" suffix in the class name. The length of a non-modifiable +descriptor is defined when compiling an application, and the length of a modifiable +descriptor can vary within the limits set by iMaxLength. +Nonmodifiable descriptors are more secure, as their length is checked during +compilation. The following figure shows the differences between these types.

            +Differences between modifiable, nonmodifiable, and pointer descriptors +

            When designing applications, avoid using fixed-length buffers as parameters +and use base classes (preferably constant base type TDesC) +instead. Descriptor objects provide a flexible interface for manipulating +the contained string, including size and length checks. Take advantage of +these when possible.

            +

            For more information and examples, see the Descriptors +Overview topic.

             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-26399981-1E45-5578-851E-D234295F3B05_d0e76153_href.png Binary file Symbian3/SDK/Source/GUID-26399981-1E45-5578-851E-D234295F3B05_d0e76153_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-26399981-1E45-5578-851E-D234295F3B05_d0e82865_href.png Binary file Symbian3/SDK/Source/GUID-26399981-1E45-5578-851E-D234295F3B05_d0e82865_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-26435FE1-D912-4AA2-96EE-82B35DA231E6.dita --- a/Symbian3/SDK/Source/GUID-26435FE1-D912-4AA2-96EE-82B35DA231E6.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,177 +0,0 @@ - - - - - -Typical -functions of the standard keysStandard -key functions - - - -Keys -Functions - - - - -

            Arrow up / Arrow down

             -
              -

            • Moves the focus one item up/down in lists and grids.

              • -

            • Moves the cursor one line up/down in editors.

              • -

            • Scrolls the view up/down in viewers.

              • -

            • Adjusts the sound volume during calls and sound playback when the device -does not have dedicated volume keys.

              • -
             -             - -

            Arrow left / Arrow right

             -
              -

            • Moves the focus one item to the left/right in grids.

              • -

            • Moves the cursor one character to the left/right in editors.

              • -

            • Moves to the previous/next view in tabbed views.

              • -

            • Moves to the previous/next document or view in certain document viewers.

              • -

            • Changes the value in a pop-up field immediately in forms.

              • -
             -             - -

            Selection key

             -
              -

            • Opens the focused item (for example, a document or folder) in selection -lists and grids.

              • -

            • Selects an option in menus and lists.

              • -

            • Opens the context sensitive Options menu when there is no item to open -and no option to select (see Selection -list).

              • -

            The Selection key must not directly activate any such function the -user would not expect in the given situation; the Selection key is strictly -a Get-in or Accept key. Therefore, the context sensitive Options menu -will be offered in states where no selectable items exist.

             -             - -

            Left softkey

             -

            Typically labeled Options. Opens the Options menu.

            Other -labels and functions:

              -

            • Select. Used in menu lists and grids where further options are -not available. Selects the focused item; same as the Selection key function.

              • -

            • OK, Yes and other positive replies; used in confirmation -queries.

              • -

            • In the Idle state, a shortcut to a specific application. Configurable -by the user, labeled according to the application.

              • -
             -             - -

            Right softkey

             -

            Typically labeled Back. Returns to the previous state.

            Other -labels and functions:

              -

            • Exit in applications' main states.

              • -

            • Cancel. Interrupts a procedure and returns to the previous state; -used in queries and other temporary states.

              • -

            • No and other negative replies; used in confirmation queries.

              • -

            • In the Idle state, a shortcut to a specific application. Configurable -by the user, labeled according to the application.

              • -
             -             - -

            Call creation

             -
              -

            • Answers the incoming call when the phone rings.

              • -

            • Creates an outgoing call when in Phonebook and other states -where the focus is in a field containing a phone number or a name associated -with a phone number.

              • -

            • Sends a message; used when in a message editor and the To field -contains a valid address.

              • -

            • Functions also as a shortcut for sending files.

              • -

            During calls:

              -

            • Puts an active call on hold; activates a held call; swaps active and -held calls, if both exist.

              • -

            • Answers a waiting call (if a call is in progress).

              • -

            In the Idle state:

              -

            • Brings up the Last Dialled Calls list for redialing.

              • -
             -             - -

            Call termination

             -
              -

            • Rejects an incoming call.

              • -

            • Ends an active call.

              • -

            • When there is only a held call, ends the held call.

              • -

            • When there is both an active call and a held call, ends the active -call and activates the held call.

              • -

            • When there are no calls and an application is active, returns to the -Idle state. The application is terminated, except for applications that play -something in the background such as music players or radio. Any unsaved data -is automatically saved (also in case the user has pressed Exit in the Options -menu).

              • -

            And in devices that have a dedicated power key:

              -

            • A long press closes down all connections (for example GPRS, data call); -however, this has no effect on IR and Bluetooth

              • -

            And in devices without a dedicated Power key:

              -

            • When control is in the Idle state (that is, there are no active calls), -a short press opens the list of Profiles (the Power key menu) and a -long press turns the device OFF regardless of whether there are active packet -data connections in the background or not.

              • -

            • When in the Idle state without any packet data connections active in -the background, a short press opens the Power key menu and a long press -turns the device off.

              • -
             -             - -

            Home / Menu key

             -
              -

            • Opens the Menu, -allowing application launching and swapping.

              • -

            • When within the Menu, returns to the home screen. -Note that there can be device-specific configurations for Home / Menu key -functionality.

              • -

            • A long press of the Home / Menu key opens the task swapping window, -allowing switching between running applications.

              • -
             -             - -

            Numeric keypad (0-9, *, #)

             -
              -

            • Numeric and alphanumeric character entry.

              • -

            • Application-specific shortcuts and other functions.

              • -
             -             - -

            Clear

             -
              -

            • Clears characters when editing text or numbers.

              • -

            • Deletes documents or other entities in lists and viewers (these functions -always require confirmation from the user).

              • -

            The Clear key is not used for back stepping or exiting; it is only -used for deletion.

             -             - -

            Edit (optional)

             -
              -

            • Opens the Editing menu in editors; the menu contains functions -for input mode changing and other editing functions. See Editing -menu for the contents of the menu.

              • -

            • In editors, can be used together with the Arrow keys to select (highlight) -text, which then enables the Copy and Cut functions.

              • -

            • In markable lists, using the Edit key together with the arrow keys -allows the user to mark several items in the list, then a function can be -executed on all the marked items as one operation.

              • -

            The Edit key is handled in a special way; the primary action (the Editing menu) -is opened from the key release event, not the key down event as usually. This -is to enable the Mark/Select function where the key is being held down -as a modifier key (see Editing -menu and Lists -and grids for more detailed descriptions of the Select and Mark functions.)

             -             - -

            Volume keys

             -

            Adjust the sound volume during calls and sound playback.

             -             - - -
             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2645AE91-8087-5423-95A7-8BC6EFD271E7.dita --- a/Symbian3/SDK/Source/GUID-2645AE91-8087-5423-95A7-8BC6EFD271E7.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-2645AE91-8087-5423-95A7-8BC6EFD271E7.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,14 +1,14 @@ - - - - - -Message Store on a Phone

            This section explains how the UI layer displays a Message Store to a phone user.

            A message centre application displays the structure of the Message Store to the user. Different UIs map the structure to different views.

            Note: The presentation of folders is done in the UI layer and not the Messaging API.

            Series 60

            The following figure shows the top level view of a message centre application on a Series 60 phone:

            - Series 60 message centre -

            In the figure, you can see that the message centre has hidden the local service and shows the standard folders at the same level as the services. Also the SMTP, SMS and MMS services are marked as hidden entries in the Message Store, and so do not appear in the message application. The outbox does not retain copies of sent messages, but are saved in the Sent folder.

            \ No newline at end of file + + + + + +Message Store on a Phone

            This section explains how the UI layer displays a Message Store to a phone user.

            A message centre application displays the structure of the Message Store to the user. Different UIs map the structure to different views.

            Note: The presentation of folders is done in the UI layer and not the Messaging API.

            Series 60

            The following figure shows the top level view of a message centre application on a Series 60 phone:

            + Series 60 message centre +

            In the figure, you can see that the message centre has hidden the local service and shows the standard folders at the same level as the services. Also the SMTP, SMS and MMS services are marked as hidden entries in the Message Store, and so do not appear in the message application. The outbox does not retain copies of sent messages, but are saved in the Sent folder.

            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2676BA6B-4BEB-5E2A-AD18-D2199465B121.dita --- a/Symbian3/SDK/Source/GUID-2676BA6B-4BEB-5E2A-AD18-D2199465B121.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-2676BA6B-4BEB-5E2A-AD18-D2199465B121.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,57 +1,57 @@ - - - - - -Secure -Software Install Tools Overview -

            The Secure Software Install Tools collection contains PC-side tools -which enable you to generate, sign and preinstall Symbian Installation files -(SIS files). The collection also includes a set of tools, which enable you -to extract information from SIS files, SWIcertstore and registry entries for -analysis.

            -
            Components
              -

            • MaKeKeys is -a stand-alone tool that enables you to create a private key-public key pair -and generate certificate requests.

              • -

            • The SWI -Analysis Toolkit provides command-line tools that enable you to:

                -

              • extract information -from software install registry entries

                • -

              • extract certificate -and its corresponding capabilities from SWIcerstore

                • -

              • validate certificate -chains and extract capability details associated with a SIS file.

                • -
              • - -
            -
            Using Secure -Software Install Tools

            You can use this collection to perform the -following tasks:

              -

            • Create an installation -file (SIS)

              You can create and sign an installation file. For -more information, see Creating -and Signing an Installation File.

              • - -

            • Extract certificate -information from SWIcertstore

              You can extract information about -certificates and their corresponding capabilities. For more information, see DumpSWICertstoreTool.

              • -

            • Extract information -from a Software Install Registry Entry

              You can extract information -such as package UID, package name and vendor name from a registry entry. For -more information, see DumpSWIRegistryTool .

              • -
            -             -MakeKeys -Overview - SWI Analysis -Toolkit Overview -Secure Software -Install SIS Tools Overview + + + + + +Secure +Software Install Tools Overview +

            The Secure Software Install Tools collection contains PC-side tools +which enable you to generate, sign and preinstall Symbian Installation files +(SIS files). The collection also includes a set of tools, which enable you +to extract information from SIS files, SWIcertstore and registry entries for +analysis.

            +
            Components
              +

            • MaKeKeys is +a stand-alone tool that enables you to create a private key-public key pair +and generate certificate requests.

              • +

            • The SWI +Analysis Toolkit provides command-line tools that enable you to:

                +

              • extract information +from software install registry entries

                • +

              • extract certificate +and its corresponding capabilities from SWIcerstore

                • +

              • validate certificate +chains and extract capability details associated with a SIS file.

                • +
              • + +
            +
            Using Secure +Software Install Tools

            You can use this collection to perform the +following tasks:

              +

            • Create an installation +file (SIS)

              You can create and sign an installation file. For +more information, see Creating +and Signing an Installation File.

              • + +

            • Extract certificate +information from SWIcertstore

              You can extract information about +certificates and their corresponding capabilities. For more information, see DumpSWICertstoreTool.

              • +

            • Extract information +from a Software Install Registry Entry

              You can extract information +such as package UID, package name and vendor name from a registry entry. For +more information, see DumpSWIRegistryTool .

              • +
            +             +MakeKeys +Overview + SWI Analysis +Toolkit Overview +Secure Software +Install SIS Tools Overview             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-26778399-0105-413F-A39D-535A3BF5EBE2-master.png Binary file Symbian3/SDK/Source/GUID-26778399-0105-413F-A39D-535A3BF5EBE2-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-26778399-0105-413F-A39D-535A3BF5EBE2_d0e58092_href.png Binary file Symbian3/SDK/Source/GUID-26778399-0105-413F-A39D-535A3BF5EBE2_d0e58092_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-26778399-0105-413F-A39D-535A3BF5EBE2_d0e61491_href.png Binary file Symbian3/SDK/Source/GUID-26778399-0105-413F-A39D-535A3BF5EBE2_d0e61491_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-267D1E20-002E-53C7-8AE5-E063206C1562.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-267D1E20-002E-53C7-8AE5-E063206C1562.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,83 @@ + + + + + +Secure stream encryption example support code

            Below is the supporting code for the secure stream example code.

            <codeblock id="GUID-02ECEC04-E291-51B3-86DF-2FB28347F5AD" xml:space="preserve"> +#include "e32std.h" +#include "f32file.h" +#include "s32file.h" +#include "pbe.h" +#include "pbedata.h" +#include "s32crypt.h" + </codeblock> <codeblock id="GUID-13A09565-981A-56C0-9AC7-B849FFBE7395" xml:space="preserve"> +/* + * Class to demonstrate the use of secure stream encryption APIs. + */ +class CSecureStreamExample : public CBase + { +public: + static CSecureStreamExample* NewLC(); + virtual ~CSecureStreamExample(); + + void WriteEncryptedDataL(const TDesC8& aInput, const TDesC& aFilename, const TDesC& aPassword); + HBufC8* ReadEncryptedDataLC(const TDesC& aFilename, const TDesC& aPassword); +private: + CSecureStreamExample(); + void ConstructL(); +private: + RFs iFs; + }; + </codeblock> <codeblock id="GUID-B23E19C7-F6AD-5CB4-A944-EFEDC45AB623" xml:space="preserve"> +CSecureStreamExample* CSecureStreamExample::NewLC() + { + CSecureStreamExample* self = new (ELeave) CSecureStreamExample(); + CleanupStack::PushL(self); + self->ConstructL(); + return self; + } + +CSecureStreamExample::CSecureStreamExample() + { + } + +void CSecureStreamExample::ConstructL() + { + User::LeaveIfError(iFs.Connect()); + } + +CSecureStreamExample::~CSecureStreamExample() + { + iFs.Close(); + } + </codeblock> <codeblock id="GUID-11B8C0DD-AD05-53BB-BAD2-6F31457A2DD9" xml:space="preserve"> +LOCAL_D void RunPBEExampleL() + { + _LIT(KFilename, "c:\\pbe_example_data.dat"); + _LIT8(KInputData, "This is the data to be encrypted."); + _LIT(KPassword, "pa55w0rd"); + + CSecureStreamExample* main = CSecureStreamExample::NewLC(); + main->WriteEncryptedDataL(KInputData, KFilename, KPassword); + HBufC8* outputData = main->ReadEncryptedDataLC(KFilename, KPassword); + ASSERT(*outputData == KInputData); + CleanupStack::PopAndDestroy(2, main); + } + </codeblock> <codeblock id="GUID-0B93114C-6801-5053-85C3-181779A6185F" xml:space="preserve"> +GLDEF_C TInt E32Main() // main function called by E32 + { + __UHEAP_MARK; + CTrapCleanup* cleanup = CTrapCleanup::New(); // get clean-up stack + TRAPD(error, RunPBEExampleL()); + __ASSERT_ALWAYS(!error,User::Panic(_L("pbe_example_code"),error)); + delete cleanup; // destroy clean-up stack + __UHEAP_MARKEND; + return 0; + } + </codeblock> </section> </conbody></concept> \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-268E2151-C758-46BF-86EB-F7D6EE44DBCF.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-268E2151-C758-46BF-86EB-F7D6EE44DBCF.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,14 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> +<!-- This component and the accompanying materials are made available under the terms of the License +"Eclipse Public License v1.0" which accompanies this distribution, +and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> +<!-- Initial Contributors: + Nokia Corporation - initial contribution. +Contributors: +--> +<!DOCTYPE concept + PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> +<concept id="GUID-268E2151-C758-46BF-86EB-F7D6EE44DBCF" xml:lang="en"><title>Encrypting and Decrypting DataThis section provides detailed information on encrypting +and decrypting data using Symmetric and Asymmetric algorithms supported +by Symbian platform. \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-269D6756-98B5-5928-9A83-261C3F729BCE_d0e335760_href.png Binary file Symbian3/SDK/Source/GUID-269D6756-98B5-5928-9A83-261C3F729BCE_d0e335760_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-269D6756-98B5-5928-9A83-261C3F729BCE_d0e341917_href.png Binary file Symbian3/SDK/Source/GUID-269D6756-98B5-5928-9A83-261C3F729BCE_d0e341917_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-26E2294F-871F-45D1-B71C-9F470703A9C8_d0e36237_href.png Binary file Symbian3/SDK/Source/GUID-26E2294F-871F-45D1-B71C-9F470703A9C8_d0e36237_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-26E2294F-871F-45D1-B71C-9F470703A9C8_d0e41804_href.png Binary file Symbian3/SDK/Source/GUID-26E2294F-871F-45D1-B71C-9F470703A9C8_d0e41804_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-26FC16BB-47D8-5DF6-9ABE-07526286597A-GENID-1-8-1-3-1-1-5-1.dita --- a/Symbian3/SDK/Source/GUID-26FC16BB-47D8-5DF6-9ABE-07526286597A-GENID-1-8-1-3-1-1-5-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,13 +0,0 @@ - - - - - -Bitmap AnimationThe section explain how to create animations using Bitmap Animation -framework. \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-26FC16BB-47D8-5DF6-9ABE-07526286597A-GENID-1-8-1-6-1-1-4-1-4-1.dita --- a/Symbian3/SDK/Source/GUID-26FC16BB-47D8-5DF6-9ABE-07526286597A-GENID-1-8-1-6-1-1-4-1-4-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,13 +0,0 @@ - - - - - -Bitmap AnimationThe section explain how to create animations using Bitmap Animation -framework. \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-26FC16BB-47D8-5DF6-9ABE-07526286597A.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-26FC16BB-47D8-5DF6-9ABE-07526286597A.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,13 @@ + + + + + +Bitmap AnimationThe section explain how to create animations using Bitmap Animation +framework. \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-270C96B0-4BDF-5A18-A8FE-FA4F78BB34EE.dita --- a/Symbian3/SDK/Source/GUID-270C96B0-4BDF-5A18-A8FE-FA4F78BB34EE.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-270C96B0-4BDF-5A18-A8FE-FA4F78BB34EE.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,834 +1,983 @@ - - - - - -Full -Example Code ListThis document lists the example code available for each module -and collection in the platform. -

            The following tables are grouped by module and collection. In each table, -the left hand column gives a link to the overview for the example. The overviews -describe the example's purpose, the APIs it demonstrates, how to build and -run it, and they provide a link to download the example's source code.

            -

            In most cases, the name in the left hand column is the example's mmp filename. -If the example has more than one mmp file, the name of its directory is used. -The right hand column gives a summary of the main purpose of the example.

            -
            Symbian Platform -Fundamentals - - - -Name -Description - - - - -

            HelloWorld

            -

            Most basic console application.

            -             - -

            CClasses

            -

            Shows a basic 'C' class and use of the cleanup stack.

            -             - -

            TAndRClasses

            -

            Shows a typical 'T' and 'R' class.

            -             - -

            MClasses1-3

            -

            Shows the use of 'M' (abstract interface) classes.

            -             - -

            StaticDLL

            -

            Shows how a statically linked DLL is used.

            -             - - -
            -
            Application -Framework - - - -Name -Description - - - - - - - - -

            BmpAnimGui

            -

            Shows how to create an animation using the Bitmap Animation framework.

            -             - -

            HelloWorld

            -

            Shows how to create a simple GUI application with a single view.

            -             - - -
            - -
            Communications -Framework

            Data Server

            - - - -Name -Description - - - - -

            Rconnection

            -

            Shows how to use the RConnection API for connection monitoring and -management.

            -             - - -
            - -
            Generic Application -Support

            Common App Services

            - - - -Name -Description - - - - -

            AlarmServerExample

            -

            Shows the client API to the alarm server.

            -             - - -
            -
            Generic OS -Services

            Compression Libraries

            - - - -Name -Description - - - - -

            EzlibExample

            -

            Shows how to use the EZLIB API to do file extraction and compression.

            -             - - -

            Generic Open Libraries

            - - - -Name -Description - - - - -

            FileAccessExample

            -

            Shows accessing the file system using P.I.P.S.

            -             - -

            HelloWorldExample

            -

            Creates a simple P.I.P.S. DLL and EXE to demonstrate function lookup -by name rather than by ordinal.

            -             - -

            hybridapp

            -

            Shows a P.I.P.S. 'hybrid' application that uses both C and native -Symbian C++ APIs.

            -             - -

            IPC

            -

            Shows inter-process communication in P.I.P.S.

            -             - -

            LibpThreadExample

            -

            Shows simple multi-threading and synchronisation in P.I.P.S. using libpthread.dll.

            -             - -

            libmexample

            -

            Shows the P.I.P.S. Standard C maths library, libm.dll.

            -             - -

            ConsoleApp

            -

            Shows a simple console-based STDLIB (C Standard library) program -that converts quantities from one unit of measurement into another.

            -             - -

            GUIApp

            -

            Shows a Techview GUI application whose engine is written using STDLIB.

            -             - -

            Hello

            -

            The simplest possible STDLIB example.

            -             - -

            posixsignals

             -

            Shows various signal use cases as supported in P.I.P.S.

            -             - - -

            Open C

            - - - -Name -Description - - - - -

            openclibz

            -

            Shows file compression/decompression. Huffman , filtered data compression, -run length encoding, compress a string given by user

            -             - -

            antiword

            -

            converts a MS-word document (i.e. .doc) file in to a plain text(i.e. -.txt) file.

            converts a MS-word document (i.e. .doc) file in to a -Adobe acrobat(i.e. .pdf) file.

            converts a MS-word document (i.e. .doc) -file in to a post-script (i.e. .ps) file.

            converts a MS-word document -(i.e. .doc) file in to a xml (i.e. .xml) file

            -             - -

            handleglobalvar

            -

            How to handle global variables within the library code.

            How -to solve WSD (Writable Static Data) problem

            -             - -

            opencmessagequeuelibraryex

            -

            Send/receive messages using message queue, demonstrated using open -C message queue library

            -             - -

            opencproducerconsumerex

            -

            Demonstrates solution for Producer/ Consumer Problem using Open -C.

            -             - -

            OpenCStringUtilitiesEx

            -

            Demonstrates string utility using open C libraries

            -             - -

            redirectprintf

            -

            how to redirect stdio to a file. libc library provides freopen API -to redirect all standard IOs (namely, stderr, stdin, or stdout).

            -             - - -

            Generic Services

            - - - -Name -Description - - - - -

            exampleRecognizer

            -

            Shows how to write a simple data recognizer.

            -             - - - - - -

            TaskSchedulerExample

            -

            Shows how to schedule and run tasks using the Task Scheduler API.

            -             - - -

            Low level Libraries and Frameworks

            - - - -Name -Description - - - - -

            Basics

            -

            Shows how to store and restore objects using the clipboard API.

            -             - -

            InterfaceClient

            -

            One of a set of three related ECom examples that provide an interface -definition, a DLL that contains two implementations of that interface, and -a client program that uses the interface.

            -             - -

            InterfaceDefinition

            -

            See InterfaceClient, above.

            -             - -

            InterfaceImplementation

            -

            See InterfaceClient, above.

            -             - -

            ReadText

            -

            Most basic resource file example, shows how to read a string resource -and print it to the console.

            -             - -

            ReadArray

            -

            Shows how to load data from a resource file into an array.

            -             - -

            MultiRead1

            -

            Shows how to open a single resource file and read a resource from -it into a descriptor.

            -             - -

            MultiRead2

            -

            Shows how to open and read from multiple resource files.

            -             - -

            ReadData

            -

            Shows how to use a resource reader to read data of various types -from a resource file into the data members of a class.

            -             - -

            EUser High -Level Library

            -

            Shows how to use EUser High Level library classes and APIs

            -             - -

            SigCheck

            -

            Shows how the signature of a resource file is checked before use.

            -             - - -

            XML

            - - - -Name -Description - - - - -

            XmlExample

            -

            Shows how to use the Xml framework to parse XML -and WBXML files.

            -             - - -
            -
            Graphics

            Font -and Bitmap Server

            - - - -Name -Description - - - - -

            BitmapsShell

            -

            Shows how to draw and manipulate bitmaps.

            -             - - -

            General

            - - - -Name -Description - - - - -

            GraphicsShell

            -

            A TechView application that demonstrates drawing points, lines and -shapes, and zooming a bitmap and text.

            -             - - -
            -
            High Level -Internet Protocols

            Application Layer Protocols

            - - - -Name -Description - - - - -

            httpexampleclient

            -

            A console application that provides a menu-driven interface to demonstrate -the HTTP API.

            -             - - -

            IMS and Streaming

            - - - -Name -Description - - - - -

            RTPExample

            -

            Shows RTP packet streaming.

            -             - - -
            -
            Kernel and -Hardware Services

            User Library

            - - - -Name -Description - - - - -

            AdvancedClientServerExample

            -

            Shows the use of asynchronous and synchronous client/server APIs -using a logical device driver (LDD) and a physical device driver (PDD).

            -             - -

            SingleRequest

            -

            Shows the basic principles of asynchronous programming by issuing -and waiting for completion of a single request.

            -             - -

            WaitLoop

            -

            Shows how a wait loop can be used to identify and handle a completed -request.

            -             - -

            RealLifeWaitLoop

            -

            Shows how the wait loop can deal with multiple asynchronous service -providers.

            -             - -

            RunComplete

            -

            Shows how active objects and an active scheduler can be used to -handle asynchronous events, using a timer.

            -             - -

            AcceptInput1-2

            -

            Shows how active objects and an active scheduler can be used to -handle asynchronous events, using keyboard input.

            -             - -

            AcceptPrintInput

            -

            Shows how active objects and an active scheduler can be used to -handle accept and print keyboard inputs to a console.

            -             - -

            Fibonacci1-3

            -

            Shows how active objects and an active scheduler can be used to -handle asynchronous events and long-running services to maintain system responsiveness.

            -             - -

            circularbuffer

            -

            Shows how to construct and use circular buffers holding different -types of objects.

            -             - -

            Simple

            -

            Shows a simple client that has a single session with a server.

            -             - -

            Complex

            -

            More complex client/server example, where the server supports multiple -subsessions within a session.

            -             - - -

            condvarglobal

            -

            Shows the use of the global condition variable IPC mechanism.

            -             - -

            condvarlocal

            -

            Shows the use of the local condition variable IPC mechanism.

            -             - -

            Basics

            -

            Shows date and time handling.

            -             - -

            BinaryData

            -

            Shows how descriptors can handle general binary data by explicitly -using the 8 bit descriptor class variants.

            -             - -

            Buffer

            -

            Shows the basic idea of buffer descriptors and how they are used.

            -             - -

            InFunct

            -

            Shows how to use descriptors as function arguments.

            -             - -

            HeapBuffer

            -

            Shows how to create and use the heap buffer descriptor HBufC.

            -             - -

            Modifier

            -

            Shows how to use the modifiable descriptor class TDes.

            -             - -

            NonModifier

            -

            Shows how to use the non-modifiable descriptor class TDesC.

            -             - -

            Pointer

            -

            Shows how to use pointer descriptors.

            -             - -

            WriteToFile

            -

            Basic example that shows how to write text to a file.

            -             - -

            DynamicArrays

            -

            Shows how to construct and use dynamic arrays.

            -             - -

            DynamicBuffers

            -

            Shows how to use the flat and segmented buffer classes.

            -             - -

            DLLs

            -

            Implements two polymorphic DLLs and shows how to load and use them.

            -             - -

            RangeChecking

            -

            Shows how to use the range checking wrapper class for C++ arrays -(TFixedArray).

            -             - -

            hashtableexample

            -

            Shows how to use the hash table APIs.

            -             - -

            Lexer

            -

            Shows how to use the lexical analyser, TLex.

            -             - -

            linkedlist

            -

            Shows how to use singly and doubly linked lists and the delta queue -class.

            -             - -

            Currency

            -

            Shows locale-specific representation of currency values and symbols.

            -             - -

            localeupdate

            -

            Shows how to load a locale DLL and read settings from it.

            -             - -

            ErrorOnFail

            -

            Shows use of the TRAPD macro, the cleanup stack -and the process of leaving. Returns an error code on failure.

            -             - -

            LeaveOnFail

            -

            As the ErrorOnFail example except it leaves on -failure.

            -             - -

            ELeaveOnFail

            -

            As the LeaveOnFail example except it calls new -(ELeave) rather than new.

            -             - -

            TrapD

            -

            Shows the use of the TRAPD macro.

            -             - -

            PushLAndPop

            -

            Shows the use of the cleanup stack and its functions PushL() and Pop().

            -             - -

            PushLPopDest

            -

            Shows the use of the cleanup stack and its functions PushL() and PopAndDestroy().

            -             - -

            NewL

            -

            Shows use of the NewL() static function.

            -             - -

            NewLC

            -

            Shows use of the NewLC() static function.

            -             - -

            SimpleOOM

            -

            Shows cleanup handling for compound classes.

            -             - -

            MemLeakOOM

            -

            Shows cleanup handling for compound classes, and avoiding memory -leaks.

            -             - -

            TwoPhaseOOM

            -

            Shows the two phase construction technique.

            -             - -

            TAnyRObjects1

            -

            Shows how cleanup can be implemented for TAny* type -objects and 'R' type (resource type) objects.

            -             - -

            TAnyRObjects2

            -

            As TAnyRObjects1 except it calls OpenLC() to -open the file and push it onto the cleanup stack in one function call.

            -             - -

            Utilities

            -

            Shows how to use the cleanup functions CleanupDeletePushL(), CleanupClosePushL() and CleanupReleasePushL(), and CleanupArrayDeletePushL().

            -             - -

            MessageQueueExample

            -

            Shows the use of the message queue in interprocess communication.

            -             - -

            pubsub

            -

            Shows the Publish and Subscribe IPC mechanism.

            -             - -

            rbufexample

            -

            Shows how to use the resizable buffer descriptor class RBuf.

            -             - -

            SecureServer

            -

            Shows how to use the policy server framework.

            -             - -

            tcharexample

            -

            Shows how to use the single character class, TChar, -and its derived classes.

            -             - -

            TLS1

            -

            Shows the use of thread local storage (TLS) in a DLL, that is set -and accessed from a separate executable.

            -             - -

            ThreadRendezvous

            -

            Shows the principle of synchronisation using the thread rendezvous -technique.

            -             - -

            BasicTimer

            -

            Shows the asynchronous timer class RTimer

            -             - -

            Periodic

            -

            Shows the differences between a periodic and a heartbeat timer.

            -             - -

            resourcemanager

            -

            Shows how to use the Power Resource Manager framework.

            -             - - -

            SemaphoreExample

             -

            Shows how to use semaphores for a multithreading application.

             -             - - -
            -
            Messaging Middleware - - - -Name -Description - - - - -

            TextMTM

            -

            Several example projects that show how to use the Messaging APIs.

            -             - -

            SearchSortExample

            -

            Shows how to use the enhanced search and sort API for message stores.

            -             - -

            BIOMessageMgr

            -

            Shows BIO messaging and parsing the BIO message.

            -             - -

            SendAs2Example

            -

            Shows how to use the SendAs v2 protocol for sending messages.

            -             - - -
            -
            Messaging Applications - - - -Name -Description - - - - -

            smsexample

            -

            Shows how to send and receive SMS messages using the Messaging Framework -APIs.

            -             - -

            Pop3Example

            -

            Shows how to create SMTP (Simple Mail Transfer Protocol) and POP -(Post Office Protocol) accounts to send and receive emails.

            -             - -

            Imap4Example

            -

            Shows how to create SMTP and IMAP (Internet Message Access Protocol) -accounts to send and receive emails.

            -             - - -
            -
            Multimedia

            Multimedia -APIs and Frameworks

            - - - -Name -Description - - - - -

            ICLCodec

            -

            Shows how to implement encoder and decoder plug-ins for the Image -Converter Library.

            -             - -

            ICLExample

            -

            Shows how to convert still images, stored in files or descriptors, -to and from bitmap objects using the Image Conversion Library (ICL) API

            -             - -

            ImageConv

            -

            Shows how to convert between standard graphics formats to and from CFbsBitmap s, -and how to rotate, flip, and zoom images.

            -             - -

            CameraExample

            -

            Shows how to use the Camera API to capture and control images.

            -             - - -
            -
            Multimedia -Middleware

            Multimedia Middleware Frameworks

            - - - -Name -Description - - - - -

            AudioClientEx

            -

            Shows how to use the Multimedia Framework's client audio interfaces -to play and record audio.

            -             - -

            MmfExCodec

            -

            Shows how to implement a codec plug-in for the Multimedia Framework -to convert media data.

            -             - -

            MmfRAWFormat

            -

            Shows how to implement format encoder and decoder plug-ins for the -Multimedia Framework.

            -             - -

            MmfExSinkSource

            -

            Shows how to implement sink and source plug-ins for the Multimedia -Framework.

            -             - -

            MmfRec

            -

            Shows how to record short audio clips using each format that the -system supports.

            -             - - -
            - -
            PC Tools

            Secure -Software Install Tools

            - - - -Name -Description - - - - -

            HelloWorld

            -

            Shows how to create a simple installation file for an application.

            -             - -

            HelloWorld

            -

            Shows how to create an installation file for a multilingual application.

            -             - - -
            - - - -
            System GUI -Framework

            Look-and-Feel Agnostic UI Foundation

            - - - -Name -Description - - - - - -

            ClockExample

            -

            Shows how to create and display digital and analogue clocks.

            -             - - - - -
            - + + + + + +Full Example Code ListThis document lists the example code available for each +module and collection in the platform. +

            The following tables are grouped by module and collection. In each +table, the left hand column gives a link to the overview for the example. +The overviews describe the example's purpose, the APIs it demonstrates, +how to build and run it, and they provide a link to download the example's +source code.

            +

            In most cases, the name in the left hand column is the example's +mmp filename. If the example has more than one mmp file, the name +of its directory is used. The right hand column gives a summary of +the main purpose of the example.

            +
            Symbian +Platform Fundamentals + + + +Name +Description + + + + +

            HelloWorld

            +

            Most basic console application.

            +             + +

            CClasses

            +

            Shows a basic 'C' class and use of the cleanup stack.

            +             + +

            TAndRClasses

            +

            Shows a typical 'T' and 'R' class.

            +             + +

            MClasses1-3

            +

            Shows the use of 'M' (abstract interface) classes.

            +             + +

            StaticDLL

            +

            Shows how a statically linked DLL is used.

            +             + + +
            +
            Application +Framework + + + +Name +Description + + + + + + + + +

            BmpAnimGui

            +

            Shows how to create an animation using the Bitmap Animation +framework.

            +             + +

            HelloWorld

            +

            Shows how to create a simple GUI application with a single +view.

            +             + + +
            + +
            Communications +Framework

            Data Server

            + + + +Name +Description + + + + +

            Rconnection

            +

            Shows how to use the RConnection API for connection monitoring +and management.

            +             + + +
            + +
            Generic +Application Support

            Common App Services

            + + + +Name +Description + + + + +

            AlarmServerExample

            +

            Shows the client API to the alarm server.

            +             + + +
            +
            Generic +OS Services

            Compression Libraries

            + + + +Name +Description + + + + +

            EzlibExample

            +

            Shows how to use the EZLIB API to do file extraction and +compression.

            +             + + +

            Generic Open Libraries

            + + + +Name +Description + + + + +

            FileAccessExample

            +

            Shows accessing the file system using P.I.P.S.

            +             + +

            HelloWorldExample

            +

            Creates a simple P.I.P.S. DLL and EXE to demonstrate function +lookup by name rather than by ordinal.

            +             + +

            hybridapp

            +

            Shows a P.I.P.S. 'hybrid' application that uses both C and +native Symbian C++ APIs.

            +             + +

            IPC

            +

            Shows inter-process communication in P.I.P.S.

            +             + +

            LibpThreadExample

            +

            Shows simple multi-threading and synchronisation in P.I.P.S. +using libpthread.dll.

            +             + +

            libmexample

            +

            Shows the P.I.P.S. Standard C maths library, libm.dll.

            +             + +

            ConsoleApp

            +

            Shows a simple console-based STDLIB (C Standard library) +program that converts quantities from one unit of measurement into +another.

            +             + +

            GUIApp

            +

            Shows a Techview GUI application whose engine is written +using STDLIB.

            +             + +

            Hello

            +

            The simplest possible STDLIB example.

            +             + +

            posixsignals

             +

            Shows various signal use cases as supported in P.I.P.S.

            +             + + +

            Open C

            + + + +Name +Description + + + + +

            openclibz

            +

            Shows file compression/decompression. Huffman , filtered +data compression, run length encoding, compress a string given by +user

            +             + +

            handleglobalvar

            +

            How to handle global variables within the library code.

            How to solve WSD (Writable Static Data) problem

            +             + +

            opencmessagequeuelibraryex

            +

            Send/receive messages using message queue, demonstrated +using open C message queue library

            +             + +

            opencproducerconsumerex

            +

            Demonstrates solution for Producer/ Consumer Problem using +Open C.

            +             + +

            OpenCStringUtilitiesEx

            +

            Demonstrates string utility using open C libraries

            +             + +

            redirectprintf

            +

            how to redirect stdio to a file. libc library provides freopen +API to redirect all standard IOs (namely, stderr, stdin, or stdout). +

            +             + + +

            Generic Services

            + + + +Name +Description + + + + +

            exampleRecognizer

            +

            Shows how to write a simple data recognizer.

            +             + + + + + +

            TaskSchedulerExample

            +

            Shows how to schedule and run tasks using the Task Scheduler +API.

            +             + + +

            Low level Libraries and Frameworks

            + + + +Name +Description + + + + +

            Basics

            +

            Shows how to store and restore objects using the clipboard +API.

            +             + +

            InterfaceClient

            +

            One of a set of three related ECom examples that provide +an interface definition, a DLL that contains two implementations of +that interface, and a client program that uses the interface.

            +             + +

            InterfaceDefinition

            +

            See InterfaceClient, above.

            +             + +

            InterfaceImplementation

            +

            See InterfaceClient, above.

            +             + +

            ReadText

            +

            Most basic resource file example, shows how to read a string +resource and print it to the console.

            +             + +

            ReadArray

            +

            Shows how to load data from a resource file into an array.

            +             + +

            MultiRead1

            +

            Shows how to open a single resource file and read a resource +from it into a descriptor.

            +             + +

            MultiRead2

            +

            Shows how to open and read from multiple resource files.

            +             + +

            ReadData

            +

            Shows how to use a resource reader to read data of various +types from a resource file into the data members of a class.

            +             + +

            EUser +High Level Library

            +

            Shows how to use EUser High Level library classes and APIs

            +             + +

            SigCheck

            +

            Shows how the signature of a resource file is checked before +use.

            +             + + +

            XML

            + + + +Name +Description + + + + +

            XmlExample

            +

            Shows how to use the Xml framework to +parse XML and WBXML files.

            +             + + +
            +
            Graphics

            Font and Bitmap Server

            + + + +Name +Description + + + + +

            BitmapsShell

            +

            Shows how to draw and manipulate bitmaps.

            +             + +

            CoverflowApp

             +

            Illustrates how the graphics architecture called ScreenPlay +creates OpenVG content on a semi-transparent or transparent UI.

            +             + + +

            General

            + + + +Name +Description + + + + +

            GraphicsShell

            +

            A TechView application that demonstrates drawing points, +lines and shapes, and zooming a bitmap and text.

            +             + + +
            +
            High +Level Internet Protocols

            Application Layer Protocols

            + + + +Name +Description + + + + +

            httpexampleclient

            +

            A console application that provides a menu-driven interface +to demonstrate the HTTP API.

            +             + + +

            IMS and Streaming

            + + + +Name +Description + + + + +

            RTPExample

            +

            Shows RTP packet streaming.

            +             + + +
            +
            Kernel +and Hardware Services

            User Library

            + + + +Name +Description + + + + +

            AdvancedClientServerExample

            +

            Shows the use of asynchronous and synchronous client/server +APIs using a logical device driver (LDD) and a physical device driver +(PDD).

            +             + +

            SingleRequest

            +

            Shows the basic principles of asynchronous programming by +issuing and waiting for completion of a single request.

            +             + +

            WaitLoop

            +

            Shows how a wait loop can be used to identify and handle +a completed request.

            +             + +

            RealLifeWaitLoop

            +

            Shows how the wait loop can deal with multiple asynchronous +service providers.

            +             + +

            RunComplete

            +

            Shows how active objects and an active scheduler can be +used to handle asynchronous events, using a timer.

            +             + +

            AcceptInput1-2

            +

            Shows how active objects and an active scheduler can be +used to handle asynchronous events, using keyboard input.

            +             + +

            AcceptPrintInput

            +

            Shows how active objects and an active scheduler can be +used to handle accept and print keyboard inputs to a console.

            +             + +

            Fibonacci1-3

            +

            Shows how active objects and an active scheduler can be +used to handle asynchronous events and long-running services to maintain +system responsiveness.

            +             + +

            circularbuffer

            +

            Shows how to construct and use circular buffers holding +different types of objects.

            +             + +

            Simple

            +

            Shows a simple client that has a single session with a server.

            +             + +

            Complex

            +

            More complex client/server example, where the server supports +multiple subsessions within a session.

            +             + + +

            condvarglobal

            +

            Shows the use of the global condition variable IPC mechanism.

            +             + +

            condvarlocal

            +

            Shows the use of the local condition variable IPC mechanism.

            +             + +

            Basics

            +

            Shows date and time handling.

            +             + +

            BinaryData

            +

            Shows how descriptors can handle general binary data by +explicitly using the 8 bit descriptor class variants.

            +             + +

            Buffer

            +

            Shows the basic idea of buffer descriptors and how they +are used.

            +             + +

            InFunct

            +

            Shows how to use descriptors as function arguments.

            +             + +

            HeapBuffer

            +

            Shows how to create and use the heap buffer descriptor HBufC.

            +             + +

            Modifier

            +

            Shows how to use the modifiable descriptor class TDes.

            +             + +

            NonModifier

            +

            Shows how to use the non-modifiable descriptor class TDesC.

            +             + +

            Pointer

            +

            Shows how to use pointer descriptors.

            +             + +

            WriteToFile

            +

            Basic example that shows how to write text to a file.

            +             + +

            DynamicArrays

            +

            Shows how to construct and use dynamic arrays.

            +             + +

            DynamicBuffers

            +

            Shows how to use the flat and segmented buffer classes.

            +             + +

            DLLs

            +

            Implements two polymorphic DLLs and shows how to load and +use them.

            +             + +

            RangeChecking

            +

            Shows how to use the range checking wrapper class for C++ +arrays (TFixedArray).

            +             + +

            hashtableexample

            +

            Shows how to use the hash table APIs.

            +             + +

            Lexer

            +

            Shows how to use the lexical analyser, TLex.

            +             + +

            linkedlist

            +

            Shows how to use singly and doubly linked lists and the +delta queue class.

            +             + +

            Currency

            +

            Shows locale-specific representation of currency values +and symbols.

            +             + +

            localeupdate

            +

            Shows how to load a locale DLL and read settings from it.

            +             + +

            ErrorOnFail

            +

            Shows use of the TRAPD macro, the cleanup +stack and the process of leaving. Returns an error code on failure.

            +             + +

            LeaveOnFail

            +

            As the ErrorOnFail example except it leaves +on failure.

            +             + +

            ELeaveOnFail

            +

            As the LeaveOnFail example except it calls new (ELeave) rather than new.

            +             + +

            TrapD

            +

            Shows the use of the TRAPD macro.

            +             + +

            PushLAndPop

            +

            Shows the use of the cleanup stack and its functions PushL() and Pop().

            +             + +

            PushLPopDest

            +

            Shows the use of the cleanup stack and its functions PushL() and PopAndDestroy().

            +             + +

            NewL

            +

            Shows use of the NewL() static function.

            +             + +

            NewLC

            +

            Shows use of the NewLC() static function.

            +             + +

            SimpleOOM

            +

            Shows cleanup handling for compound classes.

            +             + +

            MemLeakOOM

            +

            Shows cleanup handling for compound classes, and avoiding +memory leaks.

            +             + +

            TwoPhaseOOM

            +

            Shows the two phase construction technique.

            +             + +

            TAnyRObjects1

            +

            Shows how cleanup can be implemented for TAny* type objects and 'R' type (resource type) objects.

            +             + +

            TAnyRObjects2

            +

            As TAnyRObjects1 except it calls OpenLC() to open the file and push it onto the cleanup stack +in one function call.

            +             + +

            Utilities

            +

            Shows how to use the cleanup functions CleanupDeletePushL(), CleanupClosePushL() and CleanupReleasePushL(), and CleanupArrayDeletePushL().

            +             + +

            MessageQueueExample

            +

            Shows the use of the message queue in interprocess communication.

            +             + +

            pubsub

            +

            Shows the Publish and Subscribe IPC mechanism.

            +             + +

            rbufexample

            +

            Shows how to use the resizable buffer descriptor class RBuf.

            +             + +

            SecureServer

            +

            Shows how to use the policy server framework.

            +             + +

            tcharexample

            +

            Shows how to use the single character class, TChar, and its derived classes.

            +             + +

            TLS1

            +

            Shows the use of thread local storage (TLS) in a DLL, that +is set and accessed from a separate executable.

            +             + +

            ThreadRendezvous

            +

            Shows the principle of synchronisation using the thread +rendezvous technique.

            +             + +

            BasicTimer

            +

            Shows the asynchronous timer class RTimer

            +             + +

            Periodic

            +

            Shows the differences between a periodic and a heartbeat +timer.

            +             + +

            resourcemanager

            +

            Shows how to use the Power Resource Manager framework.

            +             + + +

            SemaphoreExample

             +

            Shows how to use semaphores for a multithreading application.

             +             + + +
            +
            Messaging +Middleware + + + +Name +Description + + + + +

            TextMTM

            +

            Several example projects that show how to use the Messaging +APIs.

            +             + +

            SearchSortExample

            +

            Shows how to use the enhanced search and sort API for message +stores.

            +             + +

            BIOMessageMgr

            +

            Shows BIO messaging and parsing the BIO message.

            +             + +

            SendAs2Example

            +

            Shows how to use the SendAs v2 protocol for sending messages.

            +             + + +
            +
            Messaging +Applications + + + +Name +Description + + + + +

            smsexample

            +

            Shows how to send and receive SMS messages using the Messaging +Framework APIs.

            +             + +

            Imap4Pop3Example

            +

            Shows how to create SMTP (Simple Mail Transfer Protocol) +and POP (Post Office Protocol) accounts to send and receive emails.

            Shows how to create SMTP and IMAP (Internet Message Access Protocol) +accounts to send and receive emails.

            +             + + +
            +
            Multimedia

            Multimedia APIs and Frameworks

            + + + +Name +Description + + + + +

            ICLCodec

            +

            Shows how to implement encoder and decoder plug-ins for +the Image Converter Library.

            +             + +

            ImageConverter

            +

            Shows how to convert between standard graphics formats to +and from CFbsBitmap s, and how to rotate, flip, +and zoom images.

            +             + +

            CameraExample

            +

            Shows how to use the Camera API to capture and control images.

            +             + + +
            +
            Multimedia +Middleware

            Multimedia Middleware Frameworks

            + + + +Name +Description + + + + +

            AudioClientEx

            +

            Shows how to use the Multimedia Framework's client audio +interfaces to play and record audio.

            +             + +

            MmfExCodec

            +

            Shows how to implement a codec plug-in for the Multimedia +Framework to convert media data.

            +             + +

            MmfRAWFormat

            +

            Shows how to implement format encoder and decoder plug-ins +for the Multimedia Framework.

            +             + +

            MmfExSinkSource

            +

            Shows how to implement sink and source plug-ins for the +Multimedia Framework.

            +             + + +
            +
            Networking +Services

            Network Protocols

            + + + +Name +Description + + + + +

            EchoClientEngine

            +

            The engine for the TCP/IP echo client example.

            +             + +

            EchoClientUI

            +

            The user interface for the TCP/IP echo client example.

            +             + + +

            Network Security

            + + + +Name +Description + + + + +

            SecureSockets

            +

            Shows how to create and use a secure sockets (SSL/TLS) connection.

            +             + + +
            +
            PC +Tools

            Secure Software Install Tools

            + + + +Name +Description + + + + +

            HelloWorld

            +

            Shows how to create a simple installation file for an application.

            +             + +

            HelloWorld

            +

            Shows how to create an installation file for a multilingual +application.

            +             + + +
            +
            Persistent +Data Services

            Persistent Storage

            + + + +Name +Description + + + + +

            Basics

            +

            Shows how to create and use a database using DBMS.

            +             + +

            SqlExample

            +

            Shows how to use the SQL API to create and query an SQL +database.

            +             + +

            CentRepExample

            +

            Shows how to use the central repository to store settings +and request notification of changes.

            +             + +

            WriteDirectFS

            +

            Shows how to persist objects using a direct file store and +a root stream.

            +             + +

            WritePermFS1

            +

            Shows how to write a network of objects to a permanent file +store then read them back in again.

            +             + +

            WritePermFS2

            +

            Shows how to create and use a permanent file store.

            +             + +

            StreamInStore

            +

            Shows how to externalize objects to a single stream in a +non-persistent store.

            +             + +

            WriteToMany

            +

            Shows how to write a network of objects to more than one +stream in a direct file store, and to defer the loading of an object +from the store into memory.

            +             + +

            WriteToEmbedded

            +

            Shows how an object is externalized to a store embedded +within a permanent file store.

            +             + +

            StoreMap

            +

            Shows how to stream a compound object to multiple streams +using a store map.

            +             + +

            SimpleClass

            +

            Shows streaming a simple class to and from a single stream.

            +             + +

            CompoundClass

            +

            Shows streaming a compound class to and from a single stream

            +             + +

            FeatMngrExample

            +

            Shows the use of Feature Manager APIs for dynamic management +of features.

            +             + + +
            +
            PIM

            PIM Application Services

            + + + +Name +Description + + + + +

            CalExample

            +

            Shows how to create and use a calendar file.

            +             + +

            ContactViews

            +

            Shows how to use various contact view classes to create +a view of a contact database.

            +             + + +

            PIM Application Support

            + + + +Name +Description + + + + +

            CalconExample

            +

            Shows how to convert between Gregorian and Chinese dates.

            +             + +

            VersitExample

            +

            Shows how to import and export vCards.

            +             + + +
            + +
            System +GUI Framework

            Look-and-Feel Agnostic UI Foundation

            + + + +Name +Description + + + + + +

            ClockExample

            +

            Shows how to create and display digital and analogue clocks.

            +             + + + + +
            +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-27340D18-A31D-512E-920A-B06C784A978A.dita --- a/Symbian3/SDK/Source/GUID-27340D18-A31D-512E-920A-B06C784A978A.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-27340D18-A31D-512E-920A-B06C784A978A.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,188 +1,188 @@ - - - - - -String -Pools -

            Many systems, components and applications deal with pre-defined, well known -string constants. For example, parsing and manipulating text containing structure -mostly requires comparisons against standard string constants.

            -

            In a complex system, composed of a large number of objects, there may also -be a need to pass strings between objects, and to route processing depending -on the value of some string. The implementation of the HTTP transport framework -and the XML framework are examples within the Symbian platform where such -intense string handling is required.

            -

            To improve efficiency, the Symbian platform uses the idea of the string -pool.

            -

            A string pool is referenced through an RStringPool, -which is a handle like object. The following diagram illustrates the basic -idea:

            - - String pool representation - - -

            A string pool is a mechanism for storing strings in a particular way that -makes the comparison of strings a very fast operation. It is particularly -efficient at handling strings that can be set up at program compile time. -For example, strings that identify lexical elements in a structured text. -Typically, they are well known strings that are likely to be used very often -in a given context.

            -

            Such strings are organised into tables, and each string within a table -can be referenced by an index value, which can be symbolised by an enum. Such -tables are referred to as static string tables (See Static string tables). The basic algorithm used internally ensures -that the pool contains only one string of any particular value, and uses a -reference counting mechanism to keep track of usage.

            -

            The advantages of representing string constants in such a way are:

            -
              -

            • avoiding a proliferation -of duplicate strings throughout a component or an application; typically there -is one string pool per thread, and one copy of a string

              • -

            • allowing string constants -to be represented by integer values

              • -

            • allowing strings to -be passed between objects by passing integer values, wrapped in a class (any -one of the String and RStringF classes)

              • -

            • allowing strings to -be compared by comparing the integer values.

              • -
            -

            Internally, a string pool uses hash tables to reference strings.

            -

            Static string tables and string constants can be added dynamically to the -string pool, for example, at run time. However, there is always a performance -penalty while adding either a static or a dynamic string to the string pool -as the hash tables need to be updated. This means that it is better to add -static string tables at string pool initialisation time, as this is the best -time to absorb the overhead.

            -
            Key features of string pool
              -

            • The string pool as supplied -by the Symbian platform supports any strings that can be represented -by a TDes8 descriptor; this includes ASCII or UTF-8 encoded -strings. Note that a TDes8 type can represent any type -of data , including binary data, and means that a string pool can easily handle -the extended characters of another encoding.

              • -

            • Within the string pool, -strings are of two types - case sensitive and case insensitive. This affects -the way strings are compared. Case insensitivity implies that strings are -folded for the purpose of comparison.

              • -

            • A string pool can contain -up to 4,096 static string tables, and each table can represent up 26,2144 -strings.

              • -
            -
            Static string -tables

            Static string tables are defined and built at compile time. -They are represented by a TStringTable object. A string -table can be added to the string pool by passing the string table reference -to a call to:

            void RStringTable::OpenL( const TStringTable& aTable );

            The following diagram illustrates a general picture. Note that the strings -in any given string table are deemed to be either case sensitive or case insensitive, -and this governs how comparisons are made.

            - -

            As the name implies, a static string table is declared as a const - TStringTable data member of a class with a user-defined -name. The class name is defined in a header file while the table itself is -implemented in a .cpp C++ source file. Both the header file -and the C++ source file are normally included in the project definition. Typically, -a set of enum values are also defined within the scope of the class, and each -value is associated with the strings in the table; code in other parts of -the program access the strings in the string pool using these enum values.

            The -Perl script, stringtable.pl, located in ...\syslibs\bafl\stringtools\, -can be used to generate these .cpp and .h files -from a simple text definition. The text definition file simply lists the strings -and the enum symbols to be associated with them; the file itself is given -a .st file type.

            Following is a simple example of ExampleStringTable.st file:

            # Example String Table -fstringtable ExampleStringTable -!// Some types of fruit -# This comment won't appear in the .h file, but the one above will. -EApple apple -EOrange orange -EBanana banana -# Some animals -ECat cat -EDog dog -

            The main points to note are:

              -

            • the keyword fstringtable is -used to define the name of the class that contains the string table declaration -and the enum value symbols. The class name itself follows the keyword. For -example, ExampleStringTable.

              Note that you can include -underscore characters in the class name. For example, Example_StringTable.

              • -

            • the symbols EApple and EOrange form -the enum value symbols that correspond to the strings apple and orange respectively.

              • -

            • all statements starting -with a # are comments and are completely ignored. However # characters -can appear in a string. For example ap#ple is a valid string -and is not interpreted as a comment.

              • -

            • all statements starting -with a ! are comments that are inserted into the generated header file.

              • -

            Running the Perl script with ExampleStringTable.st as -source generates the header file ExampleStringTable.h and -the C++ source file ExampleStringTable.cpp as illustrated -below:

            // Autogenerated from epoc32\build\generated\example\ExampleStringTable.st by the stringtable tool - Do not edit - -#ifndef STRINGTABLE_ExampleStringTable -#define STRINGTABLE_ExampleStringTable - -#include "StringPool.h" - -struct TStringTable; - -/** A String table */ -class ExampleStringTable - { - public: - enum TStrings - { - // Some types of fruit - /** apple */ - EApple, - /** orange */ - EOrange, - /** banana */ - EBanana, - /** cat */ - ECat, - /** dog */ - EDog - }; - static const TStringTable Table; - }; - -#endif // STRINGTABLE_ExampleStringTable - // Autogenerated from epoc32\build\generated\example\ExampleStringTable.st by the stringtable tool - Do not edit -#include <e32std.h> -#include "StringPool.h" -#include "StringTableSupport.h" -#include "ExampleStringTable.h" -#ifdef _DEBUG -#undef _DEBUG -#endif - -_STLIT8( K1, "apple" ); -_STLIT8( K2, "orange" ); -_STLIT8( K3, "banana" ); -_STLIT8( K4, "cat" ); -_STLIT8( K5, "dog" ); - -// Intermediate -const void * const KStringPointers[] = - { - ( const void* )&K1, - ( const void* )&K2, - ( const void* )&K3, - ( const void* )&K4, - ( const void* )&K5 - }; - -const TStringTable ExampleStringTable::Table = {5, KStringPointers, EFalse}; -

            The table itself is the static data member Table of -class ExampleStringTable.

            -             -Constructing -a Static String Table -Using string -pools + + + + + +String +Pools +

            Many systems, components and applications deal with pre-defined, well known +string constants. For example, parsing and manipulating text containing structure +mostly requires comparisons against standard string constants.

            +

            In a complex system, composed of a large number of objects, there may also +be a need to pass strings between objects, and to route processing depending +on the value of some string. The implementation of the HTTP transport framework +and the XML framework are examples within the Symbian platform where such +intense string handling is required.

            +

            To improve efficiency, the Symbian platform uses the idea of the string +pool.

            +

            A string pool is referenced through an RStringPool, +which is a handle like object. The following diagram illustrates the basic +idea:

            + + String pool representation + + +

            A string pool is a mechanism for storing strings in a particular way that +makes the comparison of strings a very fast operation. It is particularly +efficient at handling strings that can be set up at program compile time. +For example, strings that identify lexical elements in a structured text. +Typically, they are well known strings that are likely to be used very often +in a given context.

            +

            Such strings are organised into tables, and each string within a table +can be referenced by an index value, which can be symbolised by an enum. Such +tables are referred to as static string tables (See Static string tables). The basic algorithm used internally ensures +that the pool contains only one string of any particular value, and uses a +reference counting mechanism to keep track of usage.

            +

            The advantages of representing string constants in such a way are:

            +
              +

            • avoiding a proliferation +of duplicate strings throughout a component or an application; typically there +is one string pool per thread, and one copy of a string

              • +

            • allowing string constants +to be represented by integer values

              • +

            • allowing strings to +be passed between objects by passing integer values, wrapped in a class (any +one of the String and RStringF classes)

              • +

            • allowing strings to +be compared by comparing the integer values.

              • +
            +

            Internally, a string pool uses hash tables to reference strings.

            +

            Static string tables and string constants can be added dynamically to the +string pool, for example, at run time. However, there is always a performance +penalty while adding either a static or a dynamic string to the string pool +as the hash tables need to be updated. This means that it is better to add +static string tables at string pool initialisation time, as this is the best +time to absorb the overhead.

            +
            Key features of string pool
              +

            • The string pool as supplied +by the Symbian platform supports any strings that can be represented +by a TDes8 descriptor; this includes ASCII or UTF-8 encoded +strings. Note that a TDes8 type can represent any type +of data , including binary data, and means that a string pool can easily handle +the extended characters of another encoding.

              • +

            • Within the string pool, +strings are of two types - case sensitive and case insensitive. This affects +the way strings are compared. Case insensitivity implies that strings are +folded for the purpose of comparison.

              • +

            • A string pool can contain +up to 4,096 static string tables, and each table can represent up 26,2144 +strings.

              • +
            +
            Static string +tables

            Static string tables are defined and built at compile time. +They are represented by a TStringTable object. A string +table can be added to the string pool by passing the string table reference +to a call to:

            void RStringTable::OpenL( const TStringTable& aTable );

            The following diagram illustrates a general picture. Note that the strings +in any given string table are deemed to be either case sensitive or case insensitive, +and this governs how comparisons are made.

            + +

            As the name implies, a static string table is declared as a const + TStringTable data member of a class with a user-defined +name. The class name is defined in a header file while the table itself is +implemented in a .cpp C++ source file. Both the header file +and the C++ source file are normally included in the project definition. Typically, +a set of enum values are also defined within the scope of the class, and each +value is associated with the strings in the table; code in other parts of +the program access the strings in the string pool using these enum values.

            The +Perl script, stringtable.pl, located in ...\syslibs\bafl\stringtools\, +can be used to generate these .cpp and .h files +from a simple text definition. The text definition file simply lists the strings +and the enum symbols to be associated with them; the file itself is given +a .st file type.

            Following is a simple example of ExampleStringTable.st file:

            # Example String Table +fstringtable ExampleStringTable +!// Some types of fruit +# This comment won't appear in the .h file, but the one above will. +EApple apple +EOrange orange +EBanana banana +# Some animals +ECat cat +EDog dog +

            The main points to note are:

              +

            • the keyword fstringtable is +used to define the name of the class that contains the string table declaration +and the enum value symbols. The class name itself follows the keyword. For +example, ExampleStringTable.

              Note that you can include +underscore characters in the class name. For example, Example_StringTable.

              • +

            • the symbols EApple and EOrange form +the enum value symbols that correspond to the strings apple and orange respectively.

              • +

            • all statements starting +with a # are comments and are completely ignored. However # characters +can appear in a string. For example ap#ple is a valid string +and is not interpreted as a comment.

              • +

            • all statements starting +with a ! are comments that are inserted into the generated header file.

              • +

            Running the Perl script with ExampleStringTable.st as +source generates the header file ExampleStringTable.h and +the C++ source file ExampleStringTable.cpp as illustrated +below:

            // Autogenerated from epoc32\build\generated\example\ExampleStringTable.st by the stringtable tool - Do not edit + +#ifndef STRINGTABLE_ExampleStringTable +#define STRINGTABLE_ExampleStringTable + +#include "StringPool.h" + +struct TStringTable; + +/** A String table */ +class ExampleStringTable + { + public: + enum TStrings + { + // Some types of fruit + /** apple */ + EApple, + /** orange */ + EOrange, + /** banana */ + EBanana, + /** cat */ + ECat, + /** dog */ + EDog + }; + static const TStringTable Table; + }; + +#endif // STRINGTABLE_ExampleStringTable + // Autogenerated from epoc32\build\generated\example\ExampleStringTable.st by the stringtable tool - Do not edit +#include <e32std.h> +#include "StringPool.h" +#include "StringTableSupport.h" +#include "ExampleStringTable.h" +#ifdef _DEBUG +#undef _DEBUG +#endif + +_STLIT8( K1, "apple" ); +_STLIT8( K2, "orange" ); +_STLIT8( K3, "banana" ); +_STLIT8( K4, "cat" ); +_STLIT8( K5, "dog" ); + +// Intermediate +const void * const KStringPointers[] = + { + ( const void* )&K1, + ( const void* )&K2, + ( const void* )&K3, + ( const void* )&K4, + ( const void* )&K5 + }; + +const TStringTable ExampleStringTable::Table = {5, KStringPointers, EFalse}; +

            The table itself is the static data member Table of +class ExampleStringTable.

            +             +Constructing +a Static String Table +Using string +pools             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2735BDAF-295F-5F1E-8925-8F4212D95CD1_d0e264145_href.png Binary file Symbian3/SDK/Source/GUID-2735BDAF-295F-5F1E-8925-8F4212D95CD1_d0e264145_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2735BDAF-295F-5F1E-8925-8F4212D95CD1_d0e267853_href.png Binary file Symbian3/SDK/Source/GUID-2735BDAF-295F-5F1E-8925-8F4212D95CD1_d0e267853_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-27529BB0-8034-56B0-82FA-3E4CFDEBC99A_d0e299272_href.png Binary file Symbian3/SDK/Source/GUID-27529BB0-8034-56B0-82FA-3E4CFDEBC99A_d0e299272_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-27529BB0-8034-56B0-82FA-3E4CFDEBC99A_d0e305299_href.png Binary file Symbian3/SDK/Source/GUID-27529BB0-8034-56B0-82FA-3E4CFDEBC99A_d0e305299_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2762FDF6-F76D-5268-AE2D-4ABA807CFFEE.dita --- a/Symbian3/SDK/Source/GUID-2762FDF6-F76D-5268-AE2D-4ABA807CFFEE.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-2762FDF6-F76D-5268-AE2D-4ABA807CFFEE.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,53 +1,53 @@ - - - - - -Heap -descriptorsDescribes heap descriptors. -

            A heap descriptor provides a fixed length buffer, allocated on the heap, -to contain and access data. The data is part of the descriptor object.

            -

            The data contained in a heap descriptor can be accessed, but not changed, -through this descriptor. The data can, however, be completely replaced using -the assignment operators.

            -

            A heap descriptor also has the important property that it can be made larger -or smaller, changing the size of the descriptor's buffer. This is achieved -by reallocating the descriptor. Unlike the behaviour of dynamic buffers, reallocation -is not done automatically.

            -

            Data is accessed through functions provided by the base class.

            -

            A heap descriptor is supplied in two variants:

            -
              -

            • the 16 bit variant, -a HBufC16, to contain Unicode strings.

              • -

            • the 8 bit variant, a HBufC8, -to contain non-Unicode strings and binary data.

              • -
            -

            There is also a build independent type, HBufC. This is -the type which is most commonly used in program code; the appropriate variant -is selected at build time.

            -

            An explicit 8 bit variant is chosen for binary data. An explicit 16 bit -variant is rarely used.

            -

            The base class, TDesC, contains a data member which holds -the length of the data. The following drawing shows the layout of a HBufC object -initialised with the string of five characters representing the English word -"Hello". The descriptor object is allocated on the heap.

            -

            Although it is not possible to change the data in the descriptor directly -through the descriptor member functions, it is possible to do this -indirectly by using the Des() member function of HBufC to -first create a modifiable pointer -descriptor, a TPtr type, and then to use this descriptor's -member functions. For this reason, heap descriptors are best suited for data -that rarely changes. For data that changes frequently, it is much better to -use the resizable buffer -descriptor.

            - - -

            Example of a Heap descriptor

            -             + + + + + +Heap +descriptorsDescribes heap descriptors. +

            A heap descriptor provides a fixed length buffer, allocated on the heap, +to contain and access data. The data is part of the descriptor object.

            +

            The data contained in a heap descriptor can be accessed, but not changed, +through this descriptor. The data can, however, be completely replaced using +the assignment operators.

            +

            A heap descriptor also has the important property that it can be made larger +or smaller, changing the size of the descriptor's buffer. This is achieved +by reallocating the descriptor. Unlike the behaviour of dynamic buffers, reallocation +is not done automatically.

            +

            Data is accessed through functions provided by the base class.

            +

            A heap descriptor is supplied in two variants:

            +
              +

            • the 16 bit variant, +a HBufC16, to contain Unicode strings.

              • +

            • the 8 bit variant, a HBufC8, +to contain non-Unicode strings and binary data.

              • +
            +

            There is also a build independent type, HBufC. This is +the type which is most commonly used in program code; the appropriate variant +is selected at build time.

            +

            An explicit 8 bit variant is chosen for binary data. An explicit 16 bit +variant is rarely used.

            +

            The base class, TDesC, contains a data member which holds +the length of the data. The following drawing shows the layout of a HBufC object +initialised with the string of five characters representing the English word +"Hello". The descriptor object is allocated on the heap.

            +

            Although it is not possible to change the data in the descriptor directly +through the descriptor member functions, it is possible to do this +indirectly by using the Des() member function of HBufC to +first create a modifiable pointer +descriptor, a TPtr type, and then to use this descriptor's +member functions. For this reason, heap descriptors are best suited for data +that rarely changes. For data that changes frequently, it is much better to +use the resizable buffer +descriptor.

            + + +

            Example of a Heap descriptor

            +                         \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-27EC3C5B-175C-5D27-874C-43D46AA44C08_d0e287704_href.png Binary file Symbian3/SDK/Source/GUID-27EC3C5B-175C-5D27-874C-43D46AA44C08_d0e287704_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-27EC3C5B-175C-5D27-874C-43D46AA44C08_d0e291337_href.png Binary file Symbian3/SDK/Source/GUID-27EC3C5B-175C-5D27-874C-43D46AA44C08_d0e291337_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2922758C-37A4-436E-B0F3-358944F84E2A.dita --- a/Symbian3/SDK/Source/GUID-2922758C-37A4-436E-B0F3-358944F84E2A.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-2922758C-37A4-436E-B0F3-358944F84E2A.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,101 +1,101 @@ - - - - - -Pop-up -windows -

            Certain UI components are displayed within pop-up windows. A common characteristic -for all these components is that they are temporary states This means that -typically back stepping from one state to the previous state does not lead -into pop-up windows; they are skipped.

            -Pop-up components - - - -Component -Description - - - - -

            Options menu

             -

            The commands and options that are available in the current context -can be accessed via the Options menu. It is displayed as a list in -a pop-up window.

             -             - -

            Query

             -

            A query is a component where the software requests user input. All -query components are displayed in pop-up windows. They consist of a prompt -(possibly containing a graphical element) and some kind of an input component. -Various types of queries exist:

              -

            • A Confirmation query has either one or two possible input values, given -by using the softkeys.

              • -

            • A List query has a limited number of possible input values, and the -user selects one from a list.

              • -

            • A multi-selection List query has a limited number of possible input -values, and the user can select zero, one or more of them in one pass.

              • -

            • A Data query contains an input field for a numeric or alphanumeric -value that the user can edit.

              • -
             -             - -

            Note

             -

            A note is a feedback component that informs the user about the current -situation. They contain a text and possibly a graphical element, and their -layout is similar to a Confirmation query. However, the softkey labels do -typically not exist, as notes do not require user input and by default they -disappear within a time-out.

             -             - -

            Soft notification

             -

            Soft notifications are reminders that inform the user of events -that have typically occurred during the user's absence. Soft notifications -can only be seen in the Idle state, and the user can acknowledge them. There -are two types of soft notifications; the layouts resemble those of Confirmation -queries and List queries:

              -

            • A single soft notification contains one notification.

              • -

            • A grouped soft notification contains a number of information items -presented as a list, and a title text common to all of the items.

              • -
             -             - -

            Call window

             -

            Incoming calls and outgoing calls are presented in pop-up windows.

             -             - -

            Discreet pop-up

             -

            Discreet pop-up is a temporary pop-up that appears on the upper -left corner for certain time-out. When discreet pop-up appears, it does not -dim the background and it does not have the focus. User can navigate in the -underlying application normally.

            Pop-up can have simple touch functionality. -It can be used, for example, for the information and confirmation note.

             -             - -

            Universal indicator pop-up

             -

            Universal indicator pop-up is opened from the universal indicator -pane. It contains more information of the active status indicators.

             -             - - -
            -

            For more information, see Pop-ups

            -
            Using -pop-up windows in C++ applications

            For implementation information -on the pop-up window components, see:

              -

            • Options menu

              • -

            • Query

              • -

            • Note

              • -

            • Soft notification

              • -

            • Discreet pop-up

              • -

            • Universal indicator -pop-up

              • -
            + + + + + +Pop-up +windows +

            Certain UI components are displayed within pop-up windows. A common characteristic +for all these components is that they are temporary states This means that +typically back stepping from one state to the previous state does not lead +into pop-up windows; they are skipped.

            +Pop-up components + + + +Component +Description + + + + +

            Options menu

             +

            The commands and options that are available in the current context +can be accessed via the Options menu. It is displayed as a list in +a pop-up window.

             +             + +

            Query

             +

            A query is a component where the software requests user input. All +query components are displayed in pop-up windows. They consist of a prompt +(possibly containing a graphical element) and some kind of an input component. +Various types of queries exist:

              +

            • A Confirmation query has either one or two possible input values, given +by using the softkeys.

              • +

            • A List query has a limited number of possible input values, and the +user selects one from a list.

              • +

            • A multi-selection List query has a limited number of possible input +values, and the user can select zero, one or more of them in one pass.

              • +

            • A Data query contains an input field for a numeric or alphanumeric +value that the user can edit.

              • +
             +             + +

            Note

             +

            A note is a feedback component that informs the user about the current +situation. They contain a text and possibly a graphical element, and their +layout is similar to a Confirmation query. However, the softkey labels do +typically not exist, as notes do not require user input and by default they +disappear within a time-out.

             +             + +

            Soft notification

             +

            Soft notifications are reminders that inform the user of events +that have typically occurred during the user's absence. Soft notifications +can only be seen in the home screen, and the user can acknowledge them. There +are two types of soft notifications; the layouts resemble those of Confirmation +queries and List queries:

              +

            • A single soft notification contains one notification.

              • +

            • A grouped soft notification contains a number of information items +presented as a list, and a title text common to all of the items.

              • +
             +             + +

            Call window

             +

            Incoming calls and outgoing calls are presented in pop-up windows.

             +             + +

            Discreet pop-up

             +

            Discreet pop-up is a temporary pop-up that appears on the upper +left corner for certain time-out. When discreet pop-up appears, it does not +dim the background and it does not have the focus. User can navigate in the +underlying application normally.

            Pop-up can have simple touch functionality. +It can be used, for example, for the information and confirmation note.

             +             + +

            Universal indicator pop-up

             +

            Universal indicator pop-up is opened from the universal indicator +pane. It contains more information of the active status indicators.

             +             + + +
            +

            For more information, see Pop-ups

            +
            Using +pop-up windows in applications

            For implementation information on +the pop-up window components, see:

              +

            • Options menu

              • +

            • Query

              • +

            • Note

              • +

            • Soft notification

              • +

            • Discreet pop-up

              • +

            • Universal indicator +pop-up

              • +
             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2939EEA8-DBC9-4882-B016-9C53166569CD-master.png Binary file Symbian3/SDK/Source/GUID-2939EEA8-DBC9-4882-B016-9C53166569CD-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2939EEA8-DBC9-4882-B016-9C53166569CD_d0e56908_href.png Binary file Symbian3/SDK/Source/GUID-2939EEA8-DBC9-4882-B016-9C53166569CD_d0e56908_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2939EEA8-DBC9-4882-B016-9C53166569CD_d0e63329_href.png Binary file Symbian3/SDK/Source/GUID-2939EEA8-DBC9-4882-B016-9C53166569CD_d0e63329_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-29486886-CB54-4A83-AD6D-70F971A86DFC.dita --- a/Symbian3/SDK/Source/GUID-29486886-CB54-4A83-AD6D-70F971A86DFC.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-29486886-CB54-4A83-AD6D-70F971A86DFC.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,99 +1,99 @@ - - - - - -Application -and UI frameworks -

            The section explains how to use the features offered by the -application and UI frameworks when designing and implementing your application.

            -

            The table below illustrates different areas used in the Hello World Basic -sample application included in the Symbian Platform and provides information -on how to implement the different areas in your application using the application -and UI frameworks.

            -

            - - - - -

            Area

             -

            Example from Hello World Basic sample application

             -

            Implementation information

             -             - - - -

            Launching the application

             - - -

            -

              -

            • Framework requirements -for GUI applications

              • -

            • Implementing -application framework requirements

              • -

            • Registering -your application

              • -
             -             - -

            Handling left softkey events and launching the Options menu

             - - -

            -

              -

            • Event handling

              • -

            • Handling commands

              • -
             -             - -

            Handling key and pointer events

            - - -

            - -

            -

              -

            • Handling window -server events

              • -

            • Handling key -events

              • -

            • Handling pointer -events

              • -
             -             - -

            Rotation

             - - -

            -

            Handling -layout change events

             -             - -

            Internationalization

             - - -

            - -

            -

            Internationalization -and localization

             -             - -

            Exiting the application

             - - -

            -

            Handling -EEikCmdExit

             -             - - + + + + + +Application +and UI frameworks +

            The section explains how to use the features offered by the +application and UI frameworks when designing and implementing your application.

            +

            The table below illustrates different areas used in the Hello World Basic +sample application included in the Symbian Platform and provides information +on how to implement the different areas in your application using the application +and UI frameworks.

            +

            +

            + + + +

            Area

             +

            Example from Hello World Basic sample application

             +

            Implementation information

             +             + + + +

            Launching the application

             + + +

            +

              +

            • Framework requirements +for GUI applications

              • +

            • Implementing +application framework requirements

              • +

            • Registering +your application

              • +
             +             + +

            Handling left softkey events and launching the Options menu

             + + +

            +

              +

            • Event handling

              • +

            • Handling commands

              • +
             +             + +

            Handling key and pointer events

            + + +

            + +

            +

              +

            • Handling window +server events

              • +

            • Handling key +events

              • +

            • Handling pointer +events

              • +
             +             + +

            Rotation

             + + +

            +

            Handling +layout change events

             +             + +

            Internationalization

             + + +

            + +

            +

            Internationalization +and localization

             +             + +

            Exiting the application

             + + +

            +

            Handling +EEikCmdExit

             +             + +
            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-295341D9-A5FA-4F25-B681-C5B3264165AF.dita --- a/Symbian3/SDK/Source/GUID-295341D9-A5FA-4F25-B681-C5B3264165AF.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-295341D9-A5FA-4F25-B681-C5B3264165AF.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,22 +1,22 @@ - - - - - -Text -fields -

            Stylus usage in text fields is supported. Tapping on a text field moves -the text cursor to the tapped point. Blocks of text can be selected by moving -the stylus while holding it down against the screen (horizontal dragging). -Horizontal dragging can be continued with vertical movement to move content -upwards and downwards.

            -
            Using -text editing in C++ applications

            The API to use for providing text -editing functionality is the Editors API. For implementation information, see Using the Editors API.

            + + + + + +Text +fields +

            Stylus usage in text fields is supported. Tapping on a text field moves +the text cursor to the tapped point. Blocks of text can be selected by moving +the stylus while holding it down against the screen (horizontal dragging). +Horizontal dragging can be continued with vertical movement to move content +upwards and downwards.

            +
            Using +text editing in applications

            The API to use for providing +text editing functionality is the Editors API. For implementation information, see Using the Editors API.

             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-296F25B4-8942-5FCB-B0A2-367157B72B72_d0e336710_href.png Binary file Symbian3/SDK/Source/GUID-296F25B4-8942-5FCB-B0A2-367157B72B72_d0e336710_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-296F25B4-8942-5FCB-B0A2-367157B72B72_d0e342907_href.png Binary file Symbian3/SDK/Source/GUID-296F25B4-8942-5FCB-B0A2-367157B72B72_d0e342907_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2972C100-EE68-5182-927C-3C46E8F5C0DD-master.png Binary file Symbian3/SDK/Source/GUID-2972C100-EE68-5182-927C-3C46E8F5C0DD-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2972C100-EE68-5182-927C-3C46E8F5C0DD_d0e383129_href.png Binary file Symbian3/SDK/Source/GUID-2972C100-EE68-5182-927C-3C46E8F5C0DD_d0e383129_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-29E54156-DF94-5B34-ACAB-1417265C950D_d0e220101_href.png Binary file Symbian3/SDK/Source/GUID-29E54156-DF94-5B34-ACAB-1417265C950D_d0e220101_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-29E54156-DF94-5B34-ACAB-1417265C950D_d0e223838_href.png Binary file Symbian3/SDK/Source/GUID-29E54156-DF94-5B34-ACAB-1417265C950D_d0e223838_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-29E7942D-A00D-5771-9782-59260965C687_d0e213911_href.png Binary file Symbian3/SDK/Source/GUID-29E7942D-A00D-5771-9782-59260965C687_d0e213911_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-29E7942D-A00D-5771-9782-59260965C687_d0e217648_href.png Binary file Symbian3/SDK/Source/GUID-29E7942D-A00D-5771-9782-59260965C687_d0e217648_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-29F55D74-A206-5862-9C83-2C5045B2DB7F_d0e299287_href.png Binary file Symbian3/SDK/Source/GUID-29F55D74-A206-5862-9C83-2C5045B2DB7F_d0e299287_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-29F55D74-A206-5862-9C83-2C5045B2DB7F_d0e305314_href.png Binary file Symbian3/SDK/Source/GUID-29F55D74-A206-5862-9C83-2C5045B2DB7F_d0e305314_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2A109FEC-5173-55FD-ACA8-3CAE48A93540_d0e375491_href.png Binary file Symbian3/SDK/Source/GUID-2A109FEC-5173-55FD-ACA8-3CAE48A93540_d0e375491_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2A109FEC-5173-55FD-ACA8-3CAE48A93540_d0e381570_href.png Binary file Symbian3/SDK/Source/GUID-2A109FEC-5173-55FD-ACA8-3CAE48A93540_d0e381570_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2A4DED23-D0AB-436A-BCED-F0645FF05726-master.png Binary file Symbian3/SDK/Source/GUID-2A4DED23-D0AB-436A-BCED-F0645FF05726-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2A4DED23-D0AB-436A-BCED-F0645FF05726_d0e51533_href.png Binary file Symbian3/SDK/Source/GUID-2A4DED23-D0AB-436A-BCED-F0645FF05726_d0e51533_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2A4DED23-D0AB-436A-BCED-F0645FF05726_d0e57086_href.png Binary file Symbian3/SDK/Source/GUID-2A4DED23-D0AB-436A-BCED-F0645FF05726_d0e57086_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2A4DED23-D0AB-436A-BCED-F0645FF05726_d0e66217_href.png Binary file Symbian3/SDK/Source/GUID-2A4DED23-D0AB-436A-BCED-F0645FF05726_d0e66217_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2A4DED23-D0AB-436A-BCED-F0645FF05726_d0e68802_href.png Binary file Symbian3/SDK/Source/GUID-2A4DED23-D0AB-436A-BCED-F0645FF05726_d0e68802_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2A4DED23-D0AB-436A-BCED-F0645FF05726_d0e71460_href.png Binary file Symbian3/SDK/Source/GUID-2A4DED23-D0AB-436A-BCED-F0645FF05726_d0e71460_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2A4DED23-D0AB-436A-BCED-F0645FF05726_d0e73947_href.png Binary file Symbian3/SDK/Source/GUID-2A4DED23-D0AB-436A-BCED-F0645FF05726_d0e73947_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2AB5AA00-71B2-58F4-AE17-9A38D1E5AA99_d0e213823_href.png Binary file Symbian3/SDK/Source/GUID-2AB5AA00-71B2-58F4-AE17-9A38D1E5AA99_d0e213823_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2AB5AA00-71B2-58F4-AE17-9A38D1E5AA99_d0e217560_href.png Binary file Symbian3/SDK/Source/GUID-2AB5AA00-71B2-58F4-AE17-9A38D1E5AA99_d0e217560_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2ABCF233-7DCC-59E2-B075-81E148A1D2AB_d0e262336_href.png Binary file Symbian3/SDK/Source/GUID-2ABCF233-7DCC-59E2-B075-81E148A1D2AB_d0e262336_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2ABCF233-7DCC-59E2-B075-81E148A1D2AB_d0e266044_href.png Binary file Symbian3/SDK/Source/GUID-2ABCF233-7DCC-59E2-B075-81E148A1D2AB_d0e266044_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2B50C6B1-E1E8-44E6-840B-7FAA206E6C26_d0e42265_href.png Binary file Symbian3/SDK/Source/GUID-2B50C6B1-E1E8-44E6-840B-7FAA206E6C26_d0e42265_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2B50C6B1-E1E8-44E6-840B-7FAA206E6C26_d0e47820_href.png Binary file Symbian3/SDK/Source/GUID-2B50C6B1-E1E8-44E6-840B-7FAA206E6C26_d0e47820_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2B820ED0-D0E1-4CF0-9D63-C91806EDB8F6_d0e2807_href.png Binary file Symbian3/SDK/Source/GUID-2B820ED0-D0E1-4CF0-9D63-C91806EDB8F6_d0e2807_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2B820ED0-D0E1-4CF0-9D63-C91806EDB8F6_d0e2909_href.png Binary file Symbian3/SDK/Source/GUID-2B820ED0-D0E1-4CF0-9D63-C91806EDB8F6_d0e2909_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2B8CA0F5-8956-4D7B-B719-DE5EFD62C232.dita --- a/Symbian3/SDK/Source/GUID-2B8CA0F5-8956-4D7B-B719-DE5EFD62C232.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-2B8CA0F5-8956-4D7B-B719-DE5EFD62C232.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,23 +1,23 @@ - - - - - -Numbered -items -

            Instead of a small graphic, column A (where used separately) may contain -a number. This can be used to indicate item numbers in lists where necessary.

            - -Numbered list item - - -

            Numbered items should be used only in lists where numbers are meaningful -and give added value. There is no specific functionality (such as shortcuts) -that all numbered lists would have.

            + + + + + +Numbered +items +

            Instead of a small graphic, column A (where used separately) may contain +a number. This can be used to indicate item numbers in lists where necessary.

            + +Numbered list item + + +

            Numbered items should be used only in lists where numbers are meaningful +and give added value. There is no specific functionality (such as shortcuts) +that all numbered lists would have.

             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2BF99BD2-5DB5-5DF6-8F82-22DD2E818584_d0e18317_href.png Binary file Symbian3/SDK/Source/GUID-2BF99BD2-5DB5-5DF6-8F82-22DD2E818584_d0e18317_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2BF99BD2-5DB5-5DF6-8F82-22DD2E818584_d0e48659_href.png Binary file Symbian3/SDK/Source/GUID-2BF99BD2-5DB5-5DF6-8F82-22DD2E818584_d0e48659_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2BF99BD2-5DB5-5DF6-8F82-22DD2E818584_d0e54219_href.png Binary file Symbian3/SDK/Source/GUID-2BF99BD2-5DB5-5DF6-8F82-22DD2E818584_d0e54219_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2C443E6F-BC3D-5252-8098-9F850AA88A35.dita --- a/Symbian3/SDK/Source/GUID-2C443E6F-BC3D-5252-8098-9F850AA88A35.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-2C443E6F-BC3D-5252-8098-9F850AA88A35.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,251 +1,251 @@ - - - - - -Window -Server Component OverviewThe Window Server manages the use of the screen and input devices -by applications and controls and co-ordinates access. -
            Architecture

            The -architecture of the Window Server varies depending on whether you are using -the ScreenPlay (NGA) or non-ScreenPlay variant. -However, with a few exceptions, the client-side API is the same in both variants. -Both variants use an improved version of the Window Server, sometimes known -as WSERV2, which was introduced in Symbian^2 (Symbian OS -v9.4).

            The following diagram provides an overview of the Window Server -architecture in ScreenPlay.

            - The Window Server in ScreenPlay - -

            Below we list some of the key features of the Window Server, including -differences between the two architectures. The term surface is used -in ScreenPlay for a hardware-independent memory buffer for holding an image -or part of a scene. The UI surface is a special surface onto which -the Window Server renders all of the UI content. It is created automatically -during system start up. An external surface is any other surface—for -example, a surface that holds a video or to which OpenGL ES content is rendered.

              -

            • The Window Server has -a render stage framework, which enables the last stage of the Window Server -rendering to be customizable through plug-ins called render stages. -These can be chained to form a rendering pipeline, which takes the drawing -operations that are produced by the Window Server and ultimately passes them -to the UI surface. Render stages can selectively filter, modify, or redirect -the draw operation stream, as required—for example, to perform transition -effects (TFX).

              • -

            • In ScreenPlay, composition -takes place in two stages. First, the render stages render the drawing to -the UI surface. Then the composition engine combines the UI surface and any -external surfaces into elements (sometimes called layers) and composes -them to the screen. This enables the composition to be performed in software -or hardware accelerator chips.

              • -

            • In the non-ScreenPlay -variant, the concept of surfaces is not used and the Window Server composes -directly onto the frame buffer which is then displayed on the screen.

              • -

            • There are differences -in the plug-in framework APIs in the two architectures. In addition, in ScreenPlay, -fading effects are implemented by using render stages, whereas when ScreenPlay -is not enabled they are implemented by using a separate fader plug-in type -(not shown on the diagram).

              • -

            • In ScreenPlay, the Window -Server provides advanced pointer features, such as support for multiple pointers -and proximity and pressure coordinates. The non-ScreenPlay variant does not -provide this support.

              • -

            • ScreenPlay provides -support for externally connected displays, such as TV-out. The non-ScreenPlay -variant considers the size of each display to be fixed. However, for High-Definition -Multimedia Interface (HDMI) and composite video connectors, there are a range -of resolutions that can change dynamically. ScreenPlay provides an optional -feature that supports switching between resolutions at runtime and notifications -to Window Server clients when there are changes to the resolution and connectedness.

              • -
            -
            Building the -ScreenPlay and non-ScreenPlay variants

            To build the ScreenPlay -version of the Window Server components, declare the following macros in the Symbian_OS.hrh file.

            SYMBIAN_BUILD_GCE -SYMBIAN_GRAPHICS_BUILD_OPENWF_WSERV -

            This causes the ScreenPlay versions of the components in the -Graphics package to be built in addition to the non-ScreenPlay components. -Specifically the SYMBIAN_BUILD_GCE macro causes the ScreenPlay -version of the Window Server to be built. This means that the w32_nga.mmp and wserv_nga.mmp files -are built. These define a second macro, SYMBIAN_GRAPHICS_GCE, -which causes the ScreenPlay Window Server classes to be built.

            To include the ScreenPlay versions when building -ROM, use the SYMBIAN_GRAPHICS_USE_GCE flag.

            -
            Selecting the -ScreenPlay variant in the emulator

            To select the ScreenPlay version -of the component in the emulator, add the following line to the epoc.ini file:

            SYMBIAN_GRAPHICS_USE_GCE ON
            -
            Executables

            This -section lists the main Window Server executables. For clarity, these are divided -into three groups.

            Window Server executable and client-side libraries

            - - - -Executable -LIB -Description - - - - -

            wserv_nga.exe

            -

             -

            The ScreenPlay version of the Window Server.

            -             - -

            wserv_nonnga.exe

            -

             -

            The non-ScreenPlay version of the Window Server.

            -             - -

            ws32_nga.dll

            -

            ws32.lib

            -

            The Window Server client-side API library for the ScreenPlay variant. -See Window Server Client-Side -Library.

            -             - -

            ws32_nonnga.dll

            -

            ws32.lib

            -

            The Window Server client-side API library for the non-ScreenPlay -variant. See Window -Server Client-Side Library.

            -             - -

            wsgraphicdrawer_nga.dll

            -

            wsgraphicdrawer.lib

            -

            The server-side base classes for Window Server plug-ins in the ScreenPlay -variant. The plug-ins include graphic drawer plug-ins (which are also known -as Content Rendering Plug-ins or CRPs) and render stage plug-ins.

            -             - -

            wsgraphicdrawer_nonnga.dll

            -

            wsgraphicdrawer.lib

            -

            The server-side base classes for Window Server plug-ins in the non-ScreenPlay -variant. The plug-ins include graphic drawer plug-ins (which are also known -as Content Rendering Plug-ins or CRPs) and render stage and fader plug-ins.

            -             - -

            remotegc_nga.dll

            -

            remotegc.lib

            -

            The client-side API library for remote graphic contexts in ScreenPlay. -Remote graphic contexts store draw operations so that they can be played back -later. It is "remote" because the draw operations are generally played back -in a different location from where they are stored. For example, the draw -operations are frequently stored on the client side and then a transformation -engine uses them on the server side to make an effect.

            -             - -

            remotegc_nonnga.dll

            -

            remotegc.lib

            -

            The client-side API library for remote graphic contexts in the non-ScreenPlay -variant. This has a similar role as in ScreenPlay.

            -             - -

            profilerkeys.dll

            - -

            Window Server profiling hotkeys library in both ScreenPlay and non-ScreenPlay -variants.

            -             - - -

            Logging libraries

            - - - -Executable -Description - - - - -

            dlog.dll

            -

            On-screen logging library

            -             - -

            dlogfl.dll

            -

            File logging library

            -             - -

            dlogrd.dll

            - -             - -

            dlogsr.dll

            -

            Serial logging library

            -             - - -

            Plug-ins

            - - - -Executable -Variant -Description - - - - -

            10281922.dll

            -

            Both

            -

            This is a standard reference CRP. This type of plug-in is called -a CWsGraphics ECOM plug-in. Device creators can replace this component.

            -             - -

            2001b70b.dll

            -

            Non-ScreenPlay

            -

            This is a prototype reference render stage ECOM plug-in for the -non-ScreenPlay variant. This type of plug-in is called a CWsPlugin.

            Note: -The ScreenPlay render stage ECOM plug-in is delivered in the Window Server -Plugins component.

            -             - -

            10285c4a.dll

            -

            ScreenPlay

            -

            This is a reference ScreenPlay surface-based CRP. Device creators -can replace this component.

            -             - -

            samplegraphicsurface.dll

            -

            ScreenPlay

            -

            Sample ScreenPlay CRP (CWsGraphics) that demonstrates placing -a surface.

            -             - -

            w32stdgraphic.dll

            -

            Both

            -

            Sample CRP (CWsGraphics).

            -             - - -
            -
            Typical uses
              -

            • Application developers -use the client-side -library to control windows in their applications and respond to key -and pointer events.

              • -

            • Testers and application -developers use the logging -mechanism to log Window Server events when developing and testing their -code.

              • -

            • Device creators create -Content Rendering Plug-ins (CRPs) for showing customized content on the screen.

              • -

            • Device creators who -use ScreenPlay, can create render stage plug-ins. These enable the output -of the Window Server to be combined with auxiliary software subsystems (such -as a transition effect engine) and hardware-accelerated drawing (for example, -using OpenVG).

              • -

            • Device creators use -the wsini.ini file to -configure the Window Server to suit the specific requirements of the particular -device.

              • -
            -             -Window Server -Component - - + + + + + +Window +Server Component OverviewThe Window Server manages the use of the screen and input devices +by applications and controls and co-ordinates access. +
            Architecture

            The +architecture of the Window Server varies depending on whether you are using +the ScreenPlay (NGA) or non-ScreenPlay variant. +However, with a few exceptions, the client-side API is the same in both variants. +Both variants use an improved version of the Window Server, sometimes known +as WSERV2, which was introduced in Symbian^2 (Symbian OS +v9.4).

            The following diagram provides an overview of the Window Server +architecture in ScreenPlay.

            + The Window Server in ScreenPlay + +

            Below we list some of the key features of the Window Server, including +differences between the two architectures. The term surface is used +in ScreenPlay for a hardware-independent memory buffer for holding an image +or part of a scene. The UI surface is a special surface onto which +the Window Server renders all of the UI content. It is created automatically +during system start up. An external surface is any other surface—for +example, a surface that holds a video or to which OpenGL ES content is rendered.

              +

            • The Window Server has +a render stage framework, which enables the last stage of the Window Server +rendering to be customizable through plug-ins called render stages. +These can be chained to form a rendering pipeline, which takes the drawing +operations that are produced by the Window Server and ultimately passes them +to the UI surface. Render stages can selectively filter, modify, or redirect +the draw operation stream, as required—for example, to perform transition +effects (TFX).

              • +

            • In ScreenPlay, composition +takes place in two stages. First, the render stages render the drawing to +the UI surface. Then the composition engine combines the UI surface and any +external surfaces into elements (sometimes called layers) and composes +them to the screen. This enables the composition to be performed in software +or hardware accelerator chips.

              • +

            • In the non-ScreenPlay +variant, the concept of surfaces is not used and the Window Server composes +directly onto the frame buffer which is then displayed on the screen.

              • +

            • There are differences +in the plug-in framework APIs in the two architectures. In addition, in ScreenPlay, +fading effects are implemented by using render stages, whereas when ScreenPlay +is not enabled they are implemented by using a separate fader plug-in type +(not shown on the diagram).

              • +

            • In ScreenPlay, the Window +Server provides advanced pointer features, such as support for multiple pointers +and proximity and pressure coordinates. The non-ScreenPlay variant does not +provide this support.

              • +

            • ScreenPlay provides +support for externally connected displays, such as TV-out. The non-ScreenPlay +variant considers the size of each display to be fixed. However, for High-Definition +Multimedia Interface (HDMI) and composite video connectors, there are a range +of resolutions that can change dynamically. ScreenPlay provides an optional +feature that supports switching between resolutions at runtime and notifications +to Window Server clients when there are changes to the resolution and connectedness.

              • +
            +
            Building the +ScreenPlay and non-ScreenPlay variants

            To build the ScreenPlay +version of the Window Server components, declare the following macros in the Symbian_OS.hrh file.

            SYMBIAN_BUILD_GCE +SYMBIAN_GRAPHICS_BUILD_OPENWF_WSERV +

            This causes the ScreenPlay versions of the components in the +Graphics package to be built in addition to the non-ScreenPlay components. +Specifically the SYMBIAN_BUILD_GCE macro causes the ScreenPlay +version of the Window Server to be built. This means that the w32_nga.mmp and wserv_nga.mmp files +are built. These define a second macro, SYMBIAN_GRAPHICS_GCE, +which causes the ScreenPlay Window Server classes to be built.

            To include the ScreenPlay versions when building +ROM, use the SYMBIAN_GRAPHICS_USE_GCE flag.

            +
            Selecting the +ScreenPlay variant in the emulator

            To select the ScreenPlay version +of the component in the emulator, add the following line to the epoc.ini file:

            SYMBIAN_GRAPHICS_USE_GCE ON
            +
            Executables

            This +section lists the main Window Server executables. For clarity, these are divided +into three groups.

            Window Server executable and client-side libraries

            + + + +Executable +LIB +Description + + + + +

            wserv_nga.exe

            +

             +

            The ScreenPlay version of the Window Server.

            +             + +

            wserv_nonnga.exe

            +

             +

            The non-ScreenPlay version of the Window Server.

            +             + +

            ws32_nga.dll

            +

            ws32.lib

            +

            The Window Server client-side API library for the ScreenPlay variant. +See Window Server Client-Side +Library.

            +             + +

            ws32_nonnga.dll

            +

            ws32.lib

            +

            The Window Server client-side API library for the non-ScreenPlay +variant. See Window +Server Client-Side Library.

            +             + +

            wsgraphicdrawer_nga.dll

            +

            wsgraphicdrawer.lib

            +

            The server-side base classes for Window Server plug-ins in the ScreenPlay +variant. The plug-ins include graphic drawer plug-ins (which are also known +as Content Rendering Plug-ins or CRPs) and render stage plug-ins.

            +             + +

            wsgraphicdrawer_nonnga.dll

            +

            wsgraphicdrawer.lib

            +

            The server-side base classes for Window Server plug-ins in the non-ScreenPlay +variant. The plug-ins include graphic drawer plug-ins (which are also known +as Content Rendering Plug-ins or CRPs) and render stage and fader plug-ins.

            +             + +

            remotegc_nga.dll

            +

            remotegc.lib

            +

            The client-side API library for remote graphic contexts in ScreenPlay. +Remote graphic contexts store draw operations so that they can be played back +later. It is "remote" because the draw operations are generally played back +in a different location from where they are stored. For example, the draw +operations are frequently stored on the client side and then a transformation +engine uses them on the server side to make an effect.

            +             + +

            remotegc_nonnga.dll

            +

            remotegc.lib

            +

            The client-side API library for remote graphic contexts in the non-ScreenPlay +variant. This has a similar role as in ScreenPlay.

            +             + +

            profilerkeys.dll

            + +

            Window Server profiling hotkeys library in both ScreenPlay and non-ScreenPlay +variants.

            +             + + +

            Logging libraries

            + + + +Executable +Description + + + + +

            dlog.dll

            +

            On-screen logging library

            +             + +

            dlogfl.dll

            +

            File logging library

            +             + +

            dlogrd.dll

            + +             + +

            dlogsr.dll

            +

            Serial logging library

            +             + + +

            Plug-ins

            + + + +Executable +Variant +Description + + + + +

            10281922.dll

            +

            Both

            +

            This is a standard reference CRP. This type of plug-in is called +a CWsGraphics ECOM plug-in. Device creators can replace this component.

            +             + +

            2001b70b.dll

            +

            Non-ScreenPlay

            +

            This is a prototype reference render stage ECOM plug-in for the +non-ScreenPlay variant. This type of plug-in is called a CWsPlugin.

            Note: +The ScreenPlay render stage ECOM plug-in is delivered in the Window Server +Plugins component.

            +             + +

            10285c4a.dll

            +

            ScreenPlay

            +

            This is a reference ScreenPlay surface-based CRP. Device creators +can replace this component.

            +             + +

            samplegraphicsurface.dll

            +

            ScreenPlay

            +

            Sample ScreenPlay CRP (CWsGraphics) that demonstrates placing +a surface.

            +             + +

            w32stdgraphic.dll

            +

            Both

            +

            Sample CRP (CWsGraphics).

            +             + + +
            +
            Typical uses
              +

            • Application developers +use the client-side +library to control windows in their applications and respond to key +and pointer events.

              • +

            • Testers and application +developers use the logging +mechanism to log Window Server events when developing and testing their +code.

              • +

            • Device creators create +Content Rendering Plug-ins (CRPs) for showing customized content on the screen.

              • +

            • Device creators who +use ScreenPlay, can create render stage plug-ins. These enable the output +of the Window Server to be combined with auxiliary software subsystems (such +as a transition effect engine) and hardware-accelerated drawing (for example, +using OpenVG).

              • +

            • Device creators use +the wsini.ini file to +configure the Window Server to suit the specific requirements of the particular +device.

              • +
            +             +Window Server +Component + +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2C60C1C3-82B5-5ED3-98DF-E787193E8797.dita --- a/Symbian3/SDK/Source/GUID-2C60C1C3-82B5-5ED3-98DF-E787193E8797.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-2C60C1C3-82B5-5ED3-98DF-E787193E8797.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,213 +1,213 @@ - - - - - -SQLite -Technology GuideThis document provides background information on the internal workings -of SQLite, the database engine used by Symbian SQL. -
            Purpose

            SQLite is a fast efficient database engine -freely available to anyone to use in any way the want. The information in -this document provides important background information that you will need -to know in order to make the most of Symbian SQL and SQLite on Symbian platform.

            -
            Intended audience:

            This document is intended to -be used by Symbian platform developrs and third party application developers.

            -
            The architecture -and operation of SQLite

            The figure below shows the major modules -within SQLite. SQL statements that are to be processed are sent to the SQL -Compiler module which does a syntactic and semantic analysis of the SQL statements -and generates bytecode for carrying out the work of each statement. The generated -bytecode is then handed over to a Virtual Machine for evaluation.

            - Simplified SQLite Architecture - -

            The Virtual Machine considers the database to be a set of B-Trees, -one B-Tree for each table and one B-Tree for each index. The logic for creating, -reading, writing, updating, balancing and destroying B-Trees is contained -in the B-Tree module.

            The B-Tree module uses the Pager module to access -individual pages of the database file. The Pager module abstracts the database -file into zero or more fixed-sized pages with atomic commit and rollback semantics.

            All -interaction with the underlying file system and operating system occurs through -the OS Adaptation Layer.

            SQL Statements as Computer -Programs

            A key to understanding the operation of SQLite, or any -other SQL relational database engine, is to recognize that each statement -of SQL is really a small computer program.

            Users of SQL database engines -sometimes fail to grasp this simple truth because SQL is a peculiar programming -language. In most other computer languages the programmer must specify exactly how a -computation is to take place. But in SQL the programmer specifies what results -are needed and lets the SQL Compiler worry about how to achieve them.

            All -SQL database engines contain a SQL Compiler of some kind. The job of this -compiler is to convert SQL statements into procedural programs for obtaining -the desired result. Most SQL database engines translate SQL statements into -tree structures. The Virtual Machine modules of these databases then walk -these tree structures to evaluate the SQL statements. A few SQL database engines -translate SQL statements into native machine code.

            SQLite takes an -intermediate approach and translates SQL statements into small programs written -in a bytecode language. The SQLite bytecode is similar in concept to Java -bytecode, the parrot bytecode of Perl, or to the p-code of the UCSD Pascal -implementation. SQLite bytecode consists of operators that work with values -contained in registers or on a stack. Typical bytecode operators do things -like:

              -

            • Push a literal value -onto the stack

              • -

            • Pop two numbers off -of the stack, add them together and push the result back onto the stack

              • -

            • Move the top element -of the stack into a specific memory register

              • -

            • Jump to a specific instruction -if the top element of the stack is zero

              • -

            The SQLite bytecode supports about 125 different opcodes. There is -a remarkable resemblance between SQLite bytecode and assembly language. The -major difference is that SQLite bytecode contains a few specialized opcodes -designed to facilitate database operations that commonly occur in SQL.

            Just -as you do not need to understand the details of x86 or ARM7 assembly language -in order to make effective use of C++, so also you do not need to know any -of the details of SQLite bytecode in order to make the best use of SQLite. -The reader need only recognize that the bytecode is there and is being used -behind the scenes.

            Those who are interested can peruse the definitions -of the bytecodes in the SQLite documentation. But the details of the various -bytecodes are not important to making optimal use of SQLite and so no further -details on the bytecodes will be provided in this document.

            The B-Tree Module

            A -SQLite database file consists of one or more b-trees. Each table and each -index is a separate b-tree.

            A b-tree is a data structure discovered -in 1970 by Rudolf Bayer and Edward McCreight and is widely used in the implementation -of databases. B-trees provide an efficient means of organizing data stored -on an external storage device with fixed-sized blocks, such as a disk drive -or a flash memory card. Each entry in a b-tree has a unique key and arbitrary -data. The entries are ordered by their key which permits efficient lookup -using a binary search. The b-tree algorithm guarantees worst-case insert, -update, and access times of O(log N) where N is the number of entries.

            In -SQLite, each table is a separate b-tree and each row of the table is a separate -entry. The b-tree key is the RowID or INTEGER PRIMARY KEY for the row and -other columns in the row are stored in the data for the b-tree entry. Tables -use a variant of the b-tree algorithm call b+trees in which all data -is stored on the leaves of the tree.

            Indexes are also stored as b-trees -with one entry in the b-tree for each row of the table being indexed. The -b-tree key is composed of the values for the columns being indexed followed -by the RowID of the corresponding row in the table. Indexes do not use the -data part of the b-tree entry. Indexes use the original Bayer and McCreight -b-tree algorithm, not b+trees as tables do.

            The number of pages in -a b-tree can grow and shrink as information is inserted and removed. When -new information is inserted and the b-tree needs to grow, the B-Tree Module -may reuse pages in the database that have fallen into disuse or it may ask -the Pager module to allocate new pages at the end of the database file to -accommodate this growth. When a b-tree shrinks and pages are no longer needed, -the surplus pages are added to a free-list to be reused by future page -requests. The B-Tree module takes care of managing this free-list of unused -pages.

            The Pager Module

            The -Pager module (also called simply “the pager”) manages the reading and writing -of raw data from the database file such that reads are always consistent and -isolated and so that writes are atomic.

            The pager treats the database -file as a sequence of zero or more fixed-size pages. A typical page size might -be 1024 bytes. Within a single database all pages are the same size. The first -page of a database file is called page 1. The second is page 2. There is no -page 0. SQLite uses a page number of 0 internally to mean “no such page”.

            When -the B-Tree module needs a page of data from the database file, it asks for -the page by number from the pager. The pager then returns a pointer to the -requested data. The pager keeps a cache of recently accessed database pages -so in many cases no disk I/O has to occur to fulfil a page request.

            The -B-Tree module notifies the pager before making any changes to a page and the -pager then saves a copy of the original page content in a rollback journal -file. The rollback journal is used to restore the database to its original -state if a ROLLBACK occurs.

            After making changes to one or more pages, -the B-Tree Module may ask the pager to commit those changes. The pager then -goes through a carefully designed sequence of steps that ensure that changes -to the database are atomic. If the update process is interrupted by a program -crash, a system crash, or even a power failure, the next time the database -is accessed it will appear that either all the changes were made or else none -of them.

            Database File Format Summary

            A -SQLite database file consists of one or more fixed-sized pages. The first -page contains a 100-byte header that identifies the file as a SQLite database -and which contains operating parameters such as the page size, a file format -version number, the first page of the free-list, flags indicating whether -or not autovacuum is enabled, and so forth.

            The content of the database -is stored in one or more b-trees. Each b-tree has root page which -never moves. If the table or index is small enough to fit entirely on the -root page, then that one page contains everything there is to know about the -table or index. But most tables and indexes require more space and additional -pages must be allocated.

            The root page contains pointers (actually -page numbers) to the other pages in the b-tree. So given the root page of -a b-tree that implements a table or index, the B-Tree module is able to follow -pointers to locate any entry in the b-tree and thus any row in the corresponding -table or index.

            Auxiliary pages of a b-tree can be allocated -from anywhere within the database file and so the pages numbers of auxiliary -pages will change as information is added and removed from the b-tree. But -the root page never moves. When a new table or index is created, its root -page is assigned and remains unchanged for the lifetime of the table or index.

            Every -SQLite database contains a master table which stores the database schema. -Each row of the master table holds information about a single table, index, -view or trigger, including the original CREATE statement -that created that table, index, view or trigger. Rows that define tables and -indexes also record the root page number for the b-tree that stores the table -or index. The root page of the master table is always page 1 of the database -file, so SQLite always knows how to locate it. And from the master table it -can learn the root page of every other table and index in the database and -thus locate any information in the database.

            An Example of SQLite in -Operation

            This is what happens inside SQLite during a typical -usage scenario: When the SQL server instructs SQLite to open a database, the -SQLite library allocates a data structure to hold everything it will ever -need to know about that database connection. It also asks the pager to open -the database file, but does not immediately try to read anything or even verify -that the file is a valid database.

            The first time you actually try -to access the database, SQLite will look at the 100-byte header of the database -file to verify that the file is a SQLite database and to extract operating -parameters such as the database page size.

            After checking the header -SQLite opens and reads the entire master table. Recall that the master table -contains entries for every table, index, view and trigger in the database -and that each entry includes the complete text of the CREATE statement -that originally created the table, index, view or trigger.

            SQLite -parses these CREATE statements in order to rebuild an internal -symbol table holding the names and properties of all tables, indexes, triggers -and views in the database schema.

            Among the values stored in the header -of the database is a 32-bit schema cookie. The schema cookie is changed -whenever the database schema is modified by creating or dropping a table, -index, trigger, or view.

            When SQLite parses the database schema into -its internal symbol table, it remembers the schema cookie. Thereafter, whenever -SQLite goes to access the database file, it first compares the schema cookie -that it read when it parsed the schema to the current schema cookie value.

            If -they match, everything continues normally, but if the schema cookie has changed -that means that some other thread or process may have modified the database -schema. When that happens, SQLite has to throw out its internal symbol table -and reread and re-parse the entire database schema in order to figure out -what might have changed.

            RSqlStatement ’s RSqlStatement::Prepare() API -is used to interface with SQLite’s SQL Compiler. The Prepare() API -triggers tokenizing, parsing, and compilation of a SQL statement into the -internal bytecode representation that is used by the Virtual Machine. The -generated bytecode is stored in an object returned by SQLite often referred -to as a prepared statement.

            After compiling a SQL statement -into a prepared statement you can pass it to the Virtual Machine to be run. -This is the job of RSqlStatement ’s RSqlStatement::Next() and RSqlStatement::Exec() APIs. -These interfaces cause the bytecode contained in the prepared statement to -be run until it either completes or until it hits a breakpoint.

            A -breakpoint is hit whenever a SELECT statement generates a -row of result that needs to be returned. When a breakpoint is hit SQLite returns -control to the caller.

            The bytecode in a prepared statement object -is such that whenever a breakpoint occurs, a single row of the result of a -SELECT statement is contained on the stack of the Virtual Machine. At this -point column accessor functions can be used to retrieve individual column -values.

            RSqlStatement::Reset() can be called on -a prepared statement at any time. This rewinds the program counter of the -Virtual Machine back to the beginning and clears the stack, thus leaving the -prepared statement in a state where it is ready to start over again from the -beginning.

            RSqlStatement ’s RSqlStatement::Close() API -is merely a destructor for the prepared statement object. It calls Reset() to -clear the virtual machine stack if necessary, deallocates the generated bytecode, -and frees the container object.

            Similarly, RSqlDatabase’ s Close() API -is just a destructor for a server-side object created by SQLite when the database -was opened. SQLite asks the pager module to close the database file, clears -the symbol table, and de-allocates all associated memory.

            -             -SQL Overview - -SQL DB Overview - -SQL Server -Guide -Persistent -Storage + + + + + +SQLite +Technology GuideThis document provides background information on the internal workings +of SQLite, the database engine used by Symbian SQL. +
            Purpose

            SQLite is a fast efficient database engine +freely available to anyone to use in any way the want. The information in +this document provides important background information that you will need +to know in order to make the most of Symbian SQL and SQLite on Symbian platform.

            +
            Intended audience:

            This document is intended to +be used by Symbian platform developrs and third party application developers.

            +
            The architecture +and operation of SQLite

            The figure below shows the major modules +within SQLite. SQL statements that are to be processed are sent to the SQL +Compiler module which does a syntactic and semantic analysis of the SQL statements +and generates bytecode for carrying out the work of each statement. The generated +bytecode is then handed over to a Virtual Machine for evaluation.

            + Simplified SQLite Architecture + +

            The Virtual Machine considers the database to be a set of B-Trees, +one B-Tree for each table and one B-Tree for each index. The logic for creating, +reading, writing, updating, balancing and destroying B-Trees is contained +in the B-Tree module.

            The B-Tree module uses the Pager module to access +individual pages of the database file. The Pager module abstracts the database +file into zero or more fixed-sized pages with atomic commit and rollback semantics.

            All +interaction with the underlying file system and operating system occurs through +the OS Adaptation Layer.

            SQL Statements as Computer +Programs

            A key to understanding the operation of SQLite, or any +other SQL relational database engine, is to recognize that each statement +of SQL is really a small computer program.

            Users of SQL database engines +sometimes fail to grasp this simple truth because SQL is a peculiar programming +language. In most other computer languages the programmer must specify exactly how a +computation is to take place. But in SQL the programmer specifies what results +are needed and lets the SQL Compiler worry about how to achieve them.

            All +SQL database engines contain a SQL Compiler of some kind. The job of this +compiler is to convert SQL statements into procedural programs for obtaining +the desired result. Most SQL database engines translate SQL statements into +tree structures. The Virtual Machine modules of these databases then walk +these tree structures to evaluate the SQL statements. A few SQL database engines +translate SQL statements into native machine code.

            SQLite takes an +intermediate approach and translates SQL statements into small programs written +in a bytecode language. The SQLite bytecode is similar in concept to Java +bytecode, the parrot bytecode of Perl, or to the p-code of the UCSD Pascal +implementation. SQLite bytecode consists of operators that work with values +contained in registers or on a stack. Typical bytecode operators do things +like:

              +

            • Push a literal value +onto the stack

              • +

            • Pop two numbers off +of the stack, add them together and push the result back onto the stack

              • +

            • Move the top element +of the stack into a specific memory register

              • +

            • Jump to a specific instruction +if the top element of the stack is zero

              • +

            The SQLite bytecode supports about 125 different opcodes. There is +a remarkable resemblance between SQLite bytecode and assembly language. The +major difference is that SQLite bytecode contains a few specialized opcodes +designed to facilitate database operations that commonly occur in SQL.

            Just +as you do not need to understand the details of x86 or ARM7 assembly language +in order to make effective use of C++, so also you do not need to know any +of the details of SQLite bytecode in order to make the best use of SQLite. +The reader need only recognize that the bytecode is there and is being used +behind the scenes.

            Those who are interested can peruse the definitions +of the bytecodes in the SQLite documentation. But the details of the various +bytecodes are not important to making optimal use of SQLite and so no further +details on the bytecodes will be provided in this document.

            The B-Tree Module

            A +SQLite database file consists of one or more b-trees. Each table and each +index is a separate b-tree.

            A b-tree is a data structure discovered +in 1970 by Rudolf Bayer and Edward McCreight and is widely used in the implementation +of databases. B-trees provide an efficient means of organizing data stored +on an external storage device with fixed-sized blocks, such as a disk drive +or a flash memory card. Each entry in a b-tree has a unique key and arbitrary +data. The entries are ordered by their key which permits efficient lookup +using a binary search. The b-tree algorithm guarantees worst-case insert, +update, and access times of O(log N) where N is the number of entries.

            In +SQLite, each table is a separate b-tree and each row of the table is a separate +entry. The b-tree key is the RowID or INTEGER PRIMARY KEY for the row and +other columns in the row are stored in the data for the b-tree entry. Tables +use a variant of the b-tree algorithm call b+trees in which all data +is stored on the leaves of the tree.

            Indexes are also stored as b-trees +with one entry in the b-tree for each row of the table being indexed. The +b-tree key is composed of the values for the columns being indexed followed +by the RowID of the corresponding row in the table. Indexes do not use the +data part of the b-tree entry. Indexes use the original Bayer and McCreight +b-tree algorithm, not b+trees as tables do.

            The number of pages in +a b-tree can grow and shrink as information is inserted and removed. When +new information is inserted and the b-tree needs to grow, the B-Tree Module +may reuse pages in the database that have fallen into disuse or it may ask +the Pager module to allocate new pages at the end of the database file to +accommodate this growth. When a b-tree shrinks and pages are no longer needed, +the surplus pages are added to a free-list to be reused by future page +requests. The B-Tree module takes care of managing this free-list of unused +pages.

            The Pager Module

            The +Pager module (also called simply “the pager”) manages the reading and writing +of raw data from the database file such that reads are always consistent and +isolated and so that writes are atomic.

            The pager treats the database +file as a sequence of zero or more fixed-size pages. A typical page size might +be 1024 bytes. Within a single database all pages are the same size. The first +page of a database file is called page 1. The second is page 2. There is no +page 0. SQLite uses a page number of 0 internally to mean “no such page”.

            When +the B-Tree module needs a page of data from the database file, it asks for +the page by number from the pager. The pager then returns a pointer to the +requested data. The pager keeps a cache of recently accessed database pages +so in many cases no disk I/O has to occur to fulfil a page request.

            The +B-Tree module notifies the pager before making any changes to a page and the +pager then saves a copy of the original page content in a rollback journal +file. The rollback journal is used to restore the database to its original +state if a ROLLBACK occurs.

            After making changes to one or more pages, +the B-Tree Module may ask the pager to commit those changes. The pager then +goes through a carefully designed sequence of steps that ensure that changes +to the database are atomic. If the update process is interrupted by a program +crash, a system crash, or even a power failure, the next time the database +is accessed it will appear that either all the changes were made or else none +of them.

            Database File Format Summary

            A +SQLite database file consists of one or more fixed-sized pages. The first +page contains a 100-byte header that identifies the file as a SQLite database +and which contains operating parameters such as the page size, a file format +version number, the first page of the free-list, flags indicating whether +or not autovacuum is enabled, and so forth.

            The content of the database +is stored in one or more b-trees. Each b-tree has root page which +never moves. If the table or index is small enough to fit entirely on the +root page, then that one page contains everything there is to know about the +table or index. But most tables and indexes require more space and additional +pages must be allocated.

            The root page contains pointers (actually +page numbers) to the other pages in the b-tree. So given the root page of +a b-tree that implements a table or index, the B-Tree module is able to follow +pointers to locate any entry in the b-tree and thus any row in the corresponding +table or index.

            Auxiliary pages of a b-tree can be allocated +from anywhere within the database file and so the pages numbers of auxiliary +pages will change as information is added and removed from the b-tree. But +the root page never moves. When a new table or index is created, its root +page is assigned and remains unchanged for the lifetime of the table or index.

            Every +SQLite database contains a master table which stores the database schema. +Each row of the master table holds information about a single table, index, +view or trigger, including the original CREATE statement +that created that table, index, view or trigger. Rows that define tables and +indexes also record the root page number for the b-tree that stores the table +or index. The root page of the master table is always page 1 of the database +file, so SQLite always knows how to locate it. And from the master table it +can learn the root page of every other table and index in the database and +thus locate any information in the database.

            An Example of SQLite in +Operation

            This is what happens inside SQLite during a typical +usage scenario: When the SQL server instructs SQLite to open a database, the +SQLite library allocates a data structure to hold everything it will ever +need to know about that database connection. It also asks the pager to open +the database file, but does not immediately try to read anything or even verify +that the file is a valid database.

            The first time you actually try +to access the database, SQLite will look at the 100-byte header of the database +file to verify that the file is a SQLite database and to extract operating +parameters such as the database page size.

            After checking the header +SQLite opens and reads the entire master table. Recall that the master table +contains entries for every table, index, view and trigger in the database +and that each entry includes the complete text of the CREATE statement +that originally created the table, index, view or trigger.

            SQLite +parses these CREATE statements in order to rebuild an internal +symbol table holding the names and properties of all tables, indexes, triggers +and views in the database schema.

            Among the values stored in the header +of the database is a 32-bit schema cookie. The schema cookie is changed +whenever the database schema is modified by creating or dropping a table, +index, trigger, or view.

            When SQLite parses the database schema into +its internal symbol table, it remembers the schema cookie. Thereafter, whenever +SQLite goes to access the database file, it first compares the schema cookie +that it read when it parsed the schema to the current schema cookie value.

            If +they match, everything continues normally, but if the schema cookie has changed +that means that some other thread or process may have modified the database +schema. When that happens, SQLite has to throw out its internal symbol table +and reread and re-parse the entire database schema in order to figure out +what might have changed.

            RSqlStatement ’s RSqlStatement::Prepare() API +is used to interface with SQLite’s SQL Compiler. The Prepare() API +triggers tokenizing, parsing, and compilation of a SQL statement into the +internal bytecode representation that is used by the Virtual Machine. The +generated bytecode is stored in an object returned by SQLite often referred +to as a prepared statement.

            After compiling a SQL statement +into a prepared statement you can pass it to the Virtual Machine to be run. +This is the job of RSqlStatement ’s RSqlStatement::Next() and RSqlStatement::Exec() APIs. +These interfaces cause the bytecode contained in the prepared statement to +be run until it either completes or until it hits a breakpoint.

            A +breakpoint is hit whenever a SELECT statement generates a +row of result that needs to be returned. When a breakpoint is hit SQLite returns +control to the caller.

            The bytecode in a prepared statement object +is such that whenever a breakpoint occurs, a single row of the result of a +SELECT statement is contained on the stack of the Virtual Machine. At this +point column accessor functions can be used to retrieve individual column +values.

            RSqlStatement::Reset() can be called on +a prepared statement at any time. This rewinds the program counter of the +Virtual Machine back to the beginning and clears the stack, thus leaving the +prepared statement in a state where it is ready to start over again from the +beginning.

            RSqlStatement ’s RSqlStatement::Close() API +is merely a destructor for the prepared statement object. It calls Reset() to +clear the virtual machine stack if necessary, deallocates the generated bytecode, +and frees the container object.

            Similarly, RSqlDatabase’ s Close() API +is just a destructor for a server-side object created by SQLite when the database +was opened. SQLite asks the pager module to close the database file, clears +the symbol table, and de-allocates all associated memory.

            +             +SQL Overview + +SQL DB Overview + +SQL Server +Guide +Persistent +Storage             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2C74E932-B1CA-434B-AF96-66D52D689620.dita --- a/Symbian3/SDK/Source/GUID-2C74E932-B1CA-434B-AF96-66D52D689620.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-2C74E932-B1CA-434B-AF96-66D52D689620.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,58 +1,57 @@ - - - - - -Optional -resource file statements -

            The resource file statements listed in the following are optional; Create -resource file statements only for the UI components used by the application -for which the default implementation is not used.

            -

            For more information on resource statements for these components, see:

            -
              -

            • CBA buttons

              -
              • -

            • Menu -bar resource statements

              • -

            • View -resource statements in the view architecture

              -
              • -

            • UI -components

              - -

              Building an AVKON-based application UI is a primary choice for third-party -add-on applications that do not need advanced customization. Such an approach -guarantees compatibility across different Series 60 Developer Platform editions, -but, in turn, puts some limitations on the application UI layout imposed by -AVKON. AVKON provides a wide choice of well-designed and versatile components, -but not all of these are easily modifiable.

              - -

              AVKON or AVKON-derived components should be favoured over custom CCoeControl-derived controls. AVKON UI components scale automatically -according to screen resolution and orientation.

              -               -
                -

              • Dialogs -API

                • -

              • Editors -API

                • -

              • Form -API

                • -

              • Grids -API

                • -

              • Lists -API

                • -

              • Notes -API

                • -

              • Setting -Pages API

                • -
              -               -
              • -
            + + + + + +Optional +resource file statements +

            The resource file statements listed in the following are optional; Create +resource file statements only for the UI components used by the application +for which the default implementation is not used.

            +

            For more information on resource statements for these components, see:

            +
              +

            • CBA buttons

              +
              • +

            • Menu +bar resource statements

              • +

            • View +resource statements in the view architecture

              +
              • +

            • UI components

              + +

              Building an AVKON-based application UI is a primary choice for third-party +add-on applications that do not need advanced customization. Such an approach +guarantees compatibility across different Series 60 Developer Platform editions, +but, in turn, puts some limitations on the application UI layout imposed by +AVKON. AVKON provides a wide choice of well-designed and versatile components, +but not all of these are easily modifiable.

              + +

              AVKON or AVKON-derived components should be favoured over custom CCoeControl-derived controls. AVKON UI components scale automatically +according to screen resolution and orientation.

              +               +
                +

              • Dialogs +API

                • +

              • Editors +API

                • +

              • Form +API

                • +

              • Grids +API

                • +

              • Lists +API

                • +

              • Notes +API

                • +

              • Setting +Pages API

                • +
              +               +
              • +
             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2C8F2C68-5D25-5DB8-973C-E9CA6882A3FB_d0e323436_href.jpg Binary file Symbian3/SDK/Source/GUID-2C8F2C68-5D25-5DB8-973C-E9CA6882A3FB_d0e323436_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2C8F2C68-5D25-5DB8-973C-E9CA6882A3FB_d0e329593_href.jpg Binary file Symbian3/SDK/Source/GUID-2C8F2C68-5D25-5DB8-973C-E9CA6882A3FB_d0e329593_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2CBD504A-5538-4823-9139-2941A0BA5E8B-master.png Binary file Symbian3/SDK/Source/GUID-2CBD504A-5538-4823-9139-2941A0BA5E8B-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2CBD504A-5538-4823-9139-2941A0BA5E8B_d0e57688_href.png Binary file Symbian3/SDK/Source/GUID-2CBD504A-5538-4823-9139-2941A0BA5E8B_d0e57688_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2CBD504A-5538-4823-9139-2941A0BA5E8B_d0e63133_href.png Binary file Symbian3/SDK/Source/GUID-2CBD504A-5538-4823-9139-2941A0BA5E8B_d0e63133_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2CBD504A-5538-4823-9139-2941A0BA5E8B_d0e68374_href.png Binary file Symbian3/SDK/Source/GUID-2CBD504A-5538-4823-9139-2941A0BA5E8B_d0e68374_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2CBD504A-5538-4823-9139-2941A0BA5E8B_d0e69226_href.png Binary file Symbian3/SDK/Source/GUID-2CBD504A-5538-4823-9139-2941A0BA5E8B_d0e69226_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2CBD504A-5538-4823-9139-2941A0BA5E8B_d0e74392_href.png Binary file Symbian3/SDK/Source/GUID-2CBD504A-5538-4823-9139-2941A0BA5E8B_d0e74392_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2CEF22AD-7F80-58CE-AF5F-C7BF636D524F.dita --- a/Symbian3/SDK/Source/GUID-2CEF22AD-7F80-58CE-AF5F-C7BF636D524F.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-2CEF22AD-7F80-58CE-AF5F-C7BF636D524F.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,16 +1,16 @@ - - - - - -Camera Plug-in OverviewThis document introduces you to the Camera Plug-in component overview.
            Purpose

            The Camera Plug-in component provides an actual implementation for the Camera Framework component.

            Required background

            The Camera Plug-in component is implemented with the support of EcamPluginSupport.dll. It is expected that device creators can replace their own Camera Plug-in implementation.

            Architecture

            The Camera Plug-in component interacts with the Camera Framework component.

            The architectural relationship between Camera Plug-in and Camera Framework is shown below:

            - Camera Plug-in Component Architecture -
            APIs

            The Camera Plug-in component consists of the following library:

            API Description

            ecamstubplugin.lib

            The Camera Stub Plug-in library is used to support the EcamPluginSupport.dll which is in the Camera Framework component.

            Typical uses

            Camera Plug-in is used as a symbian support implementation for the Camera Framework Ecom plug-ins.

            Camera Stub Plug-in - Overview Camera Plug-in Support Camera + + + + + +Camera Plug-in OverviewThis document introduces you to the Camera Plug-in component overview.
            Purpose

            The Camera Plug-in component provides an actual implementation for the Camera Framework component.

            Required background

            The Camera Plug-in component is implemented with the support of EcamPluginSupport.dll. It is expected that device creators can replace their own Camera Plug-in implementation.

            Architecture

            The Camera Plug-in component interacts with the Camera Framework component.

            The architectural relationship between Camera Plug-in and Camera Framework is shown below:

            + Camera Plug-in Component Architecture +
            APIs

            The Camera Plug-in component consists of the following library:

            API Description

            ecamstubplugin.lib

            The Camera Stub Plug-in library is used to support the EcamPluginSupport.dll which is in the Camera Framework component.

            Typical uses

            Camera Plug-in is used as a symbian support implementation for the Camera Framework Ecom plug-ins.

            Camera Stub Plug-in + Overview Camera Plug-in Support Camera Framework Overview             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2D3F7471-9B92-5E49-B8BC-E0FA7AA709D7.dita --- a/Symbian3/SDK/Source/GUID-2D3F7471-9B92-5E49-B8BC-E0FA7AA709D7.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-2D3F7471-9B92-5E49-B8BC-E0FA7AA709D7.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,14 +1,14 @@ - - - - - -DevSound Overview This document provides an overview of DevSound.
            Purpose

            DevSound provides a common API for all audio functionality.

            DevSound library details

            The DLL that provides the functionality and the library to which your code must link is identified below.

            DLL LIB Short Description

            mmfdevsound.dll

            mmfdevsound.lib

            These files are used for implementing DevSound.

            Architectural relationship

            Shown below is a representation of how DevSound interacts with the MMF Controller Framework and other components:

            - DevSound and related components -

            DevSound uses the following components:

            • Client - DevSound can be used by the following clients:

              • applications

              • device creator library.

            • MMF Controller Framework

              For audio playing, recording, and conversion, the MMF client APIs interact with the lower levels of the MMF, the controller framework. The controller framework helps to manage the interface to DevSound and provides controller plug-ins for playing, recording, and converting audio data. The controller framework has two main classes RMMFController and CMMFController.

            • Controller Plug-in

              Depending on the functionality required by the client, the MMF controller framework loads the appropriate controller plug-ins. The plug-ins perform the required operations by communicating with DevSound and/or DevVideo, codecs and hardware.

              Custom controller plug-ins can be written to extend the MMF framework. For more information, see How to write a controller plug-in.

            • Audio Policy

              The Audio Policy component manages requests to access the audio hardware. For example, if DevSound needs to acquire the hardware for playing audio, it makes a request to the Audio Policy component. Depending on the priority of the request, the Audio Policy component grants or denies access to the hardware. DevSound must obey the Audio Policy.

            • Codecs

              DevSound uses codecs to convert multimedia data between different encodings.

              Custom codec plug-ins can be written. For more information, see How to write a codec plug-in.

            • Hardware Device API

              For audio functionality, the CMMFHwDevice plug-in class acts as the DevSound interface to the audio processing hardware.

            Description

            DevSound provides the interface between the Symbian platform and the audio processing hardware for all audio functionality. DevSound is responsible for providing access to audio resources, configuring audio hardware, and audio playback and recording.

            Key DevSound classes

            The DevSound API comprises the following classes:

            • CMMFDevSound is the class which forms the DevSound API.

            • MDevSoundObserver provides callbacks to users of the DevSound API. It serves as the method of communication between a client and DevSound. For example, MDevSoundObserver handles completion and cancellation requests for audio playing, recording, and conversion.

            Using DevSound

            DevSound offers the following main functions which can be used by DevSound clients:

            • Audio Settings

              DevSound can be used to initialise and configure hardware devices, for example, set microphone gain and stereo balance.

            • Audio Play

              DevSound can be used to play buffered audio data.

            • Audio Record

              DevSound can be used to record audio data.

            • Audio Convert

              DevSound can be used to convert the type, sample rate and format of audio data.

            • Tone Play

              DevSound can play a single tone, tone sequence or Dual Tone Multi-Frequency (DTMF) string.

            Playing audio Recording Audio Playing tones             \ No newline at end of file + + + + + +DevSound Overview This document provides an overview of DevSound.
            Purpose

            DevSound provides a common API for all audio functionality.

            DevSound library details

            The DLL that provides the functionality and the library to which your code must link is identified below.

            DLL LIB Short Description

            mmfdevsound.dll

            mmfdevsound.lib

            These files are used for implementing DevSound.

            Architectural relationship

            Shown below is a representation of how DevSound interacts with the MMF Controller Framework and other components:

            + DevSound and related components +

            DevSound uses the following components:

            • Client - DevSound can be used by the following clients:

              • applications

              • device creator library.

            • MMF Controller Framework

              For audio playing, recording, and conversion, the MMF client APIs interact with the lower levels of the MMF, the controller framework. The controller framework helps to manage the interface to DevSound and provides controller plug-ins for playing, recording, and converting audio data. The controller framework has two main classes RMMFController and CMMFController.

            • Controller Plug-in

              Depending on the functionality required by the client, the MMF controller framework loads the appropriate controller plug-ins. The plug-ins perform the required operations by communicating with DevSound and/or DevVideo, codecs and hardware.

              Custom controller plug-ins can be written to extend the MMF framework. For more information, see How to write a controller plug-in.

            • Audio Policy

              The Audio Policy component manages requests to access the audio hardware. For example, if DevSound needs to acquire the hardware for playing audio, it makes a request to the Audio Policy component. Depending on the priority of the request, the Audio Policy component grants or denies access to the hardware. DevSound must obey the Audio Policy.

            • Codecs

              DevSound uses codecs to convert multimedia data between different encodings.

              Custom codec plug-ins can be written. For more information, see How to write a codec plug-in.

            • Hardware Device API

              For audio functionality, the CMMFHwDevice plug-in class acts as the DevSound interface to the audio processing hardware.

            Description

            DevSound provides the interface between the Symbian platform and the audio processing hardware for all audio functionality. DevSound is responsible for providing access to audio resources, configuring audio hardware, and audio playback and recording.

            Key DevSound classes

            The DevSound API comprises the following classes:

            • CMMFDevSound is the class which forms the DevSound API.

            • MDevSoundObserver provides callbacks to users of the DevSound API. It serves as the method of communication between a client and DevSound. For example, MDevSoundObserver handles completion and cancellation requests for audio playing, recording, and conversion.

            Using DevSound

            DevSound offers the following main functions which can be used by DevSound clients:

            • Audio Settings

              DevSound can be used to initialise and configure hardware devices, for example, set microphone gain and stereo balance.

            • Audio Play

              DevSound can be used to play buffered audio data.

            • Audio Record

              DevSound can be used to record audio data.

            • Audio Convert

              DevSound can be used to convert the type, sample rate and format of audio data.

            • Tone Play

              DevSound can play a single tone, tone sequence or Dual Tone Multi-Frequency (DTMF) string.

            Playing audio Recording Audio Playing tones             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2D74594C-AFEB-550E-AD69-1C4A0455C5AC.dita --- a/Symbian3/SDK/Source/GUID-2D74594C-AFEB-550E-AD69-1C4A0455C5AC.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-2D74594C-AFEB-550E-AD69-1C4A0455C5AC.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,18 +1,18 @@ - - - - - -Structure of a Message Store

            This section provides information about the Message Store entries.

            Message Framework provides a tree view of entries in a Message Store. The tree is divided into three levels: root entry, service entry, and folder and message entry, which are provided TMsvEntry. The child entries of the root entry must be service entries. A message client application can begin from the root entry, and by successively finding the children of an entry, can traverse the whole entry tree. The parent of each entry is recorded in the index entry's details.

            The following figure illustrates how services are placed below a root entry.

            - Message Store -

            • 1: Root entry —This entry is just present to tie the tree structure together.

            • 2: Service entry —This level used for settings information, usually to set up communication protocols, for example, ISP settings. There is one local service under which local folders and messages are stored, and zero or more remote services. Remote services represent message accounts.

              There are two types of service entry:

              • Remote Services: These represent message accounts stored on remote stores such as email servers and the SIM store of SMS messages.

              • Local Services: There is a single local service under which local folders and messages are stored.

                The Message Server handles changes to local entries. Internally it may delegate changes to remote entries, such as copying and moving messages to and from a remote service, to the server MTM that owns that service.

              - Remote and local entries -

            • 3: Folder entries and message entries — Folders entries are used to group a number of message entries. For more information on folders, see Message folders. Messages store the content of a message. Message entries can have child entries which represent the structure of a message.

              Folders and messages under the local service represent messages stored on the device. Folders and messages under remote services represent a local copy of messages that are present on a remote server. For example, under a POP3 email service you can have copies of all the messages present on the POP3 email server, and under an SMS service you can have SMS messages that are stored on a SIM.

              Each message entry also has an associated service ID. The service ID is associated with a service entry whose settings is used in all Messaging operations on that message entry.

            Validity of the Message Store

            The structure of the Message store is considered to be valid only if an index entry conforms to the following rules:

            • A non-service entry cannot be owned by root and must have its service ID field set.

            • A service entry must be owned by root and have the service ID of itself.

            Important: The Message Server controls access to the entries in the store. It enforces the three levels; therefore, attempts to create message or folder entries directly under the root entry fails.

            Message Server and Store Messaging Framework Message Server and Store - Concepts Message Server and Store + + + + + +Structure of a Message Store

            This section provides information about the Message Store entries.

            Message Framework provides a tree view of entries in a Message Store. The tree is divided into three levels: root entry, service entry, and folder and message entry, which are provided TMsvEntry. The child entries of the root entry must be service entries. A message client application can begin from the root entry, and by successively finding the children of an entry, can traverse the whole entry tree. The parent of each entry is recorded in the index entry's details.

            The following figure illustrates how services are placed below a root entry.

            + Message Store +

            • 1: Root entry —This entry is just present to tie the tree structure together.

            • 2: Service entry —This level used for settings information, usually to set up communication protocols, for example, ISP settings. There is one local service under which local folders and messages are stored, and zero or more remote services. Remote services represent message accounts.

              There are two types of service entry:

              • Remote Services: These represent message accounts stored on remote stores such as email servers and the SIM store of SMS messages.

              • Local Services: There is a single local service under which local folders and messages are stored.

                The Message Server handles changes to local entries. Internally it may delegate changes to remote entries, such as copying and moving messages to and from a remote service, to the server MTM that owns that service.

              + Remote and local entries +

            • 3: Folder entries and message entries — Folders entries are used to group a number of message entries. For more information on folders, see Message folders. Messages store the content of a message. Message entries can have child entries which represent the structure of a message.

              Folders and messages under the local service represent messages stored on the device. Folders and messages under remote services represent a local copy of messages that are present on a remote server. For example, under a POP3 email service you can have copies of all the messages present on the POP3 email server, and under an SMS service you can have SMS messages that are stored on a SIM.

              Each message entry also has an associated service ID. The service ID is associated with a service entry whose settings is used in all Messaging operations on that message entry.

            Validity of the Message Store

            The structure of the Message store is considered to be valid only if an index entry conforms to the following rules:

            • A non-service entry cannot be owned by root and must have its service ID field set.

            • A service entry must be owned by root and have the service ID of itself.

            Important: The Message Server controls access to the entries in the store. It enforces the three levels; therefore, attempts to create message or folder entries directly under the root entry fails.

            Message Server and Store Messaging Framework Message Server and Store + Concepts Message Server and Store Tutorials             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2D7BD92E-E242-524B-8D83-874C32EC0503_d0e135601_href.png Binary file Symbian3/SDK/Source/GUID-2D7BD92E-E242-524B-8D83-874C32EC0503_d0e135601_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2D7BD92E-E242-524B-8D83-874C32EC0503_d0e142135_href.png Binary file Symbian3/SDK/Source/GUID-2D7BD92E-E242-524B-8D83-874C32EC0503_d0e142135_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2D93660B-8206-5D20-85F5-6FFCF4549127.dita --- a/Symbian3/SDK/Source/GUID-2D93660B-8206-5D20-85F5-6FFCF4549127.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-2D93660B-8206-5D20-85F5-6FFCF4549127.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,35 +1,35 @@ - - - - - -Persistent -storesA store is persistent if you can close it, re-open it, and then -gain access to the same data. -

            A persistent store has the concept of a root stream. The root stream is, -in effect, the starting point from which all others streams within the store -can be found.

            -

            Before closing a persistent store you have created, you must set the ID -of the root stream. After you have opened the persistent store, the first -thing you must do is look up the root stream ID. You can then open the root -stream and start reading data from the store.

            -

            Persistent stores are represented by the abstract class CPersistentStore. -This class, derived from CStreamStore has the root stream -ID and expands on the abstract framework provided by CStreamStore, -by adding behaviour for setting and retrieving the root stream ID.

            -

            File stores are an example of persistent stores.

            -

            The following diagram shows the idea of a persistent store with a root -stream:

            - -Persistent store with a root stream - - -
            See also

            File -stores

            + + + + + +Persistent +storesA store is persistent if you can close it, re-open it, and then +gain access to the same data. +

            A persistent store has the concept of a root stream. The root stream is, +in effect, the starting point from which all others streams within the store +can be found.

            +

            Before closing a persistent store you have created, you must set the ID +of the root stream. After you have opened the persistent store, the first +thing you must do is look up the root stream ID. You can then open the root +stream and start reading data from the store.

            +

            Persistent stores are represented by the abstract class CPersistentStore. +This class, derived from CStreamStore has the root stream +ID and expands on the abstract framework provided by CStreamStore, +by adding behaviour for setting and retrieving the root stream ID.

            +

            File stores are an example of persistent stores.

            +

            The following diagram shows the idea of a persistent store with a root +stream:

            + +Persistent store with a root stream + + +
            See also

            File +stores

            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2D9B17E7-2B7A-5E16-AB06-D9507457A85D.dita --- a/Symbian3/SDK/Source/GUID-2D9B17E7-2B7A-5E16-AB06-D9507457A85D.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-2D9B17E7-2B7A-5E16-AB06-D9507457A85D.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,44 +1,41 @@ - - - - - -smsexample: -SMS exampleThis example code demonstrates how to send and receive SMS messages -using the Messaging Framework APIs. -
            Description

            This -updated C++ example demonstrates programmatical handling of SMS messages. -Messages can be sent from the application and they can be received directly -into the application (that is, catching incoming messages before the user -gets any notification). In addition, messages can be deleted, copied, or moved -to other folders of the message store (inbox, outbox, drafts). The example -has been updated to be compatible with S60 5th Edition and touch UI. Important -classes: CMsvSession, CMsvEntry, CMmsClientMtm, CSmsClientMtm, CClientMtmRegistry, -KMsvMessagePartBody, ESmsMtmCommandScheduleCopy, CSmsSettings, CSmsHeader. For -more details, click on this link : sms example

            -
            Download

            Click -on the following link to download the example: smsexample.zip

            Click: browse to view the example code.

            -
            Building and -configuring
              -

            • You can build the example -from your IDE or the command line.

              If you use an IDE, import the bld.inf file -of the example into your IDE, and use the build command of the IDE.

              If -you use the command line, open a command prompt, and set the current directory -to the source code directory of the example. You can then build the example -with the SBSv1 build tools with the following commands:

              bldmake -bldfiles

              abld build

              How to use bldmake and How to use abld describe -how to use the SBSv1 build tools.

              • -

            • For the emulator, the -example builds an executable called smsexample.exe in -the epoc32\release\winscw\<udeb or urel>\ folder.

              • -
            -             -SMS MTM Overview - + + + + + +SMS +exampleThis example code demonstrates how to send and receive SMS messages +using the Messaging Framework APIs. +
            Description

            This +updated C++ example demonstrates programmatical handling of SMS messages. +Messages can be sent from the application and they can be received directly +into the application (that is, catching incoming messages before the user +gets any notification). In addition, messages can be deleted, copied, or moved +to other folders of the message store (inbox, outbox, drafts).

            +
            Download

            Click +on the following link to download the example: smsexample.zip

            Click: browse to view the example code.

            +
            Classes

            CMsvSession

            CMsvEntry

            CMmsClientMtm

            CSmsClientMtm

            CClientMtmRegistry

            CSmsHeader

            +
            Building and +configuring
              +

            • You can build the example +from your IDE or the command line.

              If you use an IDE, import the bld.inf file +of the example into your IDE, and use the build command of the IDE.

              If +you use the command line, open a command prompt, and set the current directory +to the source code directory of the example. You can then build the example +with the SBSv1 build tools with the following commands:

              bldmake +bldfiles

              abld build

              How to use bldmake and How to use abld describe +how to use the SBSv1 build tools.

              • +

            • For the emulator, the +example builds an executable called smsexample.exe in +the epoc32\release\winscw\<udeb or urel>\ folder.

              • +
            +             +SMS MTM Overview +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2DA8C6F2-93BD-5D39-9E5A-5FF8B8777CE7.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-2DA8C6F2-93BD-5D39-9E5A-5FF8B8777CE7.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,278 @@ + + + + + +How +to create a CryptoSPI plug-in +
            Introduction

            Note: +this document is intended for device manufacturers.

            The purpose of +a CryptoSPI plug-in is to implement one or more cryptographic algorithms.

            Symbian +provides a plug-in called softwarecrypto.dll that implements +all algorithms supported by the legacy (pre-Symbian^3) cryptography APIs. +In Symbian^3, the legacy APIs have all been re-implemented to use this plug-in +DLL. The source code for softwarecrypto.dll is located +under src/common/generic/security/cryptospi/source/softwarecrypto/.

            This +is a summary of the steps involved in creating a plug-in, in no particular +order. Details of each step are given in the rest of the document.

              +

            • Create the MMP file.

              • +

            • Define the characteristics of the algorithms.

              • +

            • Implement all or a subset of the functions defined in pluginentrydef.h.

              • +

            • Implement the MPlugin-derived objects.

              • +

            • Update the ROM configuration file.

              • +
            +
            How to create +the MMP file

            See for instance src/common/generic/security/cryptospi/group/softwarecrypto.mmp.

            TARGET softwarecrypto.dll +TARGETTYPE dll + +UID 0x1000008d 0x102835C2 +VENDORID 0x70000001 + +CAPABILITY All + +DEFFILE softwarecrypto.def + +USERINCLUDE . +USERINCLUDE ..\inc +USERINCLUDE ..\inc\spi +SYSTEMINCLUDE \epoc32\include +SYSTEMINCLUDE \epoc32\include\cryptospi + +SOURCEPATH ..\source\softwarecrypto +SOURCE pluginentry.cpp +SOURCE md2impl.cpp md5impl.cpp sha1impl.cpp hmacimpl.cpp +SOURCE 3desimpl.cpp desimpl.cpp rc2impl.cpp rijndaelimpl.cpp arc4impl.cpp symmetriccipherimpl.cpp +SOURCE randomimpl.cpp dsasignerimpl.cpp dsaverifyimpl.cpp rsaimpl.cpp rsafunction.cpp +SOURCE signerimpl.cpp verifierimpl.cpp asymmetriccipherimpl.cpp + +LIBRARY euser.lib cryptospi.lib + +// Depends on bigint and padding code +LIBRARY cryptography.lib +//Depends on random server for random number generation +LIBRARY random.lib

            Key points:

              +

            • 0x1000008d identifies +the DLL as static (not polymorphic or an ECOM plug-in) and 0x102835C2 is +unique to this plug-in, allocated by Symbian Signed.

              • +

            • It is recommended that +plug-ins have ALL capabilities because this ensures that +they can be loaded by client applications with any capabilities.

              • +

            • The project needs to +link against cryptospi.lib, the CryptoSPI library.

              • +

            • The plug-in needs to +link against cryptography.lib because big integers (RInteger) +are implemented in cryptography.dll.

              • +

            • SYSTEMINCLUDE +\epoc32\include\cryptospi allows code to #include the +CryptoSPI header files, which are all exported to epoc32\include\cryptospi\.

              • +
            +
            How to define +the algorithm's characteristics

            All plug-ins must define the characteristics +of their algorithm implementations that are fixed at compile time, as constant +data. Some characteristics are common to all interface types, for instance +the name and UID of the algorithm implemented, the name of the plug-in vendor, +whether the plug-in uses hardware acceleration, and whether it is FIPS certified. +Common characteristics are defined in CryptoSpi::TCommonCharacteristics:

            class TCommonCharacteristics + { + public: + ... + TInt32 iInterfaceUID; + TInt32 iAlgorithmUID; + TInt32 iImplementationUID; + const TRomLitC16* iCreatorName; + TBool iIsFIPSApproved; + TBool iIsHardwareSupported; + TUint iMaxConcurrencySupported; + const TRomLitC16* iAlgorithmName; + TInt iLatency; + TInt iThroughput; + }; +

            Other characteristics are specific to a particular interface. +For each interface type, a T class is defined as an aggregation of a TCommonCharacteristics object +and some additional characteristics particular to that interface. For instance, THashCharacteristics includes +a block size, output size and operation mode. (The operation mode can be either KHashMode or KHmacMode, +and indicates whether the hash algorithm is an HMAC or not.)

            class THashCharacteristics + { + public: + IMPORT_C TBool IsOperationModeSupported(TUid aOperationMode) const; + + public: + TCommonCharacteristics cmn; + TUint iBlockSize; + TUint iOutputSize; + const TInt32* iSupportedOperationModes; + TUint iOperationModeNum; + }; +

            All the data types relating to characteristics are defined +in plugincharacteristics.h.

            For an example, see src/common/generic/security/cryptospi/source/softwarecrypto/pluginconfig.h.

            +
            How to implement +the framework code

            Plug-in modules must implement a defined set +of functions exported at defined ordinals. The function prototypes and the +ordinals (see TPluginEntryOrdinal) are defined in pluginentrydef.h. +When a client requests an algorithm, these functions are used by CryptoSPI +to query and instantiate algorithm implementations. The simplest way to ensure +that functions are assigned the correct ordinal is to copy the softwarecryptoU.def exports +file, which can be found in the EABI and BWINS directories +in the CryptoSPI source code.

            Minimally, the plug-in DLL must implement +the function exported at ordinal 1, whose prototype is:

            typedef const TCharacteristics** (*EnumerateCharacteristicsFunc)(TUid, TInt&);

            and at least one of the algorithm factory functions. See for example +class CCryptoPluginEntry (pluginentry.h / pluginentry.cpp).

            If +the plug-in DLL does not support a particular algorithm, the ABSENT keyword +should be used in its .def file to ensure any subsequent +exports are at the correct ordinals.

            Querying the characteristics +of plug-ins

            CryptoSPI builds up a list of the characteristics +of all the plug-in DLLs by calling the function exported at ordinal 1 (EEnumerateCharacteristicsOrdinal) +for each DLL and for each interface type. Here is an example implementation:

            EXPORT_C const TCharacteristics** CCryptoPluginEntry::Enumerate(TUid aInterface, TInt& aNumPlugins) + { + const TCharacteristics** ptr(0); + switch (aInterface.iUid) + { + case KHashInterface: + { + aNumPlugins=sizeof(KHashCharacteristics)/sizeof(THashCharacteristics*); + ptr = (const TCharacteristics**) &KHashCharacteristics[0]; + } + break; + + case KRandomInterface: + { + aNumPlugins=sizeof(KRandomCharacteristics)/sizeof(TRandomCharacteristics*); + ptr= (const TCharacteristics**) &KRandomCharacteristics[0]; + } + break; + ... + } + return ptr; + } +

            Key points:

              +

            • Every plug-in must implement +this function.

              • +

            • TUid aInterface is +the interface UID, as defined in CryptoSpi::KInterfacesUids.

              • +

            • TInt& aNumPlugins should +be set to the number of algorithms of that interface type implemented by the +plug-in.

              • +

            Extended characteristics

            Extended characteristics +are those which can only be determined at runtime. They are retrieved on demand +by CryptoSPI or clients can call the plug-in's implementation of CryptoSpi::CCryptoBase::GetExtendedCharacteristicsL().

            The +function exported at ordinal 2 has this prototype:

            typedef void (*GetExtendedCharacteristicsFuncL)(TUid, CExtendedCharacteristics*&);

            Symbian defines 2 extended characteristics:

              +

            • TInt iAvailableConcurrency;

              The +number of available resources for processing the operation for the requested +plug-in. This could be zero even if no operations are in progress; for instance +cryptographic acceleration hardware is turned off to save battery power.

              • +

            • TBool iExclusiveUse;

              Whether +it is possible for the application to reserve exclusive use of hardware resources +used by the plug-in.

              • +

            Additional plug-in specific characteristics may be defined. The plug-in +creator needs to define UIDs for each of these and specify the UID when calling CryptoSpi::CExtendedCharacteristics::AddCharacteristicL().

            Algorithm instantiation

            A plug-in must implement +one or more factory methods for instantiating algorithms. The functions exported +at ordinals 3 to 20 have the following declarations. (Note that symmetric +key generation is not yet implemented by Symbian's software crypto plug-in, +so the ordinals ECreateSymmetricKeyGeneratorOrdinal and ECreateAsyncSymmetricKeyGeneratorOrdinal have +no corresponding declarations).

            typedef void (*CreateRandomFuncL)(MRandom*&, TUid, const CCryptoParams*); +typedef void (*CreateHashFuncL)(MHash*&, TUid, TUid, const CKey*, const CCryptoParams*); +typedef void (*CreateSymmetricCipherFuncL)(MSymmetricCipher*&, TUid, const CKey&, TUid, TUid, TUid, const CCryptoParams*); +typedef void (*CreateAsymmetricCipherFuncL)(MAsymmetricCipher*&, TUid, const CKey&, TUid, TUid, const CCryptoParams*); +typedef void (*CreateSignerFuncL)(MSigner*&, TUid, const CKey&, TUid, const CCryptoParams*); +typedef void (*CreateVerifierFuncL)(MVerifier*&, TUid, const CKey&, TUid, const CCryptoParams*); +typedef void (*CreateKeyAgreementFuncL)(MKeyAgreement*&, TUid, const CKey&, const CCryptoParams*); +typedef void (*CreateKeyPairGeneratorFuncL)(MKeyPairGenerator*&, TUid, const CCryptoParams*); +typedef void (*CreateAsyncRandomFuncL)(MAsyncRandom*&, TUid, const CCryptoParams*); +typedef void (*CreateAsyncHashFuncL)(MAsyncHash*&, TUid, TUid, const CKey*, const CCryptoParams*); +typedef void (*CreateAsyncSymmetricCipherFuncL)(MAsyncSymmetricCipher*&, TUid, const CKey&, TUid, TUid, TUid, const CCryptoParams*); +typedef void (*CreateAsyncAsymmetricCipherFuncL)(MAsyncAsymmetricCipher*&, TUid, const CKey&, TUid, TUid, const CCryptoParams*); +typedef void (*CreateAsyncSignerFuncL)(MAsyncSigner*&, TUid, const CKey&, TUid, const CCryptoParams*); +typedef void (*CreateAsyncVerifierFuncL)(MAsyncVerifier*&, TUid, const CKey&, TUid, const CCryptoParams*); +typedef void (*CreateAsyncKeyAgreementFuncL)(MAsyncKeyAgreement*&, TUid, const CKey&, const CCryptoParams*); +typedef void (*CreateAsyncKeyPairGeneratorFuncL)(MAsyncKeyPairGenerator*&, TUid, const CCryptoParams*);

            Clients +instantiate algorithms by calling one of the CryptoSPI factory methods, for +instance CHashFactory::CreateHashL(). All CryptoSPI factory +methods take a CCryptoParams parameter. This class allows +clients to supply arbitrary, algorithm-specific data to plug-ins, for instance +the effective key length for RC2, or the number of bytes to discard from the +keystream for ARC4.

            The data type of each parameter can be integer +(TInt), big integer (RInteger), or 8/16 +bit descriptor. Additional data types could be added in future, by extending +the TParamType enum in CCryptoParam and +deriving a class from CCryptoParam, but this is unlikely +to be necessary.

            +
            How to implement +the MPlugin-derived class

            All concrete algorithm classes are derived +from one of the abstract base classes listed below, which are in turn all +derived from MPlugin.

              +

            • Random (MRandom /MAsyncRandom)

              • +

            • Hash (MHash /MAsyncHash)

              • +

            • Symmetric cipher (MSymmetricCipher /MAsyncSymmetricCipher)

              • +

            • Asymmetric cipher (MAsymmetricCipher /MAsyncAsymmetricCipher)

              • +

            • Signer (MSigner /MAsyncSigner)

              • +

            • Verifier (MVerifier /MAsyncVerifier)

              • +

            • Key agreement (MKeyAgreement /MAsyncKeyAgreement)

              • +

            • Key pair generator (MKeyPairGenerator /MAsyncKeyPairGenerator)

              • +

            • Key generator (MSymmetricKeyGenerator /MAsyncSymmetricKeyGenerator)

              • +

            MPlugin (cryptoplugin.h) +declares the following pure virtual functions:

            virtual void Close() = 0; +virtual void Reset() = 0; +virtual void GetCharacteristicsL(const TCharacteristics*& aPluginCharacteristics) = 0; +virtual const CExtendedCharacteristics& GetExtendedCharacteristicsL() = 0; +virtual TAny* GetExtension(TUid aExtensionId) = 0;

            For example, +the random number generator plug-in implemented in softwarecrypto.dll implements +these functions as follows:

            void CRandomImpl::Close() + { + delete this; + } + +void CRandomImpl::Reset() + { //Not required + } + +const CExtendedCharacteristics* CRandomImpl::GetExtendedCharacteristicsL() + // All Symbian software plug-ins have unlimited concurrency and cannot be reserved + // for exclusive use + { + return CExtendedCharacteristics::NewL(KMaxTInt, EFalse); + } + +//Get the plug-in characteristics (defined at compile time) +void CRandomImpl::GetCharacteristicsL(const TCharacteristics*& aPluginCharacteristics) + { + //Find out how many algorithms are implemented by the plug-in + TInt randomNum = sizeof(KRandomCharacteristics)/sizeof(TRandomCharacteristics*); + for (TInt i = 0; i < randomNum; i++) + { + //Compare implementation UIDs + //ImplementationUid() is a helper function that returns KCryptoPluginRandomUid + if (KRandomCharacteristics[i]->cmn.iImplementationUID == ImplementationUid().iUid) + { + aPluginCharacteristics = KRandomCharacteristics[i]; + break; + } + } + } + +TAny* CRandomImpl::GetExtension(TUid /*aExtensionId*/) + { + return NULL; + }

            The main purpose of MPlugin::Reset() is +to reset the hardware, so is usually not relevant to a software-only implementation. GetExtension() is +intended for internal use, and may be removed from the API in future.

            These +functions are called through the client API to CryptoSPI, in other words CCryptoBase and +the various classes derived from it, in this case, CRandom. +For instance when the client calls CCryptoBase::GetCharacteristicsL(), +this calls GetCharacteristicsL() in the plug-in, or calling CRandom::GenerateRandomBytesL(), +calls GenerateRandomBytesL() in the plug-in.

            +
            The configuration +file

            The set of available plug-ins is listed in the configuration +file z:\resource\cryptospi\plug-ins.txt. Each line in +the file contains the filename of a single plug-in DLL, without the path. +The path is not required because the DLLs are assumed to be located in z:\sys\bin. +The configuration file must be on the Z: drive and therefore +additional plug-ins cannot be installed post-manufacture. Depending on the +plug-in selector in use, plug-ins may be loaded individually, as required, +or all at once when CryptoSPI is initialized. The default selector implemented +by Symbian (CLegacySelector) loads plug-in DLLs as required.

            +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2DDAAD1C-D9EB-5741-B6AE-2383646E0EDB.dita --- a/Symbian3/SDK/Source/GUID-2DDAAD1C-D9EB-5741-B6AE-2383646E0EDB.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-2DDAAD1C-D9EB-5741-B6AE-2383646E0EDB.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,70 +1,70 @@ - - - - - -Pointer -descriptorsDescribes non-modifiable pointer descriptors and modifiable pointer -descriptors. -

            A pointer descriptor represents data which can live in ROM or RAM and this -location is separate from the pointer descriptor object itself.

            -

            A pointer descriptor is an instance of a class that encapsulates a pointer -to the location of the data.

            -

            A pointer descriptor comes in two forms:

            -
              -

            • a non-modifiable pointer -descriptor.

              • -

            • a modifiable pointer -descriptor.

              • -
            -
            Non-modifiable pointer descriptor

            The data represented -by a non-modifiable pointer descriptor can be accessed, but not changed, through -this descriptor.

            Data is accessed through functions provided by the -base class.

            A non-modifiable pointer descriptor is supplied in two -variants:

              -

            • the 16 bit variant, -a TPtrC16, for representing Unicode strings.

              • -

            • the 8 bit variant, a TPtrC8, -for representing non-Unicode strings and binary data.

              • -

            There is also a build independent type, TPtrC. This -is the type which is most commonly used in program code; the appropriate variant -is selected at build time.

            An explicit 8 bit variant is chosen for -binary data. The explicit 16 bit variant is rarely used.

            The base -class, TDesC, contains a data member which holds the length -of the data. The following drawing shows the layout of a TPtrC object -for a string of five characters representing the English word "Hello".

            - -

            Non-modifiable pointer descriptor

            -
            -
            Modifiable pointer descriptor

            The data represented -by a modifiable pointer descriptor can be both accessed and changed through -this descriptor.

            The length of the data can vary between zero and -the maximum length. The maximum length of the descriptor is set by the constructor. -When the length of the data is less than the maximum, a portion of the data -area represented by the descriptor is unused.

            Data is accessed and -modified through functions provided by the base classes.

            A modifiable -pointer descriptor is supplied in two variants:

              -

            • the 16 bit variant, -a TPtr16, for representing Unicode strings.

              • -

            • the 8 bit variant, a TPtr8, -for representing non-Unicode strings and binary data.

              • -

            There is also a build independent type, TPtr. This -is the type which is most commonly used in program code; the appropriate variant -is selected at build time.

            An explicit 8 bit variant is chosen for -binary data. The explicit 16 bit variant is rarely used.

            The base -class TDesC, contains a data member that holds the length -of the data. The base class TDes, contains a data member -that holds the maximum length of the data. The following drawing shows the -layout of a TPtr object for a string of five characters representing -the English word "Hello". The maximum length to be represented by the descriptor -is 12.

            - -

            Modifiable pointer descriptor

            -
            + + + + + +Pointer +descriptorsDescribes non-modifiable pointer descriptors and modifiable pointer +descriptors. +

            A pointer descriptor represents data which can live in ROM or RAM and this +location is separate from the pointer descriptor object itself.

            +

            A pointer descriptor is an instance of a class that encapsulates a pointer +to the location of the data.

            +

            A pointer descriptor comes in two forms:

            +
              +

            • a non-modifiable pointer +descriptor.

              • +

            • a modifiable pointer +descriptor.

              • +
            +
            Non-modifiable pointer descriptor

            The data represented +by a non-modifiable pointer descriptor can be accessed, but not changed, through +this descriptor.

            Data is accessed through functions provided by the +base class.

            A non-modifiable pointer descriptor is supplied in two +variants:

              +

            • the 16 bit variant, +a TPtrC16, for representing Unicode strings.

              • +

            • the 8 bit variant, a TPtrC8, +for representing non-Unicode strings and binary data.

              • +

            There is also a build independent type, TPtrC. This +is the type which is most commonly used in program code; the appropriate variant +is selected at build time.

            An explicit 8 bit variant is chosen for +binary data. The explicit 16 bit variant is rarely used.

            The base +class, TDesC, contains a data member which holds the length +of the data. The following drawing shows the layout of a TPtrC object +for a string of five characters representing the English word "Hello".

            + +

            Non-modifiable pointer descriptor

            +
            +
            Modifiable pointer descriptor

            The data represented +by a modifiable pointer descriptor can be both accessed and changed through +this descriptor.

            The length of the data can vary between zero and +the maximum length. The maximum length of the descriptor is set by the constructor. +When the length of the data is less than the maximum, a portion of the data +area represented by the descriptor is unused.

            Data is accessed and +modified through functions provided by the base classes.

            A modifiable +pointer descriptor is supplied in two variants:

              +

            • the 16 bit variant, +a TPtr16, for representing Unicode strings.

              • +

            • the 8 bit variant, a TPtr8, +for representing non-Unicode strings and binary data.

              • +

            There is also a build independent type, TPtr. This +is the type which is most commonly used in program code; the appropriate variant +is selected at build time.

            An explicit 8 bit variant is chosen for +binary data. The explicit 16 bit variant is rarely used.

            The base +class TDesC, contains a data member that holds the length +of the data. The base class TDes, contains a data member +that holds the maximum length of the data. The following drawing shows the +layout of a TPtr object for a string of five characters representing +the English word "Hello". The maximum length to be represented by the descriptor +is 12.

            + +

            Modifiable pointer descriptor

            +
            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2E0F793F-3D80-4303-AF48-C7341F417DC9.dita --- a/Symbian3/SDK/Source/GUID-2E0F793F-3D80-4303-AF48-C7341F417DC9.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-2E0F793F-3D80-4303-AF48-C7341F417DC9.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,392 +1,392 @@ - - - - - -Editing -menu -

            Users can access editing functions using the editing menu. It is opened -by a short press of the star (*) key (or by pressing the Edit key on some -devices) when in a text editor. The editing menu looks and functions like -the Options menu, but it contains only text editing -functions, whereas other available options remain accessible from the Options menu. -The following table describes the options in the editing menu.

            -

            Only items that apply to the editor in use appear in the menu.

             -Editing menu -options - - - - - -

            Function

             -

            Description

             -             - - - -

            Special character row

             -

            One row with the most used special characters and symbols.

             -             - -

            More symbols

             -

            Opens a full grid of special characters and symbols.

             -             - -

            Predictive text

             -

            Opens a submenu for the Predictive text options.

            Some -devices may offer more advanced text input methods and editing options.

             -             - -

            Matches

             -

            Displays list of matched words when predictive text mode is on and -a word is active in the editor.

             -             - -

            Insert word

             -

            Opens a query for inserting a word (no prediction).

             -             - -

            Edit word

             -

            In prediction mode, opens the active word from the editor in a query -window for editing.

             -             - -

            Prediction on/off

             -

            A temporary setting for predictive input.

             -             - -

            Alpha mode

             -

            Switches to the alpha input mode.

             -             - -

            Number mode

             -

            Switches to the number input mode.

             -             - -

            Copy text

             -

            Starts text copying.

             -             - -

            Cut text

             -

            Starts text cutting.

             -             - -

            Paste

             -

            Pastes cut or copied text in the cursor position.

             -             - -

            Writing language

             -

            Affects key mappings and predictive input.

             -             - - -
            - -Editing menu - - -Default touch -events in editor - - - - - - -

            User action

             -

            State change

             -

            Feedback

             -             - - - -

            Touch down

             -

            Cursor is moved to the touch down position in the text field.

             -

            Visual indication of touched down state

            Tactile: Sensitive -edit effect and audio feedback is provided with touch down event.

             -             - -

            Touch release

             -

            Touch Input window is launched.

             -

            Tactile: Sensitive edit effect is provided with touch release event. -No audio feedback is provided.

             -             - -

            Touch down and drag

             -
              -

            • A block of text is selected. Touch down, drag and touch release is -performed in the text area.

              • -

            • The text remains selected after touch release.

              • -

            • Touch down a second time cancels the previous text selection and cursor -is moved to the touch down position.

              • -
             -

            Tactile:

              -

            • Sensitive edit and audio feedback is provided with touch down event.

              • -

            • Text edit and audio feedback effect is provided while selecting letters.

              • -

            • Blank edit effect given while selecting blank space.

              • -

            • Line edit and audio feedback is provided while selecting lines.

              • -

            • Empty line effect is provided while selecting empty line.

              • -

            • Pop-up open effect is provided with touch down after selecting.

              • -

             -             - -

            Touch down and drag outside

             -
              -

            • Scrolling of text that did not fit in the edit area.

              • -

            • A block of text is selected.

              • -

            • Touch down and drag to out of the text field if there is text that -can be scrolled, else no action.

              • -
             -

            Tactile: Sensitive edit and audio feedback given with touch down -effect. Specific effect given while selecting, see previous row.

             -             - - -
            -

            -Default touch -events in editor with kinetic scrolling when no text is selected - - - - - - -

            User action

             -

            State change

             -

            Feedback

             -             - - - -

            Touch down

             -

            No change

             -

            Tactile: Sensitive edit effect and audio feedback is provided with -touch down event.

             -             - -

            Touch release

             -
              -

            • Cursor is moved to the touch down position in the text field.

              • -

            • Touch Input window is launched.

              • -

            • In viewer: Inactive

              • -
             -

            Tactile: Sensitive edit effect is provided with touch release event. -No audio feedback is provided.

             -             - -

            Touch down, move horizontally and release

             -
              -

            • A block of text is selected.

              • -

            • Touch down, drag and touch release is performed in the text area.

              • -

            • The text remains selected after touch release.

              • -

            • In viewer: Opens stylus pop-up menu with available CCP menu options -after touch release.

              • -
             -

            Tactile:

              -

            • Sensitive edit and audio feedback is provided with touch down event.

              • -

            • Text edit and audio feedback effect is provided while selecting letters.

              • -

            • Blank edit effect is provided while selecting blank space.

              • -

             -             - -

            Touch down, move horizontally, then move vertically without lifting -finger and release

             -
              -

            • A block of text is selected.

              • -

            • Touch down, drag and touch release is performed in the text area.

              • -

            • The text remains selected after touch release.

              • -

            • In viewer: Opens stylus pop-up menu with available CCP menu options -after touch release.

              • -
             -

            Tactile:

              -

            • Sensitive edit and audio feedback is provided with touch down event.

              • -

            • Text edit and audio feedback effect is provided while selecting letters.

              • -

            • Blank edit effect is provided while selecting blank space.

              • -

            • Line edit and audio feedback is provided while selecting lines.

              • -

            • Empty line effect is provided while selecting empty line.

              • -

             -             - -

            Touch down, move horizontally, then release with speed

             -
              -

            • A block of text is selected.

              • -

            • Touch down, drag and touch release is performed in the text area.

              • -

            • The text remains selected after touch release.

              • -

            • Flick not applicable.

              • -
             -

            Tactile:

              -

            • Sensitive edit and audio feedback is provided with touch down event.

              • -

            • Text edit and audio feedback effect is provided while selecting letters.

              • -

            • Blank edit effect is provided while selecting blank space.

              • -

            • Line edit and audio feedback is provided while selecting lines.

              • -

            • Empty line effect is provided while selecting empty line.

              • -

             -             - -

            Touch down and move outside

             -
              -

            • Scrolling of text that did not fit in the edit area.

              • -

            • A block of text is selected.

              • -

            • Touch down and drag to out of the text field.

              • -

            • This is if there is text that can be scrolled, otherwise no action.

              • -
             -

            Tactile:

              -

            • Sensitive edit and audio feedback is provided with touch down effect.

              • -

            • Specific effect given while selecting, see previous row.

              • -

             -             - -

            Touch down, move vertically and release

             -
              -

            • Scrolling stops on release, no text is selected.

              • -

            • Cursor is moved on touch down after a certain threshold.

              • -

            • It is not immediately moved to avoid cursor jumping during dragging -and flicking.

              • -

            • No cursor is shown during scrolling. Cursor is not moved on release.

              • -
             - -             - -

            Touch down, move vertically and release with speed

             -
              -

            • Scrolling continues on flick speed and slows down (kinetic).

              • -

            • Scrolling is stopped when speed slows down or end of text is reached.

              • -

            • Boundary effect is given at the end of text. No text is selected.

              • -

            Refer to Dragging -and flicking events.

             -

            Tactile: Refer to Dragging -and flicking events.

             -             - -

            Touch down and hold and touch release

             -

            Inactive

             -

            No effect

             -             - - -
            -

            -Default touch -events in editor when text is selected - - - - - - -

            User action

             -

            State change

             -

            Feedback

             -             - - - -

            Touch down and release

             -
              -

            • When touch down and release out of the selection, highlight disappears -and cursor stays where it was.

              • -

            • In viewers: Highlight disappears.

              • -

            • When touch down and release within selected text, opens virtual input, -highlight stays as it is and can be modified in input editor.

              • -

            • In viewers: Inactive.

              • -
             -

            Tactile: Sensitive edit effect and audio feedback is provided with -touch down event.

             -             - -

            Touch down and hold

             -

            Inactive

             -

            No effect

             -             - -

            Touch down and move horizontally

             -
              -

            • When on selected text, the beginning or ending point of the selection -follows the finger and the selection changes dynamically.

              • -

            • Touch down, drag and touch release is performed in the text area.

              • -

            • The text remains selected after touch release.

              • -

            • When touch down and move horizontally outside the text selection, behavior -is inactive.

              • -
             -

            Tactile:

              -

            • Sensitive edit and audio feedback is provided with touch down event.

              • -

            • Text edit and audio feedback effect is provided while selecting letters.

              • -

            • Blank edit effect is provided while selecting blank space.

              • -

            • Line edit and audio feedback is provided while selecting lines.

              • -

            • Empty line effect is provided while selecting empty line.

              • -

            • Pop-up open effect given with touch down after selecting.

              • -

             -             - -

            Touch down, move horizontally and release with speed

             -
              -

            • When on selected text, the beginning or ending point of the selection -follows the finger and the selection changes dynamically during the drag.

              • -

            • Release with speed is disabled. Touch down, move and touch release -is performed in the text area.

              • -

            • The text remains selected after touch release up to the point of the -release.

              • -

            • When touch down and move horizontally outside the text selection, behavior -is inactive.

              • -
             - -             - -

            Touch down, move vertically and release

             -
              -

            • When on selected text, the beginning or ending point of the selection -follows the finger and the selection changes dynamically during the drag.

              • -

            • Release with speed is disabled.

              • -

            • Touch down, move and touch release is performed in the text area.

              • -

            • On touch release the text remains selected.

              • -

            • When touch down and move vertically outside selected text, content -moves with finger.

              • -

            • On touch release content movement stops and text remains selected.

              • -
             - -             - -

            Touch down and move vertically and release

             -
              -

            • Content movement stops when dragging was in effect.

              • -

            • Text remains selected.

              • -
             - -             - -

            Touch down, move vertically and release with speed

             -

            Refer to Dragging -and flicking events.

            Text remains selected.

             - -             - - -

            Touch down and move outside

             -
              -

            • Scrolling of text that did not fit in the edit area.

              • -

            • A block of text is selected.

              • -

            • Touch down and drag to out of the text field if there -is text that can be scrolled, else no action.

              • -
             -

            Tactile:

              -

            • Sensitive edit and audio feedback is provided with touch down effect.

              • -

            • Specific effect given while selecting, see row 3.

              • -

             -             - -

            Touch down outside highlighted text and move horizontally

             -

            Editors and viewers: When dragging starts, highlight disappears -from previous place and starts highlighting new text with the horizontal move.

             - -             - - + + + + + +Editing +menu +

            Users can access editing functions using the editing menu. It is opened +by a short press of the star (*) key (or by pressing the Edit key on some +devices) when in a text editor. The editing menu looks and functions like +the Options menu, but it contains only text editing +functions, whereas other available options remain accessible from the Options menu. +The following table describes the options in the editing menu.

            +

            Only items that apply to the editor in use appear in the menu.

             +
            Editing menu +options + + + + + +

            Function

             +

            Description

             +             + + + +

            Special character row

             +

            One row with the most used special characters and symbols.

             +             + +

            More symbols

             +

            Opens a full grid of special characters and symbols.

             +             + +

            Predictive text

             +

            Opens a submenu for the Predictive text options.

            Some +devices may offer more advanced text input methods and editing options.

             +             + +

            Matches

             +

            Displays list of matched words when predictive text mode is on and +a word is active in the editor.

             +             + +

            Insert word

             +

            Opens a query for inserting a word (no prediction).

             +             + +

            Edit word

             +

            In prediction mode, opens the active word from the editor in a query +window for editing.

             +             + +

            Prediction on/off

             +

            A temporary setting for predictive input.

             +             + +

            Alpha mode

             +

            Switches to the alpha input mode.

             +             + +

            Number mode

             +

            Switches to the number input mode.

             +             + +

            Copy text

             +

            Starts text copying.

             +             + +

            Cut text

             +

            Starts text cutting.

             +             + +

            Paste

             +

            Pastes cut or copied text in the cursor position.

             +             + +

            Writing language

             +

            Affects key mappings and predictive input.

             +             + + +
            + +Editing menu + + +Default touch +events in editor + + + + + + +

            User action

             +

            State change

             +

            Feedback

             +             + + + +

            Touch down

             +

            Cursor is moved to the touch down position in the text field.

             +

            Visual indication of touched down state

            Tactile: Sensitive +edit effect and audio feedback is provided with touch down event.

             +             + +

            Touch release

             +

            Touch Input window is launched.

             +

            Tactile: Sensitive edit effect is provided with touch release event. +No audio feedback is provided.

             +             + +

            Touch down and drag

             +
              +

            • A block of text is selected. Touch down, drag and touch release is +performed in the text area.

              • +

            • The text remains selected after touch release.

              • +

            • Touch down a second time cancels the previous text selection and cursor +is moved to the touch down position.

              • +
             +

            Tactile:

              +

            • Sensitive edit and audio feedback is provided with touch down event.

              • +

            • Text edit and audio feedback effect is provided while selecting letters.

              • +

            • Blank edit effect given while selecting blank space.

              • +

            • Line edit and audio feedback is provided while selecting lines.

              • +

            • Empty line effect is provided while selecting empty line.

              • +

            • Pop-up open effect is provided with touch down after selecting.

              • +

             +             + +

            Touch down and drag outside

             +
              +

            • Scrolling of text that did not fit in the edit area.

              • +

            • A block of text is selected.

              • +

            • Touch down and drag to out of the text field if there is text that +can be scrolled, else no action.

              • +
             +

            Tactile: Sensitive edit and audio feedback given with touch down +effect. Specific effect given while selecting, see previous row.

             +             + + +
            +

            +Default touch +events in editor with kinetic scrolling when no text is selected + + + + + + +

            User action

             +

            State change

             +

            Feedback

             +             + + + +

            Touch down

             +

            No change

             +

            Tactile: Sensitive edit effect and audio feedback is provided with +touch down event.

             +             + +

            Touch release

             +
              +

            • Cursor is moved to the touch down position in the text field.

              • +

            • Touch Input window is launched.

              • +

            • In viewer: Inactive

              • +
             +

            Tactile: Sensitive edit effect is provided with touch release event. +No audio feedback is provided.

             +             + +

            Touch down, move horizontally and release

             +
              +

            • A block of text is selected.

              • +

            • Touch down, drag and touch release is performed in the text area.

              • +

            • The text remains selected after touch release.

              • +

            • In viewer: Opens stylus pop-up menu with available CCP menu options +after touch release.

              • +
             +

            Tactile:

              +

            • Sensitive edit and audio feedback is provided with touch down event.

              • +

            • Text edit and audio feedback effect is provided while selecting letters.

              • +

            • Blank edit effect is provided while selecting blank space.

              • +

             +             + +

            Touch down, move horizontally, then move vertically without lifting +finger and release

             +
              +

            • A block of text is selected.

              • +

            • Touch down, drag and touch release is performed in the text area.

              • +

            • The text remains selected after touch release.

              • +

            • In viewer: Opens stylus pop-up menu with available CCP menu options +after touch release.

              • +
             +

            Tactile:

              +

            • Sensitive edit and audio feedback is provided with touch down event.

              • +

            • Text edit and audio feedback effect is provided while selecting letters.

              • +

            • Blank edit effect is provided while selecting blank space.

              • +

            • Line edit and audio feedback is provided while selecting lines.

              • +

            • Empty line effect is provided while selecting empty line.

              • +

             +             + +

            Touch down, move horizontally, then release with speed

             +
              +

            • A block of text is selected.

              • +

            • Touch down, drag and touch release is performed in the text area.

              • +

            • The text remains selected after touch release.

              • +

            • Flick not applicable.

              • +
             +

            Tactile:

              +

            • Sensitive edit and audio feedback is provided with touch down event.

              • +

            • Text edit and audio feedback effect is provided while selecting letters.

              • +

            • Blank edit effect is provided while selecting blank space.

              • +

            • Line edit and audio feedback is provided while selecting lines.

              • +

            • Empty line effect is provided while selecting empty line.

              • +

             +             + +

            Touch down and move outside

             +
              +

            • Scrolling of text that did not fit in the edit area.

              • +

            • A block of text is selected.

              • +

            • Touch down and drag to out of the text field.

              • +

            • This is if there is text that can be scrolled, otherwise no action.

              • +
             +

            Tactile:

              +

            • Sensitive edit and audio feedback is provided with touch down effect.

              • +

            • Specific effect given while selecting, see previous row.

              • +

             +             + +

            Touch down, move vertically and release

             +
              +

            • Scrolling stops on release, no text is selected.

              • +

            • Cursor is moved on touch down after a certain threshold.

              • +

            • It is not immediately moved to avoid cursor jumping during dragging +and flicking.

              • +

            • No cursor is shown during scrolling. Cursor is not moved on release.

              • +
             + +             + +

            Touch down, move vertically and release with speed

             +
              +

            • Scrolling continues on flick speed and slows down (kinetic).

              • +

            • Scrolling is stopped when speed slows down or end of text is reached.

              • +

            • Boundary effect is given at the end of text. No text is selected.

              • +

            Refer to Dragging +and flicking events.

             +

            Tactile: Refer to Dragging +and flicking events.

             +             + +

            Touch down and hold and touch release

             +

            Inactive

             +

            No effect

             +             + + +
            +

            +Default touch +events in editor when text is selected + + + + + + +

            User action

             +

            State change

             +

            Feedback

             +             + + + +

            Touch down and release

             +
              +

            • When touch down and release out of the selection, highlight disappears +and cursor stays where it was.

              • +

            • In viewers: Highlight disappears.

              • +

            • When touch down and release within selected text, opens virtual input, +highlight stays as it is and can be modified in input editor.

              • +

            • In viewers: Inactive.

              • +
             +

            Tactile: Sensitive edit effect and audio feedback is provided with +touch down event.

             +             + +

            Touch down and hold

             +

            Inactive

             +

            No effect

             +             + +

            Touch down and move horizontally

             +
              +

            • When on selected text, the beginning or ending point of the selection +follows the finger and the selection changes dynamically.

              • +

            • Touch down, drag and touch release is performed in the text area.

              • +

            • The text remains selected after touch release.

              • +

            • When touch down and move horizontally outside the text selection, behavior +is inactive.

              • +
             +

            Tactile:

              +

            • Sensitive edit and audio feedback is provided with touch down event.

              • +

            • Text edit and audio feedback effect is provided while selecting letters.

              • +

            • Blank edit effect is provided while selecting blank space.

              • +

            • Line edit and audio feedback is provided while selecting lines.

              • +

            • Empty line effect is provided while selecting empty line.

              • +

            • Pop-up open effect given with touch down after selecting.

              • +

             +             + +

            Touch down, move horizontally and release with speed

             +
              +

            • When on selected text, the beginning or ending point of the selection +follows the finger and the selection changes dynamically during the drag.

              • +

            • Release with speed is disabled. Touch down, move and touch release +is performed in the text area.

              • +

            • The text remains selected after touch release up to the point of the +release.

              • +

            • When touch down and move horizontally outside the text selection, behavior +is inactive.

              • +
             + +             + +

            Touch down, move vertically and release

             +
              +

            • When on selected text, the beginning or ending point of the selection +follows the finger and the selection changes dynamically during the drag.

              • +

            • Release with speed is disabled.

              • +

            • Touch down, move and touch release is performed in the text area.

              • +

            • On touch release the text remains selected.

              • +

            • When touch down and move vertically outside selected text, content +moves with finger.

              • +

            • On touch release content movement stops and text remains selected.

              • +
             + +             + +

            Touch down and move vertically and release

             +
              +

            • Content movement stops when dragging was in effect.

              • +

            • Text remains selected.

              • +
             + +             + +

            Touch down, move vertically and release with speed

             +

            Refer to Dragging +and flicking events.

            Text remains selected.

             + +             + + +

            Touch down and move outside

             +
              +

            • Scrolling of text that did not fit in the edit area.

              • +

            • A block of text is selected.

              • +

            • Touch down and drag to out of the text field if there +is text that can be scrolled, else no action.

              • +
             +

            Tactile:

              +

            • Sensitive edit and audio feedback is provided with touch down effect.

              • +

            • Specific effect given while selecting, see row 3.

              • +

             +             + +

            Touch down outside highlighted text and move horizontally

             +

            Editors and viewers: When dragging starts, highlight disappears +from previous place and starts highlighting new text with the horizontal move.

             + +             + +
            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2E253B30-2611-546D-AE5B-1752556FC8E8.dita --- a/Symbian3/SDK/Source/GUID-2E253B30-2611-546D-AE5B-1752556FC8E8.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-2E253B30-2611-546D-AE5B-1752556FC8E8.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,62 +1,62 @@ - - - - - -SMTP -Concepts -

            This section section describes the Simple Mail Transfer Protocol (SMTP) -and its implementation on Symbian platform.

            -
            SMTP protocol

            SMTP -is the most widely used protocol for sending emails. It is a text-based and push protocol -that cannot pull messages from a remote server on demand.

            One -or more recipients of a message are specified in a message along with the -message text and other encoded objects. The message is then transferred to -a remote server using a procedure of queries and responses between the client -and server. Either an end-user's email client (Mail User Agent (MUA)) or a -relaying server's Mail Transport Agents (MTA) can act as an SMTP client. The -SMTP client initiates a TCP connection to SMTP server on port 25 (unless overridden -by configuration).

            SMTP is more suitable for a machine permanently -connected to the Internet. To retrieve messages only on demand, which is the -most common requirement on a single-user computer, a mail client must use -POP3 or IMAP4. POP3 is mostly preferred when single-user computers connected -to the Internet only intermittently.

            -
            Symbian platform implementation of SMTP

            SMTP is -a Mail Transfer Agent (MTA) used to transfer emails to a SMTP server which -then forwards them on to a specified destination.

            Sending an email -generally consists of three phases: connect and authorise to server, send -emails and quit.

            The SMTP component is responsible for sending email -messages composed and stored in the Message Server’s Message Store.

              -

            1. The SMTP client initiates -a connection with the SMTP server. Depending on the user’s email settings, -this may have been initiated over a secure SSL/TLS socket on port 465.

              2. -

            2. Depending on how the -user has configured the email settings and the capabilities of the SMTP server, -SMTP authentication may also be required.

              3. -

            3. Mail From and -recipient To are sent.

              4. -

            4. The message header fields -for the email message stored in the Message Store are then transmitted, each -one separated by a CRLF.

              5. -

            5. The last CRLF is sent -to indicate the end of the RFC 2822 header.

              6. -

            6. The message body and -encoded attachments are sent.

              The encoding format (uuencode or MIME, -character sets) depends on the user’s email settings and locale.

              7. -

            7. Finally, the body is -terminated by a CRLF.

              CRLF sequence, and the email is queued by the -SMTP server for sending.

              8. -
            -
            SMTP example

            For more details on implementing the -IMAP4 MTM functions, see example -code.

            -             -SMTP MTM - + + + + + +SMTP +Concepts +

            This section section describes the Simple Mail Transfer Protocol (SMTP) +and its implementation on Symbian platform.

            +
            SMTP protocol

            SMTP +is the most widely used protocol for sending emails. It is a text-based and push protocol +that cannot pull messages from a remote server on demand.

            One +or more recipients of a message are specified in a message along with the +message text and other encoded objects. The message is then transferred to +a remote server using a procedure of queries and responses between the client +and server. Either an end-user's email client (Mail User Agent (MUA)) or a +relaying server's Mail Transport Agents (MTA) can act as an SMTP client. The +SMTP client initiates a TCP connection to SMTP server on port 25 (unless overridden +by configuration).

            SMTP is more suitable for a machine permanently +connected to the Internet. To retrieve messages only on demand, which is the +most common requirement on a single-user computer, a mail client must use +POP3 or IMAP4. POP3 is mostly preferred when single-user computers connected +to the Internet only intermittently.

            +
            Symbian platform implementation of SMTP

            SMTP is +a Mail Transfer Agent (MTA) used to transfer emails to a SMTP server which +then forwards them on to a specified destination.

            Sending an email +generally consists of three phases: connect and authorise to server, send +emails and quit.

            The SMTP component is responsible for sending email +messages composed and stored in the Message Server’s Message Store.

              +

            1. The SMTP client initiates +a connection with the SMTP server. Depending on the user’s email settings, +this may have been initiated over a secure SSL/TLS socket on port 465.

              2. +

            2. Depending on how the +user has configured the email settings and the capabilities of the SMTP server, +SMTP authentication may also be required.

              3. +

            3. Mail From and +recipient To are sent.

              4. +

            4. The message header fields +for the email message stored in the Message Store are then transmitted, each +one separated by a CRLF.

              5. +

            5. The last CRLF is sent +to indicate the end of the RFC 2822 header.

              6. +

            6. The message body and +encoded attachments are sent.

              The encoding format (uuencode or MIME, +character sets) depends on the user’s email settings and locale.

              7. +

            7. Finally, the body is +terminated by a CRLF.

              CRLF sequence, and the email is queued by the +SMTP server for sending.

              8. +
            +
            SMTP example

            For more details on implementing the +IMAP4 MTM functions, see example +code.

            +             +SMTP MTM +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2E3A91F9-5538-5E23-8D23-CE97B677A668_d0e172781_href.jpg Binary file Symbian3/SDK/Source/GUID-2E3A91F9-5538-5E23-8D23-CE97B677A668_d0e172781_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2E3A91F9-5538-5E23-8D23-CE97B677A668_d0e179376_href.jpg Binary file Symbian3/SDK/Source/GUID-2E3A91F9-5538-5E23-8D23-CE97B677A668_d0e179376_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2E986A81-F094-4F1D-9ECB-6A325CFA5BB4.dita --- a/Symbian3/SDK/Source/GUID-2E986A81-F094-4F1D-9ECB-6A325CFA5BB4.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-2E986A81-F094-4F1D-9ECB-6A325CFA5BB4.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,47 +1,47 @@ - - - - - -Plug-ins -

            Plug-ins connect to the system using the EPOC Component Object Model -(ECom). ECom is based on client/server architecture and provides services -to instantiate, resolve, and destroy instances of plug-ins at run time. For -more information, see the ECom -Architecture.

            -ECom framework -

            A hostile or malfunctioning plug-in may cause crashes or security leaks, -even on otherwise well-tested applications. The platform -security architecture protects the processes by verifying that the -plug-in has equal or greater set of capabilities than the process in which -it is loaded. For more information, see the ECom -and the Platform Security Architecture.

            -

            For examples, see Plug-in -Framework (ECom) Examples.

            -
            Communication -plug-ins -

            It is possible to use plug-ins to implement additional functionality -to serial, socket, and messaging frameworks. These plug-ins are especially -important for security because they deal with communication.

            -
              -

            • For serial communication there are serial protocol modules -(CSY modules ), which are loaded by the Serial Comms Server. For more information -on serial communication, see Serial -Communications Server.

              • -

            • For socket-based communication there are protocol modules -(PRT), which are loaded by the Socket Server. For more information on socket-based -communication, see Socket -Server.

              • -

            • For messaging there are Message Type Modules (MTM), which -include both client and server components. MTMs are a set of dlls -rather than a single dll. For more information, see Message Type Module.

              -
              • -
            -
            + + + + + +Plug-ins +

            Plug-ins connect to the system using the EPOC Component Object Model +(ECom). ECom is based on client/server architecture and provides services +to instantiate, resolve, and destroy instances of plug-ins at run time. For +more information, see the ECom +Architecture.

            +ECom framework +

            A hostile or malfunctioning plug-in may cause crashes or security leaks, +even on otherwise well-tested applications. The platform +security architecture protects the processes by verifying that the +plug-in has equal or greater set of capabilities than the process in which +it is loaded. For more information, see the ECom +and the Platform Security Architecture.

            +

            For examples, see Plug-in +Framework (ECom) Examples.

            +
            Communication +plug-ins +

            It is possible to use plug-ins to implement additional functionality +to serial, socket, and messaging frameworks. These plug-ins are especially +important for security because they deal with communication.

            +
              +

            • For serial communication there are serial protocol modules +(CSY modules ), which are loaded by the Serial Comms Server. For more information +on serial communication, see Serial +Communications Server.

              • +

            • For socket-based communication there are protocol modules +(PRT), which are loaded by the Socket Server. For more information on socket-based +communication, see Socket +Server.

              • +

            • For messaging there are Message Type Modules (MTM), which +include both client and server components. MTMs are a set of dlls +rather than a single dll. For more information, see Message Type Module.

              +
              • +
            +
             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2ED8BB5F-27CA-5DD3-BA0F-5773AE14A8CC_d0e202413_href.png Binary file Symbian3/SDK/Source/GUID-2ED8BB5F-27CA-5DD3-BA0F-5773AE14A8CC_d0e202413_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2ED8BB5F-27CA-5DD3-BA0F-5773AE14A8CC_d0e207421_href.png Binary file Symbian3/SDK/Source/GUID-2ED8BB5F-27CA-5DD3-BA0F-5773AE14A8CC_d0e207421_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2EF123C9-62A2-52FF-9792-66EF41F37452_d0e393415_href.png Binary file Symbian3/SDK/Source/GUID-2EF123C9-62A2-52FF-9792-66EF41F37452_d0e393415_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2EF123C9-62A2-52FF-9792-66EF41F37452_d0e393577_href.png Binary file Symbian3/SDK/Source/GUID-2EF123C9-62A2-52FF-9792-66EF41F37452_d0e393577_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2F0008EB-715C-50EC-87AD-C78619F44858_d0e221141_href.png Binary file Symbian3/SDK/Source/GUID-2F0008EB-715C-50EC-87AD-C78619F44858_d0e221141_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2F0008EB-715C-50EC-87AD-C78619F44858_d0e224878_href.png Binary file Symbian3/SDK/Source/GUID-2F0008EB-715C-50EC-87AD-C78619F44858_d0e224878_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2F264A2A-FA7A-4718-A6B6-9A764C1D1E0E.dita --- a/Symbian3/SDK/Source/GUID-2F264A2A-FA7A-4718-A6B6-9A764C1D1E0E.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,45 +0,0 @@ - - - - - -Labeling -the Selection key -

            In the portrait mode, the Selection key takes a textual label to indicate -the current functionality. The Selection key always functions identically -in both portrait and landscape orientation. In most cases, the label on the -middle softkey is the first item in the Options menu (for example,Open, Select, Play, -and so on). The Selection key functions normally in all landscape modes, but -it cannot be labelled in the landscape orientation owing to space restrictions. -Since the middle softkey label is not visible in landscape (nor in Touch UI), -it is important that the function assigned to the Selection key is as instinctive -as possible. If there is no obvious, intuitive function available in a given -situation, the context sensitive Options menu can be used.

            -

            When the Selection key opens the context sensitive Options menu -or performs the same function as the left softkey, the corresponding icons -are used. When there is an item in focus that is in itself a function (for -example, Download images or a button in a player), the middle softkey -is labelled Select. Otherwise, the middle softkey is labelled with -an appropriate text. The purpose of using a special icon for the Selection -key when it repeats the left softkey is to avoid repeating the text label -and also to promote the use of the Selection key as a quick and convenient -way of performing some typical tasks.

            -

            In case the Selection key does not perform its primary function in the -situation (and the related first Options menu item is not available) -the middle softkey label is not displayed, for example, in case of a locked -setting item, the label Change is not shown.

            - -Labeling the Selection key in the control pane: left and right softkeys -have textual labels, the Selection key has either a textual label or one of -two icons: the context sensitive Options menu icon (bottom left) or the Select -icon (bottom right). - - - -             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2F42DC8F-E489-5EA4-8413-784D34965497-GENID-1-8-1-3-1-1-7-1-6-1.dita --- a/Symbian3/SDK/Source/GUID-2F42DC8F-E489-5EA4-8413-784D34965497-GENID-1-8-1-3-1-1-7-1-6-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,12 +0,0 @@ - - - - - -UI Control Framework concepts

            The Framework is a series of related Object-Oriented base classes with clearly defined responsibilities. UI system and application developers use the framework classes, in particular those representing 'the environment', 'the user interface' and 'the generic control' as the basis for creating concrete classes with the same underlying relationships. Framework functions, virtual functions in the base classes, maintain the relationships and enable the concrete classes to receive messages (events).

            This page describes the key concepts behind the UI Control Framework.

            • to simplify access to the Window Server

            • to set a recommended framework for all UI libraries

            • to do this without imposing a particular user interface look

            Simplified access to the Window Server

            The Window Server provides a low-level API to the system’s user interface devices — screens, keyboard and pointer. The API is extensive and complex. The UI Control Framework hides much of this complexity and provides a simplified API that meets the requirements of most applications.

            Any client of the Window Server must create a window server session and an active scheduler framework to handle asynchronous inter-process communication (IPC). Events received from the Window Server must be converted into functions calls and passed to the appropriate controls. These complex tasks, which are similar for most applications, are performed by the Control Environment.

            Recommended framework for UI libraries

            In simplifying the Window Server API, the control framework makes a number of design decisions that are optimised for most applications.

            One is the framework's concept of controls. By allowing controls to represent both whole windows (window owning) and parts of windows (non-window owning) the framework makes applications run much more efficiently.

            Another is the prioritising of events. User input events, for instance, are given a higher priority than redraw events.

            A third feature is the support provided for handling key-press events and pointer events. The Window Server passes key events to the foreground application and pointer events to the window containing the point of contact, which maps to a window-owning control. In each case the Framework provides a mechanism for distributing the event to the appropriate control (normally a simple, non-window-owning control) within the application.

            User Interface policy agnostic

            Though the Framework provides a substantial amount of any application it imposes very little in the way of user interface policy and no 'Look and Feel' (LAF). It does, however, provide mechanisms for supporting system-wide LAF and for propagating run-time LAF changes.

            UI policy is provided by the core user interface library, Uikon, and the user interface library provided for a particular UI variant.

            See also

            Window server

            UI Control Framework overview

            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2F42DC8F-E489-5EA4-8413-784D34965497-GENID-1-8-1-6-1-1-4-1-6-1-6-1.dita --- a/Symbian3/SDK/Source/GUID-2F42DC8F-E489-5EA4-8413-784D34965497-GENID-1-8-1-6-1-1-4-1-6-1-6-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,12 +0,0 @@ - - - - - -UI Control Framework concepts

            The Framework is a series of related Object-Oriented base classes with clearly defined responsibilities. UI system and application developers use the framework classes, in particular those representing 'the environment', 'the user interface' and 'the generic control' as the basis for creating concrete classes with the same underlying relationships. Framework functions, virtual functions in the base classes, maintain the relationships and enable the concrete classes to receive messages (events).

            This page describes the key concepts behind the UI Control Framework.

            • to simplify access to the Window Server

            • to set a recommended framework for all UI libraries

            • to do this without imposing a particular user interface look

            Simplified access to the Window Server

            The Window Server provides a low-level API to the system’s user interface devices — screens, keyboard and pointer. The API is extensive and complex. The UI Control Framework hides much of this complexity and provides a simplified API that meets the requirements of most applications.

            Any client of the Window Server must create a window server session and an active scheduler framework to handle asynchronous inter-process communication (IPC). Events received from the Window Server must be converted into functions calls and passed to the appropriate controls. These complex tasks, which are similar for most applications, are performed by the Control Environment.

            Recommended framework for UI libraries

            In simplifying the Window Server API, the control framework makes a number of design decisions that are optimised for most applications.

            One is the framework's concept of controls. By allowing controls to represent both whole windows (window owning) and parts of windows (non-window owning) the framework makes applications run much more efficiently.

            Another is the prioritising of events. User input events, for instance, are given a higher priority than redraw events.

            A third feature is the support provided for handling key-press events and pointer events. The Window Server passes key events to the foreground application and pointer events to the window containing the point of contact, which maps to a window-owning control. In each case the Framework provides a mechanism for distributing the event to the appropriate control (normally a simple, non-window-owning control) within the application.

            User Interface policy agnostic

            Though the Framework provides a substantial amount of any application it imposes very little in the way of user interface policy and no 'Look and Feel' (LAF). It does, however, provide mechanisms for supporting system-wide LAF and for propagating run-time LAF changes.

            UI policy is provided by the core user interface library, Uikon, and the user interface library provided for a particular UI variant.

            See also

            Window server

            UI Control Framework overview

            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2F42DC8F-E489-5EA4-8413-784D34965497.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-2F42DC8F-E489-5EA4-8413-784D34965497.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,12 @@ + + + + + +UI Control Framework concepts

            The Framework is a series of related Object-Oriented base classes with clearly defined responsibilities. UI system and application developers use the framework classes, in particular those representing 'the environment', 'the user interface' and 'the generic control' as the basis for creating concrete classes with the same underlying relationships. Framework functions, virtual functions in the base classes, maintain the relationships and enable the concrete classes to receive messages (events).

            This page describes the key concepts behind the UI Control Framework.

            • to simplify access to the Window Server

            • to set a recommended framework for all UI libraries

            • to do this without imposing a particular user interface look

            Simplified access to the Window Server

            The Window Server provides a low-level API to the system’s user interface devices — screens, keyboard and pointer. The API is extensive and complex. The UI Control Framework hides much of this complexity and provides a simplified API that meets the requirements of most applications.

            Any client of the Window Server must create a window server session and an active scheduler framework to handle asynchronous inter-process communication (IPC). Events received from the Window Server must be converted into functions calls and passed to the appropriate controls. These complex tasks, which are similar for most applications, are performed by the Control Environment.

            Recommended framework for UI libraries

            In simplifying the Window Server API, the control framework makes a number of design decisions that are optimised for most applications.

            One is the framework's concept of controls. By allowing controls to represent both whole windows (window owning) and parts of windows (non-window owning) the framework makes applications run much more efficiently.

            Another is the prioritising of events. User input events, for instance, are given a higher priority than redraw events.

            A third feature is the support provided for handling key-press events and pointer events. The Window Server passes key events to the foreground application and pointer events to the window containing the point of contact, which maps to a window-owning control. In each case the Framework provides a mechanism for distributing the event to the appropriate control (normally a simple, non-window-owning control) within the application.

            User Interface policy agnostic

            Though the Framework provides a substantial amount of any application it imposes very little in the way of user interface policy and no 'Look and Feel' (LAF). It does, however, provide mechanisms for supporting system-wide LAF and for propagating run-time LAF changes.

            UI policy is provided by the core user interface library, Uikon, and the user interface library provided for a particular UI variant.

            See also

            Window server

            UI Control Framework overview

            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2F6EF388-CA87-5AAD-A4C5-37FC3CE15331_d0e243046_href.png Binary file Symbian3/SDK/Source/GUID-2F6EF388-CA87-5AAD-A4C5-37FC3CE15331_d0e243046_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2F6EF388-CA87-5AAD-A4C5-37FC3CE15331_d0e246783_href.png Binary file Symbian3/SDK/Source/GUID-2F6EF388-CA87-5AAD-A4C5-37FC3CE15331_d0e246783_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2F8B9FAD-1669-5458-BA24-2E15BB0D2F53_d0e276117_href.png Binary file Symbian3/SDK/Source/GUID-2F8B9FAD-1669-5458-BA24-2E15BB0D2F53_d0e276117_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2F8B9FAD-1669-5458-BA24-2E15BB0D2F53_d0e279803_href.png Binary file Symbian3/SDK/Source/GUID-2F8B9FAD-1669-5458-BA24-2E15BB0D2F53_d0e279803_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2F987147-1435-55F1-B61C-8413C4AD8424.dita --- a/Symbian3/SDK/Source/GUID-2F987147-1435-55F1-B61C-8413C4AD8424.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-2F987147-1435-55F1-B61C-8413C4AD8424.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,28 +1,28 @@ - - - - - -Direct -File Store StructureDescribes the structure of the file used as a Direct File Store. -

            The general structure of a direct file store, from the point of view of -the physical file containing the store, is illustrated below.

            - - - -

            The header is the content of the descriptor returned by the Des() member -function of TCheckedUid; this contains the file store type -and checksum; the length of the data is the size of a TCheckedUid object. -Note that TCheckedUid is not part of the public API.

            -

            The header is followed by the root stream ID. As the value of a stream -ID is also the offset of that stream from the start of the host, this gives -the offset of the root stream.

            -

            The root stream ID is followed by all the streams; the root stream is the -last stream.

            + + + + + +Direct +File Store StructureDescribes the structure of the file used as a Direct File Store. +

            The general structure of a direct file store, from the point of view of +the physical file containing the store, is illustrated below.

            + + + +

            The header is the content of the descriptor returned by the Des() member +function of TCheckedUid; this contains the file store type +and checksum; the length of the data is the size of a TCheckedUid object. +Note that TCheckedUid is not part of the public API.

            +

            The header is followed by the root stream ID. As the value of a stream +ID is also the offset of that stream from the start of the host, this gives +the offset of the root stream.

            +

            The root stream ID is followed by all the streams; the root stream is the +last stream.

             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2FAB8281-569A-52BE-8BC8-A2D378068706.dita --- a/Symbian3/SDK/Source/GUID-2FAB8281-569A-52BE-8BC8-A2D378068706.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-2FAB8281-569A-52BE-8BC8-A2D378068706.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,45 +1,45 @@ - - - - - -Caching -

            In Symbian OS v9.3 and earlier, index entries were stored in a single index -file in a permanent file store and the entire file was loaded into RAM on -start up. In Symbian^3 index entries are stored in an SQL database and only -the most recently used index entries are cached in RAM.

            -

            The following figure shows how a client request is completed using the -cache functionality in the Message Server.

            - - Caching architecture - - -
            Creating and -maintaining free space in memory

            Memory allocation to the cache -is done incrementally, to reduce the Message Server start up time. When the -Message Server starts, only a percentage of the maximum cache size (MsvMaximumCacheSize) -is allocated to cache. The percentage is specified by the MsvInitialCacheCreation parameter. -The next iteration of memory allocation is not initiated until the memory -threshold (set using the MsvCacheThreshold parameter) is -reached. The subsequent memory allocation is always done by a low priority -active object.

            Example

            The memory allocation strategy -is illustrated in the following figures, based on the default values (shown -in the preceding table).

            When Message Server starts, the cache is -created with an initial size of 410KB (40 percent of 1024KB). If 70 percent -of the free space in the cache gets used the server allocates an additional -205KB (20 percent of 1024).

            - -

            Message Server can make two further 205KB allocations which it does -as use reaches 70 percent of the memory already allocated.

            - -

            If more than 70 percent of the first two allocated memory chunks -is used, an additional 20 percent of memory is added to the free space.

            - -
            + + + + + +Caching +

            In Symbian OS v9.3 and earlier, index entries were stored in a single index +file in a permanent file store and the entire file was loaded into RAM on +start up. In Symbian^3 index entries are stored in an SQL database and only +the most recently used index entries are cached in RAM.

            +

            The following figure shows how a client request is completed using the +cache functionality in the Message Server.

            + + Caching architecture + + +
            Creating and +maintaining free space in memory

            Memory allocation to the cache +is done incrementally, to reduce the Message Server start up time. When the +Message Server starts, only a percentage of the maximum cache size (MsvMaximumCacheSize) +is allocated to cache. The percentage is specified by the MsvInitialCacheCreation parameter. +The next iteration of memory allocation is not initiated until the memory +threshold (set using the MsvCacheThreshold parameter) is +reached. The subsequent memory allocation is always done by a low priority +active object.

            Example

            The memory allocation strategy +is illustrated in the following figures, based on the default values (shown +in the preceding table).

            When Message Server starts, the cache is +created with an initial size of 410KB (40 percent of 1024KB). If 70 percent +of the free space in the cache gets used the server allocates an additional +205KB (20 percent of 1024).

            + +

            Message Server can make two further 205KB allocations which it does +as use reaches 70 percent of the memory already allocated.

            + +

            If more than 70 percent of the first two allocated memory chunks +is used, an additional 20 percent of memory is added to the free space.

            + +
            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-2FDD1CAE-0FBF-4CC4-9C16-5AE4F538ED85.dita --- a/Symbian3/SDK/Source/GUID-2FDD1CAE-0FBF-4CC4-9C16-5AE4F538ED85.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,34 +0,0 @@ - - - - - -Rotation -

            Whenever the orientation of UI is changed, all applications rotate 90 or -270 degrees (not only the foreground application). By default, the UI does -not rotate automatically to any other orientation while opening or closing -an application, swapping to another application, or in the case of embedded -applications or seamless task flows. In addition, the UI should not change -its orientation when another view within an application is opened.

            -

            Applications that support only one orientation, and thus trigger automatic -orientation switch, do not change the orientation of other applications. That -is, if the orientation is ’portrait’ before launching a ’landscape-only application’, -it is portrait even after exiting it.

            -

            An exception to this rule is for the applications that are launched from -the landscape application itself (for example, the Go to gallery option -in the Camera application) or embedded within the application (for example, -the embedded Browser within an image editor when downloading content). In -these cases, one orientation should remain throughout the task flow, and the -original orientation should be returned only after exiting the application -that triggered the rotation.

            -

            No queries or notes are recommended to inform or ask the user about rotation.

            - - - -             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-300B4AF5-7F6E-542D-886D-335674EDE8FD_d0e321282_href.png Binary file Symbian3/SDK/Source/GUID-300B4AF5-7F6E-542D-886D-335674EDE8FD_d0e321282_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-300B4AF5-7F6E-542D-886D-335674EDE8FD_d0e327439_href.png Binary file Symbian3/SDK/Source/GUID-300B4AF5-7F6E-542D-886D-335674EDE8FD_d0e327439_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-301488F8-B6D8-569A-B05E-19B740FE4C00.dita --- a/Symbian3/SDK/Source/GUID-301488F8-B6D8-569A-B05E-19B740FE4C00.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-301488F8-B6D8-569A-B05E-19B740FE4C00.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,61 +1,61 @@ - - - - - -Selecting -a Remote Device -

            Thought should be given to the way in which a remote device will be selected -for connection before moving on to begin the actual connection. This document -discusses some of the issues that should be considered.

            -
            Methods for selecting a remote device

            An application -can determine the remote device to which it should talk in several ways, it -may be:

              -

            • hard-wired,

              • -

            • a stored preference (application stores a previously selected device -profile to reuse),

              • -

            • selected by the user, or

              • -

            • determined programmatically.

              • -

            Each of these may be appropriate in different situations. In the -first couple of cases, the address of the remote device is simply retrieved -from storage. Functionality for the third case is provided by theBluetooth -UI .

            The final case, the program itself determining the remote -device, could be adopted for the following reasons:

              -

            • to provide a customised device selection UI to the user

              • -

            • to select a device based on some other criteria, for example, "use -the least busy LAN access point"

              • -

            The next page,Inquiring - About Remote Devices , discusses in detail how to go about this.

            -
            Where Next?

            This tutorial set takes you through -all the steps involved in setting up and communicating over a Bluetooth connection.

              -

            • Selecting a Remote -Device - This document

              • -

            • Inquiring -About Remote Devices

              • -

            • Inquiring -About Services on a Remote Device

              • -

            • Connecting -and Transferring Data to a Remote Device

              • -

            • Using -security on outgoing sockets

              • -
            -
            Where Next?

            This tutorial set takes you through -all the steps involved in setting up and communicating over a Bluetooth connection.

              -

            • Selecting a Remote -Device - This document

              • -

            • Inquiring -About Remote Devices

              • -

            • Inquiring -About Services on a Remote Device

              • -

            • Connecting -and Transferring Data to a Remote Device

              • -

            • Using -security on outgoing sockets

              • -
            + + + + + +Selecting +a Remote Device +

            Thought should be given to the way in which a remote device will be selected +for connection before moving on to begin the actual connection. This document +discusses some of the issues that should be considered.

            +
            Methods for selecting a remote device

            An application +can determine the remote device to which it should talk in several ways, it +may be:

              +

            • hard-wired,

              • +

            • a stored preference (application stores a previously selected device +profile to reuse),

              • +

            • selected by the user, or

              • +

            • determined programmatically.

              • +

            Each of these may be appropriate in different situations. In the +first couple of cases, the address of the remote device is simply retrieved +from storage. Functionality for the third case is provided by theBluetooth +UI .

            The final case, the program itself determining the remote +device, could be adopted for the following reasons:

              +

            • to provide a customised device selection UI to the user

              • +

            • to select a device based on some other criteria, for example, "use +the least busy LAN access point"

              • +

            The next page,Inquiring + About Remote Devices , discusses in detail how to go about this.

            +
            Where Next?

            This tutorial set takes you through +all the steps involved in setting up and communicating over a Bluetooth connection.

              +

            • Selecting a Remote +Device - This document

              • +

            • Inquiring +About Remote Devices

              • +

            • Inquiring +About Services on a Remote Device

              • +

            • Connecting +and Transferring Data to a Remote Device

              • +

            • Using +security on outgoing sockets

              • +
            +
            Where Next?

            This tutorial set takes you through +all the steps involved in setting up and communicating over a Bluetooth connection.

              +

            • Selecting a Remote +Device - This document

              • +

            • Inquiring +About Remote Devices

              • +

            • Inquiring +About Services on a Remote Device

              • +

            • Connecting +and Transferring Data to a Remote Device

              • +

            • Using +security on outgoing sockets

              • +
             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-301E5FAA-A1C3-4FD7-9D84-DAA61C66981B.dita --- a/Symbian3/SDK/Source/GUID-301E5FAA-A1C3-4FD7-9D84-DAA61C66981B.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-301E5FAA-A1C3-4FD7-9D84-DAA61C66981B.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,278 +1,278 @@ - - - - - -Symbian -C++ Quick StartThis Quick Start is relevant if you want to create Symbian C++ -applications that run on Symbian devices - i.e. "on top" of the Symbian platform. -Typically this will include: professional application and games developers, -professional service companies, hobbyist developers and students. -

            The tutorial shows you how to get the development tools (e.g. IDE) and -set up your development environment. It then shows you how to create a skeleton -application using Carbide.c++ and UI designer, and how to get it up and running -on both the Symbian Emulator and on the device; the whole process -takes just a few minutes!

            -

            Comes with Code: File: HelloSymbianWorld Example Code.zip

            -
            Set -up the development environment

            Assuming your computer meets -the System Requirements then setting up your PC for Symbian -C++ development is as simple as downloading and installing (do so in this -order):

              -

            1. Perl. See the Kits Q&As for notes on the recommended version.

              2. -

            2. Application Developer Toolkit (ADT).

              3. -

            3. Software Developer Kit (SDK) (full installation) -.

              4. -

            For help installing the SDK please refer to the Symbian^1 SDK Installation Guide.

            You can now -create your first application using the Carbide.c++ project wizard, as the -following sections will describe.

            -
            Starting Carbide.c++

            The -Carbide.c++ IDE is installed as part of the free Application Developer Toolkit (ADT) (step 2 in the -section above). It is the only supported/official IDE for Symbian C++ development. -

            Carbide.c++ is launched from the Windows Start button: All -Programs | Symbian Foundation ADT v<ADTVersion> | Carbide.c++ -| Carbide.++ v<CarbideVersion>.

            On start, you will be -prompted to select a workspace directory. The workspace directory contains -any projects you’ve already created in the workspace and their common settings -- such as code-formatting options (you can define multiple workspaces in order -to separate completely different tasks). If this is the first time you've -run Carbide.c++ the workspace will be empty.

            Your Symbian projects -must be on the drive where you installed your SDK. You must also ensure that -the path name of the workspace does not contain non-alphanumeric characters -or spaces. This is because the Symbian toolchain uses command line tools that -cannot read special path names.

            If you installed the SDK to drive C:\, -an example of a correct workspace path is: C:\Symbian\development\.

            - -

            Once Carbide.c++ has started, close the Welcome tab (by clicking -the cross shown circled in red below) to see the default workspace.

            - -
            -
            Creating -a Project

            To launch the Carbide.c++ Create New Project Wizard select: File -| New | Symbian OS C++ Project.

            Choose the GUI Application with -UI Designer application template (see S60 section). This template creates -a runnable GUI application with the UI Designer tool enabled (the UI -Designer allows views to be created "visually" by drag & dropping -standard UI components).

            - -

            The Next page of the wizard is "New Symbian OS C++ Project". -Define the project name - in this case "HelloWorld". Once again, make sure -the project directory is on the same drive as the SDK and does not contain -spaces or other special characters.

            - -

            The Next page of the wizard is "Symbian OS SDKs". Choose -the SDK(s) you want to use for building the project from among those installed -to your PC (You can add more SDKs to your project later on). This should include -a Symbian platform SDK. At time of writing the only -C++ Application Development SDK is the Symbian^1 SDK (Note: this is -a copy of the S60 5th Edition SDK v1.0).

            - -

            By default all build configurations will be selected:

              -

            • Emulator Debug (WINSCW) builds binaries for the Windows-hosted -emulator.

              • -

            • Phone Debug | Release (GCCE) builds binaries for the phone using -the (free) GCCE compiler that was installed with the SDK.

              • -

            • Phone Debug | Release (ARMV5) builds binaries for the phone -using the ARM RealView Compiler (RVCT). RVCT produces code that -is a few percent smaller and faster than the current versions of GCCE supported -for Symbian C++ development, but must be separately licensed from ARM. RVCT -is primarily used by phone manufacturers to build binaries for device ROM.

              • -

            Most developers should simply de-select the ARMV5 options above as -shown (the Emulator is needed by all developers, and GCCE is sufficient for -most third-party development).

            The Next page of the wizard -sets the "Application properties".

            - -

            Keep the default values. The Baseline SDK defines the common -compatibility level of your application. For example, if set to the S60 -5th Edition SDK, the UI designer doesn’t let you add elements that are -only available in later S60 5th Edition, Feature Pack 1+ SDKs and devices. -

            The Next page of the wizard allows you to choose an S60 UI -design. Keep the Empty user interface variant.

            The Next page -of the wizard "Container Name and Type" has default values that are -usually acceptable.

            The Finish button is active -in this page. The next page is optional but for the purposes of this tutorial -you should click Next, rather than Finish.

            - -

            Even though our application will only use one view, it’s usually -better to check "Support View Switching", in order to make the application -easier to extend later on.

            The Next page of the wizard "Basic -Settings" can be used to customize the project with your name and a copyright -notice for every human-readable file. It also allows you to specify the application -unique identifier (UID).

            - -

            The UID (actually the SID, but for the moment we can ignore the distinction) -defines the private area in the file system in which the application can store -its data. Among other things the UID can also be used to programmatically -identify and/or start the application.

            Carbide.c++ generates -a random UID value for you starting with ‘0xE’, which is the range of UIDs -reserved for internal development and testing. If you want to release your -application to the public, you need to get your own unique UID allocated by Symbian Signed. -

            As we do not intend to release our Hello World application to the -public, we’ll simply continue to use the value Carbide.c++ assigned us from -the development range (you can change the UID later on, although you must -be careful to change every instance of it found within your project - see How to change your application's UID).

            Select Finish to -close the wizard and create your application (there is no need to go to the Next (last) -page of the wizard as the default values are always acceptable).

            That's -it, your workspace should look similar to the screenshot below.

            - -
            -
            Targeting -the Emulator

            Normally you'll start by building for the emulator; -you can use the emulator for most of your development work (it is possible -to access the Internet through the emulator, and even simulate GPS).

            Building -for the Emulator

              -

            • First set the active build configuration. You can do this by clicking -the Manage configurations for the current project icon - in the toolbar or by selecting menu: Project | Build Configurations -| Set Active and select Emulator Debug.

              • -
            - -
              -

            • Then build the current configuration using the Build icon in the toolbar or -through the menu: Project | Build Project (You can also select a particular -configuration to build from the Build icon selector).

              • -

            Warning: If you get an error message similar to "WARNING: EPOCROOT -does not specify an existing directory", you did not place your workspace/project -on the same drive as the application development SDK (which is installed by -default to C:\). Delete the project and start again. The diagram shows how -this might appear in Carbide.c++:

            - -

            Running on the Emulator

            If your application built -successfully, click on the Run button - (Ctrl + F11). Upon the first launch of your project, Carbide.c++ -will ask you which executable you want to launch:

            - -
              -

            • If you choose HelloWorld.exe, the emulator will be launched -and your application started automatically. The emulator will close once you -exit your application.

              • -

            • If you choose Emulator the emulator (epoc.exe) will be launched -and you will need to navigate to the application and start it by clicking -on the icon (just as you do when starting an application on a device). We’ll -explain how to find the application shortly.

              • -

            It may sound more difficult to choose the second method, but it has -some advantages. You can leave the emulator running if you are only doing -small edits in your source code – simply close your application in the emulator, -recompile and restart your app through the emulator’s menu. You’ll also see -any error messages that may be shown when you exit the application, because -the emulator will not shut down instantly after you exit Hello World in the -emulator. Those error messages are also visible in Carbide.c++’s console window. -

            When the emulator starts for the first time you might have to wait -for several minutes before it is completely ready for use. Successive starts -will be a lot faster, because Windows caches most of the emulator DLLs.

            - -

            If you decide to launch the emulator and navigate to your application: First, -open the menu through the S60 menu symbol on the bottom left of the -screen. Your own application will be located at the bottom of the Applications folder; -use your mouse to navigate in the emulator’s menus.

            When you launch -your application, the main pane will be empty. As you can see, the example -application the wizard has created already supports a full user interface -and handles input from the left and right softkeys at the bottom of the screen.

            - -

            Debugging on the Emulator

            The Emulator is the -default debug target - you simply click the Debug button -.

            Debugging on the Emulator is not covered further in this -tutorial. See Carbide.c++ User Guide > Debugging projects for extensive -information on debugging using Carbide.c++.

            -
            Targeting the -Device

            The emulator can be used for most of your development work. -However, some situations still require a real device – for example, when you -want to use the camera or the acceleration sensor.

            Tip: You -should test your applications on the phone from time to time, even if it is -fully supported by the emulator.

            When you've finished development, -you'll also want to build a release version; stripping out debug code and -symbol information to make your binaries smaller and more efficient.

            Building -for the Device

            To tell the IDE that you want to build for the device, -change the active build configuration to a phone-release configuration for -GCCE (unless you have the RVCT compiler). As before, use the Manage configurations -for current project toolbar icon ( -) to select the active-build configuration.

            - -

            Next, choose to build the current configuration using the toolbar Build icon (or in the menu: Project -| Build Project).

            This will automatically compile the project -using the GCCE compiler and create an installation package – a file called HelloWorld.sisx in -your project's \HelloWorld\sis\ directory. You now need to -transfer this file to your phone to install it.

            Tip: Use -Carbide.c++ to find the file on your PC. Navigate to the file in the project -view, then right-click on it and select Show in Explorer.

            Don’t -forget to switch back to the Emulator Debug build configuration when -you continue development!

            Installing on the Device

            -You can use the PC Suite that came with your phone to install the application -on your device

              -

            • Ensure that the PC Suite is installed and running

              • -

            • Connect your device to the PC via Bluetooth or USB and add the phone -to the known devices in the PC Suite (if necessary).

              • -

            • Double-click the .sisx file in Windows Explorer or -the Project Explorer window of Carbide.c++.

              • -

            If the PC Suite is not installed on your PC, you can send the file -to the phone via Bluetooth or IrDA (if available):

              -

            • Locate the .sisx file in Windows Explorer

              • -

            • Right-click on it and select Send to | Bluetooth device.

              • -

            You will be prompted to install the application when you open the -message.

            Warning: If you get a Certificate -Error message when you try to install the application, then your -phone has been configured to prevent installation of self-signed sis files. -To change this behavior, go to Settings - Application manager - Installation -settings - Software installation and change the setting from Signed -Only to All. For other errors received upon installation, consult -the installation -error troubleshooting guide.

            Debugging on the Device

            -Debugging on a production phone is covered in the topic: Getting Started with Debugging on the Device.

            -
            Building on -the Command Line

            It is also possible to build your applications -using the command-line based Symbian toolchain. If you've never done so before -you will first need to set up the environment using the tool provided:

              -

            • Select the windows start button and select: Start | All Programs -| Symbian Foundation ADT v1.0 | Carbide.c++ | Configure environment for WINSCW -command line

              • -

            Open a command prompt in your project's /group/ folder (where the -bld.inf project file is located) and do:

            bldmake bldfiles -abld build

            The command bldmake bldfiles creates -a batch file abld.bat based on the component-definition file -(bld.inf) and the project-definition file(s) (.mmp). -The abld build command uses the batch file to build all the -default targets (i.e. for gcce and Emulator).

            You can build just one -target using

            abld build <target>

            For -example, "abld build winscw udeb" builds just the emulator -debug variant.

            You can start the emulator by selecting its executable -in your file system (it will be located at SDK DIRECTORY\epoc32\release\winscw\udeb\epoc.exe). -

            An overview of the commands and the generated outputs is shown below. -There is also extensive documentation on the build process in the Symbian Developer Library: Symbian OS build process.

            - -
            -
            Troubleshooting

            -For the vast majority of users the preceding instructions can be followed -through without issue. If however you have any build issues, then please follow -the following instructions to check that your environment is set up correctly and troubleshoot any problems that may arise.

            -
            Summary

            In -this tutorial you set up your development environment, learned how to create -a skeleton application using Carbide.c++ UI Designer, and how to get -it up and running on both the Symbian platform emulator and on the device. -

            In Going Beyond -Hello: A Tutorial for Symbian C++ Applications we will extend the basic -skeleton to create a small paint application, along the way learning more -about the application frameworks (e.g. defining menus, how to handle touch-screen -events, drawing to the screen etc.).

            -
            Related Info

            -Further reading:

              -

            • Going Beyond -Hello: A Tutorial for Symbian C++ Applications provides a step by step -guide to creating your first "real application", covering the key elements -of the application framework.

              • -

            • Fundamentals of Symbian C++ provides all the essential -information you need to understand Symbian C++.

              • -

            About the Kits:

              -

            • What -are the Kits? explains the ADT and SDK.

              • -

            • Kits Q&As.

              • -

            • Getting Started with Debugging on the Device.

              • -

            • Symbian^1 SDK Release Notes.

              • -

            • Symbian^1 SDK Installation Guide.

              • -
            + + + + + +Symbian +C++ Quick StartThis Quick Start is relevant if you want to create Symbian C++ +applications that run on Symbian devices - i.e. "on top" of the Symbian platform. +Typically this will include: professional application and games developers, +professional service companies, hobbyist developers and students. +

            The tutorial shows you how to get the development tools (e.g. IDE) and +set up your development environment. It then shows you how to create a skeleton +application using Carbide.c++ and UI designer, and how to get it up and running +on both the Symbian Emulator and on the device; the whole process +takes just a few minutes!

            +

            Comes with Code: File: HelloSymbianWorld Example Code.zip

            +
            Set +up the development environment

            Assuming your computer meets +the System Requirements then setting up your PC for Symbian +C++ development is as simple as downloading and installing (do so in this +order):

              +

            1. Perl. See the Kits Q&As for notes on the recommended version.

              2. +

            2. Application Developer Toolkit (ADT).

              3. +

            3. Software Developer Kit (SDK) (full installation) +.

              4. +

            For help installing the SDK please refer to the Symbian^1 SDK Installation Guide.

            You can now +create your first application using the Carbide.c++ project wizard, as the +following sections will describe.

            +
            Starting Carbide.c++

            The +Carbide.c++ IDE is installed as part of the free Application Developer Toolkit (ADT) (step 2 in the +section above). It is the only supported/official IDE for Symbian C++ development. +

            Carbide.c++ is launched from the Windows Start button: All +Programs | Symbian Foundation ADT v<ADTVersion> | Carbide.c++ +| Carbide.++ v<CarbideVersion>.

            On start, you will be +prompted to select a workspace directory. The workspace directory contains +any projects you’ve already created in the workspace and their common settings +- such as code-formatting options (you can define multiple workspaces in order +to separate completely different tasks). If this is the first time you've +run Carbide.c++ the workspace will be empty.

            Your Symbian projects +must be on the drive where you installed your SDK. You must also ensure that +the path name of the workspace does not contain non-alphanumeric characters +or spaces. This is because the Symbian toolchain uses command line tools that +cannot read special path names.

            If you installed the SDK to drive C:\, +an example of a correct workspace path is: C:\Symbian\development\.

            + +

            Once Carbide.c++ has started, close the Welcome tab (by clicking +the cross shown circled in red below) to see the default workspace.

            + +
            +
            Creating +a Project

            To launch the Carbide.c++ Create New Project Wizard select: File +| New | Symbian OS C++ Project.

            Choose the GUI Application with +UI Designer application template (see S60 section). This template creates +a runnable GUI application with the UI Designer tool enabled (the UI +Designer allows views to be created "visually" by drag & dropping +standard UI components).

            + +

            The Next page of the wizard is "New Symbian OS C++ Project". +Define the project name - in this case "HelloWorld". Once again, make sure +the project directory is on the same drive as the SDK and does not contain +spaces or other special characters.

            + +

            The Next page of the wizard is "Symbian OS SDKs". Choose +the SDK(s) you want to use for building the project from among those installed +to your PC (You can add more SDKs to your project later on). This should include +a Symbian platform SDK. At time of writing the only +C++ Application Development SDK is the Symbian^1 SDK (Note: this is +a copy of the S60 5th Edition SDK v1.0).

            + +

            By default all build configurations will be selected:

              +

            • Emulator Debug (WINSCW) builds binaries for the Windows-hosted +emulator.

              • +

            • Phone Debug | Release (GCCE) builds binaries for the phone using +the (free) GCCE compiler that was installed with the SDK.

              • +

            • Phone Debug | Release (ARMV5) builds binaries for the phone +using the ARM RealView Compiler (RVCT). RVCT produces code that +is a few percent smaller and faster than the current versions of GCCE supported +for Symbian C++ development, but must be separately licensed from ARM. RVCT +is primarily used by phone manufacturers to build binaries for device ROM.

              • +

            Most developers should simply de-select the ARMV5 options above as +shown (the Emulator is needed by all developers, and GCCE is sufficient for +most third-party development).

            The Next page of the wizard +sets the "Application properties".

            + +

            Keep the default values. The Baseline SDK defines the common +compatibility level of your application. For example, if set to the S60 +5th Edition SDK, the UI designer doesn’t let you add elements that are +only available in later S60 5th Edition, Feature Pack 1+ SDKs and devices. +

            The Next page of the wizard allows you to choose an S60 UI +design. Keep the Empty user interface variant.

            The Next page +of the wizard "Container Name and Type" has default values that are +usually acceptable.

            The Finish button is active +in this page. The next page is optional but for the purposes of this tutorial +you should click Next, rather than Finish.

            + +

            Even though our application will only use one view, it’s usually +better to check "Support View Switching", in order to make the application +easier to extend later on.

            The Next page of the wizard "Basic +Settings" can be used to customize the project with your name and a copyright +notice for every human-readable file. It also allows you to specify the application +unique identifier (UID).

            + +

            The UID (actually the SID, but for the moment we can ignore the distinction) +defines the private area in the file system in which the application can store +its data. Among other things the UID can also be used to programmatically +identify and/or start the application.

            Carbide.c++ generates +a random UID value for you starting with ‘0xE’, which is the range of UIDs +reserved for internal development and testing. If you want to release your +application to the public, you need to get your own unique UID allocated by Symbian Signed. +

            As we do not intend to release our Hello World application to the +public, we’ll simply continue to use the value Carbide.c++ assigned us from +the development range (you can change the UID later on, although you must +be careful to change every instance of it found within your project - see How to change your application's UID).

            Select Finish to +close the wizard and create your application (there is no need to go to the Next (last) +page of the wizard as the default values are always acceptable).

            That's +it, your workspace should look similar to the screenshot below.

            + +
            +
            Targeting +the Emulator

            Normally you'll start by building for the emulator; +you can use the emulator for most of your development work (it is possible +to access the Internet through the emulator, and even simulate GPS).

            Building +for the Emulator

              +

            • First set the active build configuration. You can do this by clicking +the Manage configurations for the current project icon + in the toolbar or by selecting menu: Project | Build Configurations +| Set Active and select Emulator Debug.

              • +
            + +
              +

            • Then build the current configuration using the Build icon in the toolbar or +through the menu: Project | Build Project (You can also select a particular +configuration to build from the Build icon selector).

              • +

            Warning: If you get an error message similar to "WARNING: EPOCROOT +does not specify an existing directory", you did not place your workspace/project +on the same drive as the application development SDK (which is installed by +default to C:\). Delete the project and start again. The diagram shows how +this might appear in Carbide.c++:

            + +

            Running on the Emulator

            If your application built +successfully, click on the Run button + (Ctrl + F11). Upon the first launch of your project, Carbide.c++ +will ask you which executable you want to launch:

            + +
              +

            • If you choose HelloWorld.exe, the emulator will be launched +and your application started automatically. The emulator will close once you +exit your application.

              • +

            • If you choose Emulator the emulator (epoc.exe) will be launched +and you will need to navigate to the application and start it by clicking +on the icon (just as you do when starting an application on a device). We’ll +explain how to find the application shortly.

              • +

            It may sound more difficult to choose the second method, but it has +some advantages. You can leave the emulator running if you are only doing +small edits in your source code – simply close your application in the emulator, +recompile and restart your app through the emulator’s menu. You’ll also see +any error messages that may be shown when you exit the application, because +the emulator will not shut down instantly after you exit Hello World in the +emulator. Those error messages are also visible in Carbide.c++’s console window. +

            When the emulator starts for the first time you might have to wait +for several minutes before it is completely ready for use. Successive starts +will be a lot faster, because Windows caches most of the emulator DLLs.

            + +

            If you decide to launch the emulator and navigate to your application: First, +open the menu through the S60 menu symbol on the bottom left of the +screen. Your own application will be located at the bottom of the Applications folder; +use your mouse to navigate in the emulator’s menus.

            When you launch +your application, the main pane will be empty. As you can see, the example +application the wizard has created already supports a full user interface +and handles input from the left and right softkeys at the bottom of the screen.

            + +

            Debugging on the Emulator

            The Emulator is the +default debug target - you simply click the Debug button +.

            Debugging on the Emulator is not covered further in this +tutorial. See Carbide.c++ User Guide > Debugging projects for extensive +information on debugging using Carbide.c++.

            +
            Targeting the +Device

            The emulator can be used for most of your development work. +However, some situations still require a real device – for example, when you +want to use the camera or the acceleration sensor.

            Tip: You +should test your applications on the phone from time to time, even if it is +fully supported by the emulator.

            When you've finished development, +you'll also want to build a release version; stripping out debug code and +symbol information to make your binaries smaller and more efficient.

            Building +for the Device

            To tell the IDE that you want to build for the device, +change the active build configuration to a phone-release configuration for +GCCE (unless you have the RVCT compiler). As before, use the Manage configurations +for current project toolbar icon ( +) to select the active-build configuration.

            + +

            Next, choose to build the current configuration using the toolbar Build icon (or in the menu: Project +| Build Project).

            This will automatically compile the project +using the GCCE compiler and create an installation package – a file called HelloWorld.sisx in +your project's \HelloWorld\sis\ directory. You now need to +transfer this file to your phone to install it.

            Tip: Use +Carbide.c++ to find the file on your PC. Navigate to the file in the project +view, then right-click on it and select Show in Explorer.

            Don’t +forget to switch back to the Emulator Debug build configuration when +you continue development!

            Installing on the Device

            +You can use the PC Suite that came with your phone to install the application +on your device

              +

            • Ensure that the PC Suite is installed and running

              • +

            • Connect your device to the PC via Bluetooth or USB and add the phone +to the known devices in the PC Suite (if necessary).

              • +

            • Double-click the .sisx file in Windows Explorer or +the Project Explorer window of Carbide.c++.

              • +

            If the PC Suite is not installed on your PC, you can send the file +to the phone via Bluetooth or IrDA (if available):

              +

            • Locate the .sisx file in Windows Explorer

              • +

            • Right-click on it and select Send to | Bluetooth device.

              • +

            You will be prompted to install the application when you open the +message.

            Warning: If you get a Certificate +Error message when you try to install the application, then your +phone has been configured to prevent installation of self-signed sis files. +To change this behavior, go to Settings - Application manager - Installation +settings - Software installation and change the setting from Signed +Only to All. For other errors received upon installation, consult +the installation +error troubleshooting guide.

            Debugging on the Device

            +Debugging on a production phone is covered in the topic: Getting Started with Debugging on the Device.

            +
            Building on +the Command Line

            It is also possible to build your applications +using the command-line based Symbian toolchain. If you've never done so before +you will first need to set up the environment using the tool provided:

              +

            • Select the windows start button and select: Start | All Programs +| Symbian Foundation ADT v1.0 | Carbide.c++ | Configure environment for WINSCW +command line

              • +

            Open a command prompt in your project's /group/ folder (where the +bld.inf project file is located) and do:

            bldmake bldfiles +abld build

            The command bldmake bldfiles creates +a batch file abld.bat based on the component-definition file +(bld.inf) and the project-definition file(s) (.mmp). +The abld build command uses the batch file to build all the +default targets (i.e. for gcce and Emulator).

            You can build just one +target using

            abld build <target>

            For +example, "abld build winscw udeb" builds just the emulator +debug variant.

            You can start the emulator by selecting its executable +in your file system (it will be located at SDK DIRECTORY\epoc32\release\winscw\udeb\epoc.exe). +

            An overview of the commands and the generated outputs is shown below. +There is also extensive documentation on the build process in the Symbian Developer Library: Symbian OS build process.

            + +
            +
            Troubleshooting

            +For the vast majority of users the preceding instructions can be followed +through without issue. If however you have any build issues, then please follow +the following instructions to check that your environment is set up correctly and troubleshoot any problems that may arise.

            +
            Summary

            In +this tutorial you set up your development environment, learned how to create +a skeleton application using Carbide.c++ UI Designer, and how to get +it up and running on both the Symbian platform emulator and on the device. +

            In Going Beyond +Hello: A Tutorial for Symbian C++ Applications we will extend the basic +skeleton to create a small paint application, along the way learning more +about the application frameworks (e.g. defining menus, how to handle touch-screen +events, drawing to the screen etc.).

            +
            Related Info

            +Further reading:

              +

            • Going Beyond +Hello: A Tutorial for Symbian C++ Applications provides a step by step +guide to creating your first "real application", covering the key elements +of the application framework.

              • +

            • Fundamentals of Symbian C++ provides all the essential +information you need to understand Symbian C++.

              • +

            About the Kits:

              +

            • What +are the Kits? explains the ADT and SDK.

              • +

            • Kits Q&As.

              • +

            • Getting Started with Debugging on the Device.

              • +

            • Symbian^1 SDK Release Notes.

              • +

            • Symbian^1 SDK Installation Guide.

              • +
             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-30201A05-C6CE-5D34-9BDF-CDA4EE44878D.dita --- a/Symbian3/SDK/Source/GUID-30201A05-C6CE-5D34-9BDF-CDA4EE44878D.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-30201A05-C6CE-5D34-9BDF-CDA4EE44878D.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,59 +1,59 @@ - - - - - -ECom -Architecture -

            In C++, the existence of abstract base classes and virtual functions allows -the programs to call, or access interfaces without knowing the actual implementation. -This mechanism gives a flexibility of writing the implementation independent -of the interface. The implementations are known as Plug-ins.

            -

            When an application wishes to use a plug-in, an object is to be instantiated -to perform the required processing. The object specifics are not known until -run-time. The general characteristics of the processing are known, and these -are presented as an interface API.

            -

            In early versions of Symbian platform, implementations were provided by polymorphic interface DLLs. -All the frameworks within the Symbian platform that needed to use plug-ins -had to provide own mechanisms for the clients to discover and instantiate -the implementations. The above method resulted in duplication of functionality.

            -

            The Plug-in (ECom) Framework introduces a generic framework that provides -a single mechanism to:

            -
              -

            • Register and discover -interface implementations

              • -

            • Select an appropriate -implementation

              • -

            • Provide version control -for plug-ins

              • -
            -
            Essentials of a Plug-In System

            A client wishes -to access an object to perform some processing. The specifics of this object -are not known until run-time. The general characteristics of the processing -are known, and are defined in an interface, but several variants of required -processing could exist, which are provided by implementations that support -the interface.

            There are four clearly-defined roles in such a system.

              -

            • The Client that -wishes to access services.

              • -

            • The Interface API that -defines how to request services.

              • -

            • The Interface Implementation that -provides the required processing.

              • -

            • The Framework that -provides the clients with the required access to the implementations.

              • -

            The relationships can be represented as follows:

            - Plug-in relationships - -

            The instantiation mechanism forms the backbone of such a system, -and is responsible for providing the services that identify, and load the -correct interface implementation at run-time. ECom is such a framework.

            We'll -now look at the system from the perspectives in turn of each of the interface -client, interface implementation, and interface definition, before summarising -the functions of the ECom.

            + + + + + +ECom +Architecture +

            In C++, the existence of abstract base classes and virtual functions allows +the programs to call, or access interfaces without knowing the actual implementation. +This mechanism gives a flexibility of writing the implementation independent +of the interface. The implementations are known as Plug-ins.

            +

            When an application wishes to use a plug-in, an object is to be instantiated +to perform the required processing. The object specifics are not known until +run-time. The general characteristics of the processing are known, and these +are presented as an interface API.

            +

            In early versions of Symbian platform, implementations were provided by polymorphic interface DLLs. +All the frameworks within the Symbian platform that needed to use plug-ins +had to provide own mechanisms for the clients to discover and instantiate +the implementations. The above method resulted in duplication of functionality.

            +

            The Plug-in (ECom) Framework introduces a generic framework that provides +a single mechanism to:

            +
              +

            • Register and discover +interface implementations

              • +

            • Select an appropriate +implementation

              • +

            • Provide version control +for plug-ins

              • +
            +
            Essentials of a Plug-In System

            A client wishes +to access an object to perform some processing. The specifics of this object +are not known until run-time. The general characteristics of the processing +are known, and are defined in an interface, but several variants of required +processing could exist, which are provided by implementations that support +the interface.

            There are four clearly-defined roles in such a system.

              +

            • The Client that +wishes to access services.

              • +

            • The Interface API that +defines how to request services.

              • +

            • The Interface Implementation that +provides the required processing.

              • +

            • The Framework that +provides the clients with the required access to the implementations.

              • +

            The relationships can be represented as follows:

            + Plug-in relationships + +

            The instantiation mechanism forms the backbone of such a system, +and is responsible for providing the services that identify, and load the +correct interface implementation at run-time. ECom is such a framework.

            We'll +now look at the system from the perspectives in turn of each of the interface +client, interface implementation, and interface definition, before summarising +the functions of the ECom.

            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-30382EFD-90D5-570C-A6CD-19D34360F329.dita --- a/Symbian3/SDK/Source/GUID-30382EFD-90D5-570C-A6CD-19D34360F329.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-30382EFD-90D5-570C-A6CD-19D34360F329.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,50 +1,50 @@ - - - - - -GraphicsShell: -drawing and zoomingA TechView application that demonstrates drawing points, lines -and shapes, and zooming a bitmap and text. -
            Download

            Click on the following link to download -the example: GraphicsShell.zip

            Download some additional files -required by the example: CommonGraphicsExampleFiles

            Click: browse to view the example code.

            View the additional -files: browse.
            -
            Description

            GraphicsShell provides -an application shell, and two concrete controls.

            CGraphicExampleControl is -a control class, derived from CCoeControl, which links the -app shell to the particular controls.

            CDrawControl illustrates -the drawing of shapes in a window. The code draws points, lines and shapes; -this exercises a variety of drawing functions provided by the window graphics -context such as MoveTo(), DrawLineTo(), DrawArc() etc.

            CZoomControl illustrates -the use of zooming.

            -
            Class Summary

            TPoint

            TRectTSize

            CWindowGc

            TRgb

            CFont

            TFontSpec

            CWindowGc

            TZoomFactor

            MGraphicsDeviceMap

            CFbsBitmap

            -
            Build

            The source code for this example -application can be found in the directory:

            examples\Graphics\GraphicsShell

            This -source code may be in the directory in which you installed the Symbian platform, -or it may be in the src\common\developerlibrary\ directory. -The directory includes the two project files needed for building the example: bld.inf and -the .mmp file.

            The -Symbian build process describes how to build this application. For -the emulator, an application called GraphicsShell.exe is -created in epoc32\release\winscw\<udeb or urel>\.

            -
            Usage
              -

            1. Launch the emulator:

              \epoc32\release\winscw\<udeb -or urel>\EPOC.EXE.

              2. -

            2. Click on GRAPHICSSHELL to -run the application. If using the TechView emulator, this will be in -the Extras menu.

              3. -

            3. The controls are listed -on the menu List of Programs. -Press the appropriate menu item to select a specific control.

              4. -

            4. Step through each phase -of the example by pressing the space bar or by tapping on the window drawn -by that example.

              5. -
            + + + + + +GraphicsShell: +drawing and zoomingA TechView application that demonstrates drawing points, lines +and shapes, and zooming a bitmap and text. +
            Download

            Click on the following link to download +the example: GraphicsShell.zip

            Download some additional files +required by the example: CommonGraphicsExampleFiles

            Click: browse to view the example code.

            View the additional +files: browse.
            +
            Description

            GraphicsShell provides +an application shell, and two concrete controls.

            CGraphicExampleControl is +a control class, derived from CCoeControl, which links the +app shell to the particular controls.

            CDrawControl illustrates +the drawing of shapes in a window. The code draws points, lines and shapes; +this exercises a variety of drawing functions provided by the window graphics +context such as MoveTo(), DrawLineTo(), DrawArc() etc.

            CZoomControl illustrates +the use of zooming.

            +
            Class Summary

            TPoint

            TRectTSize

            CWindowGc

            TRgb

            CFont

            TFontSpec

            CWindowGc

            TZoomFactor

            MGraphicsDeviceMap

            CFbsBitmap

            +
            Build

            The source code for this example +application can be found in the directory:

            examples\Graphics\GraphicsShell

            This +source code may be in the directory in which you installed the Symbian platform, +or it may be in the src\common\developerlibrary\ directory. +The directory includes the two project files needed for building the example: bld.inf and +the .mmp file.

            The +Symbian build process describes how to build this application. For +the emulator, an application called GraphicsShell.exe is +created in epoc32\release\winscw\<udeb or urel>\.

            +
            Usage
              +

            1. Launch the emulator:

              \epoc32\release\winscw\<udeb +or urel>\EPOC.EXE.

              2. +

            2. Click on GRAPHICSSHELL to +run the application. If using the TechView emulator, this will be in +the Extras menu.

              3. +

            3. The controls are listed +on the menu List of Programs. +Press the appropriate menu item to select a specific control.

              4. +

            4. Step through each phase +of the example by pressing the space bar or by tapping on the window drawn +by that example.

              5. +
             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-30647807-A0D2-4D96-975A-BF1800749977.dita --- a/Symbian3/SDK/Source/GUID-30647807-A0D2-4D96-975A-BF1800749977.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-30647807-A0D2-4D96-975A-BF1800749977.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,76 +1,76 @@ - - - - - -Configuring -the application’s platform security settings in the emulator -

            You can adjust certain security settings in the emulator. The emulator's -platform security settings are all enabled by default.

            -

            Typical use cases include:

            -
              -

            • Turning platform security diagnostics on or off

              • -

            • Turning platform security enforcement on or off

              • -

            • Disabling a set of capabilities

              • -
            -

            Important implementation considerations include:

            -
              -

            • You need to use the emulator to set platform security settings. -The feature is not available on production mobile devices.

              • -
            -
            Configuring the -settings in the emulator -

            You can enable or disable platform security settings in the emulator -through the Tools > Preferences menu or by editing the epoc.ini file. -The following illustration shows the options you have in the Platform security tab -of the Preferences window.

            -Preferences window in the emulator -

            To set the platform security settings:

            -
              -

            1. In the emulator, -open the Tools > Preferences menu and go to the Platform Security tab.

              -

              Alternatively, open the epoc.ini file which is located -in the ...\Epoc32\Data\ folder on your computer.

              2. -

            2. Modify the -desired settings:

              -
                -

              • To allow platform security to emit a diagnostics message -when a check fails, tick the Enable security debug messages checkbox -in the Platform Security tab.

                To enable this setting in the Epoc.ini file, -include the line PlatSecDiagnostics ON. To disable this setting, -modify the line to PlatSecDiagnostics OFF.

                When -the settings is enabled, the diagnostics messages are logged to epocwind.out in -a Windows temporary directory. The following is an example of a diagnostics -message:

                -153.600 *PlatSec* WARNING - Capability check would have failed - A -Message (function number=0x00000000) from Thread -Screenshot[20000555]0002::screenshot, sent to Server !MsvServer, was checked by -Thread !MsvServer[1000484b]0001::!MsvServer and was found to be missing the -capability: ReadUserData. -
                • -

              • To enable platform security to take action after a check -fails and a diagnostics message is sent, tick the Perform capability checks checkbox -in the Platform Security tab.

                To enable this setting in the Epoc.ini file, -include the line PlatSecEnforcement ON. To disable this setting, -modify the line to PlatSecEnforcement OFF.

                • -

              • To disable a check for specific capabilities, choose the -ones you wish to disable in the Granted capabilities for all applications: list -in the Platform Security tab.

                To disable a check in the Epoc.ini file, -include PlatSecDisabledCaps, followed by the capabilities -to be disabled. For example, PlatSecDisabledCaps ReadUserData+WriteUserData+UserEnvironment.

                -
                • -
              -
              3. -
            -
            -
            Additional information -on platform security settings in the emulator -

            For information on troubleshooting options, see How to troubleshoot Platform Security issues on Forum Nokia.

            -
            + + + + + +Configuring +the application’s platform security settings in the emulator +

            You can adjust certain security settings in the emulator. The emulator's +platform security settings are all enabled by default.

            +

            Typical use cases include:

            +
              +

            • Turning platform security diagnostics on or off

              • +

            • Turning platform security enforcement on or off

              • +

            • Disabling a set of capabilities

              • +
            +

            Important implementation considerations include:

            +
              +

            • You need to use the emulator to set platform security settings. +The feature is not available on production mobile devices.

              • +
            +
            Configuring the +settings in the emulator +

            You can enable or disable platform security settings in the emulator +through the Tools > Preferences menu or by editing the epoc.ini file. +The following illustration shows the options you have in the Platform security tab +of the Preferences window.

            +Preferences window in the emulator +

            To set the platform security settings:

            +
              +

            1. In the emulator, +open the Tools > Preferences menu and go to the Platform Security tab.

              +

              Alternatively, open the epoc.ini file which is located +in the ...\Epoc32\Data\ folder on your computer.

              2. +

            2. Modify the +desired settings:

              +
                +

              • To allow platform security to emit a diagnostics message +when a check fails, tick the Enable security debug messages checkbox +in the Platform Security tab.

                To enable this setting in the Epoc.ini file, +include the line PlatSecDiagnostics ON. To disable this setting, +modify the line to PlatSecDiagnostics OFF.

                When +the settings is enabled, the diagnostics messages are logged to epocwind.out in +a Windows temporary directory. The following is an example of a diagnostics +message:

                +153.600 *PlatSec* WARNING - Capability check would have failed - A +Message (function number=0x00000000) from Thread +Screenshot[20000555]0002::screenshot, sent to Server !MsvServer, was checked by +Thread !MsvServer[1000484b]0001::!MsvServer and was found to be missing the +capability: ReadUserData. +
                • +

              • To enable platform security to take action after a check +fails and a diagnostics message is sent, tick the Perform capability checks checkbox +in the Platform Security tab.

                To enable this setting in the Epoc.ini file, +include the line PlatSecEnforcement ON. To disable this setting, +modify the line to PlatSecEnforcement OFF.

                • +

              • To disable a check for specific capabilities, choose the +ones you wish to disable in the Granted capabilities for all applications: list +in the Platform Security tab.

                To disable a check in the Epoc.ini file, +include PlatSecDisabledCaps, followed by the capabilities +to be disabled. For example, PlatSecDisabledCaps ReadUserData+WriteUserData+UserEnvironment.

                +
                • +
              +
              3. +
            +
            +
            Additional information +on platform security settings in the emulator +

            For information on troubleshooting options, see How to troubleshoot Platform Security issues on Forum Nokia.

            +
             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-30987768-8B0A-5A35-820C-DBB410D2053B_d0e107453_href.png Binary file Symbian3/SDK/Source/GUID-30987768-8B0A-5A35-820C-DBB410D2053B_d0e107453_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-30987768-8B0A-5A35-820C-DBB410D2053B_d0e113991_href.png Binary file Symbian3/SDK/Source/GUID-30987768-8B0A-5A35-820C-DBB410D2053B_d0e113991_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-311BD5B5-46F6-5154-96B7-CB77EB28C1E3.dita --- a/Symbian3/SDK/Source/GUID-311BD5B5-46F6-5154-96B7-CB77EB28C1E3.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-311BD5B5-46F6-5154-96B7-CB77EB28C1E3.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,79 +1,79 @@ - - - - - -Category: -Send -

            Messaging panics from CSendAs

            - - - - -

            1

             -

            Out of range index passed to SetMtmL or SetService

             -             - -

            2

             -

            Internal discrepancy in MTM array

             -             - -

            3

             -

            Asked to create zero-length MTM array

             -             - -

            4

             -

            SetMtmL() called when a message has already been -created

             -             - -

            5

             -

            Asked to create zero-length service array

             -             - -

            6

             -

            MTM not chosen when CreateMessageL called

             -             - -

            7

             -

            Message not saved when AbandonMessage called

             -             - -

            8

             -

            Message not created when SaveMessageL called

             -             - -

            9

             -

            RecipientList, RemoveRecipient, -or AddRecipientL called without message -being saved or created

             -             - -

            10

             -

            SetSubjectL called without message -being saved or created

             -             - -

            11

             -

            SetBodyL or ValidateMessage called -without message being saved or created

             -             - -

            12

             -

            CSendAs active without asynchronous rendering being -called

             -             - -

            13

             -

            CSendAs cancelled without asynchronous rendering -being called

             -             - - + + + + + +Category: +Send +

            Messaging panics from CSendAs

            +
            + + + +

            1

             +

            Out of range index passed to SetMtmL() or SetService()

             +             + +

            2

             +

            Internal discrepancy in MTM array

             +             + +

            3

             +

            Asked to create zero-length MTM array

             +             + +

            4

             +

            SetMtmL() called when a message has already been +created

             +             + +

            5

             +

            Asked to create zero-length service array

             +             + +

            6

             +

            MTM not chosen when CreateMessageL() called

             +             + +

            7

             +

            Message not saved whenAbandonMessage() called

             +             + +

            8

             +

            Message not created when SaveMessageL() called

             +             + +

            9

             +

            RecipientList(), RemoveRecipient(), +or AddRecipientL() called without message being saved or +created

             +             + +

            10

             +

            SetSubjectL() called without message being saved +or created

             +             + +

            11

             +

            SetBodyL() orValidateMessage() called +without message being saved or created

             +             + +

            12

             +

            CSendAs() active without asynchronous rendering +being called

             +             + +

            13

             +

            CSendAs() cancelled without asynchronous rendering +being called

             +             + +
             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-314B1556-5CB5-4BCC-93C0-B22DB849D2D5.dita --- a/Symbian3/SDK/Source/GUID-314B1556-5CB5-4BCC-93C0-B22DB849D2D5.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-314B1556-5CB5-4BCC-93C0-B22DB849D2D5.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,26 +1,28 @@ - - - - - -Universal -indicator pane -

            Universal indicator pane is used for displaying universal status indicators, -that is, status indicators that need to be visible regardless of the current -application. There is room for at least three indicators, although depending -on the resolution, it may be possible to display more than three. The items -are prioritized according to their importance.

            - -Universal indicator pane. Indicators are placed side by side at the -top (above the clock in the image on the right). - - -

            The universal indicator pane is not -accessible to applications.

            + + + + + +Universal +indicator pane +

            Universal indicator pane is used for displaying universal status indicators, +that is, status indicators that need to be visible regardless of the current +application. There is room for at least three indicators, although depending +on the resolution, it may be possible to display more than three. The items +are prioritized according to their importance.

            +

            The universal indicator popup can be opened by tapping the universal +indicator pane.

            + +Universal indicator pane. Indicators are placed side by side at the +top (above the clock in the image on the right). + + +

            The universal indicator pane is not +accessible to applications.

             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-316D7B85-F827-4479-B5EE-81F210614236_d0e10243_href.png Binary file Symbian3/SDK/Source/GUID-316D7B85-F827-4479-B5EE-81F210614236_d0e10243_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-316D7B85-F827-4479-B5EE-81F210614236_d0e11518_href.png Binary file Symbian3/SDK/Source/GUID-316D7B85-F827-4479-B5EE-81F210614236_d0e11518_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-31A28040-6C8E-5C65-A697-04B30B441686-GENID-1-8-1-3-1-1-9-1-4-1-11-1.dita --- a/Symbian3/SDK/Source/GUID-31A28040-6C8E-5C65-A697-04B30B441686-GENID-1-8-1-3-1-1-9-1-4-1-11-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,59 +0,0 @@ - - - - - -FEP -ReferencesThis topic introduces miscellaneous guidelines to write a FEP. -
            Handling the -start of a transaction

            Although applications do not need to be FEP-aware -in order to work with FEPs, a situation can occur in some applications in -which the user interface can be improved by the application making use of -a FEPBASE API to communicate with the FEP above it, if there is one.

            If -no FEP is present, the expected behaviour in some UIs when the user presses -a key is for the application to do two things: firstly, it moves focus to -a previously non-focused text editor control (possibly, although not necessarily, -by launching a dialog), and secondly, it 'seeds' that text editor control -with the character associated with that key. If there is a FEP, by default -(in other words, without the application being FEP-aware) the focus change -would only happen when the FEP outputs text to the application. However, if -the FEP is designed to allow the user to compose a fairly large block of text -to send to the application (as would be likely in a Japanese FEP), it would -be better if the focus change occurred when the user starts composing their -text in the FEP. In order for this to happen, the application needs to be -FEP-aware, albeit in a fairly trivial way. The way the FEP notifies the application -that it is starting a transaction is by calling CCoeEnv ’s -member function ForEachFepObserverCall() (CCoeEnv is -defined in epoc32\include\COEMAIN.H), passing in the -address of the non-member function FepObserverHandleStartOfTransactionL() (defined -in epoc32\include\FEPBASE.H). It is important to note -that this function should only be called as the last C++ statement executed -when handling an event. The reason for this that it may take a considerable -amount of time to return (for example, it may launch a dialog and only return -when the dialog has been exited).

            -
            Text cursors

            If -a non-inline-editing FEP has a composition window into which the user types, -that window should not use a 'real' text cursor (in other words, a cursor -which is set and unset using RWindowGroup ’s SetTextCursor() and CancelTextCursor() member -functions). The reason is that the window server only allows a single text -cursor for the whole system at any one time. If the FEP’s target control is -a text editor, it should use the window server’s text cursor itself, so the -FEP should not use it. To solve this problem, the text cursor in the FEP’s -composition window can be simulated with a sprite. The class CTstInsertionPoint in -TFEP1 provides an example of this.

            -
            Shortcut keys

            As -FEPs get first refusal of all key events, there is a risk that FEPs can intercept -shortcut keys (if the UI supports them) which are intended for the application -to handle. To define a convention for FEP shortcut keys is non-trivial as -different UIs use different modifier keys and have different policies on using -them. Matters are simplified greatly if a product has a dedicated on/off key -for FEPs as this may be used in combination with other keys to carry out different -functions, as well as on its own to turn the FEP on and off. FEP authors should -consult the documentation for their target UI.

            -             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-31A28040-6C8E-5C65-A697-04B30B441686-GENID-1-8-1-6-1-1-4-1-8-1-4-1-11-1.dita --- a/Symbian3/SDK/Source/GUID-31A28040-6C8E-5C65-A697-04B30B441686-GENID-1-8-1-6-1-1-4-1-8-1-4-1-11-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,59 +0,0 @@ - - - - - -FEP -ReferencesThis topic introduces miscellaneous guidelines to write a FEP. -
            Handling the -start of a transaction

            Although applications do not need to be FEP-aware -in order to work with FEPs, a situation can occur in some applications in -which the user interface can be improved by the application making use of -a FEPBASE API to communicate with the FEP above it, if there is one.

            If -no FEP is present, the expected behaviour in some UIs when the user presses -a key is for the application to do two things: firstly, it moves focus to -a previously non-focused text editor control (possibly, although not necessarily, -by launching a dialog), and secondly, it 'seeds' that text editor control -with the character associated with that key. If there is a FEP, by default -(in other words, without the application being FEP-aware) the focus change -would only happen when the FEP outputs text to the application. However, if -the FEP is designed to allow the user to compose a fairly large block of text -to send to the application (as would be likely in a Japanese FEP), it would -be better if the focus change occurred when the user starts composing their -text in the FEP. In order for this to happen, the application needs to be -FEP-aware, albeit in a fairly trivial way. The way the FEP notifies the application -that it is starting a transaction is by calling CCoeEnv ’s -member function ForEachFepObserverCall() (CCoeEnv is -defined in epoc32\include\COEMAIN.H), passing in the -address of the non-member function FepObserverHandleStartOfTransactionL() (defined -in epoc32\include\FEPBASE.H). It is important to note -that this function should only be called as the last C++ statement executed -when handling an event. The reason for this that it may take a considerable -amount of time to return (for example, it may launch a dialog and only return -when the dialog has been exited).

            -
            Text cursors

            If -a non-inline-editing FEP has a composition window into which the user types, -that window should not use a 'real' text cursor (in other words, a cursor -which is set and unset using RWindowGroup ’s SetTextCursor() and CancelTextCursor() member -functions). The reason is that the window server only allows a single text -cursor for the whole system at any one time. If the FEP’s target control is -a text editor, it should use the window server’s text cursor itself, so the -FEP should not use it. To solve this problem, the text cursor in the FEP’s -composition window can be simulated with a sprite. The class CTstInsertionPoint in -TFEP1 provides an example of this.

            -
            Shortcut keys

            As -FEPs get first refusal of all key events, there is a risk that FEPs can intercept -shortcut keys (if the UI supports them) which are intended for the application -to handle. To define a convention for FEP shortcut keys is non-trivial as -different UIs use different modifier keys and have different policies on using -them. Matters are simplified greatly if a product has a dedicated on/off key -for FEPs as this may be used in combination with other keys to carry out different -functions, as well as on its own to turn the FEP on and off. FEP authors should -consult the documentation for their target UI.

            -             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-31A28040-6C8E-5C65-A697-04B30B441686.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-31A28040-6C8E-5C65-A697-04B30B441686.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,59 @@ + + + + + +FEP +ReferencesThis topic introduces miscellaneous guidelines to write a FEP. +
            Handling the +start of a transaction

            Although applications do not need to be FEP-aware +in order to work with FEPs, a situation can occur in some applications in +which the user interface can be improved by the application making use of +a FEPBASE API to communicate with the FEP above it, if there is one.

            If +no FEP is present, the expected behaviour in some UIs when the user presses +a key is for the application to do two things: firstly, it moves focus to +a previously non-focused text editor control (possibly, although not necessarily, +by launching a dialog), and secondly, it 'seeds' that text editor control +with the character associated with that key. If there is a FEP, by default +(in other words, without the application being FEP-aware) the focus change +would only happen when the FEP outputs text to the application. However, if +the FEP is designed to allow the user to compose a fairly large block of text +to send to the application (as would be likely in a Japanese FEP), it would +be better if the focus change occurred when the user starts composing their +text in the FEP. In order for this to happen, the application needs to be +FEP-aware, albeit in a fairly trivial way. The way the FEP notifies the application +that it is starting a transaction is by calling CCoeEnv ’s +member function ForEachFepObserverCall() (CCoeEnv is +defined in epoc32\include\COEMAIN.H), passing in the +address of the non-member function FepObserverHandleStartOfTransactionL() (defined +in epoc32\include\FEPBASE.H). It is important to note +that this function should only be called as the last C++ statement executed +when handling an event. The reason for this that it may take a considerable +amount of time to return (for example, it may launch a dialog and only return +when the dialog has been exited).

            +
            Text cursors

            If +a non-inline-editing FEP has a composition window into which the user types, +that window should not use a 'real' text cursor (in other words, a cursor +which is set and unset using RWindowGroup ’s SetTextCursor() and CancelTextCursor() member +functions). The reason is that the window server only allows a single text +cursor for the whole system at any one time. If the FEP’s target control is +a text editor, it should use the window server’s text cursor itself, so the +FEP should not use it. To solve this problem, the text cursor in the FEP’s +composition window can be simulated with a sprite. The class CTstInsertionPoint in +TFEP1 provides an example of this.

            +
            Shortcut keys

            As +FEPs get first refusal of all key events, there is a risk that FEPs can intercept +shortcut keys (if the UI supports them) which are intended for the application +to handle. To define a convention for FEP shortcut keys is non-trivial as +different UIs use different modifier keys and have different policies on using +them. Matters are simplified greatly if a product has a dedicated on/off key +for FEPs as this may be used in combination with other keys to carry out different +functions, as well as on its own to turn the FEP on and off. FEP authors should +consult the documentation for their target UI.

            +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-31A6FA69-418D-5F8D-A0FB-6A99AA8CC4E1_d0e76797_href.png Binary file Symbian3/SDK/Source/GUID-31A6FA69-418D-5F8D-A0FB-6A99AA8CC4E1_d0e76797_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-31A6FA69-418D-5F8D-A0FB-6A99AA8CC4E1_d0e83509_href.png Binary file Symbian3/SDK/Source/GUID-31A6FA69-418D-5F8D-A0FB-6A99AA8CC4E1_d0e83509_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-322A932E-5DC8-5CBB-BD3C-02F5CEDB060E.dita --- a/Symbian3/SDK/Source/GUID-322A932E-5DC8-5CBB-BD3C-02F5CEDB060E.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-322A932E-5DC8-5CBB-BD3C-02F5CEDB060E.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,584 +1,584 @@ - - - - - -Secure -Simple Pairing (SSP)Describes SSP. -
              -

            • Introduction

              • -

            • Overview

              • -

            • Symbian support for SSP

              • -

            • Implementing SSP notifiers

              • -

            • Using the Out of Band API

              • -

            • Using the dedicated bonding API

              • -
            -
            Introduction

            Secure -Simple Pairing, introduced into Bluetooth v2.1, simplifies the user experience -when pairing Bluetooth devices.

            This document describes the Symbian -platform implementation of SSP. It describes the tasks that must be performed -by UI creators to implement SSP and it describes how application developers -can use Symbian APIs to pair with Bluetooth enabled devices using SSP.

            Scope

            This document is intended for Symbian partners and developers -implementing SSP on Symbian platform. It assumes that you are familiar with -Bluetooth and with developing on Symbian platform.

            Purpose of SSP

            SSP was introduced to simplify the user experience -when pairing Bluetooth devices. Specifically:

              -

            • there is no need for -the user to think of a number

              • -

            • the authentication process -may differ for different devices and different services

              • -

            • all data transfer is -encrypted

              • -
            -
            Overview

            The pairing model

            Pre-SSP pairing is achieved by the user(s) -entering a personal identification number (PIN) on one or both devices. Devices -with no keypads, such as headsets, have their PINs (typically "0000" or "1234") -hard-wired. This is now referred to as Legacy Paring.

            Under SSP, devices -specify their authorisation requirements. The user may have to:

              -

            • press a button in response -to a simple yes or no query

              • -

            • compare two automatically -generated numbers and select 'yes' if they match or 'no' if they do not

              • -

            • enter a number on one -or both devices

              • -

            • do nothing

              • -

            Once the devices have paired the user may be asked to authorise bonding. -Bonded devices can subsequently pair with no user interaction.

            Key concepts

            - -
            Authentication
            -

            Verification that a remote device is what it claims to be. Authentication -may be unnecessary for some pairings (see Just Works), may require user intervention -(see Man in the Middle) or may be performed through another channel (see Out -of Band).

            -             - -
            Authorisation
            -

            In legacy pairing a remote device can be authorised after pairing such -that it subsequently connects automatically without user intervention. Authorisation -is on a per-service basis. See bonding.

            -             - -
            Encryption
            -

            Transmission of data between devices after SSP is always encrypted. -Under legacy pairing data transmission is not always encrypted.

            -             - -
            Man In The Middle (MITM) protection
            -

            Authentication explicitly provided by the user before pairing can take -place. Under SSP, devices and services have hard-wired authentication requirements -as follows: MITM required, MITM not required (see Just Works) and MITM desired -(subject to the user interface capabilities of the devices)

            -             - -
            Just Works
            -

            For some pairings there is little risk of a security breach so SSP -provides a mechanism for devices to pair with no explicit user authentication.

            -             - -
            Passkey
            -

            In the context of a Symbian device, which always has both a display -and a keypad, passkey authentication is used when pairing with a remote device -which has a keypad but no display. The Symbian device displays a number which -the user must enter using the keypad on the remote device

            -             - -
            Out Of Band (OOB)
            -

            Out of Band authentication is performed using a non-Bluetooth communication -channel. The data required to open an MITM protected Bluetooth connection -with a remote device is transmitted by other means.

            -             - -
            Bonding
            -

            Two devices may bond after athentication such that they can reconnect -without user intervention. Bonding is achieved on a Symbian device by storing -a link key. Symbian devices attempt to bond by default. The user or the remote -device may specify that the devices do not bond.

            -             - -
            Link key
            -

            When a connection is authenticated a link key is created. The link -key indicates the strength of authentication (legacy, authenticated or unauthenticated). -The link key may be stored by the Symbian device and used to bond (the default -behaviour) or discarded when the connection ends. The link key is not displayed -to the user.

            -             -
            -
            Symbian support -for SSP

            Components

            Most -of the changes are internal and transparent to system creators and developers. -However, some new APIs added to the Bluetooth User Library allow application -developers to use SSP features, and Licensees must implement some SSP specific -notifiers.

            The diagram below shows the interfaces and interface classes -required to implement SSP.

            Dedicated -Bonding

            Dedicated bonding is performed by the Bluetooth Pairing -Server. Applications can use the RBluetoothDedicatedBondingInitiator API -to request bonding with a specified Bluetooth device.

            Out of Band Data

            Out of Band pairing data can be passed to -the Bluetooth Pairing Server. The server can use the supplied data to pair -with the specified device. Applications can also use the RBluetoothOobData API -to retrieve OOB data for the local device to be passed to remote devices.

            Numeric Comparison Notifier

            The Bluetooth sub-system requires -a Numeric Comparison Notifier to be provided by the UI. The notifier must -handle TBTNumericComparisonParams and return a boolean -value which indicates the user's decision.

            Passkey Entry Notifier

            The Bluetooth sub-system requires -a Passkey Entry Notifier to be provided by the UI. The notifier must handle TBTPasskeyDisplayParams and TBTPasskeyDisplayUpdateParams.

            Data -Types

            SSP specific data is stored and manipulated using the following -types (significant functions and fields shown only). These types are used -in various device and service related APIs. They are defined in bt_sock.h and btdevice.h.

            #include <bt_sock.h>

            -enum TBluetoothMitmProtection - { - EMitmNotRequired = 0x0, // No Man-in-the-Middle authentication is not required. - EMitmDesired = 0x1, // Man-in-the-Middle authentication should be used where possible. - EMitmRequired = 0x2 // Man-in-the-Middle authentication is required. - }; -

            TBTAccessRequirements

            -class TBTAccessRequirements - { -public: - ... - IMPORT_C void SetAuthentication( TBluetoothMitmProtection aPreference ); - IMPORT_C TBluetoothMitmProtection MitmProtection() const; - ... - - -private: - enum TBTServiceSecuritySettings - { - EAuthenticate = 0x01, - EAuthorise = 0x02, - EEncrypt = 0x04, - EDenied = 0x08, - EMitm = 0x30, // 2 bit field for MITM - }; - - enum TBTAccessRequirementsMitmProtection - { - EAccessRequirementsMitmUndefined = 0x00, - EAccessRequirementsMitmNotRequired = 0x10, - EAccessRequirementsMitmDesired = 0x20, - EAccessRequirementsMitmRequired = 0x30 - }; - };

            TBTServiceSecurity

            -class TBTServiceSecurity - { -public: - ... - IMPORT_C void SetAuthentication( TBluetoothMitmProtection aPreference ); - IMPORT_C TBool AuthenticationRequired() const; - IMPORT_C TBluetoothMitmProtection MitmProtection() const; - ... - -private: - TBTAccessRequirements iSecurityRequirements; // Whether the service requires authentication, authorisation, encryption or min passkey len. - }; - -typedef TPckgBuf<TBTServiceSecurity> TBTServiceSecurityPckg; // Package definition for securty settings -

            #include <btdevice.h>

            TBTDeviceSecurity

            -class TBTDeviceSecurity - { -public: - - // Enumeration to provide select MITM protection required. - - enum TMitmRequired - { - EMitmUnspecified, // No specific MITM protection requirements - EMitmRequired // Require the link is MITM protected - }; - -public: - - ... - IMPORT_C void SetNoAuthenticate(TBool aDecision); - IMPORT_C void SetMitmRequirements(TMitmRequired aDecision); - ... - IMPORT_C TBool NoAuthenticate() const; - IMPORT_C TMitmRequired MitmRequirements() const; - ... - -public: - // Enumeration to assist in parsing of security settings. - enum TBTDeviceSecuritySettings - { - ENoAuthenticate = 0x01, // Don't authenticate the link @deprecated - ENoAuthorise = 0x02, // Don't authorise the connection - EEncrypt = 0x04, // Encrypt the link - EBanned = 0x08, // Don't connect to the device - EMitmProtectionRequired = 0x10, // Require the link is MITM protected - }; - }; -
            -
            Implementing -SSP notifiers

            Introdution

            The -Bluetooth sub-system has no user interface. It uses the Symbian notifier -framework for user interaction when pairing. The UI system must provide -a notifier, in plug-in form, for each user interaction required by SSP. The -notifier must receive data in a specified format from the Bluetooth sub-system, -display appropriate controls in a dialog on the screen, respond to the user's -input and send data back to the Bluetooth sub-system in a specified format.

            This -document assumes that you already have Bluetooth notifiers in your system. -It describes the key aspects of adding notifiers for SSP. The structures, -types and constants described below are defined in BTExtNotifiers.h. -You can add notifiers to an existing plug-in or create a new plug-in.

            Notifiers -are typically implemented as sleeping dialogs. A sleeping dialog has its resources -allocated when its application (in this case the Uikon Server) is started. -A sleeping dialog can therefore be displayed (roused) safely under low memory -conditions.

            Notes:

              -

            • This document does not -describe how to implement an ECOM plug-in or a sleeping dialog.

              • -

            • Customisation Kit Licensees -can find an example notifier implementation here: sf/mw/classicui/commonuisupport/uikon/examples/notifier1/

              • -

            Numeric -Comparison Notifier

            A numeric comparison notifier is required -for SSP Man in the Middle (MITM) authentication when the remote device is -capable of displaying a number to the the user and accepting a yes or no response -from the user. The notifier must display an automatically generated number -and invite the user to confirm (yes or no) that the number is the same as -the number displayed on the remote device. The notifier must return the user's -response.

            The Bluetooth Security Manager uses the following code to -ask the notifier framework to display the Numeric Comparison Notifier

            - -// defined in header file(s) - -TBTDevAddr iDevAddr ; -RNotifier iNotifier ; -TUint32 iNumericValue ; -TBool iInternallyInitiated ; -TBTNumericComparisonParamsPckg iNumericComparisonParamsPckg ; -TPckgBuf<TBool> iResultPckg ; -// - -void CBTNumericComparator::DoRequest() - { - // Start the RNotifier plugin that deals with authorisation. - - ... - - TBTDeviceName deviceName = KNullDesC ; - - iNumericComparisonParamsPckg = TBTNumericComparisonParams( iDevAddr, - deviceName, - iNumericValue, - TBTNumericComparisonParams::ERemoteCanConfirm, - iInternallyInitiated); - - iNotifier.StartNotifierAndGetResponse( iStatus, - KBTNumericComparisonNotifierUid, - iNumericComparisonParamsPckg, - iResultPckg); - SetActive(); - } -

            From the code above you can see that the Numeric Comparision -Notifier is identified by the UIDKBTNumericComparisonNotifierUid and -that it must handle data in TBTNumericComparisonParams (which -is packaged into TBTNumericComparisonParamsPckg for inter-process -transfer).

            The code fragment below shows how to extract the numeric -comparison data within a notifier.

            NOTE: You will need to implement -all of the virtual functions in MEikSrvNotifierBase2.

            -class CNumericComparisonNotifier : public CEikDialog, public MEikSrvNotifierBase2 - { -public: - - ... - - // from MEikSrvNotifierBase2 - void StartL ( const TDesC8& aBuffer, TInt aReplySlot, const RMessagePtr2& aMessage ) ; - - ... - - void Complete( TBool aDecision, TInt aReason ) ; - -private: - TInt iRepySlot ; - TNotifierInfo iInfo ; - RMessage2 iMessage ; - TBTNumeriComparisonParamsPckg iNumericComparisonParamsPckg ; - TBTDevAddr iAddr ; - TBTDeviceName iName ; - TUint32 iNumericalValue ; - - } ; - - - -//-------------------------------- - -... - -void CNumericComparisionNotifier::StartL( const TDesC8& aBuffer, TInt aReplySlot, const RMessagePtr2& aMessage ) - { - - iMessage = RMessage2( aMessage ) ; // keep a copy ofthe message so that it can be completed later. - iReplySlot = aReplySlot ; // copy the reply slot too - - // Extract the comparison parameters from the buffer - - iNumericComparisonParamsPckg.Copy( aBuffer ) ; - - iAddr = iNumericComparisonParamsPckg().DeviceAddress() ; - iName = iNumericComparisonParamsPckg().DeviceName() ; - iNumericalValue = iNumericComparisonParamsPckg().NumericalValue() ; - - ... - - RouseSleepingDialog() ; - - } - -

            Your dialog must display iNumericalValue and -ask the user if the number displayed is the same as the number displayed on -the other Bluetooth device. The user must be able to select 'Yes' or 'No'.

            The StartL() function -above must return quickly so it must not wait for the user's response. Your -notifier must complete the message (iMessage) as shown below -when the user enters a response.

            -void CNumericComparisionNotifier::Complete( TBool aDecision, TInt aReason ) - { - if ( aReason == KErrNone ) - { - TInt err = iMessage.Write( iReplySlot, TPckgC<TBool>( aDecision ) ) ; - iMessage.Complete( err ) ; - } - else - { - iMessage.Complete( aReason ) ; - } - } -

            Passkey -Notifier

            A passkey notifier is required for SSP MITM authentication -when the user must type a number on a remote device which has a keypad and -no display. The notifier displays the number that the user must type. In the -code below the notifier also displays a '*' character as the user types each -digit into the remote device.

            The Bluetooth Security Manager uses -the following code to ask the Notifier Framework to display the passkey notifier.

            - -// defined in header file(s) - -TBTDevAddr iDevAddr ; -RNotifier iNotifier ; -TUint32 iNumericValue ; // the passkey number -TBool iInternallyInitiated ; -TBTPasskeyDisplayParamsPckg iPasskeyDisplayParamsPckg ; -TBTDeviceNameUpdateParamsPckg iDeviceNameUpdateParamsPckg; -TBuf8<1> iResultPckg ; - -void CBTPasskeyEntry::DoRequest() - { - // Start the RNotifier plugin that deals with authorisation. - - ... - - TBTDeviceName deviceName ; - - deviceName = KNullDesC ; - - iPasskeyDisplayParamsPckg = TBTPasskeyDisplayParams( iDevAddr, - deviceName, - iNumericValue, - iInternallyInitiated ) ; - - iNotifier.StartNotifierAndGetResponse( iStatus, - KBTPasskeyDisplayNotifierUid, - iPasskeyDisplayParamsPckg, - iResultPckg ) ; - SetActive() ; - - } - -

            From the code above you can see that the Passkey Notifier -is identified by the UIDKBTPasskeyNotifierUid and that it -must handle data in TBTPasskeyDisplayParams (which is packaged -into TBTPasskeyDisplayParamsPckg for inter-process transfer).

            As -the user enters passkey digits into the remote device the Security Manager -also uses RNotifier::UpdateNotifierAndGetResponse() to send TBTPasskeyDisplayUpdateParams (packaged -in TBTPasskeyDisplayUdateParamsPckg) to the notifier. Your -notifier must use this information to reflect the key presses on the remote -device.

            The code fragment below shows how to extract the passkey data -within a notifier.

            NOTE: You will need to implement all of the virtual -functions in MEikSrvNotifierBase2.

            -class CPasskeyNotifier : public CEikDialog, public MEikSrvNotifierBase2 - { -public: - - ... - - // from MEikSrvNotifierBase2 - void StartL( const TDesC8& aBuffer, TInt aReplySlot, const RMessagePtr2& aMessage ) ; - TPtrC8 UpdateL( const TDesC8& aBuffer ) ; // new information - - ... - -private: - TInt iRepySlot ; - TNotifierInfo iInfo ; - RMessage2 iMessage ; - TBTPasskeyDisplayParamsPckg iPasskeyDisplayParamsPckg ; - TBTDevAddr iAddr ; - TBTDeviceName iName ; - TUint32 iNumericalValue ; // the passkey number - - } ; - -//-------------------------------- - -... - -void CPasskeyNotifier::StartL( const TDesC8& aBuffer, TInt aReplySlot, const RMessagePtr2& aMessage ) - { - - iMessage = RMessage2(aMessage); // keep a copy ofthe message so that it can be completed later. - iReplySlot = aReplySlot ; // copy the reply slot too - - // Extract the comparison parameters from the buffer - - iPasskeyDisplayParamsPckg.Copy( aBuffer ) ; - - iAddr = iPasskeyDisplayParamsPckg().DeviceAddress() ; - iName = iPasskeyDisplayParamsPckg().DeviceName() ; - iNumericValue = iPasskeyDisplayParamsPckg().NumericalValue() ; - - - ... - - RouseSleepingDialog() ; // display the passkey - - ... - - } - -void CPasskeyNotifier::UpdateL( const TDesC8& aBuffer ) - { - - // extract the contents of the buffer - - TBTNotifierUpdateParamsPckg2 pckgRaw ; - pckgRaw.Copy( aBuffer.Left( pckgRaw.MaxLength() ) ) ; - - // update the dialog to reflect the keys pressed on the remote device - - if ( pckgRaw().Type() == TBTNotifierUpdateParams2::EPasskeyDisplay ) - { - TBTPasskeyDisplayUpdateParamsPckg pckg ; - pckg.Copy( aBuffer ) ; - HCIPasskeyEntryNotificationType keypressNotification = pckg().KeypressNotification() ; - - switch (keypressNotification) - { - case EPasskeyEntryStarted : - { - break ; - } - case EPasskeyDigitEntered : - { - // display '*' - break ; - } - case EPasskeyDigitDeleted : - { - // remove '*', reposition cursor - break ; - } - case EPasskeyCleared : - { - // clear display, reposition cursor - break ; - } - case EPasskeyEntryCompleted : - { - // hide the dialog - ExitSleepingDialog() ; - break; - } - default : - break ; - } - else if( pckgRaw().Type() == TBTNotifierUpdateParams2::EDeviceName ) - { - // handle name update - } - return KNullDesC8() ; - } - - - -
            -
            Out of Band -(OOB) authentication

            Introduction

            Out -of Band authentication is achieved using a communication method other than -Bluetooth. Once OOB authentication has succeeded an encrypted Bluetooth channel -is opened between the two devices.

            The OOB API, RBluetoothOobData, -allows an application handling OOB authentication to provide pairing information -for a remote device.

            RBluetoothOobData allows -an application handling OOB authentication to retrieve pairing information -for the local device.

            Using -the OOB API

            The OOB data API is provided by the Pairing Server -(part of the Security Manager).

            - -#include <pairing.h> - - RBluetoothPairingServer pairingServer ; - RBluetoothOobData OobData ; - - - // Connect to the Pairing server - - TInt err = pairingServer.connect() ; - - // Paring session - - err = OobData.Open( iPairingServer ) ; - - - // Use the API pass hash and randomizer values to and from the pairing server. - - ... - - - // Tidy up - - OobData.Close() ; - PairingServer.Close() ; - -

            The API has three primary functions:

            RefreshLocalOobData() - -This function causes the Bluetooth controller to generate new hash and randomizer -values for the local device. To retrieve the new values call ReadLocalOobData()

            ReadLocalOobData() - -This function returns the hash and randomizer values that the Bluetooth controller -is currently using.

            ProvideRemoteOobData() - Use -this function to pass OOB data about a remote device to the Bluetooth sub-system. -Three versions of the function are available which take slightly different -parameters. Information provided using one of these functions can be cleared -using ClearRemoteOobData().

            -
            Dedicated bonding

            Introduction

            Dedicated bonding is intended for applications -which bond with a specific Bluetooth device.

            Using the dedicated bonding API

            - -#include <pairing.h> - - RBluetoothPairingServer pairingServer ; - RBluetoothDedicatedBondingInitiator bonder ; - TBTDevAddr addr ; - TRequstStatus status ; - - - // Connect to the Pairing server - - TInt err = pairingServer.connect() ; - - - // Use the Bluetooth address of the remote device bonder.Start( pairingServer, addr, status ) ; - - - // Wait for the request to complete - - User::WaitForRequest(status); - - - // Close the connection with the bonder (Must be closed before bonding with another device) - - bonder.Close(); - - pairingServer.Close() ; - -
            + + + + + +Secure +Simple Pairing (SSP)Describes SSP. +
              +

            • Introduction

              • +

            • Overview

              • +

            • Symbian support for SSP

              • +

            • Implementing SSP notifiers

              • +

            • Using the Out of Band API

              • +

            • Using the dedicated bonding API

              • +
            +
            Introduction

            Secure +Simple Pairing, introduced into Bluetooth v2.1, simplifies the user experience +when pairing Bluetooth devices.

            This document describes the Symbian +platform implementation of SSP. It describes the tasks that must be performed +by UI creators to implement SSP and it describes how application developers +can use Symbian APIs to pair with Bluetooth enabled devices using SSP.

            Scope

            This document is intended for Symbian partners and developers +implementing SSP on Symbian platform. It assumes that you are familiar with +Bluetooth and with developing on Symbian platform.

            Purpose of SSP

            SSP was introduced to simplify the user experience +when pairing Bluetooth devices. Specifically:

              +

            • there is no need for +the user to think of a number

              • +

            • the authentication process +may differ for different devices and different services

              • +

            • all data transfer is +encrypted

              • +
            +
            Overview

            The pairing model

            Pre-SSP pairing is achieved by the user(s) +entering a personal identification number (PIN) on one or both devices. Devices +with no keypads, such as headsets, have their PINs (typically "0000" or "1234") +hard-wired. This is now referred to as Legacy Paring.

            Under SSP, devices +specify their authorisation requirements. The user may have to:

              +

            • press a button in response +to a simple yes or no query

              • +

            • compare two automatically +generated numbers and select 'yes' if they match or 'no' if they do not

              • +

            • enter a number on one +or both devices

              • +

            • do nothing

              • +

            Once the devices have paired the user may be asked to authorise bonding. +Bonded devices can subsequently pair with no user interaction.

            Key concepts

            + +
            Authentication
            +

            Verification that a remote device is what it claims to be. Authentication +may be unnecessary for some pairings (see Just Works), may require user intervention +(see Man in the Middle) or may be performed through another channel (see Out +of Band).

            +             + +
            Authorisation
            +

            In legacy pairing a remote device can be authorised after pairing such +that it subsequently connects automatically without user intervention. Authorisation +is on a per-service basis. See bonding.

            +             + +
            Encryption
            +

            Transmission of data between devices after SSP is always encrypted. +Under legacy pairing data transmission is not always encrypted.

            +             + +
            Man In The Middle (MITM) protection
            +

            Authentication explicitly provided by the user before pairing can take +place. Under SSP, devices and services have hard-wired authentication requirements +as follows: MITM required, MITM not required (see Just Works) and MITM desired +(subject to the user interface capabilities of the devices)

            +             + +
            Just Works
            +

            For some pairings there is little risk of a security breach so SSP +provides a mechanism for devices to pair with no explicit user authentication.

            +             + +
            Passkey
            +

            In the context of a Symbian device, which always has both a display +and a keypad, passkey authentication is used when pairing with a remote device +which has a keypad but no display. The Symbian device displays a number which +the user must enter using the keypad on the remote device

            +             + +
            Out Of Band (OOB)
            +

            Out of Band authentication is performed using a non-Bluetooth communication +channel. The data required to open an MITM protected Bluetooth connection +with a remote device is transmitted by other means.

            +             + +
            Bonding
            +

            Two devices may bond after athentication such that they can reconnect +without user intervention. Bonding is achieved on a Symbian device by storing +a link key. Symbian devices attempt to bond by default. The user or the remote +device may specify that the devices do not bond.

            +             + +
            Link key
            +

            When a connection is authenticated a link key is created. The link +key indicates the strength of authentication (legacy, authenticated or unauthenticated). +The link key may be stored by the Symbian device and used to bond (the default +behaviour) or discarded when the connection ends. The link key is not displayed +to the user.

            +             +
            +
            Symbian support +for SSP

            Components

            Most +of the changes are internal and transparent to system creators and developers. +However, some new APIs added to the Bluetooth User Library allow application +developers to use SSP features, and Licensees must implement some SSP specific +notifiers.

            The diagram below shows the interfaces and interface classes +required to implement SSP.

            Dedicated +Bonding

            Dedicated bonding is performed by the Bluetooth Pairing +Server. Applications can use the RBluetoothDedicatedBondingInitiator API +to request bonding with a specified Bluetooth device.

            Out of Band Data

            Out of Band pairing data can be passed to +the Bluetooth Pairing Server. The server can use the supplied data to pair +with the specified device. Applications can also use the RBluetoothOobData API +to retrieve OOB data for the local device to be passed to remote devices.

            Numeric Comparison Notifier

            The Bluetooth sub-system requires +a Numeric Comparison Notifier to be provided by the UI. The notifier must +handle TBTNumericComparisonParams and return a boolean +value which indicates the user's decision.

            Passkey Entry Notifier

            The Bluetooth sub-system requires +a Passkey Entry Notifier to be provided by the UI. The notifier must handle TBTPasskeyDisplayParams and TBTPasskeyDisplayUpdateParams.

            Data +Types

            SSP specific data is stored and manipulated using the following +types (significant functions and fields shown only). These types are used +in various device and service related APIs. They are defined in bt_sock.h and btdevice.h.

            #include <bt_sock.h>

            +enum TBluetoothMitmProtection + { + EMitmNotRequired = 0x0, // No Man-in-the-Middle authentication is not required. + EMitmDesired = 0x1, // Man-in-the-Middle authentication should be used where possible. + EMitmRequired = 0x2 // Man-in-the-Middle authentication is required. + }; +

            TBTAccessRequirements

            +class TBTAccessRequirements + { +public: + ... + IMPORT_C void SetAuthentication( TBluetoothMitmProtection aPreference ); + IMPORT_C TBluetoothMitmProtection MitmProtection() const; + ... + + +private: + enum TBTServiceSecuritySettings + { + EAuthenticate = 0x01, + EAuthorise = 0x02, + EEncrypt = 0x04, + EDenied = 0x08, + EMitm = 0x30, // 2 bit field for MITM + }; + + enum TBTAccessRequirementsMitmProtection + { + EAccessRequirementsMitmUndefined = 0x00, + EAccessRequirementsMitmNotRequired = 0x10, + EAccessRequirementsMitmDesired = 0x20, + EAccessRequirementsMitmRequired = 0x30 + }; + };

            TBTServiceSecurity

            +class TBTServiceSecurity + { +public: + ... + IMPORT_C void SetAuthentication( TBluetoothMitmProtection aPreference ); + IMPORT_C TBool AuthenticationRequired() const; + IMPORT_C TBluetoothMitmProtection MitmProtection() const; + ... + +private: + TBTAccessRequirements iSecurityRequirements; // Whether the service requires authentication, authorisation, encryption or min passkey len. + }; + +typedef TPckgBuf<TBTServiceSecurity> TBTServiceSecurityPckg; // Package definition for securty settings +

            #include <btdevice.h>

            TBTDeviceSecurity

            +class TBTDeviceSecurity + { +public: + + // Enumeration to provide select MITM protection required. + + enum TMitmRequired + { + EMitmUnspecified, // No specific MITM protection requirements + EMitmRequired // Require the link is MITM protected + }; + +public: + + ... + IMPORT_C void SetNoAuthenticate(TBool aDecision); + IMPORT_C void SetMitmRequirements(TMitmRequired aDecision); + ... + IMPORT_C TBool NoAuthenticate() const; + IMPORT_C TMitmRequired MitmRequirements() const; + ... + +public: + // Enumeration to assist in parsing of security settings. + enum TBTDeviceSecuritySettings + { + ENoAuthenticate = 0x01, // Don't authenticate the link @deprecated + ENoAuthorise = 0x02, // Don't authorise the connection + EEncrypt = 0x04, // Encrypt the link + EBanned = 0x08, // Don't connect to the device + EMitmProtectionRequired = 0x10, // Require the link is MITM protected + }; + }; +
            +
            Implementing +SSP notifiers

            Introdution

            The +Bluetooth sub-system has no user interface. It uses the Symbian notifier +framework for user interaction when pairing. The UI system must provide +a notifier, in plug-in form, for each user interaction required by SSP. The +notifier must receive data in a specified format from the Bluetooth sub-system, +display appropriate controls in a dialog on the screen, respond to the user's +input and send data back to the Bluetooth sub-system in a specified format.

            This +document assumes that you already have Bluetooth notifiers in your system. +It describes the key aspects of adding notifiers for SSP. The structures, +types and constants described below are defined in BTExtNotifiers.h. +You can add notifiers to an existing plug-in or create a new plug-in.

            Notifiers +are typically implemented as sleeping dialogs. A sleeping dialog has its resources +allocated when its application (in this case the Uikon Server) is started. +A sleeping dialog can therefore be displayed (roused) safely under low memory +conditions.

            Notes:

              +

            • This document does not +describe how to implement an ECOM plug-in or a sleeping dialog.

              • +

            • Customisation Kit Licensees +can find an example notifier implementation here: sf/mw/classicui/commonuisupport/uikon/examples/notifier1/

              • +

            Numeric +Comparison Notifier

            A numeric comparison notifier is required +for SSP Man in the Middle (MITM) authentication when the remote device is +capable of displaying a number to the the user and accepting a yes or no response +from the user. The notifier must display an automatically generated number +and invite the user to confirm (yes or no) that the number is the same as +the number displayed on the remote device. The notifier must return the user's +response.

            The Bluetooth Security Manager uses the following code to +ask the notifier framework to display the Numeric Comparison Notifier

            + +// defined in header file(s) + +TBTDevAddr iDevAddr ; +RNotifier iNotifier ; +TUint32 iNumericValue ; +TBool iInternallyInitiated ; +TBTNumericComparisonParamsPckg iNumericComparisonParamsPckg ; +TPckgBuf<TBool> iResultPckg ; +// + +void CBTNumericComparator::DoRequest() + { + // Start the RNotifier plugin that deals with authorisation. + + ... + + TBTDeviceName deviceName = KNullDesC ; + + iNumericComparisonParamsPckg = TBTNumericComparisonParams( iDevAddr, + deviceName, + iNumericValue, + TBTNumericComparisonParams::ERemoteCanConfirm, + iInternallyInitiated); + + iNotifier.StartNotifierAndGetResponse( iStatus, + KBTNumericComparisonNotifierUid, + iNumericComparisonParamsPckg, + iResultPckg); + SetActive(); + } +

            From the code above you can see that the Numeric Comparision +Notifier is identified by the UIDKBTNumericComparisonNotifierUid and +that it must handle data in TBTNumericComparisonParams (which +is packaged into TBTNumericComparisonParamsPckg for inter-process +transfer).

            The code fragment below shows how to extract the numeric +comparison data within a notifier.

            NOTE: You will need to implement +all of the virtual functions in MEikSrvNotifierBase2.

            +class CNumericComparisonNotifier : public CEikDialog, public MEikSrvNotifierBase2 + { +public: + + ... + + // from MEikSrvNotifierBase2 + void StartL ( const TDesC8& aBuffer, TInt aReplySlot, const RMessagePtr2& aMessage ) ; + + ... + + void Complete( TBool aDecision, TInt aReason ) ; + +private: + TInt iRepySlot ; + TNotifierInfo iInfo ; + RMessage2 iMessage ; + TBTNumeriComparisonParamsPckg iNumericComparisonParamsPckg ; + TBTDevAddr iAddr ; + TBTDeviceName iName ; + TUint32 iNumericalValue ; + + } ; + + + +//-------------------------------- + +... + +void CNumericComparisionNotifier::StartL( const TDesC8& aBuffer, TInt aReplySlot, const RMessagePtr2& aMessage ) + { + + iMessage = RMessage2( aMessage ) ; // keep a copy ofthe message so that it can be completed later. + iReplySlot = aReplySlot ; // copy the reply slot too + + // Extract the comparison parameters from the buffer + + iNumericComparisonParamsPckg.Copy( aBuffer ) ; + + iAddr = iNumericComparisonParamsPckg().DeviceAddress() ; + iName = iNumericComparisonParamsPckg().DeviceName() ; + iNumericalValue = iNumericComparisonParamsPckg().NumericalValue() ; + + ... + + RouseSleepingDialog() ; + + } + +

            Your dialog must display iNumericalValue and +ask the user if the number displayed is the same as the number displayed on +the other Bluetooth device. The user must be able to select 'Yes' or 'No'.

            The StartL() function +above must return quickly so it must not wait for the user's response. Your +notifier must complete the message (iMessage) as shown below +when the user enters a response.

            +void CNumericComparisionNotifier::Complete( TBool aDecision, TInt aReason ) + { + if ( aReason == KErrNone ) + { + TInt err = iMessage.Write( iReplySlot, TPckgC<TBool>( aDecision ) ) ; + iMessage.Complete( err ) ; + } + else + { + iMessage.Complete( aReason ) ; + } + } +

            Passkey +Notifier

            A passkey notifier is required for SSP MITM authentication +when the user must type a number on a remote device which has a keypad and +no display. The notifier displays the number that the user must type. In the +code below the notifier also displays a '*' character as the user types each +digit into the remote device.

            The Bluetooth Security Manager uses +the following code to ask the Notifier Framework to display the passkey notifier.

            + +// defined in header file(s) + +TBTDevAddr iDevAddr ; +RNotifier iNotifier ; +TUint32 iNumericValue ; // the passkey number +TBool iInternallyInitiated ; +TBTPasskeyDisplayParamsPckg iPasskeyDisplayParamsPckg ; +TBTDeviceNameUpdateParamsPckg iDeviceNameUpdateParamsPckg; +TBuf8<1> iResultPckg ; + +void CBTPasskeyEntry::DoRequest() + { + // Start the RNotifier plugin that deals with authorisation. + + ... + + TBTDeviceName deviceName ; + + deviceName = KNullDesC ; + + iPasskeyDisplayParamsPckg = TBTPasskeyDisplayParams( iDevAddr, + deviceName, + iNumericValue, + iInternallyInitiated ) ; + + iNotifier.StartNotifierAndGetResponse( iStatus, + KBTPasskeyDisplayNotifierUid, + iPasskeyDisplayParamsPckg, + iResultPckg ) ; + SetActive() ; + + } + +

            From the code above you can see that the Passkey Notifier +is identified by the UIDKBTPasskeyNotifierUid and that it +must handle data in TBTPasskeyDisplayParams (which is packaged +into TBTPasskeyDisplayParamsPckg for inter-process transfer).

            As +the user enters passkey digits into the remote device the Security Manager +also uses RNotifier::UpdateNotifierAndGetResponse() to send TBTPasskeyDisplayUpdateParams (packaged +in TBTPasskeyDisplayUdateParamsPckg) to the notifier. Your +notifier must use this information to reflect the key presses on the remote +device.

            The code fragment below shows how to extract the passkey data +within a notifier.

            NOTE: You will need to implement all of the virtual +functions in MEikSrvNotifierBase2.

            +class CPasskeyNotifier : public CEikDialog, public MEikSrvNotifierBase2 + { +public: + + ... + + // from MEikSrvNotifierBase2 + void StartL( const TDesC8& aBuffer, TInt aReplySlot, const RMessagePtr2& aMessage ) ; + TPtrC8 UpdateL( const TDesC8& aBuffer ) ; // new information + + ... + +private: + TInt iRepySlot ; + TNotifierInfo iInfo ; + RMessage2 iMessage ; + TBTPasskeyDisplayParamsPckg iPasskeyDisplayParamsPckg ; + TBTDevAddr iAddr ; + TBTDeviceName iName ; + TUint32 iNumericalValue ; // the passkey number + + } ; + +//-------------------------------- + +... + +void CPasskeyNotifier::StartL( const TDesC8& aBuffer, TInt aReplySlot, const RMessagePtr2& aMessage ) + { + + iMessage = RMessage2(aMessage); // keep a copy ofthe message so that it can be completed later. + iReplySlot = aReplySlot ; // copy the reply slot too + + // Extract the comparison parameters from the buffer + + iPasskeyDisplayParamsPckg.Copy( aBuffer ) ; + + iAddr = iPasskeyDisplayParamsPckg().DeviceAddress() ; + iName = iPasskeyDisplayParamsPckg().DeviceName() ; + iNumericValue = iPasskeyDisplayParamsPckg().NumericalValue() ; + + + ... + + RouseSleepingDialog() ; // display the passkey + + ... + + } + +void CPasskeyNotifier::UpdateL( const TDesC8& aBuffer ) + { + + // extract the contents of the buffer + + TBTNotifierUpdateParamsPckg2 pckgRaw ; + pckgRaw.Copy( aBuffer.Left( pckgRaw.MaxLength() ) ) ; + + // update the dialog to reflect the keys pressed on the remote device + + if ( pckgRaw().Type() == TBTNotifierUpdateParams2::EPasskeyDisplay ) + { + TBTPasskeyDisplayUpdateParamsPckg pckg ; + pckg.Copy( aBuffer ) ; + HCIPasskeyEntryNotificationType keypressNotification = pckg().KeypressNotification() ; + + switch (keypressNotification) + { + case EPasskeyEntryStarted : + { + break ; + } + case EPasskeyDigitEntered : + { + // display '*' + break ; + } + case EPasskeyDigitDeleted : + { + // remove '*', reposition cursor + break ; + } + case EPasskeyCleared : + { + // clear display, reposition cursor + break ; + } + case EPasskeyEntryCompleted : + { + // hide the dialog + ExitSleepingDialog() ; + break; + } + default : + break ; + } + else if( pckgRaw().Type() == TBTNotifierUpdateParams2::EDeviceName ) + { + // handle name update + } + return KNullDesC8() ; + } + + + +
            +
            Out of Band +(OOB) authentication

            Introduction

            Out +of Band authentication is achieved using a communication method other than +Bluetooth. Once OOB authentication has succeeded an encrypted Bluetooth channel +is opened between the two devices.

            The OOB API, RBluetoothOobData, +allows an application handling OOB authentication to provide pairing information +for a remote device.

            RBluetoothOobData allows +an application handling OOB authentication to retrieve pairing information +for the local device.

            Using +the OOB API

            The OOB data API is provided by the Pairing Server +(part of the Security Manager).

            + +#include <pairing.h> + + RBluetoothPairingServer pairingServer ; + RBluetoothOobData OobData ; + + + // Connect to the Pairing server + + TInt err = pairingServer.connect() ; + + // Paring session + + err = OobData.Open( iPairingServer ) ; + + + // Use the API pass hash and randomizer values to and from the pairing server. + + ... + + + // Tidy up + + OobData.Close() ; + PairingServer.Close() ; + +

            The API has three primary functions:

            RefreshLocalOobData() - +This function causes the Bluetooth controller to generate new hash and randomizer +values for the local device. To retrieve the new values call ReadLocalOobData()

            ReadLocalOobData() - +This function returns the hash and randomizer values that the Bluetooth controller +is currently using.

            ProvideRemoteOobData() - Use +this function to pass OOB data about a remote device to the Bluetooth sub-system. +Three versions of the function are available which take slightly different +parameters. Information provided using one of these functions can be cleared +using ClearRemoteOobData().

            +
            Dedicated bonding

            Introduction

            Dedicated bonding is intended for applications +which bond with a specific Bluetooth device.

            Using the dedicated bonding API

            + +#include <pairing.h> + + RBluetoothPairingServer pairingServer ; + RBluetoothDedicatedBondingInitiator bonder ; + TBTDevAddr addr ; + TRequstStatus status ; + + + // Connect to the Pairing server + + TInt err = pairingServer.connect() ; + + + // Use the Bluetooth address of the remote device bonder.Start( pairingServer, addr, status ) ; + + + // Wait for the request to complete + + User::WaitForRequest(status); + + + // Close the connection with the bonder (Must be closed before bonding with another device) + + bonder.Close(); + + pairingServer.Close() ; + +
            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3239641A-2D13-56D7-B18D-6E65B6B24886_d0e287369_href.png Binary file Symbian3/SDK/Source/GUID-3239641A-2D13-56D7-B18D-6E65B6B24886_d0e287369_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3239641A-2D13-56D7-B18D-6E65B6B24886_d0e291002_href.png Binary file Symbian3/SDK/Source/GUID-3239641A-2D13-56D7-B18D-6E65B6B24886_d0e291002_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-329833DA-CB6E-4715-A8E6-AD838DD5A909_d0e3192_href.png Binary file Symbian3/SDK/Source/GUID-329833DA-CB6E-4715-A8E6-AD838DD5A909_d0e3192_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-329833DA-CB6E-4715-A8E6-AD838DD5A909_d0e4467_href.png Binary file Symbian3/SDK/Source/GUID-329833DA-CB6E-4715-A8E6-AD838DD5A909_d0e4467_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C.dita --- a/Symbian3/SDK/Source/GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,239 +1,239 @@ - - - - - -Search-Sort -Introduction -

            In Symbian OS v9.3 and earlier, when a search or sort query is made by -a client, Message Server searches in the permanent file store (a proprietary -formatted file), and returns the result to the client.

            -

            From Symbian^3 onwards Message Server operates with the SQL -database to store index entries. With the SQL database implementation the -Message Server makes a query on the SQL index entry table, and returns the -result to the client.

            -

            The Messaging Middleware module provides an enhanced API for searching -and sorting messages. This API can be used only when the SQL database is used -to store the index entries. The API has the following features:

            -
              -

            • Combined search (combination -of more than one simple search criteria)

              • -

            • Search based on whole -and partial words

              • -

            • Case sensitive search

              • -

            • Wildcard search

              • -

            • Count of total search -results

              • -

            • Single level sorting -of search results

              • -

            • Iterative mechanism -for clients to access the search and sort results sequentially.

              • -
            -

            The following sections include basic information on the search-sort functionality, -which is important to understand before using the search-sort APIs:

            -
              -

            • Description

              • -

            • Search-sort API summary

              • -

            • Advantages

              • -

            • Limitations

              • -
            -
            Description

            The -search-sort functionality is based on the client-server architecture. The -Messaging Middleware module provides an advanced search-sort capability if -the index entries are stored in an SQL database.

            The client creates -a search-sort query, and passes it to the Message Server. The Message Server -searches in the search-sort cache to check whether the query is a repetitive -query (a query that was already requested in the past and for which a query -ID is maintained in the search-sort cache) or a new query.

            If it is -a repetitive query, the Message Server gets the index entry from the SQL database, -and provides the search result to the client.

            If it is a new query, -the Message Server stores the search query in the cache, and passes the query -to the SQL database.

            In both the cases, the Message Server gets the -index entry from the SQL database, passes the result to the client, and maintains -the query in the search-sort cache.

            The iterative method can be used -for searching and sorting a new or a repetitive search query.

            The -following table provides detailed information on the fields supported in the -search-sort operation:

            - - - -Operation -Header -Body -TMsvEntry - - - - -

            Searching

            -

            To, cc, bcc, from, subject

            -

            Body part, whole and partial word (case sensitive and insensitive, -whole word, wildcard)

            -

            Attachment type, read, unread, new flag, priority, size, MTM type, -iDescription, iDetails, and date and time.

            -             - -

            Searching with explicit sorting

            -

            To, cc, bcc, from, subject

            -

            -

             -

            Attachment type, read, unread, new flag, priority, size, MTM type, -iDescription, iDetails, and date and time.

            -             - -

            Sorting

            -

            To, cc, bcc, from, subject

            - -

            Attachment type, read, unread, new flag, priority, size, MTM type, -iDescription, iDetails, and date and time.

            -             - - -

            Key terms

            - -
            Iterator
            -

            An iterator is a method that allows a client to access the search and -sort results sequentially. An iterator is useful when a client does not want -to provide the memory to receive an array of results.

            -             - -
            Search-sort cache
            -

            Search-sort cache contains frequently requested search-sort queries. -By default, this cache is set to 20 percent of the index entry cache.

            For -more information the search-sort cache, see Search-Sort -Cache.

            -             -
            -
            Search-sort -API summary

            Use the following APIs available in msgs.dll for -searching and sorting messages:

            - High level class diagram of new search-sort API - - -
              -

            • CMsvSearchSortOperation

              The CMsvSearchSortOperation class is used in the client application for enhanced search-sort operations -on the message store.

              This class can be used for the following:

                -

              • To run a simple or complex -search-sort request.

                • -

              • To repeat an earlier -search-sort operation by using the queryId.

                • -

              • To receive results either -in one chunk using an array or one after the other using an iterative method.

                The -search-sort results can be received as a list of TMsvId or TMsvEntry objects.
                • -
              • -

            • CMsvSearchSortQuery

              The CMsvSearchSortQuery class -is used in the client application to create a search-sort query. It has an -interface to add or set the query criteria on various message parts.

              This -class provides the following search options:

                -

              • Case sensitive search -(SetCaseSensitiveOption)

                By default this option -is set to false.

                • -

              • Whole word search (SetWholeWord)

                By -default this option is set to false.

                • -

              • Wildcard search (SetWildCardSearch)

                Allow -the use of the asterisk (*) and question mark (?) wildcards. By default this -option is set to false.

                • -

              • Subfolder search (SetSubFolderSearch)

                Include -the entries within the subfolders in the search result. By default this option -is set to false.

                The subfolder option is valid only for a search -query.
                • -

              • Explicit single level -sort (using the TMsvMessagePart aMessagePart parameter -in the CMsvSearchSortQuery::AddSearchOptionL function.

                Sorting -on one particular message part.

                • -

              The CMsvSearchSortQuery class is used with the CMsvSearchSortOperation class -when requesting a new search-sort operation.

              By -default, the search query results are not sorted. To receive a result in a -sorted order, you must send a sort request by using the CMsvSearchSortQuery::AddSortOptionL() function. -Sort options can be used with search options when creating a search-sort query.
              • -

            • TMsvMessagePart

              The TMsvMessagePart is -an enumeration type class that contains all parts of the message, including -index entry and message header. Searching or sorting is done based on the TMsvMessagePart class.

              • -

            • TMsvSearchSortResultType

              The TMsvSearchSortResultType is an enumeration class. The client uses TMsvSearchSortResultType to -specify if the search and sort results are returned as TMsvId or TMsvEntry.

              • -

            • TMsvRelationOp

              The TMsvRelationOp is -an enumeration type class that is used to provide relational operations between -the search criteria value and the value in the message part of a message.

              For -example, equal to, greater than, greater than or equal to, less than, and -less than or equal to.

              • -

            • TMsvSortOrder

              The TMsvSortOrder is -an enumeration type class that is used to provide the sorting options for -sorting queries. The search or sort results can be sorted in ascending or -descending order.

              • -
            -
            Advantages

            The -following are the advantages of the enhanced search-sort functionality:

              -

            • Search messages by the -following fields:

              Most of the following fields are applicable to -email messages:
                -

              • Sender, recipient list -(cc, to, bcc), subject

                • -

              • Mail size and size range

                • -

              • Date and date range

                • -

              • Message type (SMS, Email, -MMS, and BIO message)

                • -

              • Priority (high, medium, -and low)

                • -

              • Attachment types (linked -attachment and file attachment)

                • -

              • Message status

                For -example, New, Read, Unread, and so on.

                • -
              • -

            • Search messages containing -a specified string in a specified message part.

              • -

            • Search within subfolders -of the parent folder.

              • -

            • Provides combined search -and sort options to the client.

              • -

            • Provides explicit single -level of sorting with implicit sort by data and time.

              • -

            • Allows client to implement -more versatile UI views.

              • -

            • Returns total number -of search-sort count without sending the resultant data. For example, the -number of unread messages in the inbox.

              • -

            • Provides good RAM performance -for repetitive search-sort requests, as the Messaging framework maintains -a search-sort cache for frequently used search-sort requests.

              • -
            -
            Limitations

            The -following are the limitations of the advanced search and sort functionality:

              -

            • The search-sort operation -for a specific value in a specific message part is supported, but searching -for a specific value in all message parts is not supported.

              • -

            • Index entry is migrated -to SQL. The header and body part are yet to be migrated to SQL. So the iterative -method is supported only if the message parts in the index entry are used -in creating the search-sort query.

              • -

            • The following are not -supported in the iterative method because the limitations of SQL:

                -

              • Accessing the next set -of values, that is, next n values (results).

                • -

              • Accessing the previous -value or the previous set of values.

                • -

              • Accessing a random value -or a random set of values.

                • -
              • -

            • Multi level sorting -is not supported.

              • -

            • A search query can use -a maximum of five message parts as search criteria in a combined search.

              • -

            • Sorting on message body -is not supported.

              • -

            • Search-sort operation -cannot be performed on all the message parts present in index entry. The supported -list consists of message parts present in message header, message body and -a partial list of message parts from index entry. See the TMsvMessagePart enumeration -class for the supported message parts.

              • -
            -             -Search-Sort -Cache -Example code - + + + + + +Search-Sort +Introduction +

            In Symbian OS v9.3 and earlier, when a search or sort query is made by +a client, Message Server searches in the permanent file store (a proprietary +formatted file), and returns the result to the client.

            +

            From Symbian^3 onwards Message Server operates with the SQL +database to store index entries. With the SQL database implementation the +Message Server makes a query on the SQL index entry table, and returns the +result to the client.

            +

            The Messaging Middleware module provides an enhanced API for searching +and sorting messages. This API can be used only when the SQL database is used +to store the index entries. The API has the following features:

            +
              +

            • Combined search (combination +of more than one simple search criteria)

              • +

            • Search based on whole +and partial words

              • +

            • Case sensitive search

              • +

            • Wildcard search

              • +

            • Count of total search +results

              • +

            • Single level sorting +of search results

              • +

            • Iterative mechanism +for clients to access the search and sort results sequentially.

              • +
            +

            The following sections include basic information on the search-sort functionality, +which is important to understand before using the search-sort APIs:

            +
              +

            • Description

              • +

            • Search-sort API summary

              • +

            • Advantages

              • +

            • Limitations

              • +
            +
            Description

            The +search-sort functionality is based on the client-server architecture. The +Messaging Middleware module provides an advanced search-sort capability if +the index entries are stored in an SQL database.

            The client creates +a search-sort query, and passes it to the Message Server. The Message Server +searches in the search-sort cache to check whether the query is a repetitive +query (a query that was already requested in the past and for which a query +ID is maintained in the search-sort cache) or a new query.

            If it is +a repetitive query, the Message Server gets the index entry from the SQL database, +and provides the search result to the client.

            If it is a new query, +the Message Server stores the search query in the cache, and passes the query +to the SQL database.

            In both the cases, the Message Server gets the +index entry from the SQL database, passes the result to the client, and maintains +the query in the search-sort cache.

            The iterative method can be used +for searching and sorting a new or a repetitive search query.

            The +following table provides detailed information on the fields supported in the +search-sort operation:

            + + + +Operation +Header +Body +TMsvEntry + + + + +

            Searching

            +

            To, cc, bcc, from, subject

            +

            Body part, whole and partial word (case sensitive and insensitive, +whole word, wildcard)

            +

            Attachment type, read, unread, new flag, priority, size, MTM type, +iDescription, iDetails, and date and time.

            +             + +

            Searching with explicit sorting

            +

            To, cc, bcc, from, subject

            +

            -

             +

            Attachment type, read, unread, new flag, priority, size, MTM type, +iDescription, iDetails, and date and time.

            +             + +

            Sorting

            +

            To, cc, bcc, from, subject

            + +

            Attachment type, read, unread, new flag, priority, size, MTM type, +iDescription, iDetails, and date and time.

            +             + + +

            Key terms

            + +
            Iterator
            +

            An iterator is a method that allows a client to access the search and +sort results sequentially. An iterator is useful when a client does not want +to provide the memory to receive an array of results.

            +             + +
            Search-sort cache
            +

            Search-sort cache contains frequently requested search-sort queries. +By default, this cache is set to 20 percent of the index entry cache.

            For +more information the search-sort cache, see Search-Sort +Cache.

            +             +
            +
            Search-sort +API summary

            Use the following APIs available in msgs.dll for +searching and sorting messages:

            + High level class diagram of new search-sort API + + +
              +

            • CMsvSearchSortOperation

              The CMsvSearchSortOperation class is used in the client application for enhanced search-sort operations +on the message store.

              This class can be used for the following:

                +

              • To run a simple or complex +search-sort request.

                • +

              • To repeat an earlier +search-sort operation by using the queryId.

                • +

              • To receive results either +in one chunk using an array or one after the other using an iterative method.

                The +search-sort results can be received as a list of TMsvId or TMsvEntry objects.
                • +
              • +

            • CMsvSearchSortQuery

              The CMsvSearchSortQuery class +is used in the client application to create a search-sort query. It has an +interface to add or set the query criteria on various message parts.

              This +class provides the following search options:

                +

              • Case sensitive search +(SetCaseSensitiveOption)

                By default this option +is set to false.

                • +

              • Whole word search (SetWholeWord)

                By +default this option is set to false.

                • +

              • Wildcard search (SetWildCardSearch)

                Allow +the use of the asterisk (*) and question mark (?) wildcards. By default this +option is set to false.

                • +

              • Subfolder search (SetSubFolderSearch)

                Include +the entries within the subfolders in the search result. By default this option +is set to false.

                The subfolder option is valid only for a search +query.
                • +

              • Explicit single level +sort (using the TMsvMessagePart aMessagePart parameter +in the CMsvSearchSortQuery::AddSearchOptionL function.

                Sorting +on one particular message part.

                • +

              The CMsvSearchSortQuery class is used with the CMsvSearchSortOperation class +when requesting a new search-sort operation.

              By +default, the search query results are not sorted. To receive a result in a +sorted order, you must send a sort request by using the CMsvSearchSortQuery::AddSortOptionL() function. +Sort options can be used with search options when creating a search-sort query.
              • +

            • TMsvMessagePart

              The TMsvMessagePart is +an enumeration type class that contains all parts of the message, including +index entry and message header. Searching or sorting is done based on the TMsvMessagePart class.

              • +

            • TMsvSearchSortResultType

              The TMsvSearchSortResultType is an enumeration class. The client uses TMsvSearchSortResultType to +specify if the search and sort results are returned as TMsvId or TMsvEntry.

              • +

            • TMsvRelationOp

              The TMsvRelationOp is +an enumeration type class that is used to provide relational operations between +the search criteria value and the value in the message part of a message.

              For +example, equal to, greater than, greater than or equal to, less than, and +less than or equal to.

              • +

            • TMsvSortOrder

              The TMsvSortOrder is +an enumeration type class that is used to provide the sorting options for +sorting queries. The search or sort results can be sorted in ascending or +descending order.

              • +
            +
            Advantages

            The +following are the advantages of the enhanced search-sort functionality:

              +

            • Search messages by the +following fields:

              Most of the following fields are applicable to +email messages:
                +

              • Sender, recipient list +(cc, to, bcc), subject

                • +

              • Mail size and size range

                • +

              • Date and date range

                • +

              • Message type (SMS, Email, +MMS, and BIO message)

                • +

              • Priority (high, medium, +and low)

                • +

              • Attachment types (linked +attachment and file attachment)

                • +

              • Message status

                For +example, New, Read, Unread, and so on.

                • +
              • +

            • Search messages containing +a specified string in a specified message part.

              • +

            • Search within subfolders +of the parent folder.

              • +

            • Provides combined search +and sort options to the client.

              • +

            • Provides explicit single +level of sorting with implicit sort by data and time.

              • +

            • Allows client to implement +more versatile UI views.

              • +

            • Returns total number +of search-sort count without sending the resultant data. For example, the +number of unread messages in the inbox.

              • +

            • Provides good RAM performance +for repetitive search-sort requests, as the Messaging framework maintains +a search-sort cache for frequently used search-sort requests.

              • +
            +
            Limitations

            The +following are the limitations of the advanced search and sort functionality:

              +

            • The search-sort operation +for a specific value in a specific message part is supported, but searching +for a specific value in all message parts is not supported.

              • +

            • Index entry is migrated +to SQL. The header and body part are yet to be migrated to SQL. So the iterative +method is supported only if the message parts in the index entry are used +in creating the search-sort query.

              • +

            • The following are not +supported in the iterative method because the limitations of SQL:

                +

              • Accessing the next set +of values, that is, next n values (results).

                • +

              • Accessing the previous +value or the previous set of values.

                • +

              • Accessing a random value +or a random set of values.

                • +
              • +

            • Multi level sorting +is not supported.

              • +

            • A search query can use +a maximum of five message parts as search criteria in a combined search.

              • +

            • Sorting on message body +is not supported.

              • +

            • Search-sort operation +cannot be performed on all the message parts present in index entry. The supported +list consists of message parts present in message header, message body and +a partial list of message parts from index entry. See the TMsvMessagePart enumeration +class for the supported message parts.

              • +
            +             +Search-Sort +Cache +Example code +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-32D39AB1-D1B0-5F44-8226-0777B8010C7D_d0e107413_href.png Binary file Symbian3/SDK/Source/GUID-32D39AB1-D1B0-5F44-8226-0777B8010C7D_d0e107413_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-32D39AB1-D1B0-5F44-8226-0777B8010C7D_d0e113951_href.png Binary file Symbian3/SDK/Source/GUID-32D39AB1-D1B0-5F44-8226-0777B8010C7D_d0e113951_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-330FBB90-E622-4FD1-A189-64656F68A10D.dita --- a/Symbian3/SDK/Source/GUID-330FBB90-E622-4FD1-A189-64656F68A10D.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,50 +0,0 @@ - - - - - -Displaying an image -on the screen -

            The Symbian Image Converter Library (ICL) supports the decoding of image -files. You can use the ICL architecture to load an image stored in a file -or a descriptor and convert it to a CFbsBitmap object. -Use this bitmap object, for example, to display the image on the screen of -the mobile device after the capture.

            -

            For a reference example, see S60 Platform: Image Converter Example on Forum Nokia.

            -
            To convert an image to display on the screen -
              -

            1. Use the methods -of the CImageDecoder (or CBufferedImageDecoder) class to construct your application.

              -
                -

              • Create a CImageDecoder object using CImageDecoder::DataNewL() (for descriptor) -or CImageDecoder::FileNewL() (for file) method.

                -
                • -

              • Select a suitable plugin for the actual decoding.

                -
                • -

              • Request information about the image using, for example, CImageDecoder::FrameInfo() and CImageDecoder::FrameCount().

                • -

              • Decode the image using the CImageDecoder::Convert() method.

                • -
              -
              2. -

            2. Include ImageConversion.h and Fbs.h header -files in the appropriate class file(s).

              3. -

            3. Make sure -you have correct capabilities information -set for your application. You need at least the ReadUserData capability.

              -
              4. -

            4. Make sure imageconversion.lib, bafl.lib, fbscli.lib and efsrv.lib are accessible to your -linker when compiling your application by including them in your mmp file -or by editing the project properties in your IDE, depending on your build -environment.

              5. -
            -
            -
            See also -

            Image Display -Library Overview

            -
            -             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3314123F-205D-5E05-9041-DB9836B7812B.dita --- a/Symbian3/SDK/Source/GUID-3314123F-205D-5E05-9041-DB9836B7812B.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-3314123F-205D-5E05-9041-DB9836B7812B.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,55 +1,47 @@ - - - - - -File -Access Example: Accessing the File System Using P.I.P.S. -

            This example application shows, using a P.I.P.S. (P.I.P.S. Is POSIX on -the Symbian platform) program, the restrictions on file access that are imposed -by the Symbian platform Security model.

            -

            It shows that programs can access their own directories, but -cannot, without platform security capabilities not available to ordinary programs, -access the directories of other programs, or the system binary directory sys/bin.

            -

            This example defines an executable file with no platform security capabilities. -The program first creates its own secure directory that it can write to and -read from. It then attempts to use a file in a private directory of another -program, and then in sys/bin, and shows that these attempts -are denied.

            -
            Download

            Click -on the following link to download the example: FileAccessExample.zip

            Click: browse to view the example code.

            -
            Description

            The -following sections provide more information about the steps that the example -performs.

            Create a secure directory

            The example creates -an empty secure directory for the program by using the mkdir() function.

            This -empty secure directory is created in C:\private\E80000C9, -as 0xE80000C9 is a unique identifier for the program (as specified by the -third UID in its project file).

            -

            Write and read -a file in the private directory

            The example writes and reads -a file in the secure directory using the fopen() and other -file stream functions.

            Write and read a file in the private directory -of another program

            The example attempts to write and read a file -in the secure directory of another program.

            The fopen() function -is expected to return NULL, indicating that access is not -possible, as the program has insufficient platform security capabilities.

            Write -and read a file in the sys/bin directory

            The example attempts -to write and read a file in the system's sys/bin directory, -where program binaries are stored.

            Again, the fopen() function -is expected to return NULL, indicating that access is not -possible, as the program has insufficient platform security capabilities.

            -
            Related APIs

            mkdir()

            fopen()

            -
            Build

            The Symbian build process describes -how to build this example application.

            The example builds an executable -called fileaccessexample.exe in the standard locations.

            To -run the example, start fileaccessexample.exe from the -file system or from your IDE. After launching the executable, depending on -the emulator you are using, you may need to navigate away from the application -launcher or shell screen to view the console.

            + + + + + +File Access Example: Accessing the File System Using P.I.P.S. +

            This example application shows, using a P.I.P.S. (P.I.P.S. Is POSIX +on the Symbian platform) program, the restrictions on file access +that are imposed by the Symbian platform Security model.

            +

            It shows that programs can access their own directories, but cannot, +without platform security capabilities not available to ordinary programs, +access the directories of other programs, or the system binary directory sys/bin.

            +

            This example defines an executable file with no platform security +capabilities. The program first creates its own secure directory that +it can write to and read from. It then attempts to use a file in a +private directory of another program, and then in sys/bin, and shows that these attempts are denied.

            +
            Download

            Click on the following link to download the example: FileAccessExample.zip

            Click: browse to view the example code.

            +
            Description

            The following sections provide more information about the steps +that the example performs.

            Create a secure directory

            The example creates an empty secure directory for the program +by using the mkdir(const char *,mode_t) function.

            This empty secure directory is created in C:\private\E80000C9, as 0xE80000C9 is a unique identifier for the program (as specified +by the third UID in its project file).

            +

            Write +and read a file in the private directory

            The example +writes and reads a file in the secure directory using the fopen(const char *, const char *) and other file stream +functions.

            Write and read a file in the private directory +of another program

            The example attempts to write and +read a file in the secure directory of another program.

            The fopen() function is expected to return NULL, indicating that access is not possible, as the program has insufficient +platform security capabilities.

            Write and read a file in +the sys/bin directory

            The example attempts to write and +read a file in the system's sys/bin directory, +where program binaries are stored.

            Again, the fopen() function is expected to return NULL, indicating +that access is not possible, as the program has insufficient platform +security capabilities.

            +
            Related +APIs

            mkdir(const char *,mode_t)

            fopen(const char *, const char *)

            +
            Build

            The Symbian +build process describes how to build this example application.

            The example builds an executable called fileaccessexample.exe in the standard locations.

            To run the example, start fileaccessexample.exe from the file system or from your +IDE. After launching the executable, depending on the emulator you +are using, you may need to navigate away from the application launcher +or shell screen to view the console.

            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-33241691-7362-5FA1-A3B0-C3FA550E5E09.dita --- a/Symbian3/SDK/Source/GUID-33241691-7362-5FA1-A3B0-C3FA550E5E09.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-33241691-7362-5FA1-A3B0-C3FA550E5E09.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,131 +1,131 @@ - - - - - -Store -OverviewProvides structured data storage, using networks of streams. -
            Purpose

            It -is often necessary to persist a data structure such as an object by writing -it to memory as a sequence of bytes called a stream. A complex object is persisted -as multiple streams collectively known as a store. The Store component provides -access to stores in Symbian platform.

            -
            Required background

            The -Store component requires no specific background apart from C++ and Symbian -platform.

            -
            Key concepts -and terms

            The API has the following key concepts.

            - -
            stream store
            -

            a store consisting of streams, implemented by CStreamStore

            -             - -
            persistent store
            -

            a store which persists beyond the lifetime of the application which -creates it, implemented by CPersistentStore

            -             - -
            embedded store
            -

            a store which can itself be stored as a stream in another store, implemented -by CEmbeddedStore

            -             - -
            memory store
            -

            a store which resides in memory and exists only for the life of the -store object, implemented by CBufStore

            -             - -
            dictionary store base and streams
            -

            a sequence of streams accessed by a UID, implemented by CDictionaryStore

            -             -
            -
            Architecture

            A -stream is a representation of a data structure (such as an object) as a sequence -of bytes. Structures as complex as most applications require multiple streams -to store their state. This is termed a store. Stream types that work with -stores are provided by the Store -Streams API.

            The Stores API defines both base classes that -define store abstractions without specifying the storage medium, and some -concrete store types.

            The abstract classes are used as the base classes -of separate APIs which use particular storage media. In particular the File Stores API defines -further concrete stores which use file storage. Its base class, CFileStore extends CPersistentStore and -has its own subclasses such as CDirectFileStore. Concrete -store types do not have to provide all the stream manipulation functionality -defined by the base class interfaces: for example, direct file stores do not -support individual deletion of streams within a store.

            Dictionary -stores are accessed by a UID whereas stream stores are accessed by a stream -ID. Persistent stores persist beyond the lifetime of the application that -created them: they have a root stream from which the other streams in the -store can be found. Embedded stores can be stored as streams in other stores: -once written they cannot be modified.

            Stores are integrated with the -application architecture as defined in the Uikon Core API. That expects file-based -and embedded applications to handle their data storage through stores.

            Stores -are also the basis of the relational database provided by DBMS.

            -Store inheritance diagram - -
            -
            APIs - - - -API -Description - - - - -

            CStreamStore

            -

            Provides the core abstract framework for stores allowing streams -to be created and manipulated

            -             - -

            CPersistentStore

            -

            Persistent store abstract base class

            -             - -

            CEmbeddedStore

            -

            Encapsulates an embedded store

            -             - -

            CBufStore

            -

            In-memory non-persistent store

            -             - -

            CDictionaryStore

            -

            Dictionary store interface

            -             - -

            RStoreReadStream

            -

            Supports the opening and manipulation of an existing stream in a -store

            -             - -

            RStoreWriteStream

            -

            Supports the writing of a stream to a store

            -             - -

            RFileBuf

            -

            A stream buffer hosted by a file

            -             - - -
            -
            Typical uses

            A -typical use of stores is to write files to memory without using the file server. -This is a good thing to do when an application uses embedded documents.

            -             -Persistent -Storage Overview -File Stores -Overview -Store Streams - Overview -Streaming -Overview + + + + + +Store +OverviewProvides structured data storage, using networks of streams. +
            Purpose

            It +is often necessary to persist a data structure such as an object by writing +it to memory as a sequence of bytes called a stream. A complex object is persisted +as multiple streams collectively known as a store. The Store component provides +access to stores in Symbian platform.

            +
            Required background

            The +Store component requires no specific background apart from C++ and Symbian +platform.

            +
            Key concepts +and terms

            The API has the following key concepts.

            + +
            stream store
            +

            a store consisting of streams, implemented by CStreamStore

            +             + +
            persistent store
            +

            a store which persists beyond the lifetime of the application which +creates it, implemented by CPersistentStore

            +             + +
            embedded store
            +

            a store which can itself be stored as a stream in another store, implemented +by CEmbeddedStore

            +             + +
            memory store
            +

            a store which resides in memory and exists only for the life of the +store object, implemented by CBufStore

            +             + +
            dictionary store base and streams
            +

            a sequence of streams accessed by a UID, implemented by CDictionaryStore

            +             +
            +
            Architecture

            A +stream is a representation of a data structure (such as an object) as a sequence +of bytes. Structures as complex as most applications require multiple streams +to store their state. This is termed a store. Stream types that work with +stores are provided by the Store +Streams API.

            The Stores API defines both base classes that +define store abstractions without specifying the storage medium, and some +concrete store types.

            The abstract classes are used as the base classes +of separate APIs which use particular storage media. In particular the File Stores API defines +further concrete stores which use file storage. Its base class, CFileStore extends CPersistentStore and +has its own subclasses such as CDirectFileStore. Concrete +store types do not have to provide all the stream manipulation functionality +defined by the base class interfaces: for example, direct file stores do not +support individual deletion of streams within a store.

            Dictionary +stores are accessed by a UID whereas stream stores are accessed by a stream +ID. Persistent stores persist beyond the lifetime of the application that +created them: they have a root stream from which the other streams in the +store can be found. Embedded stores can be stored as streams in other stores: +once written they cannot be modified.

            Stores are integrated with the +application architecture as defined in the Uikon Core API. That expects file-based +and embedded applications to handle their data storage through stores.

            Stores +are also the basis of the relational database provided by DBMS.

            +Store inheritance diagram + +
            +
            APIs + + + +API +Description + + + + +

            CStreamStore

            +

            Provides the core abstract framework for stores allowing streams +to be created and manipulated

            +             + +

            CPersistentStore

            +

            Persistent store abstract base class

            +             + +

            CEmbeddedStore

            +

            Encapsulates an embedded store

            +             + +

            CBufStore

            +

            In-memory non-persistent store

            +             + +

            CDictionaryStore

            +

            Dictionary store interface

            +             + +

            RStoreReadStream

            +

            Supports the opening and manipulation of an existing stream in a +store

            +             + +

            RStoreWriteStream

            +

            Supports the writing of a stream to a store

            +             + +

            RFileBuf

            +

            A stream buffer hosted by a file

            +             + + +
            +
            Typical uses

            A +typical use of stores is to write files to memory without using the file server. +This is a good thing to do when an application uses embedded documents.

            +             +Persistent +Storage Overview +File Stores +Overview +Store Streams + Overview +Streaming +Overview             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-337FA49D-DE53-5568-9A5C-D6AE3F25E0A6_d0e76412_href.png Binary file Symbian3/SDK/Source/GUID-337FA49D-DE53-5568-9A5C-D6AE3F25E0A6_d0e76412_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-337FA49D-DE53-5568-9A5C-D6AE3F25E0A6_d0e83124_href.png Binary file Symbian3/SDK/Source/GUID-337FA49D-DE53-5568-9A5C-D6AE3F25E0A6_d0e83124_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3382507E-1B21-418C-A908-DD3F688C0672-master.png Binary file Symbian3/SDK/Source/GUID-3382507E-1B21-418C-A908-DD3F688C0672-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3382507E-1B21-418C-A908-DD3F688C0672_d0e36608_href.png Binary file Symbian3/SDK/Source/GUID-3382507E-1B21-418C-A908-DD3F688C0672_d0e36608_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3382507E-1B21-418C-A908-DD3F688C0672_d0e42175_href.png Binary file Symbian3/SDK/Source/GUID-3382507E-1B21-418C-A908-DD3F688C0672_d0e42175_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3382507E-1B21-418C-A908-DD3F688C0672_d0e51756_href.png Binary file Symbian3/SDK/Source/GUID-3382507E-1B21-418C-A908-DD3F688C0672_d0e51756_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3382507E-1B21-418C-A908-DD3F688C0672_d0e57359_href.png Binary file Symbian3/SDK/Source/GUID-3382507E-1B21-418C-A908-DD3F688C0672_d0e57359_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3382507E-1B21-418C-A908-DD3F688C0672_d0e68090_href.png Binary file Symbian3/SDK/Source/GUID-3382507E-1B21-418C-A908-DD3F688C0672_d0e68090_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3382507E-1B21-418C-A908-DD3F688C0672_d0e69011_href.png Binary file Symbian3/SDK/Source/GUID-3382507E-1B21-418C-A908-DD3F688C0672_d0e69011_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3382507E-1B21-418C-A908-DD3F688C0672_d0e73223_href.png Binary file Symbian3/SDK/Source/GUID-3382507E-1B21-418C-A908-DD3F688C0672_d0e73223_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3382507E-1B21-418C-A908-DD3F688C0672_d0e74156_href.png Binary file Symbian3/SDK/Source/GUID-3382507E-1B21-418C-A908-DD3F688C0672_d0e74156_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3385079E-84F4-534F-B937-BD3A568D71BC.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-3385079E-84F4-534F-B937-BD3A568D71BC.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,110 @@ + + + + + +Password +Based Encryption (PBE) example code +

            This example covers:

            +
              +

            • Encrypting some data with a password and writing it to a file

              • +

            • Reading the data back from the file and decrypting it with the same password.

              • +
            +

            This example code is for reference only - it would be better to use:

            +
              +

            • Secure +stream example code

              • +

            • Secure +store example code

              • +
            +
            Encrypting +data with a password and writing it to a file
              +

            • Supporting +code for this example

              • +
            +void CPBEExample::WriteEncryptedDataL(const TDesC8& aInput, const TDesC& aFilename, const TDesC& aPassword) + { + // Open a stream to the output file + RFileWriteStream writeStream; + User::LeaveIfError(writeStream.Replace(iFs, aFilename, EFileShareExclusive | EFileWrite)); + CleanupClosePushL(writeStream); + + // Create a CPBEncryptElement object, passing details of the encryption we + // are using and the user's password + CPBEncryptElement* encryption = CPBEncryptElement::NewLC(aPassword, ECipherDES_CBC); + + // This is used to create a CPBEncryptor object + CPBEncryptor* encryptor = encryption->NewEncryptLC(); + + // Create a buffer of appropriate size to hold the ciphertext + HBufC8* ciphertextTemp = HBufC8::NewLC(encryptor->MaxFinalOutputLength(aInput.Length())); + TPtr8 ciphertext = ciphertextTemp->Des(); + + // Encrypt the input data into the ciphertext buffer + encryptor->ProcessFinalL(aInput, ciphertext); + + // Store encryption data. This contains details of the encryption used (e.g., + // cipher, key size) as well as things like the salt. This must be stored + // along with the encrypted data, otherwise it is not possible to decrypt it + // again! + writeStream << encryption->EncryptionData(); + + // Store the ciphertext + writeStream << ciphertext; + + // Commit the stream + writeStream.CommitL(); + + // Free memory (writeStream, encryption, encryptor, ciphertextTemp) + CleanupStack::PopAndDestroy(4, &writeStream); + } +
            +
            Reading data +from a file and decrypting it
              +

            • Supporting +code for this example

              • +
            +HBufC8* CPBEExample::ReadEncryptedDataLC(const TDesC& aFilename, const TDesC& aPassword) + { + // Open a stream to the input file + RFileReadStream readStream; + User::LeaveIfError(readStream.Open(iFs, aFilename, EFileRead)); + CleanupClosePushL(readStream); + + // Read the encryption data from the file + CPBEncryptionData* encryptionData = CPBEncryptionData::NewLC(readStream); + + // Recreate the CPBEncryptElement object, using the encryption data from the + // file and the user's password. This will leave with KErrBadPassphrase if + // the password is wrong. + CPBEncryptElement* encryption = CPBEncryptElement::NewLC(*encryptionData, aPassword); + + // This is used to create a CPBDecryptor object + CPBDecryptor* decryptor = encryption->NewDecryptLC(); + + // Read the ciphertext + HBufC8* ciphertext = HBufC8::NewLC(readStream, KMaxTInt); + + // Allocate a buffer for the plaintext (this will be returned to the caller) + HBufC8* plaintextBuf = HBufC8::NewLC(decryptor->MaxFinalOutputLength(ciphertext->Length())); + TPtr8 plaintext = plaintextBuf->Des(); + + // Decrypt the data + decryptor->ProcessFinalL(*ciphertext, plaintext); + + // Free memory (readStream, encryptionData, encryption, decryptor, ciphertext, plaintext) + CleanupStack::Pop(plaintextBuf); // don't free this + CleanupStack::PopAndDestroy(5, &readStream); + CleanupStack::PushL(plaintextBuf); + + // Return plaintext to the caller + return plaintextBuf; + } +
            +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-33D50AB9-AFA8-521F-8A85-031C24EA7D25.dita --- a/Symbian3/SDK/Source/GUID-33D50AB9-AFA8-521F-8A85-031C24EA7D25.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-33D50AB9-AFA8-521F-8A85-031C24EA7D25.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,113 +1,113 @@ - - - - - -Libxml2 -Overview -

            This section describes the libxml2 component which is a wrapper for the -standard libxml2 C library.

            -
            Purpose

            The libxml2 component provides XML processing, -parsing and validation APIs. You can call its C functions directly or use -the C++ wrapper.

            -
            Required background

            The libxml2 component is based -on the standard libxml2 library.

            -
            Architecture

            The libxml2 component is the core -of the XML collection. Two other components rely on it: the XML -Framework and the XML -DOM Engine.

            - Package diagram for the libxml2 component - -

            The libxml2 sub-component provides direct access to the C API of -the standard libxml2 library.

            The Utilities sub-component provides -object-oriented access to the C functions: it also implements the resource -management and error handling capabilities of the Symbian Platform.

            If -your Symbian Platform build does not include the libxml2 component, the XML -DOM Engine and the libxml2 SAX parser plug-in are automatically excluded.

            - -
            APIs

            The XMLEngPushL() function -opens and initializes the libxml2 library parser. The XMLEngPopAndClose() function -closes the library parser and frees its resources. You must call the XMLEngPushL() function -before any parsing and serialisation operations, and call the XMLEngPopAndClose() function -when these operations are completed.

            The following table lists the -most relevant wrapper classes of the libxml2 library. High-level classes are -in the XML DOM Engine component.

            - - - -API -Description - - - - -

            xmlGlobalState

            -

            Global data providing access to most of the libxml2 library: settings, -function pointers, and so on. Available through TLS

            -             - -

            TXmlEngString

            -

            General-purpose string: pointer-sized object containing a zero-terminated -UTF-8 string.

            -             - -

            TXmlEngConstString

            -

            Read-only version of TXmlEngString.

            -             - - -

            The following table lists the most relevant C structures of the -libxml2 library.

            - - - -API -Description - - - - -

            _xmlDoc

            -

            Document. Provides access to the tree of nodes.

            -             - -

            _xmlNode

            -

            Node. Provides access to its children and chain of attributes.

            -             - -

            _xmlAttribute

            -

            Attribute.

            -             - -

            _xmlElement

            -

            Element.

            -             - -

            xmlAttributeType::_xmlElementContent

            -

            Container for the contents of an element.

            -             - -

            _xmlSchema and _xmlDtd

            -

            Validation trees. These structures have no C++ wrappers.

            -             - -

            _xmlXPathParserContext

            -

            XPath evaluation context.

            -             - - -
            -
            Typical uses

            When porting existing software, use -the C functions of the standard libxml2 library and refer to the libxml2 Reference Manual for more information.

            To -take advantage of the standard types and exception handling provided by the -Symbian Platform, use the C++ APIs.

            -             -XML DOM Engine -error handling + + + + + +Libxml2 +Overview +

            This section describes the libxml2 component which is a wrapper for the +standard libxml2 C library.

            +
            Purpose

            The libxml2 component provides XML processing, +parsing and validation APIs. You can call its C functions directly or use +the C++ wrapper.

            +
            Required background

            The libxml2 component is based +on the standard libxml2 library.

            +
            Architecture

            The libxml2 component is the core +of the XML collection. Two other components rely on it: the XML +Framework and the XML +DOM Engine.

            + Package diagram for the libxml2 component + +

            The libxml2 sub-component provides direct access to the C API of +the standard libxml2 library.

            The Utilities sub-component provides +object-oriented access to the C functions: it also implements the resource +management and error handling capabilities of the Symbian Platform.

            If +your Symbian Platform build does not include the libxml2 component, the XML +DOM Engine and the libxml2 SAX parser plug-in are automatically excluded.

            + +
            APIs

            The XMLEngPushL() function +opens and initializes the libxml2 library parser. The XMLEngPopAndClose() function +closes the library parser and frees its resources. You must call the XMLEngPushL() function +before any parsing and serialisation operations, and call the XMLEngPopAndClose() function +when these operations are completed.

            The following table lists the +most relevant wrapper classes of the libxml2 library. High-level classes are +in the XML DOM Engine component.

            + + + +API +Description + + + + +

            xmlGlobalState

            +

            Global data providing access to most of the libxml2 library: settings, +function pointers, and so on. Available through TLS

            +             + +

            TXmlEngString

            +

            General-purpose string: pointer-sized object containing a zero-terminated +UTF-8 string.

            +             + +

            TXmlEngConstString

            +

            Read-only version of TXmlEngString.

            +             + + +

            The following table lists the most relevant C structures of the +libxml2 library.

            + + + +API +Description + + + + +

            _xmlDoc

            +

            Document. Provides access to the tree of nodes.

            +             + +

            _xmlNode

            +

            Node. Provides access to its children and chain of attributes.

            +             + +

            _xmlAttribute

            +

            Attribute.

            +             + +

            _xmlElement

            +

            Element.

            +             + +

            xmlAttributeType::_xmlElementContent

            +

            Container for the contents of an element.

            +             + +

            _xmlSchema and _xmlDtd

            +

            Validation trees. These structures have no C++ wrappers.

            +             + +

            _xmlXPathParserContext

            +

            XPath evaluation context.

            +             + + +
            +
            Typical uses

            When porting existing software, use +the C functions of the standard libxml2 library and refer to the libxml2 Reference Manual for more information.

            To +take advantage of the standard types and exception handling provided by the +Symbian Platform, use the C++ APIs.

            +             +XML DOM Engine +error handling             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-33D93E96-98A9-4116-9028-3241D76A1036.dita --- a/Symbian3/SDK/Source/GUID-33D93E96-98A9-4116-9028-3241D76A1036.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-33D93E96-98A9-4116-9028-3241D76A1036.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,76 +1,70 @@ - - - - - -Enabling -additional touch events for your applicationThe Symbian platform provides additional touch events to enable -drag events using CCoeControl::EnableDragEvents()and -to specify screen areas for touch events. -

            By default, the Symbian platform sends only EButton1Up and EButton1Down touch -events to applications.

            -

            If you want to enable EDrag touch events, implement CCoeControl::EnableDragEvents() in -your container class.

            -

            When the mobile device user drags the stylus on the screen, TPointerEvent::EDrag() events -are sent. When dragging stops, the application receives the event TPointerEvent::EButton1Up().

            -void CTableauControl::ConstructL( const TRect& aRect ) - { - // This is parent window - CreateWindowL(); - - EnableDragEvents(); - - //SetRect( aRect ); - SetExtentToWholeScreen(); - - - // Initialize component array - InitComponentArrayL(); - - - //Implement your own logic here - ActivateL(); - } -

            It is enough that the container control set EnableDragEvents() in -its construction. EnableDragEvents() need not be set again -for the child controls to receive dragging events.

            -
            Controlling -which control receives a touch event

            Particularly when you are receiving -drag events it may be that an object in the window may be drawn by one control, -while the pointer is over another control. In cases where you want to ensure -that pointer events are received by the intended control, implement CCoeControl::SetPointerCapture().

            When -a control receives a TPointerEvent::EButton1Down() event, -all events will be sent to this control until the next TPointerEvent::EButton1Up() event. -If you want to have events to be sent to another control before the TPointerEvent::EButton1Up() event, -call SetPointerCapture(ETrue) from the new control.

            When -the new control has received its pointer event and TPointerEvent::EButton1Up() has -been received, you have to call SetPointerCapture(EFalse) from -the new control to stop events being sent to it indefinitely.

            -
            Specifying -screen areas for touch events

            To specify screen areas (TRect) -for touch events, see the example below.

            void CTableauControl::HandlePointerEventL(const TPointerEvent& aPointerEvent) - { - // Does the user point exit text on screen? - // iExitRect is rectangle of the text area on screen. - if (iExitRect.Contains(aPointerEvent.iPosition)) - { - if (iEikonEnv->QueryWinL(_L("Klondike"),_L("Exit?"))) - { - // Exit was pointed, then do exit - (static_cast<CKlondikeAppUi*>(iEikonEnv->AppUi()))->HandleCommandL(EEikCmdExit); - return; - } - } - ... - }
            -
            Ignoring events -other than pointer up in your control

            In cases where you want to -make sure your control receives only touch EButton1Up events -after receiving a touch EButton1Down event, implement CCoeControl::IgnoreEventsUntilNextPointerUp().

            + + + + + +Enabling additional touch events for your applicationThe Symbian platform provides additional touch events to +enable drag events and to specify screen areas for touch events. +

            By default, the Symbian platform sends only EButton1Up and EButton1Down touch events to applications.

            +

            If you want to enable EDrag touch events, +implement CCoeControl::EnableDragEvents() in your +container class.

            +

            When the mobile device user drags the stylus on the screen, TPointerEvent::EDrag() events are sent. When dragging stops, +the application receives the event TPointerEvent::EButton1Up().

            +void CTableauControl::ConstructL( const TRect& aRect ) + { + // This is parent window + CreateWindowL(); + + EnableDragEvents(); + + SetRect( aRect ); + SetExtentToWholeScreen(); + + + // Initialize component array + InitComponentArrayL(); + + + //Implement your own logic here + ActivateL(); + } +

            It is enough that the container control set EnableDragEvents() in its construction. EnableDragEvents() need not +be set again for the child controls to receive dragging events.

            +
            Controlling +which control receives a touch event

            Particularly when you +are receiving drag events it may be that an object in the window may +be drawn by one control, while the pointer is over another control. +In cases where you want to ensure that pointer events are received +by the intended control, implement CCoeControl::SetPointerCapture().

            When a control receives a TPointerEvent::EButton1Down() event, all events will be sent to this control until the next TPointerEvent::EButton1Up() event. If you want to have +events to be sent to another control before theTPointerEvent::EButton1Up() event, call SetPointerCapture(ETrue) from the new +control.

            When the new control has received its pointer event +and TPointerEvent::EButton1Up() has been received, +you have to call SetPointerCapture(EFalse) from the +new control to stop events being sent to it indefinitely.

            +
            Specifying +screen areas for touch events

            To specify screen areas (TRect) for touch events, see the example below.

            void CTableauControl::HandlePointerEventL(const TPointerEvent& aPointerEvent) + { + // Does the user point exit text on screen? + // iExitRect is rectangle of the text area on screen. + if (iExitRect.Contains(aPointerEvent.iPosition)) + { + if (iEikonEnv->QueryWinL(_L("Klondike"),_L("Exit?"))) + { + // Exit was pointed, then do exit + (static_cast<CKlondikeAppUi*>(iEikonEnv->AppUi()))->HandleCommandL(EEikCmdExit); + return; + } + } + ... + }
            +
            Ignoring +events other than pointer up in your control

            In cases where +you want to make sure your control receives only touch EButton1Up events after receiving a touch EButton1Down event, implement CCoeControl::IgnoreEventsUntilNextPointerUp().

            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-341CE215-056C-45B6-ABE2-C75442605147_d0e62833_href.png Binary file Symbian3/SDK/Source/GUID-341CE215-056C-45B6-ABE2-C75442605147_d0e62833_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-347ACB44-5D07-5EA6-8751-E424A118859D_d0e131819_href.jpg Binary file Symbian3/SDK/Source/GUID-347ACB44-5D07-5EA6-8751-E424A118859D_d0e131819_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-347ACB44-5D07-5EA6-8751-E424A118859D_d0e138353_href.jpg Binary file Symbian3/SDK/Source/GUID-347ACB44-5D07-5EA6-8751-E424A118859D_d0e138353_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3490A064-8421-4ABB-9E93-99A5565CF4D7.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-3490A064-8421-4ABB-9E93-99A5565CF4D7.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,62 @@ + + + + + +Additional +Connection PreferencesExtended Connection Preferences API allows applications to set +a few additional preferences that customize the connection establishment. +These preferences, when used with specific SNAP ID, SNAP Type , IAP or connection +selection dialog enable the applications to have more control on the connection. +

            The additional +connection preferences that can be set using the Extended Connection +Preferences API are listed below. One or more of the preferences can be set +based on connection establishment requirements. For more details on the restrictions +regarding the preferences that can be used jointly, refer TExtendedConnPref .

             + +Define Bearer +Filtering +

            Extended Connection Preferences API allows the application to limit +the used bearers.

            In the below example, only WLAN bearer is allowed.

            preferences.SetBearerSet( TExtendedConnPref::EExtendedConnBearerWLAN ); +             +             +Disallow Automatic +Bearer Switching +

            The established connection can be broken by the middleware when a +better connection is available. For example, when a known WLAN IAP is available, +the established 3G connection is disconnected. This is also known as Forced +Roaming. Forced Roaming is enabled by default.

            The sudden disconnection +can be disabled by the applications prior to connection establishment.

            preferences.SetForcedRoaming( EFalse );

            Forced +roaming applies only on connections made to the Internet SNAP.

             +             +Inform middleware +that application handles contention +

            When there are multiple active connections and there is a requirement +for a new connection , the list of active connections are displayed and the +user selects the connection to be disconnected. This accommodates the new +connection request to be processed.

            If the Disconnect dialog is disabled, +the contention situation is not exposed to the user and the application handles + the contention by itself.

            preferences.SetDisconnectDialog( EFalse );             +             +Disable connecting +soft notes and Queries +

            During connection establishment , pop-ups(soft notes) indicate the +state of the connection providing visibility and cost awareness to the user. +The application can disable these soft notes using the Extended Connection +Preferences API.

            The application can start a connection and roam between +different bearers without any notes about connection state shown to the user.

            preferences.SetNoteBehaviour( TExtendedConnPref::ENoteBehaviourConnDisableNotes );

            The application can start a connection and roam between different bearers +without displaying any queries to the user but inform the user on the events +with dialogs or notes. The user is able to see the notes about connection +state. Queries that need user confirmation are not exposed to the user.

            preferences.SetNoteBehaviour( TExtendedConnPref::ENoteBehaviourConnDisableQueries ); +

            The application can start a connection and roam between different +bearers without any queries, dialogs or notes. The connection state details +are not exposed to the user.

            preferences.SetNoteBehaviour( TExtendedConnPref::ENoteBehaviourConnSilent );             +             +             +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-34BEF44B-EFBE-41EB-941D-0410FCB6782E.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-34BEF44B-EFBE-41EB-941D-0410FCB6782E.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,61 @@ + + + + + +Extended +Connection PreferencesThe Extended Connection Preferences API provides customized control +over the connection establishment process followed by the applications. +
            Purpose

            The Extended Connection Preferences +API is used to control and customize the connection establishment behavior +of applications. The API handles applications with special needs in connectivity +accordingly. For example, connection to a specific SNAP or connection +to a specific IAP so on. Many applications do not need a customized connection +establishment process and hence, usage of this API is not needed by majority +of applications.

            +
            Required Background

            The extended connection preferences +are passed to RConnection::Start() function as part of TConnPrefList object.

            The +user of the API should link against extendedconnpref.lib and netmeta.lib +and include the header file, extendedconnpref.h.

            +
            API Summary

            The API defines extended connection +preferences as a set of parameters. The class that handles the preference +parameters is described below:

            + + + +Class Name +Description + + + TExtendedConnPref +

            Is derived from SMetaDataECom and defines the +functions that set the preferences for a customized connection.

             +             + + +
            +
            Architectural Relationships +Class Relationships for TExtendedConnPref + +
            +
            Typical Uses

            The API provides the following key +services:

              +

            • Open a connection to a specific Service Network Access Point (SNAP) +(By specifying Type)

              • +

            • Open a connection to a specific SNAP (By specifying the SNAP ID)

              • +

            • Open a connection to a specific Internet Access Point (IAP)

              • +

            • Open a connection by querying the connection method from the user

              • +

            • Open a connection without the discreet pop-ups

              • +

            • Open a connection without any queries

              • +

            • Disallow automatic switch to Wireless Local Area Network (WLAN)

              • +

            • Bearer filtering

              • +

            • Inform middleware that application handles contention

              • +
            +
            See also
            +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-352850A9-227F-45DB-8DCD-C6268954B4ED.dita --- a/Symbian3/SDK/Source/GUID-352850A9-227F-45DB-8DCD-C6268954B4ED.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-352850A9-227F-45DB-8DCD-C6268954B4ED.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,62 +1,62 @@ - - - - - -Window -owning and non-window owning controls -
            Window-owning -controls -

            Window-owning controls have the same size and position as a window in -the display. Each window has a one-to-one relationship with the control that -covers it, and shares its behavior with that control.

            -

            Examples of window-owning controls include:

            -
              -

            • top-level control in Traditional -Symbian platform architecture

              • -

            • the sub-panes in the status pane

              • -

            • pop-up windows, when a sense of layering is required

              -
              • -
            -

            The following code snippet is an example of the second phase construction -of a window-owning control:

            -CMyControl::ConstructL() - { - CreateWindowL(); // This makes the control window- - // owning - SetRectL(ClientRect()); // This sets the control’s - // size - ActivateL(); // This must be called before - // the control can be drawn - } - -

            CEikAppUi::ClientRect() returns the screen area -available to the application for drawing. This typically does not include -the space that is reserved for the status/control panes.

            -

            For more information, see The -run-time control hierarchy

            -
            -
            Non-window-owning -controls -

            Non-window-owning controls typically cover only part of a window on -the display, and must be contained in window-owning controls. They are faster -and require fewer resources than window-owning controls.

            -

            Examples of non-window-owning controls include:

            -
              -

            • command buttons

              • -

            • edit windows

              • -

            • labels

              • -
            -

            Non-window-owning controls are assigned to window-owning controls by -calling CCoeControl::SetContainerWindowL() when the control -is constructed.

            -

            For more information, see The -run-time control hierarchy

            -
            + + + + + +Window +owning and non-window owning controls +
            Window-owning +controls +

            Window-owning controls have the same size and position as a window in +the display. Each window has a one-to-one relationship with the control that +covers it, and shares its behavior with that control.

            +

            Examples of window-owning controls include:

            +
              +

            • top-level control in Traditional +Symbian platform architecture

              • +

            • the sub-panes in the status pane

              • +

            • pop-up windows, when a sense of layering is required

              +
              • +
            +

            The following code snippet is an example of the second phase construction +of a window-owning control:

            +CMyControl::ConstructL() + { + CreateWindowL(); // This makes the control window- + // owning + SetRectL(ClientRect()); // This sets the control’s + // size + ActivateL(); // This must be called before + // the control can be drawn + } + +

            CEikAppUi::ClientRect() returns the screen area +available to the application for drawing. This typically does not include +the space that is reserved for the status/control panes.

            +

            For more information, see The +run-time control hierarchy

            +
            +
            Non-window-owning +controls +

            Non-window-owning controls typically cover only part of a window on +the display, and must be contained in window-owning controls. They are faster +and require fewer resources than window-owning controls.

            +

            Examples of non-window-owning controls include:

            +
              +

            • command buttons

              • +

            • edit windows

              • +

            • labels

              • +
            +

            Non-window-owning controls are assigned to window-owning controls by +calling CCoeControl::SetContainerWindowL() when the control +is constructed.

            +

            For more information, see The +run-time control hierarchy

            +
             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3542A39C-8D0F-53A0-A5A2-81F381D3BA7B_d0e315024_href.png Binary file Symbian3/SDK/Source/GUID-3542A39C-8D0F-53A0-A5A2-81F381D3BA7B_d0e315024_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3542A39C-8D0F-53A0-A5A2-81F381D3BA7B_d0e321418_href.png Binary file Symbian3/SDK/Source/GUID-3542A39C-8D0F-53A0-A5A2-81F381D3BA7B_d0e321418_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-35521A99-3F1F-5EE1-8078-FFD8A298C0BD_d0e192564_href.png Binary file Symbian3/SDK/Source/GUID-35521A99-3F1F-5EE1-8078-FFD8A298C0BD_d0e192564_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-35521A99-3F1F-5EE1-8078-FFD8A298C0BD_d0e197572_href.png Binary file Symbian3/SDK/Source/GUID-35521A99-3F1F-5EE1-8078-FFD8A298C0BD_d0e197572_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3560E862-CB68-584F-B9B6-FCD9F0D202DC_d0e254247_href.png Binary file Symbian3/SDK/Source/GUID-3560E862-CB68-584F-B9B6-FCD9F0D202DC_d0e254247_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3560E862-CB68-584F-B9B6-FCD9F0D202DC_d0e257954_href.png Binary file Symbian3/SDK/Source/GUID-3560E862-CB68-584F-B9B6-FCD9F0D202DC_d0e257954_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-356B54BB-E389-5562-A2D9-80A472EAC9A3_d0e7042_href.png Binary file Symbian3/SDK/Source/GUID-356B54BB-E389-5562-A2D9-80A472EAC9A3_d0e7042_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-356B54BB-E389-5562-A2D9-80A472EAC9A3_d0e8317_href.png Binary file Symbian3/SDK/Source/GUID-356B54BB-E389-5562-A2D9-80A472EAC9A3_d0e8317_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-358412B8-8B98-419F-99E6-28A01ED99B79_d0e3705_href.png Binary file Symbian3/SDK/Source/GUID-358412B8-8B98-419F-99E6-28A01ED99B79_d0e3705_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-358412B8-8B98-419F-99E6-28A01ED99B79_d0e4980_href.png Binary file Symbian3/SDK/Source/GUID-358412B8-8B98-419F-99E6-28A01ED99B79_d0e4980_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-35E9F104-95F7-511F-B0C5-AB64BCA972D0.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-35E9F104-95F7-511F-B0C5-AB64BCA972D0.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,167 @@ + + + + + +Asymmetric +ciphers -- guide +
              +

            • What is asymmetric cryptography?

              • +

            • Types of asymmetric algorithms supported

              • +

            • Base classes and their derived classes

              • +
            +
            What is asymmetric +cryptography?

            Asymmetric ciphers, unlike symmetric ciphers, are +algorithms that involve the use of two keys: a private key and a public key. +The private key is kept secret, while the public key is made publicly available. +For schemes which are thought to be secure, it is believed that deriving the +private key from the public key, or any transformation resulting from the +public key, is computationally infeasible.

            This type of algorithm generates +the keys as key pairs. This means that if one key in the pair is used to encrypt +some data, only the other key can decrypt it, and vice versa.

            +The diagram above shows the encryption and decryption process using: +an asymmetric algorithm; a plaintext message, M; a private key, K1, and a +public key, K2 (or vice versa); and the ciphertext, K1(M). + +

            Although it varies depending on the specific algorithm, the generation +of asymmetric keys is much slower than symmetric key generation.

            There +are four basic primitives in asymmetric cryptography: encryption and decryption, +and signing and verification.

            Encryption +schemes

            In order to encrypt a message with an asymmetric scheme, +one performs a well-known transformation on the message using the public key +of the intended recipient. Upon receipt, the receiver can decrypt this message +using the inverse transformation and the associated private key. Provided +that only the intended recipient knows the associated private key, it is believed +that message secrecy between the sender and receiver is achieved.

            Signature schemes

            Conversely, +in order to digitally sign a message with an asymmetric scheme, one performs +another well-known transformation on the message using one's own private key. +Both the original message and the resulting transformation are sent to the +intended recipient. Upon receipt, the receiver can verify that the message +was signed by the associated private key by performing the inverse operation +with the public key as input, and then comparing the received message with +the message obtained from the transformation of the signature.

            +
            Types of asymmetric +algorithms supported

            The following asymmetric algorithms are supported:

            + + + +

            Asymmetric algorithm

             +

            What it's used for

             +

            Specified in:

             +             + + + +

            RSA

            +

            both encryption and digital signatures

            +

            PKCS#1 v1.5

            +             + +

            DSA (Digital Signature Algorithm)

            +

            signing data

            +

            FIPS 186-2 CR1

            +             + +

            DH (Diffie-Hellman)

            +

            secure exchange of keys between two parties

            +

            PKCS#3

            +             + + +

            RSA

            The +Cryptography library allows support for RSA as specified in PKCS#1 v1.5. The library does not, in and of itself, +fulfil all the requirements of PKCS#1 v1.5. This is because the Cryptography +library’s modular design allows applications utilizing it to provide their +own mechanisms of certain operations. At minimum, signature input data (be +prepared in compliance with PKCS#1 v1.5) must be provided by applications +in order to support PKCS#1 v1.5.

              +

            • Private Key Encryption and Decryption

              RSA private keys +provide functionality for encrypting and decrypting data with the private +key. Encrypting with the private key is typically used in signature generation +while decrypting would be used for key exchange or confidentiality of other +small amounts of data.

              The basic mathematics involved in the encryption +and decryption is identical, the differences lay with the handling of padding; +encryption adds padding while decryption removes and checks it.

              • +

            • Padding

              For padding the existing PKCS#1 padding mechanism +is used. However, this interface allows the use of any defined padding mechanism.

              • +

            • Key Generation

              Before any private keys can be used they +need to be generated. They can be generated on the device or generated elsewhere.

              An +RSA modulus takes the form of the product of a pair of large prime numbers, +which will be generated randomly and considered prime if they pass a probabilistic +primality test (where the chance of claiming a non-prime is prime is less +than 1 in 230). This generation process can be rather long-winded, +even for relatively small keys.

              While there is no actually limit on +RSA modulus sizes, for most applications they range from 512 bits to 4096 +bits.

              • +

            DSA

            The +Cryptography library allows support for NIST Digital Signature Standard (DSS) +as specified in FIPS 186-2 change request 1. The standard specifies +DSA as the algorithm for digital signatures and SHA-1 for hashing. At minimum, +the following items must be provided by applications using the library in +order to be fully compliant:

              +

            • Signature input data +must be hashed with SHA-1 as specified in FIPS 180-1.

              or should it be

              Signature +input data must be hashed with SHA-1 as specified in FIPS 180-2.

              • +

            • A FIPS-186-2 CR 1 compliant +random number generator must be supplied. The library provides a mechanism +for using such a random number generator if required.

              • +

            • For backwards compatibility +reasons, the Cryptography library continues to allow prime moduli of less +than 1024 bits to be used. If an application wanted to be fully compliant +with the FIPS 186-2 CR1, it should refuse to submit requests to the Cryptography +library to sign data with a prime modulus of less than 1024 bits.

              • +

            The following are some important features of DSA:

              +

            • Key Generation

              DSA keys have an associated set of parameters, +these parameters are generally public and used across a community of users. +If some parameters are supplied the key generation will use those parameters +or it will generate a set if there are none supplied.

              • +

            • Parameter Generation

              Parameter generation for DSA keys +is implemented as specified in FIPS-186.

              • +

            Diffie-Hellman (DH)

            The Cryptography library +supports Diffie-Hellman as specified in PKCS#3. Note that due to security concerns and a serious +lack of interoperable implementations, the library does not support DH parameter +generation. It is up to the application using the DH implementation to ensure +that they trust the source of the parameters they intend to use for a DH key +exchange.

            +
            Base classes +and their derived classes

            The asymmetric cipher API is used by +the certman (certitificate management) component for WTLS and X.509 certificate +support and by appinst for SIS file signature verification. It is also used +by Networking (TLS/IPSec).

            CRSAParameters, CDSAParameters, +and CDHParameters are the base classes that allow a client +to use the supported asymmetric algorithms listed above. The classes hold +the domain parameters used by the public key algorithms. They are used by +some of the asymmetric algorithms to define some common mathematical structures +used by the encryption or signature processes.

            The diagrams below +show the main classes used in asymmetric cipher framework. Blue dotted arrows +indicate that a class is contained or used by another class. The arrows are +labelled with the variable(s) through which the pointed class is accessible. +The color of the boxes indicates the type of Symbian class, i.e., M, C, R or T class. For detailed information on each component see the Cryptography API +Reference material.

            RSA, padding and associated classes

            +The inheritance diagram above shows the <codeph>RInteger</codeph> and <codeph>CRSAParameters</codeph> classes, +and also the <codeph>CEncryptor</codeph>, <codeph>CDecryptor</codeph> and <codeph>CPadding</codeph> abstract +classes. Also shown are the following classes from the Cryptography API: <codeph>TInteger</codeph>, <codeph>MCryptoSystem</codeph>, <codeph>CRSAPKCS1v15Decryptor</codeph>, <codeph>CRSAPKCS1v15Encryptor</codeph>, <codeph>CRSAPrivateKey</codeph>, <codeph>CRSAPublicKey</codeph>, <codeph>CRSAPrivateKeyStandard</codeph>, <codeph>CRSAPrivateKeyCRT</codeph>, <codeph>CRSAKeyPair</codeph>, <codeph>CPaddingPKCS7</codeph>, <codeph>CPaddingPKCS1Encryption</codeph>, <codeph>CPaddingNone</codeph>, <codeph>CPaddingPKCS1Signature</codeph>, and <codeph>CPaddingSSLv3</codeph>. + + + +The inheritance diagram above shows the <codeph>CRSASigner</codeph> and <codeph>CRSAVerifier</codeph> classes. +Also shown are the following classes from the Cryptography API: <codeph>MSignatureSystem</codeph>, <codeph>CSigner</codeph>, <codeph>CRSAPKCS1v15Signer</codeph>, <codeph>CRSAParameters</codeph>, <codeph>CRSAPrivateKey</codeph>, <codeph>CRSAPublicKey</codeph>, <codeph>CPadding</codeph>, <codeph>CPaddingPKCS1Signature</codeph>, <codeph>CVerifier</codeph>, and <codeph>CRSAPKCS1v15Verifier</codeph>. + + +

            DSA and associated classes

            +The inheritance diagram above shows the <codeph>CDSAParameters</codeph> class. +Also shown are the following classes from the Cryptography API: <codeph>MSignatureSystem</codeph>, <codeph>TInteger</codeph>, <codeph>RInteger</codeph>, <codeph>CSigner</codeph>, <codeph>CDSASigner</codeph>, <codeph>CDSASignature</codeph>, <codeph>CDSAPrimeCertificate</codeph>, <codeph>CDSAKeyPair</codeph>, <codeph>CDSAPrivateKey</codeph>, <codeph>CDSAPublicKey</codeph>, <codeph>CVerifier</codeph>, +and <codeph>CDSAVerifier</codeph>. + +

            DH and associated classes

            + The inheritance diagram above shows the <codeph>CDHParameters</codeph> class. +Also shown are the following classes from the Cryptography API: <codeph>TInteger</codeph>, <codeph>RInteger</codeph>, <codeph>CDHPrivateKey</codeph>, <codeph>CDHPublicKey</codeph>, <codeph>CDH</codeph>, and <codeph>CDHKeyPair</codeph>. + +
            +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-361BB951-DB74-4D83-ACFC-812383C8129C.dita --- a/Symbian3/SDK/Source/GUID-361BB951-DB74-4D83-ACFC-812383C8129C.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-361BB951-DB74-4D83-ACFC-812383C8129C.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,45 +1,45 @@ - - - - - -Activating -items in a listThis document describes the code changes required to activate items -in a list on single-tap. - -Replace the EEventItemDoubleClicked event -with EEventItemSingleClicked. Remove the EEventItemClicked processing -code if any. -

            The following code snippet illustrates the changes to the event -handling code of a File Browser application.

            // ---------------------------------------------------------------------------- -// CFileBrowseBaseView::HandleListBoxEventL -// -// If single-tap is enabled, the touch related events must be handled here -// ---------------------------------------------------------------------------- -// -void CFileBrowseBaseView::HandleListBoxEventL(CEikListBox* /*aListBox*/, TListBoxEvent aEventType) - { - if(AknLayoutUtils::PenEnabled()) - { - switch (aEventType) - { - //case EEventItemDoubleClicked: ----- Remove this code-------------- - case EEventItemSingleClicked: //------- Include this new event for item activation--- - { - NavigateL(iListBox->CurrentItemIndex()); // user defined function for navigating to the selected folder - OpenFolderL(); // user defined function for opening the selected folder - break; - } - } - } -} -             -             -             + + + + + +Activating +items in a listThis document describes the code changes required to activate items +in a list on single-tap. + +Replace the EEventItemDoubleClicked event +with EEventItemSingleClicked. Remove the EEventItemClicked processing +code if any. +

            The following code snippet illustrates the changes to the event +handling code of a File Browser application.

            // ---------------------------------------------------------------------------- +// CFileBrowseBaseView::HandleListBoxEventL +// +// If single-tap is enabled, the touch related events must be handled here +// ---------------------------------------------------------------------------- +// +void CFileBrowseBaseView::HandleListBoxEventL(CEikListBox* /*aListBox*/, TListBoxEvent aEventType) + { + if(AknLayoutUtils::PenEnabled()) + { + switch (aEventType) + { + //case EEventItemDoubleClicked: ----- Remove this code-------------- + case EEventItemSingleClicked: //------- Include this new event for item activation--- + { + NavigateL(iListBox->CurrentItemIndex()); // user defined function for navigating to the selected folder + OpenFolderL(); // user defined function for opening the selected folder + break; + } + } + } +} +             +             +                         \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-36221068-4E6D-4E03-AF9A-AD9465F1C6B6-master.png Binary file Symbian3/SDK/Source/GUID-36221068-4E6D-4E03-AF9A-AD9465F1C6B6-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-36221068-4E6D-4E03-AF9A-AD9465F1C6B6_d0e63652_href.png Binary file Symbian3/SDK/Source/GUID-36221068-4E6D-4E03-AF9A-AD9465F1C6B6_d0e63652_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3637DBF8-BABF-4F84-9A7D-8FF66A118261_d0e64475_href.png Binary file Symbian3/SDK/Source/GUID-3637DBF8-BABF-4F84-9A7D-8FF66A118261_d0e64475_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3637DBF8-BABF-4F84-9A7D-8FF66A118261_d0e65306_href.png Binary file Symbian3/SDK/Source/GUID-3637DBF8-BABF-4F84-9A7D-8FF66A118261_d0e65306_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-36539894-580E-5774-AA79-7F640E8C59E1.dita --- a/Symbian3/SDK/Source/GUID-36539894-580E-5774-AA79-7F640E8C59E1.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-36539894-580E-5774-AA79-7F640E8C59E1.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,150 +1,159 @@ - - - - - -Central -Repository Initialisation Files GuideThis topic describes the concepts of initialisation files used -by the Central Repository. -
            Initialisation file properties

            The mechanisms of -key spaces, capabilities and SIDs are used to write the content of an initialisation -file.

            Owner

            The owner of a repository (the application responsible -for backing it up) is identified by its SID. Example:

            -[owner] -0x12345 -

            Metadata

            Settings of a repository are given values and also -metadata values. The Default Metadata section of a repository gives the settings -global default metadata values which may be overridden by individual metadata -values assigned in the Main section. A metadata value is held as a 32 bit -integer whose binary digits encode separate items of metadata. The most significant -eight bits (most significant byte) of the integer are reserved for internal -purposes. The other 24 bits of the integer have no reserved significance. -Two of the eight bits are exposed for use by application developers.

              -

            • The least significant -bit of the most significant byte is set to 1 to indicate that a backup operation -applies to the setting.

              • -

            • The second least significant -bit of the most significant byte is set to 1 to indicate that a restore factory -settings operation applies to the setting.

              • -

            What is meant by least and most significant? An example may help. -A hexadecimal number such as 03020100 is stored as a single 32 bit integer. -The integer can be analysed as a sequence of four bytes:

            03 02 01 -00

            The leftmost byte, 03, is the most significant byte because it -represents a larger quantity (03000000) than the other three (02000, 0100 -and 00). Each byte consists of eight bits. In binary notation they are

            00000011 -00000010 00000001 00000000

            The rightmost bit of the leftmost byte -is the least significant bit of the most significant byte because it represents -a smaller quantity (1) than its neighbour to the left (10) which is the second -least significant bit of the most significant byte. These are the two exposed -bits of the metadata value and the hexadecimal integer 03020100 has both of -them set to 1. The 32 bits are sometimes referred to by number (32 for the -leftmost down to 1 for the rightmost): thus the exposed bits are also called -bits 26 and 25.

            Global default metadata values consist simply of a -32 bit integer. Default metadata values can also be applied to a range of -settings by prefixing either a pair of keys representing a continuous range, -or else a partial key and a key mask prefixed by "mask=". Example:

            -[defaultMeta] -0x00000010 -0x100 0x400 0x00000020 -0x1000 mask = 0x04 0x00000040 -
            -
            Access policies

            An access policy grants read or -write permissions on a setting or a group of settings to an application or -a group of applications. Applications are identified by their SID and groups -of applications by their capability name.

            Decide which applications -you want to grant permissions to, and whether you are going to identify them -by capability or SID. SIDs are unsigned integers which identify an application -and are assigned by Symbian Signed. Identify the settings and groups of settings -which are to be written and read: you will need their keys and partial keys. -Determine which applications need read or write permissions on which settings.

            You -create an access policy by combining these elements using the following syntax.

              -

            • A capname is one of -'TCB' 'CommDD' etc. A caplist is two or -three capnames separated by a comma and whitespace. A read caps statement -is "cap_rd" followed by a capname or a caplist.

              • -

            • A read sid statement -is "sid_rd " followed by an SID.

              • -

            • A read policy is a read -sid statement or a read caps statement or one of each separated by whitespace. -A write policy is the same as a read policy with "_wr" instead of "_rd". An -access policy is a read policy or a write policy or one of each separated -by whitespace.

              • -

            • Instead of granting -or denying permissions to specified applications, you can create global permissions -by using the words 'AlwaysPass' or 'AlwaysFail' in place of an SID. For instance, -'sid_rd AlwaysPass' grants read permissions to all applications, 'sid_wr AlwaysFail' -denies write permissions to all applications and so on.

              • -

            An access policy constructed on these lines with no further qualification -creates permissions on all the settings in a repository (this is called a -default policy). To create permissions on individual settings (a single policy) -or a group of settings (a range policy or a mask policy depending on implementation) -we use the keys of those settings.

              -

            • A single policy is a -default policy prefixed with a key referring to a single setting.

              • -

            • A range policy is a -default policy prefixed with two keys, the lowerkey and the upperkey. The -policy assigns permissions on all settings with keys between the lowerkey -and the upperkey inclusively.

              • -

            • A mask policy is an -access policy prefixed with a partial key and then "mask=" and a keymask.

              • -

            • A custom policy is a -single policy, a range policy or a mask policy. A policy list is a custom -policy or several custom policies separated by whitespace.

              • -

            We have now defined the structure of the access policy section of -an initialisation file. It consists of a line reading "[PlatSec]" followed -by a default policy or a policy list or one of each separated by whitespace. -Where several policies in a list apply to the same key, the later policy overrides -the earlier. The read policies, each on a separate line, must precede the -write policies, each on a separate line.

            -
            Initial values

            Initial values are assigned to -settings in the Main section of an initialisation file. Each line begins with -a setting identified by an individual key or a group of settings identified -by a pair of keys representing a range or else a keymask and a partial key. -Following the key or keys comes the data type of the setting, one of int, real, -string, string8 or binary. Next comes the -actual initial value of the setting and finally, as an optional item, the -metadata value of the setting. Example:

            -[main] - -1 int 1 0 -2 real 2.732 0xa -5 string "test\\\"string\"" 2 -6 int 12 0xf -8 real 1.5 1 -11 string string 0x305 -12 string8 string 0x305 - -0x11 real 1.5 12 -0x101 int 100 0 -
            -
            Initialisation -file format

            You use an initialisation file to register a repository -by saving it to device memory. Ideally you do this at ROM build time and save -to the directory z:\private\10202BE9\ (this is the Central -Repository directory, named after its UID). It is also possible to register -a repository after build time using the Symbian Software Installer to save -it to the C drive. This process requires a signed SIS file and is explained -below. In either case, the file name of the repository is the same as its -UID.

            A repository may be saved to memory as a text file. The encoding -must be UTF-16, no other format being supported. However, you are recommended -to convert this text file to binary format and save the binary to device memory -for reasons of performance. Retrieval times are an order of magnitude faster -using binary files. You convert text to binary with the tool CentRepConv.exe -as documented in CenRep Converter -Tool Tutorial. CentRepConv.exe can also be used to convert binary files -back to text format (in a slightly lossy way due to differences in the specification -of the two formats).

            -             -Central Repository - Overview -Central Repository -Guide -CenRep Converter -Tool Tutorial + + + + + +Central Repository Initialisation Files GuideThis topic describes the concepts of initialisation files +used by the Central Repository. +
            Initialisation +file properties

            The mechanisms of key spaces, capabilities +and SIDs are used to write the content of an initialisation file.

            Owner

            The owner of a repository (the application +responsible for backing it up) is identified by its SID. Example:

            +[owner] +0x12345 +

            Metadata

            Settings of a repository are given values +and also metadata values. The Default Metadata section of a repository +gives the settings global default metadata values which may be overridden +by individual metadata values assigned in the Main section. A metadata +value is held as a 32 bit integer whose binary digits encode separate +items of metadata. The most significant eight bits (most significant +byte) of the integer are reserved for internal purposes. The other +24 bits of the integer have no reserved significance. Two of the eight +bits are exposed for use by application developers.

              +

            • The least significant +bit of the most significant byte is set to 1 to indicate that a backup +operation applies to the setting.

              • +

            • The second least +significant bit of the most significant byte is set to 1 to indicate +that a restore factory settings operation applies to the setting.

              • +

            What is meant by least and most significant? An example may +help. A hexadecimal number such as 03020100 is stored as a single +32 bit integer. The integer can be analysed as a sequence of four +bytes:

            03 02 01 00

            The leftmost byte, 03, is the most +significant byte because it represents a larger quantity (03000000) +than the other three (02000, 0100 and 00). Each byte consists of eight +bits. In binary notation they are

            00000011 00000010 00000001 +00000000

            The rightmost bit of the leftmost byte is the least +significant bit of the most significant byte because it represents +a smaller quantity (1) than its neighbour to the left (10) which is +the second least significant bit of the most significant byte. These +are the two exposed bits of the metadata value and the hexadecimal +integer 03020100 has both of them set to 1. The 32 bits are sometimes +referred to by number (32 for the leftmost down to 1 for the rightmost): +thus the exposed bits are also called bits 26 and 25.

            Global +default metadata values consist simply of a 32 bit integer. Default +metadata values can also be applied to a range of settings by prefixing +either a pair of keys representing a continuous range, or else a partial +key and a key mask prefixed by "mask=". Example:

            +[defaultMeta] +0x00000010 +0x100 0x400 0x00000020 +0x1000 mask = 0x04 0x00000040 +
            +
            Access +policies

            An access policy grants read or write permissions +on a setting or a group of settings to an application or a group of +applications. Applications are identified by their SID and groups +of applications by their capability name.

            Decide which applications +you want to grant permissions to, and whether you are going to identify +them by capability or SID. SIDs are unsigned integers which identify +an application and are assigned by Symbian Signed. Identify the settings +and groups of settings which are to be written and read: you will +need their keys and partial keys. Determine which applications need +read or write permissions on which settings.

            You create an +access policy by combining these elements using the following syntax.

              +

            • A capname is +one of 'TCB' 'CommDD' etc. A caplist +is two or three capnames separated by a comma and whitespace. A read +caps statement is "cap_rd" followed by a capname or a caplist.

              • +

            • A read sid statement +is "sid_rd " followed by an SID.

              • +

            • A read policy +is a read sid statement or a read caps statement or one of each separated +by whitespace. A write policy is the same as a read policy with "_wr" +instead of "_rd". An access policy is a read policy or a write policy +or one of each separated by whitespace.

              • +

            • Instead of granting +or denying permissions to specified applications, you can create global +permissions by using the words 'AlwaysPass' or 'AlwaysFail' in place +of an SID. For instance, 'sid_rd AlwaysPass' grants read permissions +to all applications, 'sid_wr AlwaysFail' denies write permissions +to all applications and so on.

              • +

            An access policy constructed on these lines with no further +qualification creates permissions on all the settings in a repository +(this is called a default policy). To create permissions on individual +settings (a single policy) or a group of settings (a range policy +or a mask policy depending on implementation) we use the keys of those +settings.

              +

            • A single policy +is a default policy prefixed with a key referring to a single setting.

              • +

            • A range policy +is a default policy prefixed with two keys, the lowerkey and the upperkey. +The policy assigns permissions on all settings with keys between the +lowerkey and the upperkey inclusively.

              • +

            • A mask policy +is an access policy prefixed with a partial key and then "mask=" and +a keymask.

              • +

            • A custom policy +is a single policy, a range policy or a mask policy. A policy list +is a custom policy or several custom policies separated by whitespace.

              • +

            We have now defined the structure of the access policy section +of an initialisation file. It consists of a line reading "[PlatSec]" +followed by a default policy or a policy list or one of each separated +by whitespace. Where several policies in a list apply to the same +key, the later policy overrides the earlier. The read policies, each +on a separate line, must precede the write policies, each on a separate +line.

            +
            Initial +values

            Initial values are assigned to settings in the +Main section of an initialisation file. Each line begins with a setting +identified by an individual key or a group of settings identified +by a pair of keys representing a range or else a keymask and a partial +key. Following the key or keys comes the data type of the setting, +one of int, real, string, string8 or binary. Next comes the actual +initial value of the setting and finally, as an optional item, the +metadata value of the setting. Example:

            +[main] + +1 int 1 0 +2 real 2.732 0xa +5 string "test\\\"string\"" 2 +6 int 12 0xf +8 real 1.5 1 +11 string string 0x305 +12 string8 string 0x305 + +0x11 real 1.5 12 +0x101 int 100 0 +
            +
            Initialisation +file format

            You use an initialisation file to register +a repository by saving it to device memory. Ideally you do this at +ROM build time and save to the directory z:\private\10202BE9\ (this is the Central Repository directory, named after its UID). +It is also possible to register a repository after build time using +the Symbian Software Installer to save it to the C drive. This process +requires a signed SIS file and is explained below. In either case, +the file name of the repository is the same as its UID.

            A +repository may be saved to memory as a text file. The encoding must +be UTF-16, no other format being supported. However, you are recommended +to convert this text file to binary format and save the binary to +device memory for reasons of performance. Retrieval times are an order +of magnitude faster using binary files. You convert text to binary +with the tool CentRepConv.exe as documented in CenRep Converter +Tool Tutorial. CentRepConv.exe can also be used to convert +binary files back to text format (in a slightly lossy way due to differences +in the specification of the two formats).

            +             +Central +Repository Overview +Central +Repository Guide +CenRep +Converter Tool Tutorial             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-36BB14BD-34B3-4F5D-A670-707710E57585_d0e36549_href.png Binary file Symbian3/SDK/Source/GUID-36BB14BD-34B3-4F5D-A670-707710E57585_d0e36549_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-36BB14BD-34B3-4F5D-A670-707710E57585_d0e42116_href.png Binary file Symbian3/SDK/Source/GUID-36BB14BD-34B3-4F5D-A670-707710E57585_d0e42116_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-36BCDD1F-3713-5DF0-8D8A-CF093694B636.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-36BCDD1F-3713-5DF0-8D8A-CF093694B636.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,136 @@ + + + + + +Secure store encryption example code

            This example covers:

            • Creating and opening a new secure store protected by the supplied password

            • Opening an existing secure store

            • Writing some data to a new stream in the currently opened store, and returning the ID of the stream

            • Reading the data in a given stream from the currently opened store

            • Closing the currently opened store

            • Changing the password for the currently opened store.

            Also, see:

            • PBE example code

            • Secure stream example code

            Creating and opening a new secure store protected by the supplied password

            • Supporting code for this example

            +void CSecureStoreExample::CreateNewStoreL(const TDesC& aPassword) + { + // Check store is not already open + ASSERT(!iEncryptSet && !iSecureStore && !iFileStore); + + // Create a standard file store + iFileStore = CPermanentFileStore::ReplaceL(iFs, iFilename, EFileRead | EFileWrite | EFileShareExclusive); + iFileStore->SetTypeL(KPermanentFileStoreLayoutUid); + + // Create a CPBEncryptSet object (because a store is comprised of multiple + // independent objects) + TPBPassword password(aPassword); + iEncryptSet = CPBEncryptSet::NewL(password, ECipherDES_CBC); + + // Write encryption data and encrypted master key to the root stream of the + // store. We need to store both of these pieces of information to be able + // to access the secure store at a later time. + RStoreWriteStream writeStream; + TStreamId rootId = writeStream.CreateLC(*iFileStore); + writeStream << iEncryptSet->EncryptionData(); + writeStream << iEncryptSet->EncryptedMasterKey(); + writeStream.CommitL(); + CleanupStack::PopAndDestroy(&writeStream); + iFileStore->SetRootL(rootId); + iFileStore->CommitL(); + + // Create the secure store - this wraps the file store providing transparent + // encryption/decryption of streams. + iSecureStore = CSecureStore::NewL(*iFileStore, *iEncryptSet); + } +
            Opening an existing secure store

            • Supporting code for this example

            +// Leaves with KErrBadPassphrase if the password is +// not the same as the one used when creating the store. +void CSecureStoreExample::OpenExistingStoreL(const TDesC& aPassword) + { + // Check store is not already open + ASSERT(!iEncryptSet && !iSecureStore && !iFileStore); + + // Open a standard file store + iFileStore = CPermanentFileStore::OpenL(iFs, iFilename, EFileRead | EFileWrite | EFileShareExclusive); + + // Read the encryption data and encrypted master key from the root stream + TStreamId rootId = iFileStore->Root(); + RStoreReadStream readStream; + readStream.OpenLC(*iFileStore, rootId); + CPBEncryptionData* encryptionData = CPBEncryptionData::NewLC(readStream); + HBufC8* encryptedMasterKey = HBufC8::NewLC(readStream, KMaxTInt); + + // Use these to recreate the CPBEncryptSet object (this leaves if + // aPassword is wrong) + iEncryptSet = CPBEncryptSet::NewL(*encryptionData, *encryptedMasterKey, aPassword); + + // Create the secure store + iSecureStore = CSecureStore::NewL(*iFileStore, *iEncryptSet); + + // Free memory + CleanupStack::PopAndDestroy(3, &readStream); + } +
            Writing some data to a new stream in the currently opened store, and returning the ID of the stream

            • Supporting code for this example

            +TStreamId CSecureStoreExample::WriteEncryptedDataL(const TDesC8& aInput) + { + // Check store is open + ASSERT(iEncryptSet && iSecureStore && iFileStore); + + // Create a new stream in the store + RStoreWriteStream writeStream; + TStreamId newStreamId = writeStream.CreateLC(*iSecureStore); + + // Write data - this is automatically encrypted + writeStream << aInput; + writeStream.CommitL(); + iSecureStore->CommitL(); + + CleanupStack::PopAndDestroy(&writeStream); + return newStreamId; + } +
            Reading the data in a given stream from the currently opened store

            • Supporting code for this example

            +HBufC8* CSecureStoreExample::ReadEncryptedDataLC(TStreamId aStreamId) + { + // Check store is open + ASSERT(iEncryptSet && iSecureStore && iFileStore); + + // Open an existing stream in the store + RStoreReadStream readStream; + readStream.OpenLC(*iSecureStore, aStreamId); + + // Read data - this is automatically decrypted + HBufC8* output = HBufC8::NewL(readStream, KMaxTInt); + + CleanupStack::PopAndDestroy(&readStream); + CleanupStack::PushL(output); + return output; + } +
            Closing the currently opened store

            • Supporting code for this example

            +void CSecureStoreExample::CloseStore() + { + delete iSecureStore; + iSecureStore = NULL; + delete iEncryptSet; + iEncryptSet = NULL; + delete iFileStore; + iFileStore = NULL; + } +
            Changing the password for the currently opened store

            • Supporting code for this example

            +void CSecureStoreExample::ChangePasswordL(const TDesC& aNewPassword) + { + // Check store is open + ASSERT(iEncryptSet && iSecureStore && iFileStore); + + // Change password on encrypt set object + iEncryptSet->ChangePasswordL(aNewPassword); + + // Must now rewrite data in root stream + TStreamId rootId = iFileStore->Root(); + RStoreWriteStream writeStream; + writeStream.ReplaceLC(*iFileStore, rootId); + writeStream << iEncryptSet->EncryptionData(); + writeStream << iEncryptSet->EncryptedMasterKey(); + writeStream.CommitL(); + iFileStore->CommitL(); + + CleanupStack::PopAndDestroy(&writeStream); + } +
            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-36BD6059-6547-5754-8BE0-F8051A838C14.dita --- a/Symbian3/SDK/Source/GUID-36BD6059-6547-5754-8BE0-F8051A838C14.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-36BD6059-6547-5754-8BE0-F8051A838C14.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,20 +1,94 @@ - - - - - -Using Time-Nudge-Capture Drive Mode This topic describes how to capture an image using Time-Nudge-Capture drive mode in the Ecam API.

            Before you start you should understand the following topics:

            • Capturing Image.

            • Advanced Camera Settings Overview.

            The EDriveModeTimeNudgeCapture mode allows you to specify the amount of images to be captured both before and after the capture button key press. The numbers of pre- or post-capture images to be captured are set by the TDriveModeDependentAttributes values, with the total number of images being calculated as follows:

            Total number of captured images = iParam1 + 1 + iParam2 where iParam1 and iParam2 represent pre and post capture images respectively, and 1 represents the present image.

            Call CCamera::New2L(MCameraObserver2 - &,TInt,TInt) to create an instance of CCamera. Call CCamera::CCameraPreImageCaptureControl to create an image capture object. Call CCamera::PrepareImageCapture(const - TPrepareImageParameter&, MCaptureImageObserver&) to prepare for capturing the image. TPrepareImageParameter uses TDriveModeDependentAttributes to set the number of images before and after the camera capture key press event. The iDriveMode value in TPrepareImageParameter should be replaced into the EDriveModeTimeNudgeCapture value, to support the time-nudge-capture drive mode. If an aErrorCode occurs while preparing an image, you have to call CCamera::PrepareImageComplete(CCamera::CCameraImageCapture*, - TInt). Note: The PrepareImageComplete() callback is deferred until the implementation is ready with the pre-image data saved in the buffer so that you can press the capture key at any time. Meanwhile the implementation continues saving the latest pre-capture images until the CaptureImage() function is called. Call CCamera::CaptureImage(CCameraCapture*) to capture an image. Note: You can call the CaptureImage() function to capture the current image exposed to the sensor plus the required number of post-image capture images. Call the MCaptureImageObserver::IndividualImageControlHandle(CCamera::CCameraImageCapture&, - TPostCaptureControlId) function for each captured image to pass the individual id of each image to the client. Call MCaptureImageObserver::ImageCaptureComplete(CCamera::CCameraImageCapture&, - TInt) and - [a11]CCamera::HandleEvent(KUidECamEventReadyForNextCapture) to notify the client that the current capture operation has finished. Note: This must only occur once the implementation has saved another set of pre-image capture images. This is so that the implementation is ready to receive further CaptureImage() calls. Call CCamera::CCameraPostImageCaptureControl(TUid, - TPostCaptureControlUid) to control the post image capture after capturing the desired image. Call the CCamera::HandleEvent(KUidECamEventReadyForNextPrepare) function when you have deleted the current CCameraImageCapture object. Note: In this drive mode, only one instance of CCameraImageCapture can be created at any one time, i.e. PrepareImageCapture() can only be called once. In order to successfully call PrepareImageCapture() again and create a new CCameraImageCapture object, clients must first destroy the previous one. Therefore, the implementation should only issue this callback once the client has deleted the object.             Controlling Pre-Image Capture Controlling Still-Image - Capture Controlling Captured Image             \ No newline at end of file + + + + + +Using +Time-Nudge-Capture Drive Mode This topic describes how to capture an image using Time-Nudge-Capture +drive mode in the Ecam API. +

            Before you start +you should understand the following topics:

              +

            • Capturing Still +Images

              • +

            • Advanced +Camera Settings Overview.

              • +
             +

            The CCamera::CCameraAdvancedSettings::EDriveModeTimeNudgeCapture mode +allows you to specify the amount of images to be captured both before and +after the capture button key press. The numbers of pre- or post-capture images +to be captured are set by the CCamera::CCameraPreImageCaptureControl::TDriveModeDependentAttributes values, +with the total number of images being calculated as follows:

            Total +number of captured images = iParam1 + 1 + iParam2 where iParam1 and iParam2 represent +pre and post capture images respectively, and 1 represents the present image.

            + + +Call CCamera::New2L(MCameraObserver2 &,TInt,TInt) to +create an instance of CCamera. + + +Call CCamera::CCameraPreImageCaptureControl to create +an image capture object. + + +Call CCamera::CCameraPreImageCaptureControl::PrepareImageCapture(const +TPrepareImageParameters &,MCaptureImageObserver &) to prepare +for capturing the image. TPrepareImageParameter uses TDriveModeDependentAttributes to +set the number of images before and after the camera capture key press event. +The iDriveMode value in TPrepareImageParameter should +be replaced into the EDriveModeTimeNudgeCapture value, to +support the time-nudge-capture drive mode. +If an aErrorCode occurs while preparing an image, you +have to call CCamera::PrepareImageComplete(CCamera::CCameraImageCapture*, +TInt). +Note: The PrepareImageComplete() callback is deferred +until the implementation is ready with the pre-image data saved in the buffer +so that you can press the capture key at any time. Meanwhile the implementation +continues saving the latest pre-capture images until the CaptureImage() function +is called. + + +Call CCamera::CaptureImage() to capture an image. +Note: You can call the CaptureImage() function to capture +the current image exposed to the sensor plus the required number of post-image +capture images. + + +Call the MCaptureImageObserver::IndividualImageControlHandle(CCamera::CCameraImageCapture +&,TPostCaptureControlId) function for each captured image to +pass the individual id of each image to the client. + + +Call MCaptureImageObserver::ImageCaptureComplete(CCamera::CCameraImageCapture +&,TInt) and MCameraObserver2::HandleEvent(const TECAMEvent +&) to notify the client that the current capture operation has +finished. +Note: This must only occur once the implementation has saved another +set of pre-image capture images. This is so that the implementation is ready +to receive further CaptureImage() calls. + + +Call CCamera::CCameraPostImageCaptureControl::CCameraPostImageCaptureControl(CCamera::CCameraImageCapture +*,TPostCaptureControlId) to control the post image capture after +capturing the desired image. + + +Call the MCameraObserver2::HandleEvent(const TECAMEvent &) function +when you have deleted the current CCameraImageCapture object. +Note: In this drive mode, only one instance of CCameraImageCapture can +be created at any one time, that is, PrepareImageCapture() can +only be called once. In order to successfully call PrepareImageCapture() again +and create a new CCameraImageCapture object, clients must +first destroy the previous one. Therefore, the implementation should only +issue this callback once the client has deleted the object. + + +             +Camera Library + +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-36C3A2FD-F4F9-5B8C-91B7-40C29B3D2224.dita --- a/Symbian3/SDK/Source/GUID-36C3A2FD-F4F9-5B8C-91B7-40C29B3D2224.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-36C3A2FD-F4F9-5B8C-91B7-40C29B3D2224.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,12 +1,105 @@ - - - - - - Overview

            This section provides an overview of the Camera Framework.

            Purpose

            The ECam component supplies a header file (.h) and library definition files (.def). These specify the API and binary interfaces that device creators can implement. They provide an interface for cross-platform, compatible camera clients to access the camera on any given device. The Camera Framework supports any concrete ECam implementation only as a ECom plug-in. The ROM plug-in with the highest version number is selected at instantiation phase. The Symbian version of ECam is a stub for easy replacement by an alternate implementation.

            Required background

            ECam is a component of the Multimedia subsystem.

            Architectural relationships

            Clients have specific priorities and may pre-empt others in their interactions with the camera. When a camera client needs to share the camera with another client, it creates a handle to the camera and passes this handle to the component. Clients that share with each other are called collaborative clients.

            Platform security requires that applications have the UserEnvironment capability to create a Camera object. Clients with the MultimediaDD capability are given a higher priority.

            Note: The process by which a client passes a handle to another client is beyond the scope of this Camera Framework guide.

            Application developers and device creators implement the ECam API for the camera hardware on their phone. All cameras are ECom plug-ins sub-classed from the CCameraplugin class.

            API summary

            The Camera Framework includes the following APIs.

            ECam APIs

            • Camera

              This provides functionality to control a digital camera and to request and receive specific image data from it.

              See also Key Onboard ECam API Classes

            • Advanced Settings

              This provides domain specific getters and setters for well known camera hardware settings. This is used to query the camera for the list of supported and currently active hardware settings. For a specific setting, clients can query the camera for the list of supported values.

            • Camera Viewfinder

              This provides the support for both direct and client viewfinder. It also provides information regarding the current state of that direct viewfinder. The different possible states are active, paused and inactive.

              See also Key Viewfinder Classes

              Note: The direct viewfinder is applicable only for viewfinders that use Ccamera viewfinder methods.

            • Camera Histogram

              This gets the histogram data in a specified format for an image (for example, luminance based histogram, average colour value histogram and so on).

            • Camera Overlay

              This overlays an image onto the viewfinder, snapshots, still images and video. A client can create multiple overlays, each one with different properties.

            • Camera plug-in Support

              All cameras are ECom plug-ins sub-classed from Ccameraplugin class and register support for the interface KuidOnboardCameraplugin in their resource file. Symbian introduced plug-in support for ECam from v9.1 onwards. Before that, device creators were supposed to re-implement ECam, which was effectively reference code.

            • Camera Snap Shot

              Clients can use snapshots to show captured images on the display almost instantly (while in the background the image may be processed by using some compression algorithm before storing the data). The client can specify the properties of the snapshot, such as size, background colour and position to be used if the snapshot has been scaled and so on. Snapshot object can be created specifically for still images and video APIs.

            Typical uses

            Camera Component Users

            • Camera plug-ins

            • Multimedia Framework plug-ins

            Camera Component tasks

            The camera component is used for the following:

            • Onboard Camera

            • Camera plug-in Support

            • Advanced Settings

            • Camera plug-in

            • Histogram

            • Overlay

            • Snapshot

            • Viewfinder

            Onboard Camera

            The Onboard Camera provides functionality to control a digital camera and to request and receive specific image data from it.

            Advanced Settings

            The Advanced Settings gets or sets individual setting value as well as retrieve their current ranges.

            Camera plug-in

            This API, an ECom plug-in, is introduced as an alternative to static linking. This allows the partners to replace the camera implementation more easily.

            Histogram

            The Histogram provides the functionality needed to work with histogram data in a specified format for an image.

            Overlay

            The Overlay is used to overlay an image onto the viewfinder, snapshots, still images and video.

            Snapshot

            The Snapshot allows the client to request snapshot data in a specified image format for both still images and video.

            Viewfinder

            The Viewfinder enables to pause and resume the direct viewfinder which is currently active and has been started using Ccamera methods.

            See also

            Onboard Camera Overview

            Camera Plug-in Support Overview

            Advanced Camera Settings Overview

            Histogram Overview

            Overlay API Overview

            Snapshot API Overview

            Viewfinder API Overview

            \ No newline at end of file + + + + + + Overview +

            This section provides an overview of the Camera Framework.

            +
            Purpose

            The ECam component supplies a header file +(.h) and library definition files (.def). +These specify the API and binary interfaces that device creators can implement. +They provide an interface for cross-platform, compatible camera clients to +access the camera on any given device. The Camera Framework supports any concrete +ECam implementation only as a ECom plug-in. The ROM plug-in with the highest +version number is selected at instantiation phase. The Symbian version of +ECam is a stub for easy replacement by an alternate implementation.

            +
            Required background

            ECam is a component of the +Multimedia subsystem.

            +
            Architectural relationships

            Clients have specific +priorities and may pre-empt others in their interactions with the camera. +When a camera client needs to share the camera with another client, it creates +a handle to the camera and passes this handle to the component. Clients that +share with each other are called collaborative clients.

            Platform security +requires that applications have the UserEnvironment capability +to create a Camera object. Clients with the MultimediaDD capability +are given a higher priority.

            Note: The process by which a +client passes a handle to another client is beyond the scope of this Camera +Framework guide.

            Application developers and device creators implement +the ECam API for the camera hardware on their phone. All cameras are ECom +plug-ins sub-classed from the CCameraPlugin class.

            +
            API summary

            The Camera Framework includes the following +APIs.

            ECam APIs

              +

            • Camera

              This +provides functionality to control a digital camera and to request and receive +specific image data from it.

              See also Key +Onboard ECam API Classes

              • +

            • Advanced Settings

              This +provides domain specific getters and setters for well known camera hardware +settings. This is used to query the camera for the list of supported and currently +active hardware settings. For a specific setting, clients can query the camera +for the list of supported values.

              • +

            • Camera Viewfinder

              This +provides the support for both direct and client viewfinder. It also provides +information regarding the current state of that direct viewfinder. The different +possible states are active, paused and inactive.

              See also Key Viewfinder Classes

              Note: The direct viewfinder +is applicable only for viewfinders that use Ccamera viewfinder methods.

              • +

            • Camera Histogram

              This +gets the histogram data in a specified format for an image (for example, luminance +based histogram, average colour value histogram and so on).

              • +

            • Camera Overlay

              This +overlays an image onto the viewfinder, snapshots, still images and video. +A client can create multiple overlays, each one with different properties.

              • +

            • Camera plug-in Support

              All +cameras are ECom plug-ins sub-classed from CCameraPlugin class +and register support for the interface KUidOnboardCameraPlugin in +their resource file. Symbian introduced plug-in support for ECam from v9.1 +onwards. Before that, device creators were supposed to re-implement ECam, +which was effectively reference code.

              • +

            • Camera Snap Shot

              Clients +can use snapshots to show captured images on the display almost instantly +(while in the background the image may be processed by using some compression +algorithm before storing the data). The client can specify the properties +of the snapshot, such as size, background colour and position to be used if +the snapshot has been scaled and so on. Snapshot object can be created specifically +for still images and video APIs.

              • +
            +
            Typical uses

            Camera Component Users

              +

            • Camera plug-ins

              • +

            • Multimedia Framework +plug-ins

              • +

            Camera +Component tasks

            The camera component is used for the following:

              +

            • Onboard Camera

              • +

            • Camera plug-in Support

              • +

            • Advanced Settings

              • +

            • Camera plug-in

              • +

            • Histogram

              • +

            • Overlay

              • +

            • Snapshot

              • +

            • Viewfinder

              • +

            Onboard +Camera

            The Onboard Camera provides functionality to control a +digital camera and to request and receive specific image data from it.

            Advanced Settings

            The Advanced Settings gets or sets individual +setting value as well as retrieve their current ranges.

            Camera plug-in

            This API, an ECom plug-in, is introduced as +an alternative to static linking. This allows the partners to replace the +camera implementation more easily.

            Histogram

            The Histogram provides the functionality needed to work with histogram +data in a specified format for an image.

            Overlay

            The Overlay is used to overlay an image onto the +viewfinder, snapshots, still images and video.

            Snapshot

            The Snapshot allows the client to request snapshot +data in a specified image format for both still images and video.

            Viewfinder

            The Viewfinder enables to pause and resume the +direct viewfinder which is currently active and has been started using Ccamera +methods.

            +
            See also

            Onboard +Camera Overview

            Camera +Plug-in Support Overview

            Advanced +Camera Settings Overview

            Histogram +Overview

            Overlay +API Overview

            Snapshot +API Overview

            Viewfinder +API Overview

            +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-36F18DC4-7BD0-59C6-95E9-8FD945B86D7E_d0e233427_href.png Binary file Symbian3/SDK/Source/GUID-36F18DC4-7BD0-59C6-95E9-8FD945B86D7E_d0e233427_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-36F18DC4-7BD0-59C6-95E9-8FD945B86D7E_d0e237164_href.png Binary file Symbian3/SDK/Source/GUID-36F18DC4-7BD0-59C6-95E9-8FD945B86D7E_d0e237164_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-36FD1F9A-FA1C-5822-A95F-720600E8F418.dita --- a/Symbian3/SDK/Source/GUID-36FD1F9A-FA1C-5822-A95F-720600E8F418.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-36FD1F9A-FA1C-5822-A95F-720600E8F418.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,14 +1,14 @@ - - - - - -Contact Items Management

            A Contact Item is an element in a Contact Database. Contact Items can be added, read, edited and removed from the database. As the diagram below shows, a Contact Item can be:

            • a contact card - either generic cards (CContactCard) or the device owner's card (CContactOwnCard)

            • a template card (CContactTemplate) - a card that sets the initial fields for other Contact Items

            • a collection of Contact Items (CContactItemPlusGroup) - a group that holds a set of associated Contact Item IDs

            • a contact which maps to the device's ICC (CContactICCEntry) or SIM (CContactCard).

            Each Contact Item is uniquely identified in the database by a Contact Item ID (TContactItemId). More than one Contact Item ID is referred to using a Contact Item ID array (CContactIdArray).

            - CONTACT ITEM HIERARCHY -

            Contact Items have an access count and attributes ('hidden', for example). The access count is a record of the number of objects referencing a Contact Item. A Contact Item cannot be fully deleted until its access count is zero.

            Note: Fields in a Contact Item also have attributes. Attribute values specified in the Contact Item override those in the contained fields.

            Contact Items are accessed through the CContactDatabase class. Opening a Contact Item (using CContactDatabase::OpenContactL()) locks it so that it cannot be edited by another client. Closing the Contact Item (using CContactDatabase::CloseContactL()) releases the lock on the item without saving any changes made to it. Committing the Contact Item (using CContactDatabase::CommitContactL()) releases the lock and saves any changes made to it.

            Contact Item Fields

            Each Contact Item contains a number of fields (CContactItemFieldSet). Each field (CContactItemField) in CContactItemFieldSet has a content type, (CContentType), and a storage type, (TStorageType) and the field data (CContactTextField, CContactStoreField, CContactAgentField or CContactDateField).

            A content type contains at least one UID, using TFieldType. A storage type identifies the type of data (text, binary, contact agent ID, date/time) stored in a Contact Item field. As numeric field data is not supported all numbers are stored as text.

            Each field can also have a label which identifies the field to a user, for example, first name, last name. Fields can have attributes assigned to them such as hidden, disabled, synchronised, read only, user added, template and speed dial.

            Contact Groups

            A Contact Group (CContactGroup class) is a Contact Item which holds a set of associated Contact Item IDs. The members of the group may be contact cards, own cards, or even other groups. The group has a label which identifies the group such as 'family', or 'colleagues' to users. The type of a Contact Group is KUidContactGroup, as returned by CContactGroup::Type().

            It is possible to construct a group using CContactGroup::CreateContactGroupL(). These functions create the group, optionally with a label, add it to the database, and return a pointer to it. To create an association between a card and a group, use CContactDatabase::AddContactToGroupL(). To remove the association, use CContactDatabase::RemoveContactFromGroupL(). To find out which groups a card belongs to, use CContactCard::GroupsJoinedLC() or CContactOwnCard::GroupsJoinedLC().

            \ No newline at end of file + + + + + +Contact Items Management

            A Contact Item is an element in a Contact Database. Contact Items can be added, read, edited and removed from the database. As the diagram below shows, a Contact Item can be:

            • a contact card - either generic cards (CContactCard) or the device owner's card (CContactOwnCard)

            • a template card (CContactTemplate) - a card that sets the initial fields for other Contact Items

            • a collection of Contact Items (CContactItemPlusGroup) - a group that holds a set of associated Contact Item IDs

            • a contact which maps to the device's ICC (CContactICCEntry) or SIM (CContactCard).

            Each Contact Item is uniquely identified in the database by a Contact Item ID (TContactItemId). More than one Contact Item ID is referred to using a Contact Item ID array (CContactIdArray).

            + CONTACT ITEM HIERARCHY +

            Contact Items have an access count and attributes ('hidden', for example). The access count is a record of the number of objects referencing a Contact Item. A Contact Item cannot be fully deleted until its access count is zero.

            Note: Fields in a Contact Item also have attributes. Attribute values specified in the Contact Item override those in the contained fields.

            Contact Items are accessed through the CContactDatabase class. Opening a Contact Item (using CContactDatabase::OpenContactL()) locks it so that it cannot be edited by another client. Closing the Contact Item (using CContactDatabase::CloseContactL()) releases the lock on the item without saving any changes made to it. Committing the Contact Item (using CContactDatabase::CommitContactL()) releases the lock and saves any changes made to it.

            Contact Item Fields

            Each Contact Item contains a number of fields (CContactItemFieldSet). Each field (CContactItemField) in CContactItemFieldSet has a content type, (CContentType), and a storage type, (TStorageType) and the field data (CContactTextField, CContactStoreField, CContactAgentField or CContactDateField).

            A content type contains at least one UID, using TFieldType. A storage type identifies the type of data (text, binary, contact agent ID, date/time) stored in a Contact Item field. As numeric field data is not supported all numbers are stored as text.

            Each field can also have a label which identifies the field to a user, for example, first name, last name. Fields can have attributes assigned to them such as hidden, disabled, synchronised, read only, user added, template and speed dial.

            Contact Groups

            A Contact Group (CContactGroup class) is a Contact Item which holds a set of associated Contact Item IDs. The members of the group may be contact cards, own cards, or even other groups. The group has a label which identifies the group such as 'family', or 'colleagues' to users. The type of a Contact Group is KUidContactGroup, as returned by CContactGroup::Type().

            It is possible to construct a group using CContactGroup::CreateContactGroupL(). These functions create the group, optionally with a label, add it to the database, and return a pointer to it. To create an association between a card and a group, use CContactDatabase::AddContactToGroupL(). To remove the association, use CContactDatabase::RemoveContactFromGroupL(). To find out which groups a card belongs to, use CContactCard::GroupsJoinedLC() or CContactOwnCard::GroupsJoinedLC().

            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-37042E73-123B-437B-8EC4-8FC6C3AD6D47_d0e3183_href.png Binary file Symbian3/SDK/Source/GUID-37042E73-123B-437B-8EC4-8FC6C3AD6D47_d0e3183_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-37042E73-123B-437B-8EC4-8FC6C3AD6D47_d0e4458_href.png Binary file Symbian3/SDK/Source/GUID-37042E73-123B-437B-8EC4-8FC6C3AD6D47_d0e4458_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-377B04D8-4E8B-54C7-AE7F-8BD47CB81758_d0e10475_href.png Binary file Symbian3/SDK/Source/GUID-377B04D8-4E8B-54C7-AE7F-8BD47CB81758_d0e10475_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-377B04D8-4E8B-54C7-AE7F-8BD47CB81758_d0e9200_href.png Binary file Symbian3/SDK/Source/GUID-377B04D8-4E8B-54C7-AE7F-8BD47CB81758_d0e9200_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-37888891-DFB2-5A93-9547-3B22410906BF_d0e299302_href.png Binary file Symbian3/SDK/Source/GUID-37888891-DFB2-5A93-9547-3B22410906BF_d0e299302_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-37888891-DFB2-5A93-9547-3B22410906BF_d0e305329_href.png Binary file Symbian3/SDK/Source/GUID-37888891-DFB2-5A93-9547-3B22410906BF_d0e305329_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-379D9401-04A2-4A32-A3BF-C6F127E8F074_d0e3412_href.png Binary file Symbian3/SDK/Source/GUID-379D9401-04A2-4A32-A3BF-C6F127E8F074_d0e3412_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-379D9401-04A2-4A32-A3BF-C6F127E8F074_d0e4687_href.png Binary file Symbian3/SDK/Source/GUID-379D9401-04A2-4A32-A3BF-C6F127E8F074_d0e4687_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-37C193CD-3D8A-56A5-B78C-0A6FE7163EC2_d0e324269_href.png Binary file Symbian3/SDK/Source/GUID-37C193CD-3D8A-56A5-B78C-0A6FE7163EC2_d0e324269_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-37C193CD-3D8A-56A5-B78C-0A6FE7163EC2_d0e330426_href.png Binary file Symbian3/SDK/Source/GUID-37C193CD-3D8A-56A5-B78C-0A6FE7163EC2_d0e330426_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-37D2EFAE-FB55-5015-90CE-1361144C411E_d0e220875_href.png Binary file Symbian3/SDK/Source/GUID-37D2EFAE-FB55-5015-90CE-1361144C411E_d0e220875_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-37D2EFAE-FB55-5015-90CE-1361144C411E_d0e224612_href.png Binary file Symbian3/SDK/Source/GUID-37D2EFAE-FB55-5015-90CE-1361144C411E_d0e224612_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-37DCD20D-E123-5B62-976D-F91AD99A765D_d0e323490_href.jpg Binary file Symbian3/SDK/Source/GUID-37DCD20D-E123-5B62-976D-F91AD99A765D_d0e323490_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-37DCD20D-E123-5B62-976D-F91AD99A765D_d0e329647_href.jpg Binary file Symbian3/SDK/Source/GUID-37DCD20D-E123-5B62-976D-F91AD99A765D_d0e329647_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-37E8A48E-09B8-5958-9263-B33EDAE3F7C6-GENID-1-8-1-3-1-1-7-1-3-1.dita --- a/Symbian3/SDK/Source/GUID-37E8A48E-09B8-5958-9263-B33EDAE3F7C6-GENID-1-8-1-3-1-1-7-1-3-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,81 +0,0 @@ - - - - - -UI -Control Framework Overview -
            Architectural -relationships

            The control framework provides an abstract middle -layer between the low-level windowing functionality, provided by the Window -Server, and concrete user interface classes provided by UIKON and UI variant-specific -libraries.

            Application developers use the API directly to create their -own controls and indirectly through derived classes provided by UIKON and -AVKON.

            - Cone architectural relationships - -
            -
            Description

            Controls

            A -control is a rectangular area of a window that may respond to user input. -Controls have a number of properties that determine their behavior and their -relationships to other controls and windows.

            A control is represented -by the class CCoeControl.

            A simple control is -one which contains no other controls.

            A container control is -one which contains one or more controls. A container control is also referred -to as a compound control. The contained controls may themselves be -container controls. When a control is contained in a container control it -is called a component control. A component control is always redrawn -when its container control is redrawn.

            The following diagram shows -simple controls in orange and container controls in grey.

            - Simple and compound controls - -

            Controls and Windows

            A window may be considered -as a transparent layer. Windows are managed by the Window Server and described elsewhere. A control -provides a means of access to a window - it can be drawn onto the window and -can receive input.

            Each window has a one-to-one relationship with -a single control that covers it precisely. This control is referred to as -a window-owning control. A window-owning control shares the behavior -of its window, in particular the parent-child window relationships which govern -the window's position and overlapping behavior.

            A non-window-owning -control typically covers only part of a window. It cannot be moved around -on the screen independently of its window, cannot draw outside its window -and is always a component control.

            You might think of a window-owning -control as a piece of glass and a non-window-owning control as a sticker on -a window-owning control.

            Application User Interface (AppUi) framework

            The -application user interface framework provides support for the distribution -of key events to an application's controls. It maintains a control stack to -which an application must add all the top-level container controls that it -wishes to handle key events, setting a priority for each. When a key event -occurs, the framework offers it to each control on the stack in priority order -until it is consumed.

            The application user interface framework is -provided by the base class CCoeAppUi. UIKON and UI variants -specialize CCoeAppUi further. Applications derive from the -variant AppUi.

            CCoeAppUi provides a simplified -interface to the View -Server which enables seamless switching between different views across -various applications.

            Control Environment (CoeEnv)

            The -Control Environment simplifies the interface to the Window Server and provides -an environment for creating controls. It is a single instance (a singleton) -of the class CCoeEnv which encapsulates an active scheduler -and active objects for communicating with the window server. CCoeEnv is -created automatically by the framework and a pointer stored in Thread Local -Storage (TLS). It is available through CCoeControl::CoeEnv(), CCoeAppUi::CoeEnv() and -through its own static function, CCoeEnv::Static(), which -is less efficient.

            The control environment also provides simplified -access to drawing functions, fonts, and resource files which are used by most -applications.

            -
            See also
              -

            • Uikon Overview

              • -

            • View Server -Overview

              • -

            • Window Server

              • -

            • Asynchronous -Programming (active scheduler & active objects)

              • -
            -             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-37E8A48E-09B8-5958-9263-B33EDAE3F7C6-GENID-1-8-1-6-1-1-4-1-6-1-3-1.dita --- a/Symbian3/SDK/Source/GUID-37E8A48E-09B8-5958-9263-B33EDAE3F7C6-GENID-1-8-1-6-1-1-4-1-6-1-3-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,81 +0,0 @@ - - - - - -UI -Control Framework Overview -
            Architectural -relationships

            The control framework provides an abstract middle -layer between the low-level windowing functionality, provided by the Window -Server, and concrete user interface classes provided by UIKON and UI variant-specific -libraries.

            Application developers use the API directly to create their -own controls and indirectly through derived classes provided by UIKON and -AVKON.

            - Cone architectural relationships - -
            -
            Description

            Controls

            A -control is a rectangular area of a window that may respond to user input. -Controls have a number of properties that determine their behavior and their -relationships to other controls and windows.

            A control is represented -by the class CCoeControl.

            A simple control is -one which contains no other controls.

            A container control is -one which contains one or more controls. A container control is also referred -to as a compound control. The contained controls may themselves be -container controls. When a control is contained in a container control it -is called a component control. A component control is always redrawn -when its container control is redrawn.

            The following diagram shows -simple controls in orange and container controls in grey.

            - Simple and compound controls - -

            Controls and Windows

            A window may be considered -as a transparent layer. Windows are managed by the Window Server and described elsewhere. A control -provides a means of access to a window - it can be drawn onto the window and -can receive input.

            Each window has a one-to-one relationship with -a single control that covers it precisely. This control is referred to as -a window-owning control. A window-owning control shares the behavior -of its window, in particular the parent-child window relationships which govern -the window's position and overlapping behavior.

            A non-window-owning -control typically covers only part of a window. It cannot be moved around -on the screen independently of its window, cannot draw outside its window -and is always a component control.

            You might think of a window-owning -control as a piece of glass and a non-window-owning control as a sticker on -a window-owning control.

            Application User Interface (AppUi) framework

            The -application user interface framework provides support for the distribution -of key events to an application's controls. It maintains a control stack to -which an application must add all the top-level container controls that it -wishes to handle key events, setting a priority for each. When a key event -occurs, the framework offers it to each control on the stack in priority order -until it is consumed.

            The application user interface framework is -provided by the base class CCoeAppUi. UIKON and UI variants -specialize CCoeAppUi further. Applications derive from the -variant AppUi.

            CCoeAppUi provides a simplified -interface to the View -Server which enables seamless switching between different views across -various applications.

            Control Environment (CoeEnv)

            The -Control Environment simplifies the interface to the Window Server and provides -an environment for creating controls. It is a single instance (a singleton) -of the class CCoeEnv which encapsulates an active scheduler -and active objects for communicating with the window server. CCoeEnv is -created automatically by the framework and a pointer stored in Thread Local -Storage (TLS). It is available through CCoeControl::CoeEnv(), CCoeAppUi::CoeEnv() and -through its own static function, CCoeEnv::Static(), which -is less efficient.

            The control environment also provides simplified -access to drawing functions, fonts, and resource files which are used by most -applications.

            -
            See also
              -

            • Uikon Overview

              • -

            • View Server -Overview

              • -

            • Window Server

              • -

            • Asynchronous -Programming (active scheduler & active objects)

              • -
            -             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-37E8A48E-09B8-5958-9263-B33EDAE3F7C6.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-37E8A48E-09B8-5958-9263-B33EDAE3F7C6.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,81 @@ + + + + + +UI +Control Framework Overview +
            Architectural +relationships

            The control framework provides an abstract middle +layer between the low-level windowing functionality, provided by the Window +Server, and concrete user interface classes provided by UIKON and UI variant-specific +libraries.

            Application developers use the API directly to create their +own controls and indirectly through derived classes provided by UIKON and +AVKON.

            + Cone architectural relationships + +
            +
            Description

            Controls

            A +control is a rectangular area of a window that may respond to user input. +Controls have a number of properties that determine their behavior and their +relationships to other controls and windows.

            A control is represented +by the class CCoeControl.

            A simple control is +one which contains no other controls.

            A container control is +one which contains one or more controls. A container control is also referred +to as a compound control. The contained controls may themselves be +container controls. When a control is contained in a container control it +is called a component control. A component control is always redrawn +when its container control is redrawn.

            The following diagram shows +simple controls in orange and container controls in grey.

            + Simple and compound controls + +

            Controls and Windows

            A window may be considered +as a transparent layer. Windows are managed by the Window Server and described elsewhere. A control +provides a means of access to a window - it can be drawn onto the window and +can receive input.

            Each window has a one-to-one relationship with +a single control that covers it precisely. This control is referred to as +a window-owning control. A window-owning control shares the behavior +of its window, in particular the parent-child window relationships which govern +the window's position and overlapping behavior.

            A non-window-owning +control typically covers only part of a window. It cannot be moved around +on the screen independently of its window, cannot draw outside its window +and is always a component control.

            You might think of a window-owning +control as a piece of glass and a non-window-owning control as a sticker on +a window-owning control.

            Application User Interface (AppUi) framework

            The +application user interface framework provides support for the distribution +of key events to an application's controls. It maintains a control stack to +which an application must add all the top-level container controls that it +wishes to handle key events, setting a priority for each. When a key event +occurs, the framework offers it to each control on the stack in priority order +until it is consumed.

            The application user interface framework is +provided by the base class CCoeAppUi. UIKON and UI variants +specialize CCoeAppUi further. Applications derive from the +variant AppUi.

            CCoeAppUi provides a simplified +interface to the View +Server which enables seamless switching between different views across +various applications.

            Control Environment (CoeEnv)

            The +Control Environment simplifies the interface to the Window Server and provides +an environment for creating controls. It is a single instance (a singleton) +of the class CCoeEnv which encapsulates an active scheduler +and active objects for communicating with the window server. CCoeEnv is +created automatically by the framework and a pointer stored in Thread Local +Storage (TLS). It is available through CCoeControl::CoeEnv(), CCoeAppUi::CoeEnv() and +through its own static function, CCoeEnv::Static(), which +is less efficient.

            The control environment also provides simplified +access to drawing functions, fonts, and resource files which are used by most +applications.

            +
            See also
              +

            • Uikon Overview

              • +

            • View Server +Overview

              • +

            • Window Server

              • +

            • Asynchronous +Programming (active scheduler & active objects)

              • +
            +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-38089CC3-D969-5501-9FDA-BB0369D5D6A9_d0e280262_href.png Binary file Symbian3/SDK/Source/GUID-38089CC3-D969-5501-9FDA-BB0369D5D6A9_d0e280262_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-38089CC3-D969-5501-9FDA-BB0369D5D6A9_d0e283948_href.png Binary file Symbian3/SDK/Source/GUID-38089CC3-D969-5501-9FDA-BB0369D5D6A9_d0e283948_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3829BD20-3DCB-5489-8FC4-07F954E391BF.dita --- a/Symbian3/SDK/Source/GUID-3829BD20-3DCB-5489-8FC4-07F954E391BF.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-3829BD20-3DCB-5489-8FC4-07F954E391BF.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,40 +1,40 @@ - - - - - -Local -and global handlesThis document explains the distinction between local and global -handles. -

            This is the issue of Kernel side object visibility.

            -

            Handles are said to be local or global.

            -

            A handle is local, if the Kernel object which that handle represents -is only visible to the thread that created it; no other thread can open a -handle to the same Kernel object.

            -

            Typically, code constructs the appropriate RHandleBase derived -object, e.g. an RMutex, and calls its Create(), CreateLocal() or -equivalent function to create the corresponding Kernel object.

            -

            A handle is global, if the Kernel object which that handle represents -is visible to all threads across all processes; any thread in any process -can open a handle to that same Kernel object. Typically, such a Kernel object -is intended for sharing.

            -

            For a global handle. the corresponding Kernel object is assigned a name. -The name gives that Kernel object an identity and is the key property which -allows other threads to open a handle onto that same object. It is usual to -use a TFindHandleBase derived class to locate a global -Kernel object. The following diagram shows the general idea.

            - - - -

            See also:

            -
              -

            • Names -and fullnames in reference counting objects.

              • -
            + + + + + +Local +and global handlesThis document explains the distinction between local and global +handles. +

            This is the issue of Kernel side object visibility.

            +

            Handles are said to be local or global.

            +

            A handle is local, if the Kernel object which that handle represents +is only visible to the thread that created it; no other thread can open a +handle to the same Kernel object.

            +

            Typically, code constructs the appropriate RHandleBase derived +object, e.g. an RMutex, and calls its Create(), CreateLocal() or +equivalent function to create the corresponding Kernel object.

            +

            A handle is global, if the Kernel object which that handle represents +is visible to all threads across all processes; any thread in any process +can open a handle to that same Kernel object. Typically, such a Kernel object +is intended for sharing.

            +

            For a global handle. the corresponding Kernel object is assigned a name. +The name gives that Kernel object an identity and is the key property which +allows other threads to open a handle onto that same object. It is usual to +use a TFindHandleBase derived class to locate a global +Kernel object. The following diagram shows the general idea.

            + + + +

            See also:

            +
              +

            • Names +and fullnames in reference counting objects.

              • +
             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-382B8A9D-9D10-54CD-91A6-B9E7A2477662.dita --- a/Symbian3/SDK/Source/GUID-382B8A9D-9D10-54CD-91A6-B9E7A2477662.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-382B8A9D-9D10-54CD-91A6-B9E7A2477662.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,78 +1,84 @@ - - - - - -SendAs -v2.0 -
            Description

            The -application establishes a session with the SendAs server, sets -a message entry, creates a message, sets its body text, adds a recipient, -sends the message and closes the session. The sequence of events is detailed -in the following list:

              -

            • Create a session with -the SendAs server using CMsvSession::OpenSyncL() function.

              • -

            • Set the message entry -using the CMsvEntry::SetEntryL() function.

              • -

            • After setting the entry, -the application gets a selection containing the IDs of all the context children, -using the CMsvEntry::ChildrenL() function.

              • -

            • The connection to the -server is made using the default number of message slots available to a session, -which is 4, (KSendAsDefaultMessageSlots).

              • -

            • The draft folder is -emptied, before creating a new message.

              • -

            • Fetch the names and -UIDs for the filtered list of message types using the RSendAs::FilteredMessageTypesL() function -to create a SendAs message. Then the UID based on the message type is returned, -and with the entry set on the drafts folder a SendAs message is created by -calling the RSendAsMessage::CreateL() function.

              • -

            • Set a body text for -the message and specify the recipients. In this example, the body text is -set using an option, which is read from the user. Option given to the user -are '1' for 8-bit encoding, '2' for 16-bit encoding and '0' or by default -its unicode type of encoding. The encoded descriptor is set as the message's -body text using the RSendAsMessage::SetBodyTextL()function.

              • -

            • The recipients are added using the RSendAsMessage::AddRecipientL() function. -The recipient's address is held in a descriptor. The alias is the displayed -recipient name.

              • -

            • The recipient type is -one of the TSendAsRecipientType enumeration values, that -is, one of the following:

                -

              • ESendAsRecipientTo - -The recipient goes in the 'To' field.

                • -

              • ESendAsRecipientCc - -The recipient goes in the 'Cc' field

                • -

              • ESendAsRecipientBcc - -The recipient goes in the 'Bcc' field

                • -

              If the 'Cc' field is not supported, the recipient will instead be -added to the 'To' field since these are functionally equivalent.

              If -the 'Bcc' field is not supported, this function will return KErrNotSupported.

              • -

            The example also displays the names of the accounts present in the -list.

            To demonstrate this, 3 new accounts are appended and they are -displayed in a for-loop by calling CSendAsAccounts::AccountNames().MdcaPoint(i), -where the MdcaPoint() function takes in the integer value -of the current iteration in the for-loop and indexes into a descriptor array.

            The -example also demonstrates how to refine the available message types of the -connected session using the RSendAs::FilterAgainstCapability() function.

            The RSendAsMessage::SendMessage() function is used asynchronously to send the message. Finally the RsendAs::Close() function -is used to end the session with SendAs server.

            -
            Download

            Click -on the following link to download the example: sendAs.zip

            Click: browse to view the example code.

            -
            Class summary

            The SendAs v2 example application -uses the following classes:

            CMsvEntry MMsvEntryObserver CMsvSession RSendAs CSendAsMessageTypes CSendAsAccounts CSendAsAccounts CMsvOperationWait RSendAsMessage

            -
            Build

            The Symbian build process describes -how to build an application.

            The SendAs example builds an executable -called SendAs2Example.exe in the standard location (\epoc32\release\winscw\ <build_variant> for -CodeWarrior). After launching the executable, depending on the emulator you -are using, you may need to task away from the app launcher/shell screen to -view the console.

            -
            See also

            To -create advanced applications using the SendAs API refer to the complete SendAs API reference -documentation, which details all the features of the API.

            + + + + + +SendAs v2.0 +
            Description

            The application establishes a session with the SendAs server, +sets a message entry, creates a message, sets its body text, adds +a recipient, sends the message and closes the session. The sequence +of events is detailed in the following list:

              +

            • Create a session +with the SendAs server using CMsvSession::OpenSyncL(MMsvSessionObserver +&) function.

              • +

            • Set the message +entry using the CMsvEntry::SetEntryL(TMsvId) function.

              • +

            • After setting +the entry, the application gets a selection containing the IDs of +all the context children, using the CMsvEntry::ChildrenL()const function.

              • +

            • The connection +to the server is made using the default number of message slots available +to a session, which is 4, (KSendAsDefaultMessageSlots).

              • +

            • The draft folder +is emptied, before creating a new message.

              • +

            • Fetch the names +and UIDs for the filtered list of message types using the RSendAs::FilteredMessageTypesL() function to create a SendAs +message. Then the UID based on the message type is returned, and with +the entry set on the drafts folder a SendAs message is created by +calling the RSendAsMessage::CreateL(RSendAs &,TSendAsAccount) function.

              • +

            • Set a body text +for the message and specify the recipients. In this example, the body +text is set using an option, which is read from the user. Option given +to the user are '1' for 8-bit encoding, '2' for 16-bit encoding and +'0' or by default its unicode type of encoding. The encoded descriptor +is set as the message's body text using the RSendAsMessage::SetBodyTextL(const +CRichText &)function.

              • +

            • The recipients are added using the RSendAsMessage::AddRecipientL(const +TDesC &,TSendAsRecipientType) function. The recipient's +address is held in a descriptor. The alias is the displayed recipient +name.

              • +

            • The recipient +type is one of the TSendAsRecipientType enumeration +values, that is, one of the following:

                +

              • ESendAsRecipientTo - The recipient goes in the 'To' field.

                • +

              • ESendAsRecipientCc - The recipient goes in the 'Cc' field

                • +

              • ESendAsRecipientBcc - The recipient goes in the 'Bcc' field

                • +

              If the 'Cc' field is not supported, the recipient will instead +be added to the 'To' field since these are functionally equivalent.

              If the 'Bcc' field is not supported, this function will return KErrNotSupported.

              • +

            The example also displays the names of the accounts present +in the list.

            To demonstrate this, 3 new accounts are appended +and they are displayed in a for-loop by calling CSendAsAccounts::AccountNames().MdcaPoint(i), where the MdcaPoint() function takes in the +integer value of the current iteration in the for-loop and indexes +into a descriptor array.

            The example also demonstrates how +to refine the available message types of the connected session using +the RSendAs::FilterAgainstCapability() function.

            The RSendAsMessage::SendMessage() function +is used asynchronously to send the message. Finally the RsendAs::Close() function is used to end the session with SendAs server.

            +
            Download

            Click on the following link to download the example: sendAs.zip

            Click: browse to view the example code.

            +
            Class +summary

            The SendAs v2 example application uses the following +classes:

              +

            • CMsvEntry

              • +

            • MMsvEntryObserver

              • +

            • CMsvSession

              • +

            • RSendAs

              • +

            • CSendAsMessageTypes

              • +

            • CSendAsAccounts

              • +

            • CSendAsAccounts

              • +

            • CMsvOperationWait

              • +

            • RSendAsMessage

              • +
            +
            Build

            The Symbian +build process describes how to build an application.

            The SendAs example builds an executable called SendAs2Example.exe in the standard location (\epoc32\release\winscw\ <build_variant> for CodeWarrior). After launching the +executable, depending on the emulator you are using, you may need +to task away from the app launcher/shell screen to view the console.

            +
            See +also

            To create advanced applications using the SendAs API +refer to the complete SendAs API +reference documentation, which details all the features of the API.

            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-383A96FD-99C3-593C-B7A2-58153F4050DE-master.png Binary file Symbian3/SDK/Source/GUID-383A96FD-99C3-593C-B7A2-58153F4050DE-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-383A96FD-99C3-593C-B7A2-58153F4050DE_d0e383779_href.png Binary file Symbian3/SDK/Source/GUID-383A96FD-99C3-593C-B7A2-58153F4050DE_d0e383779_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3853600F-A096-53A6-8E68-4815ED85FD05_d0e176377_href.png Binary file Symbian3/SDK/Source/GUID-3853600F-A096-53A6-8E68-4815ED85FD05_d0e176377_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3853600F-A096-53A6-8E68-4815ED85FD05_d0e182971_href.png Binary file Symbian3/SDK/Source/GUID-3853600F-A096-53A6-8E68-4815ED85FD05_d0e182971_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-385BB488-5C32-58A7-8401-F3F0A0707DD9.dita --- a/Symbian3/SDK/Source/GUID-385BB488-5C32-58A7-8401-F3F0A0707DD9.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-385BB488-5C32-58A7-8401-F3F0A0707DD9.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,57 +1,63 @@ - - - - - -User -Interface MTM implementation -

            Note: This example is designed to work with Techview and there -is no guarantee that it will work on other interfaces

            -
            Example Code

            Click on the following link to download -the example:.TextMTM.zip

            Click: browse to view the example code.

            The files reproduced -here are the main files contained in the examples directory. Some extra files -may be needed to run the examples, and these will be found in the appropriate -examples directory.

            -
            Class summary

            CBaseMtmUi TMsvId CMsvOperation CEikFileSaveAsDialog CEikDialog

            -
            Description

            The txtu project -demonstrates a User Interface MTM. The central class is CTextMtmUi, -derived from the User Interface MTM base class CBaseMtmUi.

            Note -that the txtu project has dependencies on some GUI components -that might not be present on all SDKs.

            txtu implements -the following MTM functionality:

            -
            Basic functions for messages

            Create(): -this creates a new local message in the Draft folder, -with description field set to "New Text", and then invokes edit.

            Edit(): -no UI for editing and viewing text messages is implemented. A simple stub -is provided that simply appends the text "Edited document" to the message -and puts up an information message.

            If an edit command is invoked -on a remote message entry (an entry under a Text service entry), the MTM offers -to copy it to the local Inbox first. This is performed by class CEditRemoteOperation. -and dialog resource r_dialog_refuse_edit_remote_message.

            Open() and View(): -these functions for a message context simply calls the edit function.

            CopyToL(), MoveToL(), CopyFromL(), MoveFromL() and DeleteL(): simple implementations -of these functions are provided that use the CMsvEntry copy, -move and delete functions. These commands are passed to the Message Server, -which then passes them on to the Server-side Text MTM.

            ReplyL() and ForwardL(): -there is no UI support for message replies and forwarding.

            -
            Basic functions for services

            Create() and Edit(): -when requested to create a new Text service entry, a dialog pops up allowing -the user to specify the folder associated with the service. This is performed -by class CTextMtmEditServiceDialog and resource r_dialog_service_settings. -The service entry can then be edited later on, to change the folder.

            After -the service entry is created or changed, an automatic refresh will be triggered.

            -
            MTM-specific operations

            The following MTM-specific -operations are accepted:

              -

            • Refresh: this command -refreshes the currently highlighted service entry. It calls the MTM-specific -operations provided by the Client-side MTM to do this.

              • -

            • Export text to file: -exports the text contained in a text message to a file. This is performed -by DoExportTextFromMessageL().

              • -
            + + + + + +User Interface MTM implementation +

            Note: This example is designed to work with Techview and +there is no guarantee that it will work on other interfaces

            +
            Example +Code

            Click on the following link to download the example:.TextMTM.zip

            Click: browse to view the example code.

            The files +reproduced here are the main files contained in the examples directory. +Some extra files may be needed to run the examples, and these will +be found in the appropriate examples directory.

            +
            Class +summary
              +

            • CBaseMtmUi

              • +

            • TMsvId

              • +

            • CMsvOperation

              • +

            • CEikFileSaveAsDialog

              • +

            • CEikDialog

              • +
            +
            Description

            The txtu project demonstrates a User Interface +MTM. The central class is CTextMtmUi, derived from +the User Interface MTM base class CBaseMtmUi.

            Note that the txtu project has dependencies +on some GUI components that might not be present on all SDKs.

            txtu implements the following MTM functionality:

            +
            Basic +functions for messages

            Create(): this +creates a new local message in the Draft folder, with description field set to "New Text", and then invokes +edit.

            Edit(): no UI for editing and viewing +text messages is implemented. A simple stub is provided that simply +appends the text "Edited document" to the message and puts up an information +message.

            If an edit command is invoked on a remote message +entry (an entry under a Text service entry), the MTM offers to copy +it to the local Inbox first. This is performed by class CEditRemoteOperation. and dialog resource r_dialog_refuse_edit_remote_message.

            Open() and View(): these +functions for a message context simply calls the edit function.

            CopyToL(), MoveToL(), CopyFromL(), MoveFromL() and DeleteL(): simple implementations of these functions are provided that use +the CMsvEntry copy, move and delete functions. These +commands are passed to the Message Server, which then passes them +on to the Server-side Text MTM.

            ReplyL() and ForwardL(): there is no UI support for message +replies and forwarding.

            +
            Basic +functions for services

            Create() and Edit(): when requested to create a new Text service entry, +a dialog pops up allowing the user to specify the folder associated +with the service. This is performed by class CTextMtmEditServiceDialog and resource r_dialog_service_settings. The service +entry can then be edited later on, to change the folder.

            After +the service entry is created or changed, an automatic refresh will +be triggered.

            +
            MTM-specific +operations

            The following MTM-specific operations are accepted:

              +

            • Refresh: this +command refreshes the currently highlighted service entry. It calls +the MTM-specific operations provided by the Client-side MTM to do +this.

              • +

            • Export text +to file: exports the text contained in a text message to a file. This +is performed by DoExportTextFromMessageL().

              • +
             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-38679CA2-0066-589C-988F-AC14B7E2F107-GENID-1-8-1-3-1-1-9-1-4-1-10-1.dita --- a/Symbian3/SDK/Source/GUID-38679CA2-0066-589C-988F-AC14B7E2F107-GENID-1-8-1-3-1-1-9-1-4-1-10-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,144 +0,0 @@ - - - - - -Interacting -with text editor controls -
            Introduction

            The -public parts of the MCoeFepAwareTextEditor class (which is -defined in epoc32\include\FEPBASE.H) are as follows:

            class MCoeFepAwareTextEditor - { -public: - virtual void StartFepInlineEditL(const TDesC& aInitialInlineText, TInt aPositionOfInsertionPointInInlineText, TBool aCursorVisibility, const MFormCustomDraw*, MFepInlineTextFormatRetriever&, MFepPointerEventHandlerDuringInlineEdit&)=0; - virtual void UpdateFepInlineTextL(const TDesC& aNewInlineText, TInt aPositionOfInsertionPointInInlineText)=0; - virtual void SetInlineEditingCursorVisibilityL(TBool aCursorVisibility)=0; - IMPORT_C void CommitFepInlineEditL(CCoeEnv& aConeEnvironment); - virtual void CancelFepInlineEdit()=0; - virtual TInt DocumentLengthForFep() const=0; - virtual TInt DocumentMaximumLengthForFep() const=0; - virtual void SetCursorSelectionForFepL(const TCursorSelection& aCursorSelection)=0; - virtual void GetCursorSelectionForFep(TCursorSelection& aCursorSelection) const=0; - virtual void GetEditorContentForFep(TDes& aEditorContent, TInt aDocumentPosition, TInt aLengthToRetrieve) const=0; - virtual void GetFormatForFep(TCharFormat& aFormat, TInt aDocumentPosition) const=0; - virtual void GetScreenCoordinatesForFepL(TPoint& aLeftSideOfBaseLine, TInt& aHeight, TInt& aAscent, TInt aDocumentPosition) const=0; - IMPORT_C MCoeFepAwareTextEditor_Extension1* Extension1(); -private: - virtual void DoCommitFepInlineEditL()=0; - IMPORT_C virtual MCoeFepAwareTextEditor_Extension1* Extension1(TBool& aSetToTrue); - };

            An implementation of this interface is provided by TechView’s CEikEdwin class -(CEikEdwin was part of Uikon until Symbian OS v7.0s). MCoeFepAwareTextEditor member -functions can be divided into two categories:

              -

            • Functions for inline editing.

              • -

            • Other functions that can broadly be categorized under the title 'context -awareness'.

              • -

            -
            Inline editing

            Inline -editing means the text to be sent to the application is composed inside the -target text editing control, rather than in the FEP’s floating window. This -requires the cooperation of the target text editing control which must implement -the MCoeFepAwareTextEditor interface. An inline editing transaction -consists of the following sequence:

              -

            • a call to StartFepInlineEditL(),

              • -

            • zero, one or more calls -to UpdateFepInlineTextL(),

              • -

            • finally, a call to either CommitFepInlineEditL() or CancelFepInlineEdit(). (Note that CCoeFep::SimulateKeyEventsL() is not used at -all in inline editing: the text is sent to the application via an entirely -different mechanism.)

              • -

            The second parameter (TInt aPositionOfInsertionPointInInlineText) -to StartFepInlineEditL() and UpdateFepInlineTextL() indicates -where, in the inline text (which is passed as the first parameter), the insertion -point, or cursor, is to appear. Note that the first parameter to UpdateFepInlineTextL() must -be used to pass the entire inline text, not merely any new text to -be combined with the old inline text. The third parameter (TBool aCursorVisibility) -controls whether the insertion point is visible or not. As the types of the -fourth, fifth and sixth parameters are abstract base classes, the FEP must -create objects derived from these classes (MFormCustomDraw, MFepInlineTextFormatRetriever and MFepPointerEventHandlerDuringInlineEdit) and pass references. These object(s) must remain in existence for the entire -duration of the inline editing transaction.

            Note that MFormCustomDraw pointer -may NULL. MFormCustomDraw belongs to the FORM component -and is not described here. It enables the FEP to do advanced formatting of -the inline text. The details of the other two interface classes used in inline -editing are discussed next.

            MFepInlineTextFormatRetriever (defined -in epoc32\include\FEPITFR.H) has a single (pure) virtual -function whose signature is as follows:

            virtual void GetFormatOfFepInlineText(TCharFormat& aFormat, TInt& aNumberOfCharactersWithSameFormat, TInt aPositionOfCharacter) const=0;

            The first parameter is to be set by the function to the format of the -inline text. For example, TFEP1plugin’s implementation of this function sets -this parameter to red, underlined text. MCoeFepAwareTextEditor provides -a member function for finding out the ambient TCharFormat of -the text editor: GetFormatForFep(). This can be called inside -the FEP’s implementation of GetFormatOfFepInlineText() to -make any necessary adjustments to the format of the inline text to ensure -that it differentiates itself from the surrounding text.

            The second -and third parameters to GetFormatOfFepInlineText() enable -different parts of the inline text to have different formats. Their use is -best illustrated by an example (albeit an artificial one). Suppose the FEP -requires the first four characters of the inline text to be red, the next -two characters (if there are any) to be green, and any subsequent characters -to be blue, the GetFormatOfFepInlineText() function would -look as follows:

            void Xxxxx::GetFormatOfFepInlineText(TCharFormat& aFormat, TInt& aNumberOfCharactersWithSameFormat, TInt aPositionOfCharacter) const - { - const TInt lengthOfRemainderOfInlineText=iBuffer.Length()-aPositionOfCharacter; - aFormat=iBaseFormatForInlineText; - aFormat.iFontPresentation.iTextColor.SetRed(0); - aFormat.iFontPresentation.iTextColor.SetGreen(0); - aFormat.iFontPresentation.iTextColor.SetBlue(0); - if (aPositionOfCharacter==0) - { - // first four characters are red - aFormat.iFontPresentation.iTextColor.SetRed(255); - aNumberOfCharactersWithSameFormat=Min(4, lengthOfRemainderOfInlineText); - } - else if (aPositionOfCharacter==4) - { - // next two characters are green - aFormat.iFontPresentation.iTextColor.SetGreen(255); - aNumberOfCharactersWithSameFormat=Min(2, lengthOfRemainderOfInlineText); - } - else if (aPositionOfCharacter==6) - { - // any subsequent characters are blue - aFormat.iFontPresentation.iTextColor.SetBlue(255); - aNumberOfCharactersWithSameFormat=lengthOfRemainderOfInlineText; - } - }

            MFepPointerEventHandlerDuringInlineEdit (which -is defined in epoc32\include\FEPBASE.H) gives the FEP -the opportunity to handle pointer events which occur in the area on the screen -occupied by the inline text. It has a single (pure) virtual function whose -signature is as follows:

            virtual void HandlePointerEventInInlineTextL(TPointerEvent::TType aType, TUint aModifiers, TInt aPositionInInlineText)=0;

            The parameters indicate to the FEP the event’s type (for instance pointer -down, pointer drag or pointer up), the keyboard modifiers (for instance caps -lock and shift) and the logical position of the event in the inline text.

            -
            Context awareness

            As -well as providing support for inline editing, the MCoeFepAwareTextEditor interface -class enables the FEP to find out information about the text editor control -with focus. DocumentLengthForFep() returns the length of -the text held in the text editor. DocumentMaximumLengthForFep() returns -the upper limit (if any) on the length of text that the text editor can hold. SetCursorSelectionForFepL() selects -the specified text range in the text editor, and GetCursorSelectionForFep() sets -its parameter to the selected text range in the text editor. GetEditorContentForFep() allows -the FEP to retrieve any segment of the text held in the text editor. GetFormatForFep() sets -its first parameter according to the character format at the position in the -text editor specified by the second parameter. GetScreenCoordinatesForFepL() sets -the first parameter to the screen coordinates of the left end of the baseline -of the character glyph whose position in the text editor is specified by the -last parameter. The second and third parameters are set, respectively, to -the height and ascent of the font used at that document position. This function -can be used, for example, to position a FEP window as close as possible to -the text editor’s insertion point (in other words, the cursor position).

            The Extension1() member -function of MCoeFepAwareTextEditor returns a pointer to -an object of the interface class MCoeFepAwareTextEditor_Extension1 - (defined in epoc32\include\FEPBASE.H). -This class has two public (pure) virtual functions whose signatures are as -follows:

            virtual void SetStateTransferingOwnershipL(CState* aState, TUid aTypeSafetyUid)=0; -virtual CState* State(TUid aTypeSafetyUid)=0;

            The CState class -is defined within the scope of the MCoeFepAwareTextEditor_Extension1 class. -The purpose of the UIDs in the two functions above is to enable the FEP to -safely downcast the CState pointer returned by the State() function -to a pointer to a derived class known about by the FEP. The CState class -is provided to enable FEPs to store state information inside text editor controls, -where that state information is only of interest to the FEP.

            -             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-38679CA2-0066-589C-988F-AC14B7E2F107-GENID-1-8-1-6-1-1-4-1-8-1-4-1-10-1.dita --- a/Symbian3/SDK/Source/GUID-38679CA2-0066-589C-988F-AC14B7E2F107-GENID-1-8-1-6-1-1-4-1-8-1-4-1-10-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,144 +0,0 @@ - - - - - -Interacting -with text editor controls -
            Introduction

            The -public parts of the MCoeFepAwareTextEditor class (which is -defined in epoc32\include\FEPBASE.H) are as follows:

            class MCoeFepAwareTextEditor - { -public: - virtual void StartFepInlineEditL(const TDesC& aInitialInlineText, TInt aPositionOfInsertionPointInInlineText, TBool aCursorVisibility, const MFormCustomDraw*, MFepInlineTextFormatRetriever&, MFepPointerEventHandlerDuringInlineEdit&)=0; - virtual void UpdateFepInlineTextL(const TDesC& aNewInlineText, TInt aPositionOfInsertionPointInInlineText)=0; - virtual void SetInlineEditingCursorVisibilityL(TBool aCursorVisibility)=0; - IMPORT_C void CommitFepInlineEditL(CCoeEnv& aConeEnvironment); - virtual void CancelFepInlineEdit()=0; - virtual TInt DocumentLengthForFep() const=0; - virtual TInt DocumentMaximumLengthForFep() const=0; - virtual void SetCursorSelectionForFepL(const TCursorSelection& aCursorSelection)=0; - virtual void GetCursorSelectionForFep(TCursorSelection& aCursorSelection) const=0; - virtual void GetEditorContentForFep(TDes& aEditorContent, TInt aDocumentPosition, TInt aLengthToRetrieve) const=0; - virtual void GetFormatForFep(TCharFormat& aFormat, TInt aDocumentPosition) const=0; - virtual void GetScreenCoordinatesForFepL(TPoint& aLeftSideOfBaseLine, TInt& aHeight, TInt& aAscent, TInt aDocumentPosition) const=0; - IMPORT_C MCoeFepAwareTextEditor_Extension1* Extension1(); -private: - virtual void DoCommitFepInlineEditL()=0; - IMPORT_C virtual MCoeFepAwareTextEditor_Extension1* Extension1(TBool& aSetToTrue); - };

            An implementation of this interface is provided by TechView’s CEikEdwin class -(CEikEdwin was part of Uikon until Symbian OS v7.0s). MCoeFepAwareTextEditor member -functions can be divided into two categories:

              -

            • Functions for inline editing.

              • -

            • Other functions that can broadly be categorized under the title 'context -awareness'.

              • -

            -
            Inline editing

            Inline -editing means the text to be sent to the application is composed inside the -target text editing control, rather than in the FEP’s floating window. This -requires the cooperation of the target text editing control which must implement -the MCoeFepAwareTextEditor interface. An inline editing transaction -consists of the following sequence:

              -

            • a call to StartFepInlineEditL(),

              • -

            • zero, one or more calls -to UpdateFepInlineTextL(),

              • -

            • finally, a call to either CommitFepInlineEditL() or CancelFepInlineEdit(). (Note that CCoeFep::SimulateKeyEventsL() is not used at -all in inline editing: the text is sent to the application via an entirely -different mechanism.)

              • -

            The second parameter (TInt aPositionOfInsertionPointInInlineText) -to StartFepInlineEditL() and UpdateFepInlineTextL() indicates -where, in the inline text (which is passed as the first parameter), the insertion -point, or cursor, is to appear. Note that the first parameter to UpdateFepInlineTextL() must -be used to pass the entire inline text, not merely any new text to -be combined with the old inline text. The third parameter (TBool aCursorVisibility) -controls whether the insertion point is visible or not. As the types of the -fourth, fifth and sixth parameters are abstract base classes, the FEP must -create objects derived from these classes (MFormCustomDraw, MFepInlineTextFormatRetriever and MFepPointerEventHandlerDuringInlineEdit) and pass references. These object(s) must remain in existence for the entire -duration of the inline editing transaction.

            Note that MFormCustomDraw pointer -may NULL. MFormCustomDraw belongs to the FORM component -and is not described here. It enables the FEP to do advanced formatting of -the inline text. The details of the other two interface classes used in inline -editing are discussed next.

            MFepInlineTextFormatRetriever (defined -in epoc32\include\FEPITFR.H) has a single (pure) virtual -function whose signature is as follows:

            virtual void GetFormatOfFepInlineText(TCharFormat& aFormat, TInt& aNumberOfCharactersWithSameFormat, TInt aPositionOfCharacter) const=0;

            The first parameter is to be set by the function to the format of the -inline text. For example, TFEP1plugin’s implementation of this function sets -this parameter to red, underlined text. MCoeFepAwareTextEditor provides -a member function for finding out the ambient TCharFormat of -the text editor: GetFormatForFep(). This can be called inside -the FEP’s implementation of GetFormatOfFepInlineText() to -make any necessary adjustments to the format of the inline text to ensure -that it differentiates itself from the surrounding text.

            The second -and third parameters to GetFormatOfFepInlineText() enable -different parts of the inline text to have different formats. Their use is -best illustrated by an example (albeit an artificial one). Suppose the FEP -requires the first four characters of the inline text to be red, the next -two characters (if there are any) to be green, and any subsequent characters -to be blue, the GetFormatOfFepInlineText() function would -look as follows:

            void Xxxxx::GetFormatOfFepInlineText(TCharFormat& aFormat, TInt& aNumberOfCharactersWithSameFormat, TInt aPositionOfCharacter) const - { - const TInt lengthOfRemainderOfInlineText=iBuffer.Length()-aPositionOfCharacter; - aFormat=iBaseFormatForInlineText; - aFormat.iFontPresentation.iTextColor.SetRed(0); - aFormat.iFontPresentation.iTextColor.SetGreen(0); - aFormat.iFontPresentation.iTextColor.SetBlue(0); - if (aPositionOfCharacter==0) - { - // first four characters are red - aFormat.iFontPresentation.iTextColor.SetRed(255); - aNumberOfCharactersWithSameFormat=Min(4, lengthOfRemainderOfInlineText); - } - else if (aPositionOfCharacter==4) - { - // next two characters are green - aFormat.iFontPresentation.iTextColor.SetGreen(255); - aNumberOfCharactersWithSameFormat=Min(2, lengthOfRemainderOfInlineText); - } - else if (aPositionOfCharacter==6) - { - // any subsequent characters are blue - aFormat.iFontPresentation.iTextColor.SetBlue(255); - aNumberOfCharactersWithSameFormat=lengthOfRemainderOfInlineText; - } - }

            MFepPointerEventHandlerDuringInlineEdit (which -is defined in epoc32\include\FEPBASE.H) gives the FEP -the opportunity to handle pointer events which occur in the area on the screen -occupied by the inline text. It has a single (pure) virtual function whose -signature is as follows:

            virtual void HandlePointerEventInInlineTextL(TPointerEvent::TType aType, TUint aModifiers, TInt aPositionInInlineText)=0;

            The parameters indicate to the FEP the event’s type (for instance pointer -down, pointer drag or pointer up), the keyboard modifiers (for instance caps -lock and shift) and the logical position of the event in the inline text.

            -
            Context awareness

            As -well as providing support for inline editing, the MCoeFepAwareTextEditor interface -class enables the FEP to find out information about the text editor control -with focus. DocumentLengthForFep() returns the length of -the text held in the text editor. DocumentMaximumLengthForFep() returns -the upper limit (if any) on the length of text that the text editor can hold. SetCursorSelectionForFepL() selects -the specified text range in the text editor, and GetCursorSelectionForFep() sets -its parameter to the selected text range in the text editor. GetEditorContentForFep() allows -the FEP to retrieve any segment of the text held in the text editor. GetFormatForFep() sets -its first parameter according to the character format at the position in the -text editor specified by the second parameter. GetScreenCoordinatesForFepL() sets -the first parameter to the screen coordinates of the left end of the baseline -of the character glyph whose position in the text editor is specified by the -last parameter. The second and third parameters are set, respectively, to -the height and ascent of the font used at that document position. This function -can be used, for example, to position a FEP window as close as possible to -the text editor’s insertion point (in other words, the cursor position).

            The Extension1() member -function of MCoeFepAwareTextEditor returns a pointer to -an object of the interface class MCoeFepAwareTextEditor_Extension1 - (defined in epoc32\include\FEPBASE.H). -This class has two public (pure) virtual functions whose signatures are as -follows:

            virtual void SetStateTransferingOwnershipL(CState* aState, TUid aTypeSafetyUid)=0; -virtual CState* State(TUid aTypeSafetyUid)=0;

            The CState class -is defined within the scope of the MCoeFepAwareTextEditor_Extension1 class. -The purpose of the UIDs in the two functions above is to enable the FEP to -safely downcast the CState pointer returned by the State() function -to a pointer to a derived class known about by the FEP. The CState class -is provided to enable FEPs to store state information inside text editor controls, -where that state information is only of interest to the FEP.

            -             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-38679CA2-0066-589C-988F-AC14B7E2F107.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-38679CA2-0066-589C-988F-AC14B7E2F107.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,144 @@ + + + + + +Interacting +with text editor controls +
            Introduction

            The +public parts of the MCoeFepAwareTextEditor class (which is +defined in epoc32\include\FEPBASE.H) are as follows:

            class MCoeFepAwareTextEditor + { +public: + virtual void StartFepInlineEditL(const TDesC& aInitialInlineText, TInt aPositionOfInsertionPointInInlineText, TBool aCursorVisibility, const MFormCustomDraw*, MFepInlineTextFormatRetriever&, MFepPointerEventHandlerDuringInlineEdit&)=0; + virtual void UpdateFepInlineTextL(const TDesC& aNewInlineText, TInt aPositionOfInsertionPointInInlineText)=0; + virtual void SetInlineEditingCursorVisibilityL(TBool aCursorVisibility)=0; + IMPORT_C void CommitFepInlineEditL(CCoeEnv& aConeEnvironment); + virtual void CancelFepInlineEdit()=0; + virtual TInt DocumentLengthForFep() const=0; + virtual TInt DocumentMaximumLengthForFep() const=0; + virtual void SetCursorSelectionForFepL(const TCursorSelection& aCursorSelection)=0; + virtual void GetCursorSelectionForFep(TCursorSelection& aCursorSelection) const=0; + virtual void GetEditorContentForFep(TDes& aEditorContent, TInt aDocumentPosition, TInt aLengthToRetrieve) const=0; + virtual void GetFormatForFep(TCharFormat& aFormat, TInt aDocumentPosition) const=0; + virtual void GetScreenCoordinatesForFepL(TPoint& aLeftSideOfBaseLine, TInt& aHeight, TInt& aAscent, TInt aDocumentPosition) const=0; + IMPORT_C MCoeFepAwareTextEditor_Extension1* Extension1(); +private: + virtual void DoCommitFepInlineEditL()=0; + IMPORT_C virtual MCoeFepAwareTextEditor_Extension1* Extension1(TBool& aSetToTrue); + };

            An implementation of this interface is provided by TechView’s CEikEdwin class +(CEikEdwin was part of Uikon until Symbian OS v7.0s). MCoeFepAwareTextEditor member +functions can be divided into two categories:

              +

            • Functions for inline editing.

              • +

            • Other functions that can broadly be categorized under the title 'context +awareness'.

              • +

            +
            Inline editing

            Inline +editing means the text to be sent to the application is composed inside the +target text editing control, rather than in the FEP’s floating window. This +requires the cooperation of the target text editing control which must implement +the MCoeFepAwareTextEditor interface. An inline editing transaction +consists of the following sequence:

              +

            • a call to StartFepInlineEditL(),

              • +

            • zero, one or more calls +to UpdateFepInlineTextL(),

              • +

            • finally, a call to either CommitFepInlineEditL() or CancelFepInlineEdit(). (Note that CCoeFep::SimulateKeyEventsL() is not used at +all in inline editing: the text is sent to the application via an entirely +different mechanism.)

              • +

            The second parameter (TInt aPositionOfInsertionPointInInlineText) +to StartFepInlineEditL() and UpdateFepInlineTextL() indicates +where, in the inline text (which is passed as the first parameter), the insertion +point, or cursor, is to appear. Note that the first parameter to UpdateFepInlineTextL() must +be used to pass the entire inline text, not merely any new text to +be combined with the old inline text. The third parameter (TBool aCursorVisibility) +controls whether the insertion point is visible or not. As the types of the +fourth, fifth and sixth parameters are abstract base classes, the FEP must +create objects derived from these classes (MFormCustomDraw, MFepInlineTextFormatRetriever and MFepPointerEventHandlerDuringInlineEdit) and pass references. These object(s) must remain in existence for the entire +duration of the inline editing transaction.

            Note that MFormCustomDraw pointer +may NULL. MFormCustomDraw belongs to the FORM component +and is not described here. It enables the FEP to do advanced formatting of +the inline text. The details of the other two interface classes used in inline +editing are discussed next.

            MFepInlineTextFormatRetriever (defined +in epoc32\include\FEPITFR.H) has a single (pure) virtual +function whose signature is as follows:

            virtual void GetFormatOfFepInlineText(TCharFormat& aFormat, TInt& aNumberOfCharactersWithSameFormat, TInt aPositionOfCharacter) const=0;

            The first parameter is to be set by the function to the format of the +inline text. For example, TFEP1plugin’s implementation of this function sets +this parameter to red, underlined text. MCoeFepAwareTextEditor provides +a member function for finding out the ambient TCharFormat of +the text editor: GetFormatForFep(). This can be called inside +the FEP’s implementation of GetFormatOfFepInlineText() to +make any necessary adjustments to the format of the inline text to ensure +that it differentiates itself from the surrounding text.

            The second +and third parameters to GetFormatOfFepInlineText() enable +different parts of the inline text to have different formats. Their use is +best illustrated by an example (albeit an artificial one). Suppose the FEP +requires the first four characters of the inline text to be red, the next +two characters (if there are any) to be green, and any subsequent characters +to be blue, the GetFormatOfFepInlineText() function would +look as follows:

            void Xxxxx::GetFormatOfFepInlineText(TCharFormat& aFormat, TInt& aNumberOfCharactersWithSameFormat, TInt aPositionOfCharacter) const + { + const TInt lengthOfRemainderOfInlineText=iBuffer.Length()-aPositionOfCharacter; + aFormat=iBaseFormatForInlineText; + aFormat.iFontPresentation.iTextColor.SetRed(0); + aFormat.iFontPresentation.iTextColor.SetGreen(0); + aFormat.iFontPresentation.iTextColor.SetBlue(0); + if (aPositionOfCharacter==0) + { + // first four characters are red + aFormat.iFontPresentation.iTextColor.SetRed(255); + aNumberOfCharactersWithSameFormat=Min(4, lengthOfRemainderOfInlineText); + } + else if (aPositionOfCharacter==4) + { + // next two characters are green + aFormat.iFontPresentation.iTextColor.SetGreen(255); + aNumberOfCharactersWithSameFormat=Min(2, lengthOfRemainderOfInlineText); + } + else if (aPositionOfCharacter==6) + { + // any subsequent characters are blue + aFormat.iFontPresentation.iTextColor.SetBlue(255); + aNumberOfCharactersWithSameFormat=lengthOfRemainderOfInlineText; + } + }

            MFepPointerEventHandlerDuringInlineEdit (which +is defined in epoc32\include\FEPBASE.H) gives the FEP +the opportunity to handle pointer events which occur in the area on the screen +occupied by the inline text. It has a single (pure) virtual function whose +signature is as follows:

            virtual void HandlePointerEventInInlineTextL(TPointerEvent::TType aType, TUint aModifiers, TInt aPositionInInlineText)=0;

            The parameters indicate to the FEP the event’s type (for instance pointer +down, pointer drag or pointer up), the keyboard modifiers (for instance caps +lock and shift) and the logical position of the event in the inline text.

            +
            Context awareness

            As +well as providing support for inline editing, the MCoeFepAwareTextEditor interface +class enables the FEP to find out information about the text editor control +with focus. DocumentLengthForFep() returns the length of +the text held in the text editor. DocumentMaximumLengthForFep() returns +the upper limit (if any) on the length of text that the text editor can hold. SetCursorSelectionForFepL() selects +the specified text range in the text editor, and GetCursorSelectionForFep() sets +its parameter to the selected text range in the text editor. GetEditorContentForFep() allows +the FEP to retrieve any segment of the text held in the text editor. GetFormatForFep() sets +its first parameter according to the character format at the position in the +text editor specified by the second parameter. GetScreenCoordinatesForFepL() sets +the first parameter to the screen coordinates of the left end of the baseline +of the character glyph whose position in the text editor is specified by the +last parameter. The second and third parameters are set, respectively, to +the height and ascent of the font used at that document position. This function +can be used, for example, to position a FEP window as close as possible to +the text editor’s insertion point (in other words, the cursor position).

            The Extension1() member +function of MCoeFepAwareTextEditor returns a pointer to +an object of the interface class MCoeFepAwareTextEditor_Extension1 + (defined in epoc32\include\FEPBASE.H). +This class has two public (pure) virtual functions whose signatures are as +follows:

            virtual void SetStateTransferingOwnershipL(CState* aState, TUid aTypeSafetyUid)=0; +virtual CState* State(TUid aTypeSafetyUid)=0;

            The CState class +is defined within the scope of the MCoeFepAwareTextEditor_Extension1 class. +The purpose of the UIDs in the two functions above is to enable the FEP to +safely downcast the CState pointer returned by the State() function +to a pointer to a derived class known about by the FEP. The CState class +is provided to enable FEPs to store state information inside text editor controls, +where that state information is only of interest to the FEP.

            +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-38C8F8B0-C259-5B03-A13E-10DBED4071F2.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-38C8F8B0-C259-5B03-A13E-10DBED4071F2.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,131 @@ + + + + + +Signing +and verification +

            The following example demonstrates signing and verifying with DSA keys. +It generates a DSA key pair from the factory, signs some randomly generated +data using the private key and then verifies the signature using the public +key.

            +#include <legacyselector.h> +#include <cryptosignatureapi.h> +#include <cryptokeypairgeneratorapi.h> +#include <random.h> +#include <keypair.h> + +using namespace CryptoSpi; + +//Get a DSA key pair generator +CKeyPairGenerator* keyPairGeneratorImpl = NULL; + +TRAPD(err,CKeyPairGeneratorFactory::CreateKeyPairGeneratorL + (keyPairGeneratorImpl, + KDSAKeyPairGeneratorAlgorithmUid, + NULL)); + +if(keyPairGeneratorImpl && (err == KErrNone)) + { + CleanupStack::PushL(keyPairGeneratorImpl); + CCryptoParams* keyParameters = CCryptoParams::NewLC(); + + //Create a DSA key pair + CKeyPair* keyPair = NULL; + + //Hardcode the keybit to 512 + TRAP(err,keyPairGeneratorImpl->GenerateKeyPairL + (512, + *keyParameters, + keyPair)); + + if(keyPair && (err == KErrNone)) + { + CleanupStack::PushL(keyPair); + + //Create a pointer for the signing implementation object + CSigner* signerImpl = NULL; + + //Create a signer implementation object using the private key + const CKey& privateKey = keyPair->PrivateKey(); + TRAP(err,CSignatureFactory::CreateSignerL( + signerImpl, + KDsaSignerUid, + privateKey, + KPaddingModeNoneUid, + NULL)); + + if(!signerImpl || (err != KErrNone)) + { + User::Panic(_L("Signer/Verifier"),err); + } + else + { + CleanupStack::PushL(signerImpl); + + //Create the object to hold the signature + CCryptoParams* signature = CCryptoParams::NewLC(); + + //Generate random data; 128 bytes max length and 128 bytes long + TBuf8<128> message(128); + TRandom::RandomL(message); + + //Sign the random data + //On return, second parameter contains the signature + TRAP(err,signerImpl->SignL(message, *signature)); + + if(err != KErrNone) + { + User::Panic(_L("Signature using private key"),err); + } + + //Now verify the signature using the public key + CVerifier* verifierImpl = NULL; + + const CKey& publicKey = keyPair->PublicKey(); + + // Create a verification object from the factory + TRAP(err,CSignatureFactory::CreateVerifierL(verifierImpl, + KDsaVerifierUid, + publicKey, + KPaddingModeNoneUid, + NULL)); + + if (!verifierImpl || (err != KErrNone)) + { + User::Panic(_L("Signer/Verifier"),err); + } + else + { + CleanupStack::PushL(verifierImpl); + + TBool verifyResult = EFalse; + + //Verify the signature using the public key + verifierImpl->VerifyL(message, *signature, verifyResult); + + if (verifyResult == EFalse) + { + User::Panic(_L("Signer/Verifier"),err); + } + + CleanupStack::PopAndDestroy(verifierImpl); + } + + CleanupStack::PopAndDestroy(signature); + CleanupStack::PopAndDestroy(signerImpl); + } + + CleanupStack::PopAndDestroy(keyPair); + } + + CleanupStack::PopAndDestroy(keyParameters); + CleanupStack::PopAndDestroy(keyPairGeneratorImpl); + } +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-38FF81FD-0C23-586D-AFAE-9F0761A36BAD_d0e213777_href.png Binary file Symbian3/SDK/Source/GUID-38FF81FD-0C23-586D-AFAE-9F0761A36BAD_d0e213777_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-38FF81FD-0C23-586D-AFAE-9F0761A36BAD_d0e217514_href.png Binary file Symbian3/SDK/Source/GUID-38FF81FD-0C23-586D-AFAE-9F0761A36BAD_d0e217514_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-39186342-960A-46A4-BC35-851F53665FA8.dita --- a/Symbian3/SDK/Source/GUID-39186342-960A-46A4-BC35-851F53665FA8.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-39186342-960A-46A4-BC35-851F53665FA8.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,112 +1,112 @@ - - - - - -Writing -the Version 3 Registration Resource FileThe version 3 registration resource file is an evolution of the -version 2 . This version is evolved to accommodate extended interfaces. - -Set Info_format -to the type of info record that is, IMPLEMENTATION_INFO or BINARY_IMPLEMENTATION_INFO. - - -default_data: -The data identifier field used by the resolver to determine if the implementation -matches a client request. -

            In IMPLEMENTATION_INFO structure, the data type -is changed to accommodate maximum 2 strings with 255 bytes each.

            In BINARY_IMPLEMENTATION_INFO, -the data type is changed to accommodate a maximum 512 bytes.

            -             -opaque_data: -A binary data field that can contain additional data. This additional data -can be used by the custom resolvers. -

            In IMPLEMENTATION_INFO structure, the data type -is changed to accommodate maximum 2 strings with 255 bytes each.

            In BINARY_IMPLEMENTATION_INFO structure, -the data type is changed to accommodate a maximum 512 bytes.

            -             -extended_interfaces a -maximum 8 UID's extended interfaces for both IMPLEMENTATION_INFO structure -and BINARY_IMPLEMENTATION_INFO structure. - -FLAG_ROM_ONLY changed -from bool data type to bit flag. -

            rom_only set to 1 indicates the ROM-only implementation -must be used.

            rom_only set to 0 indicates the ROM-only -implementation can be overidden.

             -             -In REGISTRY_INFO structure, -the resource_format_version must be RESOURCE_FORMAT_VERSION_3 . - - -In INTERFACE_INFOstructure, -the interface_uid is renamed to instantiation_interface_uid. - -In REGISTRY_INFO structure, -the resource_format_version must be RESOURCE_FORMAT_VERSION_3. - - -             -#define IMPLEMENTATION_INFO_RECORD_TYPE1 1 -STRUCT IMPLEMENTATION_INFO - { - BYTE info_format; // = IMPLEMENTATION_INFO_RECORD_TYPE1 - LONG implementation_uid; - BYTE version_no; - LTEXT display_name; - LEN BYTE LTEXT8 default_data[]; // maximum 2 strings with 255 bytes each - LEN BYTE LTEXT8 opaque_data[]; // maximum 2 strings with 255 bytes each - LONG extended_interfaces[]; // maximum 8 extended interfaces - BYTE flags; - } - -#define IMPLEMENTATION_INFO_RECORD_TYPE2 2 -STRUCT BINARY_IMPLEMENTATION_INFO - { - BYTE info_format; // = IMPLEMENTATION_INFO_RECORD_TYPE2 - LONG implementation_uid; - BYTE version_no; - LTEXT display_name; - BYTE default_data[]; // maximum 512 bytes - BYTE opaque_data[]; // maximum 512 bytes - LONG extended_interfaces[]; // maximum 8 extended interfaces - BYTE flags; - } - -STRUCT INTERFACE_INFO - { - LONG instantiation_interface_uid; - STRUCT implementations[]; // maximum 8 implementations for each interface - } - -STRUCT REGISTRY_INFO - { - LONG resource_format_version; // Use RESOURCE_FORMAT_VERSION_3 - LONG dll_uid; - STRUCT interfaces[]; // maximum 4 interfaces - } -

              -

            • Maximum of fourINTERFACE_INFO structures can be defined -in one resource file.

              • -

            • Maximum of eight IMPLEMENTATION_INFO or BINARY_IMPLEMENTATION_INFO structures -in each INTERFACE_INFO . Totally eight structures can be -defined.

              • -

            • Maximum eight extended interfaces in each IMPLEMENTATION_INFO record.

              • -

            • In a IMPLEMENTATION_INFO record a maximum of two strings -with 255 bytes each can be used for default_data oropaque_data definitions.

              • -

            • In a BINARY_IMPLEMENTATION_INFO record, a maximum -of 512 bytes each for default_data or opaque_data definitions. -

              • -

             -             -Writing a -Standard Registration Resource File -Writing the -Version 2 Registration Resource File + + + + + +Writing +the Version 3 Registration Resource FileThe version 3 registration resource file is an evolution of the +version 2 . This version is evolved to accommodate extended interfaces. + +Set Info_format +to the type of info record that is, IMPLEMENTATION_INFO or BINARY_IMPLEMENTATION_INFO. + + +default_data: +The data identifier field used by the resolver to determine if the implementation +matches a client request. +

            In IMPLEMENTATION_INFO structure, the data type +is changed to accommodate maximum 2 strings with 255 bytes each.

            In BINARY_IMPLEMENTATION_INFO, +the data type is changed to accommodate a maximum 512 bytes.

            +             +opaque_data: +A binary data field that can contain additional data. This additional data +can be used by the custom resolvers. +

            In IMPLEMENTATION_INFO structure, the data type +is changed to accommodate maximum 2 strings with 255 bytes each.

            In BINARY_IMPLEMENTATION_INFO structure, +the data type is changed to accommodate a maximum 512 bytes.

            +             +extended_interfaces a +maximum 8 UID's extended interfaces for both IMPLEMENTATION_INFO structure +and BINARY_IMPLEMENTATION_INFO structure. + +FLAG_ROM_ONLY changed +from bool data type to bit flag. +

            rom_only set to 1 indicates the ROM-only implementation +must be used.

            rom_only set to 0 indicates the ROM-only +implementation can be overidden.

             +             +In REGISTRY_INFO structure, +the resource_format_version must be RESOURCE_FORMAT_VERSION_3 . + + +In INTERFACE_INFOstructure, +the interface_uid is renamed to instantiation_interface_uid. + +In REGISTRY_INFO structure, +the resource_format_version must be RESOURCE_FORMAT_VERSION_3. + + +             +#define IMPLEMENTATION_INFO_RECORD_TYPE1 1 +STRUCT IMPLEMENTATION_INFO + { + BYTE info_format; // = IMPLEMENTATION_INFO_RECORD_TYPE1 + LONG implementation_uid; + BYTE version_no; + LTEXT display_name; + LEN BYTE LTEXT8 default_data[]; // maximum 2 strings with 255 bytes each + LEN BYTE LTEXT8 opaque_data[]; // maximum 2 strings with 255 bytes each + LONG extended_interfaces[]; // maximum 8 extended interfaces + BYTE flags; + } + +#define IMPLEMENTATION_INFO_RECORD_TYPE2 2 +STRUCT BINARY_IMPLEMENTATION_INFO + { + BYTE info_format; // = IMPLEMENTATION_INFO_RECORD_TYPE2 + LONG implementation_uid; + BYTE version_no; + LTEXT display_name; + BYTE default_data[]; // maximum 512 bytes + BYTE opaque_data[]; // maximum 512 bytes + LONG extended_interfaces[]; // maximum 8 extended interfaces + BYTE flags; + } + +STRUCT INTERFACE_INFO + { + LONG instantiation_interface_uid; + STRUCT implementations[]; // maximum 8 implementations for each interface + } + +STRUCT REGISTRY_INFO + { + LONG resource_format_version; // Use RESOURCE_FORMAT_VERSION_3 + LONG dll_uid; + STRUCT interfaces[]; // maximum 4 interfaces + } +

              +

            • Maximum of fourINTERFACE_INFO structures can be defined +in one resource file.

              • +

            • Maximum of eight IMPLEMENTATION_INFO or BINARY_IMPLEMENTATION_INFO structures +in each INTERFACE_INFO . Totally eight structures can be +defined.

              • +

            • Maximum eight extended interfaces in each IMPLEMENTATION_INFO record.

              • +

            • In a IMPLEMENTATION_INFO record a maximum of two strings +with 255 bytes each can be used for default_data oropaque_data definitions.

              • +

            • In a BINARY_IMPLEMENTATION_INFO record, a maximum +of 512 bytes each for default_data or opaque_data definitions. +

              • +

             +             +Writing a +Standard Registration Resource File +Writing the +Version 2 Registration Resource File             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-395C240D-6487-5832-B5F6-FC92991001FE_d0e376424_href.png Binary file Symbian3/SDK/Source/GUID-395C240D-6487-5832-B5F6-FC92991001FE_d0e376424_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-395C240D-6487-5832-B5F6-FC92991001FE_d0e382491_href.png Binary file Symbian3/SDK/Source/GUID-395C240D-6487-5832-B5F6-FC92991001FE_d0e382491_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3978E21E-9B7A-4BEA-9B0A-10C247F6451B_d0e65859_href.png Binary file Symbian3/SDK/Source/GUID-3978E21E-9B7A-4BEA-9B0A-10C247F6451B_d0e65859_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-399F7F7D-3E8E-58BB-9925-9F34C561C39A_d0e299332_href.png Binary file Symbian3/SDK/Source/GUID-399F7F7D-3E8E-58BB-9925-9F34C561C39A_d0e299332_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-399F7F7D-3E8E-58BB-9925-9F34C561C39A_d0e305359_href.png Binary file Symbian3/SDK/Source/GUID-399F7F7D-3E8E-58BB-9925-9F34C561C39A_d0e305359_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-39A8FBC9-5FD6-4F92-B71E-5C5438ECFD46.dita --- a/Symbian3/SDK/Source/GUID-39A8FBC9-5FD6-4F92-B71E-5C5438ECFD46.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-39A8FBC9-5FD6-4F92-B71E-5C5438ECFD46.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,129 +1,129 @@ - - - - - -OOM -Monitor OverviewThis section provides an overview of the functionality and the -architecture of the OOM Monitor component. -
            Purpose

            The -OOM Monitor Client API monitors the memory situations and handles out of memory -situations. OOM monitor is responsible to maintain good memory level in the -device. In case of low memory situation, OOM Monitor releases memory by closing -applications based on the priority defined. For information on priority, refer -to OOM Monitor Priority.

            -
            -
            Key concepts
            - -
            LOW_RAM_THRESHOLD
            -

            It is the minimum amount of free RAM that is specified for the device. -This value must be specified in the monitor configuration file.

            -             - -
            GOOD_RAM_THRESHOLD
            -

            It is the required amount of free RAM that is specified for the device. -This value must be specified in the monitor configuration file.

            -             - -
            Normal RAM rotation
            -

            Whenever the amount of free RAM decreases below LOW_RAM_THRESHOLD the -OOM Monitor releases RAM by closing applications based on the priorities. -This process is called as normal RAM rotation.

            -             -

            For information on OOM Monitor Priority and Optional RAM allocation, -refer to OOM Monitor -Concepts

            -
            Architecture

            The -basic function of the OOM Monitor is to monitor the amount of free RAM in -the mobile device. Whenever the amount of free RAM decreases below a defined LOW_RAM_THRESHOLD threshold -value, the OOM Monitor is triggered. The OOM Monitor then releases RAM by -closing applications running on background in order to raise the amount of -free RAM above the defined GOOD_RAM_THRESHOLD value.

            - - - -
            -
            APIs

            The -OOM Monitor Client API consists of ROomMonitorSession class. -The main functions of this class are:

            - - - -

            Function

             -

            Description

             -             - -

            RequestFreeMemory()

             -

            Requests the OOM monitor to allocate RAM.

             -             - -

            SetOomPriority()

             -

            Sets the priority for an application as high, busy or normal. The -application priorities must be defined in TOomPriority variable.

             -             - -

            RequestOptionalRam()

             -

            Requests the OOM monitor to allocate optional RAM.

             -             - - -

            The OOM Monitor Client API also consists of COomMonitorPlugin class. -The main functions of this plug-in class are:

            - - - -

            Function

             -

            Description

             -             - -

            FreeRam()

             -

            Requests to release RAM when the system RAM level becomes low.

             -             - -

            MemoryGood()

             -

            Called when the system RAM level improves to good from low RAM situation. -Once the memory level is good, the OOM plug-in can again start allocating -optional RAM.

             -             - - -
            -
            Typical Uses

            Applications -can use the following functionality provided by the OOM Monitor component -to:

              -

            • Safely allocate large amount of RAM. For more information, refer to Requesting for Large Memory -Allocation.

              • -

            • Change its priority in order to protect itself from being closed by -the OOM Monitor. For more information, refer to Changing -the Priority.

              • -

            • Allocate optional RAM to applications when additional RAM is requested. -For more information, refer to Requesting -for Optional RAM Allocation.

              • -

            • Prevent OOM errors from happening by monitoring the amount of free -RAM in the system. When the amount of free RAM drops below the specified threshold -value, OOM Monitor automatically closes applications that are staying idle -in the background in order to give more RAM to the applications that are active. -For more information, refer to Out -of Memory Error.

              • -

            • Assign priority for each action that can be used to release RAM (i.e. -closing an application or calling an OOM plug-in). When releasing RAM, OOM -Monitor uses the priorities to determine the order of closing applications -and calling plug-ins. As a result RAM is always released by minimizing the -negative impact to the user, provided the priorities are correctly configured -for the device. For more information, refer to Priority -Configuration.

              • -
            -
            Related information
              -

            • OOM Monitor -Concepts

              • -

            • Using OOM Monitor

              • -

            • OOM Monitor -Reference

              • -
            + + + + + +OOM +Monitor OverviewThis section provides an overview of the functionality and the +architecture of the OOM Monitor component. +
            Purpose

            The +OOM Monitor Client API monitors the memory situations and handles out of memory +situations. OOM monitor is responsible to maintain good memory level in the +device. In case of low memory situation, OOM Monitor releases memory by closing +applications based on the priority defined. For information on priority, refer +to OOM Monitor Priority.

            +
            +
            Key concepts
            + +
            LOW_RAM_THRESHOLD
            +

            It is the minimum amount of free RAM that is specified for the device. +This value must be specified in the monitor configuration file.

            +             + +
            GOOD_RAM_THRESHOLD
            +

            It is the required amount of free RAM that is specified for the device. +This value must be specified in the monitor configuration file.

            +             + +
            Normal RAM rotation
            +

            Whenever the amount of free RAM decreases below LOW_RAM_THRESHOLD the +OOM Monitor releases RAM by closing applications based on the priorities. +This process is called as normal RAM rotation.

            +             +

            For information on OOM Monitor Priority and Optional RAM allocation, +refer to OOM Monitor +Concepts

            +
            Architecture

            The +basic function of the OOM Monitor is to monitor the amount of free RAM in +the mobile device. Whenever the amount of free RAM decreases below a defined LOW_RAM_THRESHOLD threshold +value, the OOM Monitor is triggered. The OOM Monitor then releases RAM by +closing applications running on background in order to raise the amount of +free RAM above the defined GOOD_RAM_THRESHOLD value.

            + + + +
            +
            APIs

            The +OOM Monitor Client API consists of ROomMonitorSession class. +The main functions of this class are:

            + + + +

            Function

             +

            Description

             +             + +

            RequestFreeMemory()

             +

            Requests the OOM monitor to allocate RAM.

             +             + +

            SetOomPriority()

             +

            Sets the priority for an application as high, busy or normal. The +application priorities must be defined in TOomPriority variable.

             +             + +

            RequestOptionalRam()

             +

            Requests the OOM monitor to allocate optional RAM.

             +             + + +

            The OOM Monitor Client API also consists of COomMonitorPlugin class. +The main functions of this plug-in class are:

            + + + +

            Function

             +

            Description

             +             + +

            FreeRam()

             +

            Requests to release RAM when the system RAM level becomes low.

             +             + +

            MemoryGood()

             +

            Called when the system RAM level improves to good from low RAM situation. +Once the memory level is good, the OOM plug-in can again start allocating +optional RAM.

             +             + + +
            +
            Typical Uses

            Applications +can use the following functionality provided by the OOM Monitor component +to:

              +

            • Safely allocate large amount of RAM. For more information, refer to Requesting for Large Memory +Allocation.

              • +

            • Change its priority in order to protect itself from being closed by +the OOM Monitor. For more information, refer to Changing +the Priority.

              • +

            • Allocate optional RAM to applications when additional RAM is requested. +For more information, refer to Requesting +for Optional RAM Allocation.

              • +

            • Prevent OOM errors from happening by monitoring the amount of free +RAM in the system. When the amount of free RAM drops below the specified threshold +value, OOM Monitor automatically closes applications that are staying idle +in the background in order to give more RAM to the applications that are active. +For more information, refer to Out +of Memory Error.

              • +

            • Assign priority for each action that can be used to release RAM (i.e. +closing an application or calling an OOM plug-in). When releasing RAM, OOM +Monitor uses the priorities to determine the order of closing applications +and calling plug-ins. As a result RAM is always released by minimizing the +negative impact to the user, provided the priorities are correctly configured +for the device. For more information, refer to Priority +Configuration.

              • +
            +
            Related information
              +

            • OOM Monitor +Concepts

              • +

            • Using OOM Monitor

              • +

            • OOM Monitor +Reference

              • +
             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-39A995DC-F047-4B41-A60D-27063CE329BE.dita --- a/Symbian3/SDK/Source/GUID-39A995DC-F047-4B41-A60D-27063CE329BE.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-39A995DC-F047-4B41-A60D-27063CE329BE.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,77 +1,77 @@ - - - - - -Planning -system and software security -

            Devices based on the Symbian platform are capable of joining both public -and private networks and often have the functionality of a normal desktop -computer. However, the average user does not perceive the device as a computer, -but rather as a regular phone that is safe from security threats. This creates -an opportunity for hostile attackers to infiltrate the device and wreak severe -direct or indirect damage (for example, by penetrating into the corporate -intranet).

            -

            It is, however, possible to anticipate these kinds of threats, and protect -applications by using the security features offered by the Symbian platform, -and by expanding security policies to cover mobile devices and services.

            -

            To develop system or software security, repeat the following steps:

            -
              -

            1. Define and -evaluate all critical assets (resources, information).

              2. -

            2. Identify all -possible threats, vulnerabilities, and potential attacks, and estimate the -extent of possible damage.

              Areas to examine in the Symbian platform -are system resources, removable media, and communication between components.

              -
              3. -

            3. Prioritize -high-risk vulnerabilities, and select and implement corresponding security -features. If risks are sufficiently low, protective measures may be unnecessary.

              -
              4. -

            4. Repeat these -steps until the necessary level of protection is achieved.

              5. -
            -

            -Security development process -

            The security development process is guided by cost, efficiency, and usability. -If security is too tight, this may be expensive and affect both performance -and the user's experience of the system or software. On the other hand, if -security is too slack, this may result in severe damage and, in the long run, -be even more costly.

            -
            Security methods -

            The list below contains the most common and important security methods -used in the mobile world:

            -
              -

            • Ciphering enables confidentiality. Information is -accessible only by authorized parties. With ciphering it is also possible -to maintain integrity.

              • -

            • Hash function (checksum) can be used to verify -integrity and detect information tampering.

              • -

            • Signing allows attaching of information to a certain -source.

              • -

            • Authentication ensures that the object is what it -claims to be.

              • -

            • Access control restricts unauthorized access to resources.

              -
              • -

            • Authorization is permission to perform tasks on behalf -of somebody else.

              • -

            • Certification is provided usually by a third party -to prove information validity.

              • -

            • Recovery mechanisms are usually implemented as redundancy -(duplication of information or routes).

              • -

            • In communication it is possible to use, for example, error -correction to repair transmission failures, random traffic generation to -keep the line occupied, and packet uniforming to blend important packets -into traffic.

              • -
            -

            Some of the methods above are interconnected (for example, certification -requires that the information is signed) and not all of them are of equal -importance, since some basic methods form a base for more complicated methods.

            -
            + + + + + +Planning +system and software security +

            Devices based on the Symbian platform are capable of joining both public +and private networks and often have the functionality of a normal desktop +computer. However, the average user does not perceive the device as a computer, +but rather as a regular phone that is safe from security threats. This creates +an opportunity for hostile attackers to infiltrate the device and wreak severe +direct or indirect damage (for example, by penetrating into the corporate +intranet).

            +

            It is, however, possible to anticipate these kinds of threats, and protect +applications by using the security features offered by the Symbian platform, +and by expanding security policies to cover mobile devices and services.

            +

            To develop system or software security, repeat the following steps:

            +
              +

            1. Define and +evaluate all critical assets (resources, information).

              2. +

            2. Identify all +possible threats, vulnerabilities, and potential attacks, and estimate the +extent of possible damage.

              Areas to examine in the Symbian platform +are system resources, removable media, and communication between components.

              +
              3. +

            3. Prioritize +high-risk vulnerabilities, and select and implement corresponding security +features. If risks are sufficiently low, protective measures may be unnecessary.

              +
              4. +

            4. Repeat these +steps until the necessary level of protection is achieved.

              5. +
            +

            +Security development process +

            The security development process is guided by cost, efficiency, and usability. +If security is too tight, this may be expensive and affect both performance +and the user's experience of the system or software. On the other hand, if +security is too slack, this may result in severe damage and, in the long run, +be even more costly.

            +
            Security methods +

            The list below contains the most common and important security methods +used in the mobile world:

            +
              +

            • Ciphering enables confidentiality. Information is +accessible only by authorized parties. With ciphering it is also possible +to maintain integrity.

              • +

            • Hash function (checksum) can be used to verify +integrity and detect information tampering.

              • +

            • Signing allows attaching of information to a certain +source.

              • +

            • Authentication ensures that the object is what it +claims to be.

              • +

            • Access control restricts unauthorized access to resources.

              +
              • +

            • Authorization is permission to perform tasks on behalf +of somebody else.

              • +

            • Certification is provided usually by a third party +to prove information validity.

              • +

            • Recovery mechanisms are usually implemented as redundancy +(duplication of information or routes).

              • +

            • In communication it is possible to use, for example, error +correction to repair transmission failures, random traffic generation to +keep the line occupied, and packet uniforming to blend important packets +into traffic.

              • +
            +

            Some of the methods above are interconnected (for example, certification +requires that the information is signed) and not all of them are of equal +importance, since some basic methods form a base for more complicated methods.

            +
             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-39AAB0D3-6D4D-5DE3-B894-F5E763D3E19B_d0e244607_href.png Binary file Symbian3/SDK/Source/GUID-39AAB0D3-6D4D-5DE3-B894-F5E763D3E19B_d0e244607_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-39AAB0D3-6D4D-5DE3-B894-F5E763D3E19B_d0e248344_href.png Binary file Symbian3/SDK/Source/GUID-39AAB0D3-6D4D-5DE3-B894-F5E763D3E19B_d0e248344_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-39B5850D-EAAD-56BC-B75A-2104033814E6.dita --- a/Symbian3/SDK/Source/GUID-39B5850D-EAAD-56BC-B75A-2104033814E6.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-39B5850D-EAAD-56BC-B75A-2104033814E6.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,106 +1,106 @@ - - - - - -Audio -Component Framework Overview -

            This document provides an overview of the Audio Component Framework (ACF) -API.

            -
            Purpose

            In the Advanced Audio Adaptation Framework -(A3F) architecture, the client defines the required audio functionality by -grouping several audio processing units together. Audio processing units are -logical entities, not directly related to any specific audio hardware, that -represent basic audio functions. Examples of audio processing units include:

              -

            • Source - a source of -multimedia data.

              • -

            • CODEC - an encoder or -decoder of multimedia data.

              • -

            • Sink - a consumer of -multimedia data.

              • -

            ACF provides a collective notion for the audio processing units being -grouped together so that they can be considered as a single entity. Audio -processing units are grouped into audio streams. An audio stream consists -of at least a source, a codec and a sink. The audio stream allows control -of the audio processing units connected to the stream, for example, starting -or pausing, and also provides information about the state of the audio processing -units connected to it, for example, uninitialized or active.

            Furthermore, -one or more audio streams can be grouped into a logical unit called a context. -The following diagram shows a context which contains two audio streams:

            - Audio streams in a context - -

            Using a context means that, for the purposes of pre-emption, all -audio streams in the context can be controlled as a single unit. For example, -if an audio stream needs to be stopped because it uses a resource that is -required by another higher priority audio stream, then all the other audio -streams in the context can be stopped at the same time.

            -
            Audio Component Framework API Library Details

            The -DLL that provides the functionality and the library to which your code must -link is identified below.

            - - - -DLL -LIB -Short Description - - - - -

            audiocontextfactory.dll

            -

            audiocontextfactory.lib

            -

            These files are used for implementing the ACF API.

            -             - - -
            -
            Architectural Relationship

            This API is part of -the Advanced Audio Adaptation Framework (A3F). A3F provides a new standardised -implementation of DevSound which is configured by default from Symbian OS -v9.5 onwards. A3F interacts with a specially customised DevSound (configured -as optional) through the Audio -Component Library (ACL) API and the ACF API.

            -
            Description

            ACF is responsible for delivering transactional -behaviour. This means ensuring that when a change is applied to one audio -processing unit in a context, the same change is applied to all the audio -processing units in the context and if any fail then no change is made.

            In -order to apply changes to the audio processing units in a context, the client -must call the asynchronous Commit() method. -On success, event callbacks are sent to the client to state that the Commit() was -properly received and processed. If the Commit() fails, then -the implementation is "rolled-back". Alternatively, the client may receive -an event callback stating that audio resources were lost due to pre-emption -by a higher priority audio client.

            -
            Key Audio Component Framework API Classes

            ACF comprises -the following key classes:

              -

            • MAudioSource - -generic interface for different types of audio sources.

              • -

            • MAudioCodec - -the generic abstract interface for codecs.

              • -

            • MAudioSink - -generic interface for different types of audio sinks.

              • -

            • MAudioStream - -the main control interface for the state of an audio stream.

              • -

            • MAudioContext - -the interface to an audio context. The client can use MAudioContext to -manage the audio streams and audio processing units contained in a context.

              • -
            -
            Using Audio Component Framework API

            ACF can be -used to:

              -

            • Apply changes made to -the audio processing units in a context.

              Pending changes are applied -using the asynchronous Commit() call. -When a Commit() has been completed, the client is informed -by the appropriate ContextEvent() callback -of MAudioContextObserver.

              • -
            -
            See Also

            Audio -Component Framework Tutorial

            Audio -Processing Tutorial

            + + + + + +Audio +Component Framework Overview +

            This document provides an overview of the Audio Component Framework (ACF) +API.

            +
            Purpose

            In the Advanced Audio Adaptation Framework +(A3F) architecture, the client defines the required audio functionality by +grouping several audio processing units together. Audio processing units are +logical entities, not directly related to any specific audio hardware, that +represent basic audio functions. Examples of audio processing units include:

              +

            • Source - a source of +multimedia data.

              • +

            • CODEC - an encoder or +decoder of multimedia data.

              • +

            • Sink - a consumer of +multimedia data.

              • +

            ACF provides a collective notion for the audio processing units being +grouped together so that they can be considered as a single entity. Audio +processing units are grouped into audio streams. An audio stream consists +of at least a source, a codec and a sink. The audio stream allows control +of the audio processing units connected to the stream, for example, starting +or pausing, and also provides information about the state of the audio processing +units connected to it, for example, uninitialized or active.

            Furthermore, +one or more audio streams can be grouped into a logical unit called a context. +The following diagram shows a context which contains two audio streams:

            + Audio streams in a context + +

            Using a context means that, for the purposes of pre-emption, all +audio streams in the context can be controlled as a single unit. For example, +if an audio stream needs to be stopped because it uses a resource that is +required by another higher priority audio stream, then all the other audio +streams in the context can be stopped at the same time.

            +
            Audio Component Framework API Library Details

            The +DLL that provides the functionality and the library to which your code must +link is identified below.

            + + + +DLL +LIB +Short Description + + + + +

            audiocontextfactory.dll

            +

            audiocontextfactory.lib

            +

            These files are used for implementing the ACF API.

            +             + + +
            +
            Architectural Relationship

            This API is part of +the Advanced Audio Adaptation Framework (A3F). A3F provides a new standardised +implementation of DevSound which is configured by default from Symbian OS +v9.5 onwards. A3F interacts with a specially customised DevSound (configured +as optional) through the Audio +Component Library (ACL) API and the ACF API.

            +
            Description

            ACF is responsible for delivering transactional +behaviour. This means ensuring that when a change is applied to one audio +processing unit in a context, the same change is applied to all the audio +processing units in the context and if any fail then no change is made.

            In +order to apply changes to the audio processing units in a context, the client +must call the asynchronous Commit() method. +On success, event callbacks are sent to the client to state that the Commit() was +properly received and processed. If the Commit() fails, then +the implementation is "rolled-back". Alternatively, the client may receive +an event callback stating that audio resources were lost due to pre-emption +by a higher priority audio client.

            +
            Key Audio Component Framework API Classes

            ACF comprises +the following key classes:

              +

            • MAudioSource - +generic interface for different types of audio sources.

              • +

            • MAudioCodec - +the generic abstract interface for codecs.

              • +

            • MAudioSink - +generic interface for different types of audio sinks.

              • +

            • MAudioStream - +the main control interface for the state of an audio stream.

              • +

            • MAudioContext - +the interface to an audio context. The client can use MAudioContext to +manage the audio streams and audio processing units contained in a context.

              • +
            +
            Using Audio Component Framework API

            ACF can be +used to:

              +

            • Apply changes made to +the audio processing units in a context.

              Pending changes are applied +using the asynchronous Commit() call. +When a Commit() has been completed, the client is informed +by the appropriate ContextEvent() callback +of MAudioContextObserver.

              • +
            +
            See Also

            Audio +Component Framework Tutorial

            Audio +Processing Tutorial

            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3A506E2A-2999-458B-BBA2-DCC4D2EA5492_d0e41135_href.png Binary file Symbian3/SDK/Source/GUID-3A506E2A-2999-458B-BBA2-DCC4D2EA5492_d0e41135_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3A506E2A-2999-458B-BBA2-DCC4D2EA5492_d0e46692_href.png Binary file Symbian3/SDK/Source/GUID-3A506E2A-2999-458B-BBA2-DCC4D2EA5492_d0e46692_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3A6BEF56-ADBF-543E-B70A-52195DE3E92A.dita --- a/Symbian3/SDK/Source/GUID-3A6BEF56-ADBF-543E-B70A-52195DE3E92A.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-3A6BEF56-ADBF-543E-B70A-52195DE3E92A.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,78 +1,78 @@ - - - - - -Calendar -Overview -

            The Calendar component provides access to calendar stores, with functionality -to fetch, update, save and delete calendar entries.

            -
            Purpose and scope

            Calendar provides access to -calendar stores, with functionality to fetch, update, save and delete calendar -entries. This functionality is as the standard RFC 2445, which defines a common -format for openly exchanging calendar and scheduling information across the -internet. New functionality includes: attachment support, defining geographic -locations, logging, expanded search capabilities and support for removable -media.

            -
            Architectural relationship

            The Calendar component -uses the Alarm server and TZ (time zone converter) components and merges CalInterimApi -and AgnModel.

            Calendar is a single component that contains: Agenda -Server, AgnModel and CalInterimAPI. CalInterimAPI contains classes that hold -information about calendar entries. AgnModel is a DLL which is shared across -the client and the server. Agenda Server provides calendar file management -on behalf of all clients.

            Calendar's implementation of import and -export behaviour is done using the AgnVersit2 plug-in.

            - Calendar dependencies - -
            -
            Description

            This document describes the following -key areas:

            The Calendar Server

            The -Calendar Server manipulates calendar files and connects to the -client when single or multiple sessions (CCalSession) are -instantiated.

            Calendar entries

            A calendar entry, class CCalEntry, -can be an appointment, a to-do item, an event, a reminder, or an anniversary. -It contains repeat definition and synchronisation information as well as group -scheduling data.

            Calendar views

            The -API provides the following views for -accessing the calendar:

            Entry view

            CCalEntryView allows accessing -and manipulating calendar entries. For example, you can add, delete update -and search for a calendar entry,

            Instance view

            CCalInstanceView allows -individual instance(s) that are generated from an entry to be accessed and -deleted.

            Calendar user

            CCalUser represents -a calendar user, -such as a meeting participant. The class provides attributes and methods that -are common to all the calendar users, including the user’s email address, -sent-by and common name fields.

            Setting -the Repeat Rule

            Setting -the repeat rule allows events to occur regularly at specified intervals.

            Setting the alarm

            Within a calendar entry CCalAlarm allows -you to set an alarm of -a specific type.

            Categorising -an entry

            Categorisation of -calendar entries can be done using built-in or user-defined types.

            Importing and Exporting Entries

            This API enables calendar -entries to be exported -and imported to and from a specific data format.

            Callback interfaces

            The -API uses two types of callback -interfaces: change notifications, and progress/completion notifications. -Change notifications monitor changes to calendar entries. Progress/completion -notifications monitor the progress and completion of asynchronous tasks.

            Attachment support

            Calendar -provides the ability to associate an object with a calendar entry. An attachment can be -a URI reference, a file or binary data.

            Removable media support

            Creates, -modifies and deletes calendar files on removable -media.

            GEO property

            The GEO property represents -the geographical location of a calendar entry.

            TRANSP property

            The TRANSP property indicates -whether an entry 'blocks' a calendar busy view.

            iCalendar and vCalendar properties

            Lists the properties in -iCalendar and vCalendar that Calendar supports using the AgnVersit2 plug-in. -Also details the import and export of time properties.

            Expanded search capabilities

            These -offer the ability to search all -text fields, to search entries within a given time frame, and to return results -in an iterator class.

            Adding a user-defined 32-bit -field

            Calendar entries now allows for creation of a user-defined -32-bit field. The value of the field is defined by the vendor. Field -creation, storage and access are carried out by APIs within the CCalEntry class.

            + + + + + +Calendar +Overview +

            The Calendar component provides access to calendar stores, with functionality +to fetch, update, save and delete calendar entries.

            +
            Purpose and scope

            Calendar provides access to +calendar stores, with functionality to fetch, update, save and delete calendar +entries. This functionality is as the standard RFC 2445, which defines a common +format for openly exchanging calendar and scheduling information across the +internet. New functionality includes: attachment support, defining geographic +locations, logging, expanded search capabilities and support for removable +media.

            +
            Architectural relationship

            The Calendar component +uses the Alarm server and TZ (time zone converter) components and merges CalInterimApi +and AgnModel.

            Calendar is a single component that contains: Agenda +Server, AgnModel and CalInterimAPI. CalInterimAPI contains classes that hold +information about calendar entries. AgnModel is a DLL which is shared across +the client and the server. Agenda Server provides calendar file management +on behalf of all clients.

            Calendar's implementation of import and +export behaviour is done using the AgnVersit2 plug-in.

            + Calendar dependencies + +
            +
            Description

            This document describes the following +key areas:

            The Calendar Server

            The +Calendar Server manipulates calendar files and connects to the +client when single or multiple sessions (CCalSession) are +instantiated.

            Calendar entries

            A calendar entry, class CCalEntry, +can be an appointment, a to-do item, an event, a reminder, or an anniversary. +It contains repeat definition and synchronisation information as well as group +scheduling data.

            Calendar views

            The +API provides the following views for +accessing the calendar:

            Entry view

            CCalEntryView allows accessing +and manipulating calendar entries. For example, you can add, delete update +and search for a calendar entry,

            Instance view

            CCalInstanceView allows +individual instance(s) that are generated from an entry to be accessed and +deleted.

            Calendar user

            CCalUser represents +a calendar user, +such as a meeting participant. The class provides attributes and methods that +are common to all the calendar users, including the user’s email address, +sent-by and common name fields.

            Setting +the Repeat Rule

            Setting +the repeat rule allows events to occur regularly at specified intervals.

            Setting the alarm

            Within a calendar entry CCalAlarm allows +you to set an alarm of +a specific type.

            Categorising +an entry

            Categorisation of +calendar entries can be done using built-in or user-defined types.

            Importing and Exporting Entries

            This API enables calendar +entries to be exported +and imported to and from a specific data format.

            Callback interfaces

            The +API uses two types of callback +interfaces: change notifications, and progress/completion notifications. +Change notifications monitor changes to calendar entries. Progress/completion +notifications monitor the progress and completion of asynchronous tasks.

            Attachment support

            Calendar +provides the ability to associate an object with a calendar entry. An attachment can be +a URI reference, a file or binary data.

            Removable media support

            Creates, +modifies and deletes calendar files on removable +media.

            GEO property

            The GEO property represents +the geographical location of a calendar entry.

            TRANSP property

            The TRANSP property indicates +whether an entry 'blocks' a calendar busy view.

            iCalendar and vCalendar properties

            Lists the properties in +iCalendar and vCalendar that Calendar supports using the AgnVersit2 plug-in. +Also details the import and export of time properties.

            Expanded search capabilities

            These +offer the ability to search all +text fields, to search entries within a given time frame, and to return results +in an iterator class.

            Adding a user-defined 32-bit +field

            Calendar entries now allows for creation of a user-defined +32-bit field. The value of the field is defined by the vendor. Field +creation, storage and access are carried out by APIs within the CCalEntry class.

            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3A8755A9-139E-4845-9B52-13AEECF9EBBD-master.png Binary file Symbian3/SDK/Source/GUID-3A8755A9-139E-4845-9B52-13AEECF9EBBD-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3A8755A9-139E-4845-9B52-13AEECF9EBBD_d0e52689_href.png Binary file Symbian3/SDK/Source/GUID-3A8755A9-139E-4845-9B52-13AEECF9EBBD_d0e52689_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3A8755A9-139E-4845-9B52-13AEECF9EBBD_d0e58816_href.png Binary file Symbian3/SDK/Source/GUID-3A8755A9-139E-4845-9B52-13AEECF9EBBD_d0e58816_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3AA34D0C-539D-4D4E-9337-EB5B83AEF4C1-master.png Binary file Symbian3/SDK/Source/GUID-3AA34D0C-539D-4D4E-9337-EB5B83AEF4C1-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3AA34D0C-539D-4D4E-9337-EB5B83AEF4C1_d0e51732_href.png Binary file Symbian3/SDK/Source/GUID-3AA34D0C-539D-4D4E-9337-EB5B83AEF4C1_d0e51732_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3AA34D0C-539D-4D4E-9337-EB5B83AEF4C1_d0e51813_href.png Binary file Symbian3/SDK/Source/GUID-3AA34D0C-539D-4D4E-9337-EB5B83AEF4C1_d0e51813_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3AA34D0C-539D-4D4E-9337-EB5B83AEF4C1_d0e57314_href.png Binary file Symbian3/SDK/Source/GUID-3AA34D0C-539D-4D4E-9337-EB5B83AEF4C1_d0e57314_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3AA34D0C-539D-4D4E-9337-EB5B83AEF4C1_d0e57418_href.png Binary file Symbian3/SDK/Source/GUID-3AA34D0C-539D-4D4E-9337-EB5B83AEF4C1_d0e57418_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3AA34D0C-539D-4D4E-9337-EB5B83AEF4C1_d0e57765_href.png Binary file Symbian3/SDK/Source/GUID-3AA34D0C-539D-4D4E-9337-EB5B83AEF4C1_d0e57765_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3AA34D0C-539D-4D4E-9337-EB5B83AEF4C1_d0e58473_href.png Binary file Symbian3/SDK/Source/GUID-3AA34D0C-539D-4D4E-9337-EB5B83AEF4C1_d0e58473_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3AA34D0C-539D-4D4E-9337-EB5B83AEF4C1_d0e62127_href.png Binary file Symbian3/SDK/Source/GUID-3AA34D0C-539D-4D4E-9337-EB5B83AEF4C1_d0e62127_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3AA34D0C-539D-4D4E-9337-EB5B83AEF4C1_d0e62495_href.png Binary file Symbian3/SDK/Source/GUID-3AA34D0C-539D-4D4E-9337-EB5B83AEF4C1_d0e62495_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3AA34D0C-539D-4D4E-9337-EB5B83AEF4C1_d0e68976_href.png Binary file Symbian3/SDK/Source/GUID-3AA34D0C-539D-4D4E-9337-EB5B83AEF4C1_d0e68976_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3AA34D0C-539D-4D4E-9337-EB5B83AEF4C1_d0e69055_href.png Binary file Symbian3/SDK/Source/GUID-3AA34D0C-539D-4D4E-9337-EB5B83AEF4C1_d0e69055_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3AA34D0C-539D-4D4E-9337-EB5B83AEF4C1_d0e74118_href.png Binary file Symbian3/SDK/Source/GUID-3AA34D0C-539D-4D4E-9337-EB5B83AEF4C1_d0e74118_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3AA34D0C-539D-4D4E-9337-EB5B83AEF4C1_d0e74200_href.png Binary file Symbian3/SDK/Source/GUID-3AA34D0C-539D-4D4E-9337-EB5B83AEF4C1_d0e74200_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3AF1F492-3D7D-5F8C-B1AE-16FBD8224775.dita --- a/Symbian3/SDK/Source/GUID-3AF1F492-3D7D-5F8C-B1AE-16FBD8224775.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-3AF1F492-3D7D-5F8C-B1AE-16FBD8224775.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,163 +1,163 @@ - - - - - -Resource -Files -

            Resource files contain data separated from executable code. The purpose -of using resource files are to define user interface components and store -localisable data.

            -

            The application framework defined by the Uikon Core expects features of -the application UI, such as menus, to be supplied in a resource file. The -framework reads these resources itself. Other user interface components, such -as dialogs, can also be easily created from resources, without the application -needing to use this API itself.

            -

            The API has two key concepts - resource file reader and resource component -reader.

            -
            Resource file reader

            Resource files contain data -in numbered resources. The resource file reader allows such files to be opened -and closed, and individual resources within them, as identified by symbolic -identifiers, to be read into binary descriptors. Data items are then extracted -from these descriptors using the resource component reader.

            The resource -file can be read using RResourceFile.

            -
            Resource component reader

            A resource is defined -as a struct. Struct members can be simple, such as integers and strings, or -complex, such as other structs, or arrays of structs. The resource component -reader is used to read these struct members from a binary descriptor holding -the resource into C++ variables. The application must ensure that it places -the struct members into variables of appropriate types.

            The resource -component header information can be accessed using TResourceReader.

            -
            Basic resource -file use

            The basic concepts involved with using resource files -are as follows:

              -

            • In a resource file, -define structs or use appropriate pre-defined structs and then define resources -that use those structs.

              • -

            • Run the resource compiler -to produce both a generated header file and a resource file. The generated -header file defines the symbols which a program uses to refer to the resources.

              • -

            A program which requires a resource file then performs the following:

              -

            • Includes the generated -header file in the appropriate source file to get symbolic access to the IDs -of the resources contained within the file.

              • -

            • Opens a RResourceFile object, -specifying the generated resource file name.

              • -

            • Reads any resource that -is required. The resource is identified by a symbolic ID which has been #define d -as a number; the content of the resource is read into a binary descriptor, -derived from TDesC8.

              • -

            • Converts the binary -descriptor into whatever target format is appropriate for the data in the -resource file.

              • -

            • Discards the descriptor, -if appropriate, when the binary descriptor has been fully converted into its -target format.

              • -

            • Closes the RResourceFile when -all operations on the resource file are complete.

              • -

            The resource text can be changed and the resources recompiled without -altering or recompiling the C++ program. For example, to alter the language -used by text strings.

            -
            Resource File Interface

            Resource files contain data -in numbered resources. A resource file has the following format:

            - -

            A resource file is generated from text input using the resource compiler. -The index can be used to efficiently find a resource given its numeric ID. -There can be 1 to 4095 resources in a resource file. Each resource contains -binary data whose length is determined by subtracting the start position of -the resource from the start of the next resource (or from the start of the -index, for the last resource in the file).

            Functions for handling -resources in a resource file are encapsulated in the RResourceFile class. -This class provides functions for:

              -

            • opening and closing the file

              • -

            • reading resources

              • -

            • support for using multiple resource files

              • -

            Generally, the process for reading a resource is to read it into -a buffer of sufficient length, analyse it and place its data into C++ classes. -Then, if appropriate, release the buffer.

            The TResourceReader class -must be used to simplify the process of resource data analysis.

            -
            File types -in resource file usage

            The file types involved in resource file -usage are defined in the following diagram:

            - File types - -

            These files work together as follows:

              -

            • the C++ compiler and -linker, together, take .cpp source files and produce .exe output -(or .dll, or .app, or another such -extension).

              • -

            • the resource compiler -takes a .rss source file containing RESOURCE statements -and converts it into a .rsc resource file which contains -the resources the executable program will use. It also produces a .rsg generated -header file, which contains the symbolic IDs of these resources.

              • -

            • the .rsg file -is #include d by the .cpp file, so that -the C++ compiler has access to the symbolic IDs of the resources that will -be used.

              • -

            • C++ class definitions -are specified in a .h file; a typical application will -include several system header files and usually one or more of its own.

              • -

            • resource structs are -specified in a .rh file. A typical application will use -system-provided resource headers, which define standard controls etc. Only -if the application requires its own structs, will it include its own .rh file.

              • -

            • flag values are #define d -in a file which must be available to both the C++ compiler and the resource -compiler: the .hrh extension is used for this and .hrh files -are typically #include d into the .h file -that defines the classes (for C++) and the .rh file that -defines the structs (for the resource compiler).

              • -
            -
            Type safety -issues

            Software systems implemented in C++ are designed to be type-safe. -Proper use of header files, make utilities, type declarations, classes and -templates makes it difficult to pass data of the wrong type to functions, -to assign data of the wrong type to variables, or to construct a program whose -modules are inconsistent with one another. Thus a major source of programming -errors is detected while the program is being built, before running it.

            A -program which uses resources must have a resource file which matches that -program's requirements. However, the resource file and the executable program -are only loosely bound together. A variety of errors are possible while dealing -with resources, which cannot be detected during the build process. Programmers -should be aware of these and take appropriate measures to avoid them.

            Additional -sources of error include:

              -

            • Having a program and -resource file which do not correspond.

              This can arise because the -resource file formats were updated, or the program was updated, but the resource -file was not updated. When the program is run, the resources it loads are -in the wrong format.

              • -

            • The structures in the -resource file may be of a different format from that expected by the C++ program.

              If -the C++ program expects a LONG while a WORD is -present in the resource file, then the C++ program will read two extra bytes -from the data item in the resource file. Any subsequent data read from that -resource will be an error.

              This kind of error can only be avoided -by C++ programs knowing which structs they are dealing with, knowing the data -layouts of those structs in a resource file and writing code which works in -that context.

              • -

            • Having resources of -unexpected type.

              The most likely reason for this to arise is because -there is no type safety in the resource compiler. Thus, it is possible for -a programmer to wrongly guess what kind of struct a particular resource must -use. Appropriate comments in the .rh files and the documentation -of the resource file, will help to reduce this kind of error.

              • -

            The resource compiler does provide some elementary safety features:

              -

            • All resources are represented -by a symbolic ID. This ensures that the resource IDs used by the C++ program -and those expected by the compiler match, if the recommended build procedures -are followed.

              • -

            • Flag values, maximum -length constants and some other values, may be defined in a .hrh file. -This ensures that C++ programs uses correct resource.

              • -
            -             -Reading a -string resource + + + + + +Resource +Files +

            Resource files contain data separated from executable code. The purpose +of using resource files are to define user interface components and store +localisable data.

            +

            The application framework defined by the Uikon Core expects features of +the application UI, such as menus, to be supplied in a resource file. The +framework reads these resources itself. Other user interface components, such +as dialogs, can also be easily created from resources, without the application +needing to use this API itself.

            +

            The API has two key concepts - resource file reader and resource component +reader.

            +
            Resource file reader

            Resource files contain data +in numbered resources. The resource file reader allows such files to be opened +and closed, and individual resources within them, as identified by symbolic +identifiers, to be read into binary descriptors. Data items are then extracted +from these descriptors using the resource component reader.

            The resource +file can be read using RResourceFile.

            +
            Resource component reader

            A resource is defined +as a struct. Struct members can be simple, such as integers and strings, or +complex, such as other structs, or arrays of structs. The resource component +reader is used to read these struct members from a binary descriptor holding +the resource into C++ variables. The application must ensure that it places +the struct members into variables of appropriate types.

            The resource +component header information can be accessed using TResourceReader.

            +
            Basic resource +file use

            The basic concepts involved with using resource files +are as follows:

              +

            • In a resource file, +define structs or use appropriate pre-defined structs and then define resources +that use those structs.

              • +

            • Run the resource compiler +to produce both a generated header file and a resource file. The generated +header file defines the symbols which a program uses to refer to the resources.

              • +

            A program which requires a resource file then performs the following:

              +

            • Includes the generated +header file in the appropriate source file to get symbolic access to the IDs +of the resources contained within the file.

              • +

            • Opens a RResourceFile object, +specifying the generated resource file name.

              • +

            • Reads any resource that +is required. The resource is identified by a symbolic ID which has been #define d +as a number; the content of the resource is read into a binary descriptor, +derived from TDesC8.

              • +

            • Converts the binary +descriptor into whatever target format is appropriate for the data in the +resource file.

              • +

            • Discards the descriptor, +if appropriate, when the binary descriptor has been fully converted into its +target format.

              • +

            • Closes the RResourceFile when +all operations on the resource file are complete.

              • +

            The resource text can be changed and the resources recompiled without +altering or recompiling the C++ program. For example, to alter the language +used by text strings.

            +
            Resource File Interface

            Resource files contain data +in numbered resources. A resource file has the following format:

            + +

            A resource file is generated from text input using the resource compiler. +The index can be used to efficiently find a resource given its numeric ID. +There can be 1 to 4095 resources in a resource file. Each resource contains +binary data whose length is determined by subtracting the start position of +the resource from the start of the next resource (or from the start of the +index, for the last resource in the file).

            Functions for handling +resources in a resource file are encapsulated in the RResourceFile class. +This class provides functions for:

              +

            • opening and closing the file

              • +

            • reading resources

              • +

            • support for using multiple resource files

              • +

            Generally, the process for reading a resource is to read it into +a buffer of sufficient length, analyse it and place its data into C++ classes. +Then, if appropriate, release the buffer.

            The TResourceReader class +must be used to simplify the process of resource data analysis.

            +
            File types +in resource file usage

            The file types involved in resource file +usage are defined in the following diagram:

            + File types + +

            These files work together as follows:

              +

            • the C++ compiler and +linker, together, take .cpp source files and produce .exe output +(or .dll, or .app, or another such +extension).

              • +

            • the resource compiler +takes a .rss source file containing RESOURCE statements +and converts it into a .rsc resource file which contains +the resources the executable program will use. It also produces a .rsg generated +header file, which contains the symbolic IDs of these resources.

              • +

            • the .rsg file +is #include d by the .cpp file, so that +the C++ compiler has access to the symbolic IDs of the resources that will +be used.

              • +

            • C++ class definitions +are specified in a .h file; a typical application will +include several system header files and usually one or more of its own.

              • +

            • resource structs are +specified in a .rh file. A typical application will use +system-provided resource headers, which define standard controls etc. Only +if the application requires its own structs, will it include its own .rh file.

              • +

            • flag values are #define d +in a file which must be available to both the C++ compiler and the resource +compiler: the .hrh extension is used for this and .hrh files +are typically #include d into the .h file +that defines the classes (for C++) and the .rh file that +defines the structs (for the resource compiler).

              • +
            +
            Type safety +issues

            Software systems implemented in C++ are designed to be type-safe. +Proper use of header files, make utilities, type declarations, classes and +templates makes it difficult to pass data of the wrong type to functions, +to assign data of the wrong type to variables, or to construct a program whose +modules are inconsistent with one another. Thus a major source of programming +errors is detected while the program is being built, before running it.

            A +program which uses resources must have a resource file which matches that +program's requirements. However, the resource file and the executable program +are only loosely bound together. A variety of errors are possible while dealing +with resources, which cannot be detected during the build process. Programmers +should be aware of these and take appropriate measures to avoid them.

            Additional +sources of error include:

              +

            • Having a program and +resource file which do not correspond.

              This can arise because the +resource file formats were updated, or the program was updated, but the resource +file was not updated. When the program is run, the resources it loads are +in the wrong format.

              • +

            • The structures in the +resource file may be of a different format from that expected by the C++ program.

              If +the C++ program expects a LONG while a WORD is +present in the resource file, then the C++ program will read two extra bytes +from the data item in the resource file. Any subsequent data read from that +resource will be an error.

              This kind of error can only be avoided +by C++ programs knowing which structs they are dealing with, knowing the data +layouts of those structs in a resource file and writing code which works in +that context.

              • +

            • Having resources of +unexpected type.

              The most likely reason for this to arise is because +there is no type safety in the resource compiler. Thus, it is possible for +a programmer to wrongly guess what kind of struct a particular resource must +use. Appropriate comments in the .rh files and the documentation +of the resource file, will help to reduce this kind of error.

              • +

            The resource compiler does provide some elementary safety features:

              +

            • All resources are represented +by a symbolic ID. This ensures that the resource IDs used by the C++ program +and those expected by the compiler match, if the recommended build procedures +are followed.

              • +

            • Flag values, maximum +length constants and some other values, may be defined in a .hrh file. +This ensures that C++ programs uses correct resource.

              • +
            +             +Reading a +string resource             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3B0602F1-4294-43C4-9E7A-B1A33291C22F.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-3B0602F1-4294-43C4-9E7A-B1A33291C22F.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,42 @@ + + + + + +Establishing +a connection with destination networksDestination networks, also known as Service Network Access Points +(SNAPs) avoid the connectivity problems that are related to the access point +being fixed for the duration of the data connection. With the availability +of WLAN and other data bearers, the number of access points has grown considerably. + With WLAN, the availability of an access point can change frequently. A +fixed access point in selection often leads to a poor access point choice. +Because the network environment is now more dynamic, you can have either a +safe but slow connection, or a fast but unreliable connection. In practice +this means that the application is either stuck with using GPRS or the user +must continuously change the settings to point to the WLAN access point that +happens to be available. A fixed access point leads to non-optimal usage +of available connections, especially with applications that use long-lasting +data connections. +

            Applications +should monitor the connection state by using platform services (such as Connection +Monitor Server API) and avoid polling and keep-alives. If the application +protocol mandates the use of timers, they should be tuned so that the control +data over the air is minimized.

            + +Defining +Connection Management Items + +Prompting +the user to select a destination network + +Starting +the Connection through the Destination Network + + +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3B2957D0-4D1A-5289-BE2A-AC8CD34A54E6_d0e266338_href.png Binary file Symbian3/SDK/Source/GUID-3B2957D0-4D1A-5289-BE2A-AC8CD34A54E6_d0e266338_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3B2957D0-4D1A-5289-BE2A-AC8CD34A54E6_d0e270046_href.png Binary file Symbian3/SDK/Source/GUID-3B2957D0-4D1A-5289-BE2A-AC8CD34A54E6_d0e270046_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3BA7EB01-D967-44B2-B817-91722C59F2DE-master.png Binary file Symbian3/SDK/Source/GUID-3BA7EB01-D967-44B2-B817-91722C59F2DE-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3BA7EB01-D967-44B2-B817-91722C59F2DE_d0e65995_href.png Binary file Symbian3/SDK/Source/GUID-3BA7EB01-D967-44B2-B817-91722C59F2DE_d0e65995_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3BA7EB01-D967-44B2-B817-91722C59F2DE_d0e71245_href.png Binary file Symbian3/SDK/Source/GUID-3BA7EB01-D967-44B2-B817-91722C59F2DE_d0e71245_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3BB539EF-E1DE-4EB4-A9F0-BB31430DD64A-master.png Binary file Symbian3/SDK/Source/GUID-3BB539EF-E1DE-4EB4-A9F0-BB31430DD64A-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3BB539EF-E1DE-4EB4-A9F0-BB31430DD64A_d0e63738_href.png Binary file Symbian3/SDK/Source/GUID-3BB539EF-E1DE-4EB4-A9F0-BB31430DD64A_d0e63738_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3C16A9DC-E4E6-4892-B0E5-E3AF2F950F03-master.png Binary file Symbian3/SDK/Source/GUID-3C16A9DC-E4E6-4892-B0E5-E3AF2F950F03-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3C16A9DC-E4E6-4892-B0E5-E3AF2F950F03_d0e58883_href.png Binary file Symbian3/SDK/Source/GUID-3C16A9DC-E4E6-4892-B0E5-E3AF2F950F03_d0e58883_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3C16A9DC-E4E6-4892-B0E5-E3AF2F950F03_d0e59473_href.png Binary file Symbian3/SDK/Source/GUID-3C16A9DC-E4E6-4892-B0E5-E3AF2F950F03_d0e59473_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3C3BBE1F-D7A2-5021-830B-78084334C883.dita --- a/Symbian3/SDK/Source/GUID-3C3BBE1F-D7A2-5021-830B-78084334C883.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,30 +0,0 @@ - - - - - -Controlling Captured Image

            This document explains you how to control captured images.

            Purpose

            This document provides a detailed explanation on the use of Post ImageCapture Control API.

            Introduction

            This classes provide necessary framework to retrieve the image data from individual images and also to apply control on the captured images individually.

            Using Post ImageCapture Control

            The following tasks are covered on Post ImageCapture Control implementation:

            1. Provide concrete implementation of McameraImageCapture class to create CcameraPostImageCaptureControl facade class.

            2. Create object of class CCameraPostImageCaptureControl to control each captured still image.

            3. Pass a pointer to McameraPostImageCaptureControl object to the CcameraPostImageCaptureControl object.

            4. Call McameraImageCapture:: - CreatePostImageCaptureControlImpl method with UID value KECamMCameraPostImageCaptureControlUid to get the interface pointer.

              This creates a newly created interface to represent the individual image.

            5. Use KECamMCameraPostImageCaptureControlUid ID to map the individual image with the CCameraPostImageCaptureControl instance.

            6. Use CCameraPostImageCaptureControl class to control each captured still image.

            Use CCameraImageProcessing::TRelativeFlipping to describe the various relative flipping of an image. The image can be flipped horizontally or vertically.

            Note:

            • CCameraPostImageCaptureControl objects will become unavailable if a new image capture request is issued, while the previous request is still not completed.

            • Make sure you destroy CCameraPostImageCaptureControl object when individual image cancellation is completed and/or individual image is saved.

            The following example code snippets illustrates the use of Post ImageCapture Control classes.

            class MCameraImageCapture -{ -... -... -TAny* CCamImageCapture::CreatePostImageCaptureControlImpl(TUid aInterface, TPostCaptureControlId aPostCaptureControlId) -... -} - -CCamera::CCameraPostImageCaptureControl* postImageCaptureControl; - -CCamPostImageCaptureControl* camPostImageCaptureControl; -static_cast<MCameraPostImageCaptureControl*>(camPostImageCaptureControl); - -if(aInterface.iUid == KECamMCameraPostImageCaptureControlUidValue) - camPostImageCaptureControl = CCamPostImageCaptureControl::NewL(const_cast<CCamImageCapture&>(*this)); - -//Use of CCameraPostImageCaptureControl for Image Capture - CCamera::CCameraPostImageCaptureControl* postImgCapt = NULL;

            Post ImageCapture Control implementation lets you do the following tasks:

            • retrieve the image data for individual images

            • retrieve the post image capture identity for this class object

            • retrieve the sequence number of the individual image

            • pause or resume the background processing associated with this individual image

            • retrieve information about the current state of the individual image and/or the current state of the image buffer.

            • retrieve the image buffer after notifying the availability of the individual image through associated call-backs.

            See also

            Controlling Pre-Image Capture

            Controlling Still-image Capture

            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3C61E57D-BBBB-4E52-8C99-F359CB83D1BC-master.png Binary file Symbian3/SDK/Source/GUID-3C61E57D-BBBB-4E52-8C99-F359CB83D1BC-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3C61E57D-BBBB-4E52-8C99-F359CB83D1BC_d0e58928_href.png Binary file Symbian3/SDK/Source/GUID-3C61E57D-BBBB-4E52-8C99-F359CB83D1BC_d0e58928_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3C61E57D-BBBB-4E52-8C99-F359CB83D1BC_d0e59856_href.png Binary file Symbian3/SDK/Source/GUID-3C61E57D-BBBB-4E52-8C99-F359CB83D1BC_d0e59856_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3C8FD050-1CD4-5AFB-ACB7-4264536BB300_d0e322219_href.png Binary file Symbian3/SDK/Source/GUID-3C8FD050-1CD4-5AFB-ACB7-4264536BB300_d0e322219_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3C8FD050-1CD4-5AFB-ACB7-4264536BB300_d0e328376_href.png Binary file Symbian3/SDK/Source/GUID-3C8FD050-1CD4-5AFB-ACB7-4264536BB300_d0e328376_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3CA039D8-A74D-4C9E-B4F5-6E153C7F65A1.dita --- a/Symbian3/SDK/Source/GUID-3CA039D8-A74D-4C9E-B4F5-6E153C7F65A1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,33 +0,0 @@ - - - - - -Finger -vs. stylus -

            Consider the use cases of the application when deciding whether -to use finger or stylus control, or possibly hardware keys. Eliminate the -need to switch from using a finger or stylus on the touch screen, to using -any of the hardware keys. Design should enable completing a task with the -same interaction method as it was started with.

            If your application -is intended to be used with the stylus, rather than a finger, try to present -this clearly to the users from the top level. It can be frustrating to start -using an application with finger touch, then switching to stylus, for example, -if the components on screen suddenly get smaller.

            Decide whether -the application is to be used with a single hand, or two hands. Make sure -users are able to use at least the most important functions with only one -hand, even though the application is designed to be used mainly with two hands. - With touch screen devices, this means that the users should be able to perform -most basic actions with their thumb.

            Applications that require the -use of both hands include:

              -

            • Applications that require the use of stylus

              • -

            • Applications that are intended for landscape mode

              • -

            • Applications that require data input

              • -
            -             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3CA473CB-E79C-5B32-8B5B-F222B3DDEF3B.dita --- a/Symbian3/SDK/Source/GUID-3CA473CB-E79C-5B32-8B5B-F222B3DDEF3B.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-3CA473CB-E79C-5B32-8B5B-F222B3DDEF3B.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,14 +1,14 @@ - - - - - -Speech Recognition Controller Overview

            This document provides an overview of the Speech Recognition Controller (SRC) component.

            Purpose

            The Speech Recognition Controller component provides speech recognition services for clients requiring speech recognition functionality. The SRC component comprises a client utility, a data handler and a custom commands library.

            Required background

            Automatic Speech Recognition (ASR) is a technology that enables users to use speech to interact with devices. ASR works by converting speech into a machine-readable form. Voice activated dialling is an example of an ASR application.

            Architectural relationships

            The ASR Client Utility is dependent on the Multimedia Framework. The MMF acts as the interface between the ASR Client Utility and the low level DevASR. A Speech Recognition Services (SRS) controller plugin is responsible for transporting speech recognition requests from the MMF to the DevASR. For playback, the DevASR implementation uses DevSound to play the recorded speech.

            The relationship between the SRC component and other multimedia components is shown below.

            - SRC component architectural relationship -
            API summary

            The SRC component includes the following APIs:

            API Description

            Automatic Speech Recognition Client Utility

            Client side interface for ASR.

            For more information, see Automatic Speech Recognition Client Utility Overview.

            Automatic Speech Recognition Custom Commands

            Custom commands for ASR.

            For more information, see Automatic Speech Recognition Custom Commands Overview.

            Automatic Speech Recognition Data Handling

            Recognition data handling for ASR.

            For more information, see Automatic Speech Recognition Data Handling Overview.

            Typical uses

            The SRC component is used for the following:

            • Recognising spoken input.

            • Training a new model.

            • Manipulating grammars, lexicons and models.

            See also

            DevSound Overview

            \ No newline at end of file + + + + + +Speech Recognition Controller Overview

            This document provides an overview of the Speech Recognition Controller (SRC) component.

            Purpose

            The Speech Recognition Controller component provides speech recognition services for clients requiring speech recognition functionality. The SRC component comprises a client utility, a data handler and a custom commands library.

            Required background

            Automatic Speech Recognition (ASR) is a technology that enables users to use speech to interact with devices. ASR works by converting speech into a machine-readable form. Voice activated dialling is an example of an ASR application.

            Architectural relationships

            The ASR Client Utility is dependent on the Multimedia Framework. The MMF acts as the interface between the ASR Client Utility and the low level DevASR. A Speech Recognition Services (SRS) controller plugin is responsible for transporting speech recognition requests from the MMF to the DevASR. For playback, the DevASR implementation uses DevSound to play the recorded speech.

            The relationship between the SRC component and other multimedia components is shown below.

            + SRC component architectural relationship +
            API summary

            The SRC component includes the following APIs:

            API Description

            Automatic Speech Recognition Client Utility

            Client side interface for ASR.

            For more information, see Automatic Speech Recognition Client Utility Overview.

            Automatic Speech Recognition Custom Commands

            Custom commands for ASR.

            For more information, see Automatic Speech Recognition Custom Commands Overview.

            Automatic Speech Recognition Data Handling

            Recognition data handling for ASR.

            For more information, see Automatic Speech Recognition Data Handling Overview.

            Typical uses

            The SRC component is used for the following:

            • Recognising spoken input.

            • Training a new model.

            • Manipulating grammars, lexicons and models.

            See also

            DevSound Overview

            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3D110AD3-C5C7-533C-8E57-C4E3D032A229_d0e196324_href.png Binary file Symbian3/SDK/Source/GUID-3D110AD3-C5C7-533C-8E57-C4E3D032A229_d0e196324_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3D110AD3-C5C7-533C-8E57-C4E3D032A229_d0e201332_href.png Binary file Symbian3/SDK/Source/GUID-3D110AD3-C5C7-533C-8E57-C4E3D032A229_d0e201332_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3D8FE2A7-E544-51B9-9572-492A3B61377C_d0e76331_href.png Binary file Symbian3/SDK/Source/GUID-3D8FE2A7-E544-51B9-9572-492A3B61377C_d0e76331_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3D8FE2A7-E544-51B9-9572-492A3B61377C_d0e83043_href.png Binary file Symbian3/SDK/Source/GUID-3D8FE2A7-E544-51B9-9572-492A3B61377C_d0e83043_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3D9C4B45-EEA0-581C-A9E5-8B2535014930.dita --- a/Symbian3/SDK/Source/GUID-3D9C4B45-EEA0-581C-A9E5-8B2535014930.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-3D9C4B45-EEA0-581C-A9E5-8B2535014930.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,14 +1,14 @@ - - - - - -Image Conversion Library Overview

            This document introduces you to the Image Conversion functionality.

            Purpose

            Image Conversion functionality supports many features like encoding, decoding, scaling, rotating, producing mirror image, flipping and cropping images.

            Image Conversion Library Details

            To use Image Conversion, you must obtain necessary binaries in the form of DLL file to implement the image encoding and the image decoding functions.

            DLL LIB Short Description

            imageconversion.dll

            imageconversion.lib

            These files are used for implementing image conversion operation.

            Architectural Relationship

            Image Conversion is primarily used for Image Encoding and Image Decoding. The following diagram shows how the Image Encoding and the Image Decoding interacts with other components.

            - Image Conversion system diagram -
            Description

            The Image conversion provides several features to enable the conversion and basic manipulation of images. Conversions can be made from images stored in files or descriptors to CFbsBitmap objects, or from CFbsBitmap and CFrameImageData objects to files or descriptors. Features of the image conversion function include:

            • Standard decoders that can decode single or multiframe images, images with bitmasks, images with in-image or in-frame comments.

            • Support for progressive decoding.

            • Functions to decode images stored in files or descriptors.

            • Standard encoder that can encode single frame images and images with in image comments.

            • Functions to manipulate image properties such as scale, rotation, dithering and progressive decoding.

            • Advanced thread control for encoder and decoders.

            Key Image Conversion Classes

            The key classes are

            Image Encoding

            Image encoding is the process of taking a bitmap stored in a CFbsBitmap, converting it to a specified format and writing the output to a file or descriptor. Typical sources of bitmap data are cameras and paint applications. The CImageEncoder object is created specifying the source image and encoder plugin as parameters. The CImageEncoder::Convert() function then encodes the image using the methods provided by the plugin. The results of the conversion are then saved to a file or descriptor.

            Image Decoding

            Image decoding is the process of taking an image stored in a file or descriptor, converting it from a specified format and writing the output to a CFbsBitmap. The CImageDecoder object is created specifying the source image and decoder plugin as parameters. The CImageDecoder::Convert() function then decodes the image using the methods provided by the plugin. The results of the conversion are then saved to a CFbsBitmap.

            Image Processor

            Image Processor is an interface to process the decoded image using the CImageProcessor class.

            Using Image Conversion

            The Image Conversion functionality is used for the following:

            • Rotate, crop, mirror and flip an image frame during decode operation.

            • Scaling with reduction factor of an image during decode operation.

            • Decode an image by requesting pixel data block by block.

            • Decode an image from a descriptor or a file.

            • Decode an image using a mask for the image with transparency.

            • Decode an image using separate thread.

            • Decode a JPEG image thumbnail.

            • Decode a GIF multi-frame image.

            • Decode an image that supports YUV format into an image frame.

            • Turning OFF and ON dithering during decode operation of the image.

            • Encode a bitmap or an image frame into a descriptor or a file.

            • Encode an image frame by passing pixel data block by block.

            • Rotate, mirror and flip an image during encode functionality.

            • Rotate a bitmap image.

            • Scaling a bitmap image with or without a mask.

            Imaging Frameworks Overview Image Conversion Overview Image Encoding Tutorial Image Decoding Tutorial Guide to Symbian supplied Codecs             \ No newline at end of file + + + + + +Image Conversion Library Overview

            This document introduces you to the Image Conversion functionality.

            Purpose

            Image Conversion functionality supports many features like encoding, decoding, scaling, rotating, producing mirror image, flipping and cropping images.

            Image Conversion Library Details

            To use Image Conversion, you must obtain necessary binaries in the form of DLL file to implement the image encoding and the image decoding functions.

            DLL LIB Short Description

            imageconversion.dll

            imageconversion.lib

            These files are used for implementing image conversion operation.

            Architectural Relationship

            Image Conversion is primarily used for Image Encoding and Image Decoding. The following diagram shows how the Image Encoding and the Image Decoding interacts with other components.

            + Image Conversion system diagram +
            Description

            The Image conversion provides several features to enable the conversion and basic manipulation of images. Conversions can be made from images stored in files or descriptors to CFbsBitmap objects, or from CFbsBitmap and CFrameImageData objects to files or descriptors. Features of the image conversion function include:

            • Standard decoders that can decode single or multiframe images, images with bitmasks, images with in-image or in-frame comments.

            • Support for progressive decoding.

            • Functions to decode images stored in files or descriptors.

            • Standard encoder that can encode single frame images and images with in image comments.

            • Functions to manipulate image properties such as scale, rotation, dithering and progressive decoding.

            • Advanced thread control for encoder and decoders.

            Key Image Conversion Classes

            The key classes are

            Image Encoding

            Image encoding is the process of taking a bitmap stored in a CFbsBitmap, converting it to a specified format and writing the output to a file or descriptor. Typical sources of bitmap data are cameras and paint applications. The CImageEncoder object is created specifying the source image and encoder plugin as parameters. The CImageEncoder::Convert() function then encodes the image using the methods provided by the plugin. The results of the conversion are then saved to a file or descriptor.

            Image Decoding

            Image decoding is the process of taking an image stored in a file or descriptor, converting it from a specified format and writing the output to a CFbsBitmap. The CImageDecoder object is created specifying the source image and decoder plugin as parameters. The CImageDecoder::Convert() function then decodes the image using the methods provided by the plugin. The results of the conversion are then saved to a CFbsBitmap.

            Image Processor

            Image Processor is an interface to process the decoded image using the CImageProcessor class.

            Using Image Conversion

            The Image Conversion functionality is used for the following:

            • Rotate, crop, mirror and flip an image frame during decode operation.

            • Scaling with reduction factor of an image during decode operation.

            • Decode an image by requesting pixel data block by block.

            • Decode an image from a descriptor or a file.

            • Decode an image using a mask for the image with transparency.

            • Decode an image using separate thread.

            • Decode a JPEG image thumbnail.

            • Decode a GIF multi-frame image.

            • Decode an image that supports YUV format into an image frame.

            • Turning OFF and ON dithering during decode operation of the image.

            • Encode a bitmap or an image frame into a descriptor or a file.

            • Encode an image frame by passing pixel data block by block.

            • Rotate, mirror and flip an image during encode functionality.

            • Rotate a bitmap image.

            • Scaling a bitmap image with or without a mask.

            Imaging Frameworks Overview Image Conversion Overview Image Encoding Tutorial Image Decoding Tutorial Guide to Symbian supplied Codecs             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3DD37A41-E822-5CB6-A59E-0B309B5627D9_d0e184580_href.png Binary file Symbian3/SDK/Source/GUID-3DD37A41-E822-5CB6-A59E-0B309B5627D9_d0e184580_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3DD37A41-E822-5CB6-A59E-0B309B5627D9_d0e191176_href.png Binary file Symbian3/SDK/Source/GUID-3DD37A41-E822-5CB6-A59E-0B309B5627D9_d0e191176_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3DE276E8-D2C7-5297-AF3B-40B0B8733572.dita --- a/Symbian3/SDK/Source/GUID-3DE276E8-D2C7-5297-AF3B-40B0B8733572.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-3DE276E8-D2C7-5297-AF3B-40B0B8733572.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,41 +1,41 @@ - - - - - -Inter-thread -Data TransferThe mechanism for copying data between threads is called inter-thread -data transfer and is handled by the four functions provided by the RThread handle. -

            Data can be passed between threads. The threads can be in the same process -or in different processes. The functions provides by the RThread class -are:

            -
              -

            • ReadL()

              • -

            • WriteL()

              • -

            • GetDesLength()

              • -

            • GetDesMaxLength()

              • -
            -

            The functions are used in the implementation of the RMessage class -which, in turn, is used for passing information between clients and servers.

            -

            The ReadL() and WriteL() functions, which -transfer data, assume that both source and target data are descriptors.

            -

            Typically, code executing in the current thread will have a handle to another -thread. The code in the current thread copies data from the other thread, -represented by an RThread handle, by calling its ReadL() function. -Copying data to the other thread is similar, but is done using -the WriteL() function. The following diagram illustrates -this:

            - - - -

            The source or target location in the other thread is identified -by pointer. The pointer only has meaning within the context of that thread; -attempting to reference the pointer directly from within the current thread -is meaningless and may cause an exception.

            + + + + + +Inter-thread +Data TransferThe mechanism for copying data between threads is called inter-thread +data transfer and is handled by the four functions provided by the RThread handle. +

            Data can be passed between threads. The threads can be in the same process +or in different processes. The functions provides by the RThread class +are:

            +
              +

            • ReadL()

              • +

            • WriteL()

              • +

            • GetDesLength()

              • +

            • GetDesMaxLength()

              • +
            +

            The functions are used in the implementation of the RMessage class +which, in turn, is used for passing information between clients and servers.

            +

            The ReadL() and WriteL() functions, which +transfer data, assume that both source and target data are descriptors.

            +

            Typically, code executing in the current thread will have a handle to another +thread. The code in the current thread copies data from the other thread, +represented by an RThread handle, by calling its ReadL() function. +Copying data to the other thread is similar, but is done using +the WriteL() function. The following diagram illustrates +this:

            + + + +

            The source or target location in the other thread is identified +by pointer. The pointer only has meaning within the context of that thread; +attempting to reference the pointer directly from within the current thread +is meaningless and may cause an exception.

             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3E0E2E54-CD8A-5BAF-A87B-BF51FD8890D6_d0e431356_href.png Binary file Symbian3/SDK/Source/GUID-3E0E2E54-CD8A-5BAF-A87B-BF51FD8890D6_d0e431356_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3E0E2E54-CD8A-5BAF-A87B-BF51FD8890D6_d0e431518_href.png Binary file Symbian3/SDK/Source/GUID-3E0E2E54-CD8A-5BAF-A87B-BF51FD8890D6_d0e431518_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3E1199E4-4F19-58BB-B1EC-8975A04B68FF_d0e213809_href.png Binary file Symbian3/SDK/Source/GUID-3E1199E4-4F19-58BB-B1EC-8975A04B68FF_d0e213809_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3E1199E4-4F19-58BB-B1EC-8975A04B68FF_d0e217546_href.png Binary file Symbian3/SDK/Source/GUID-3E1199E4-4F19-58BB-B1EC-8975A04B68FF_d0e217546_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3E23788D-4D67-5E9B-961F-B67D7471BB71_d0e133201_href.png Binary file Symbian3/SDK/Source/GUID-3E23788D-4D67-5E9B-961F-B67D7471BB71_d0e133201_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3E23788D-4D67-5E9B-961F-B67D7471BB71_d0e139735_href.png Binary file Symbian3/SDK/Source/GUID-3E23788D-4D67-5E9B-961F-B67D7471BB71_d0e139735_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3E80A006-F8D8-45C5-9773-7CC239AE86D9_d0e194049_href.png Binary file Symbian3/SDK/Source/GUID-3E80A006-F8D8-45C5-9773-7CC239AE86D9_d0e194049_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3E80A006-F8D8-45C5-9773-7CC239AE86D9_d0e199057_href.png Binary file Symbian3/SDK/Source/GUID-3E80A006-F8D8-45C5-9773-7CC239AE86D9_d0e199057_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3EF88A1D-CCB6-5DE5-9CA6-F6E785A6898A.dita --- a/Symbian3/SDK/Source/GUID-3EF88A1D-CCB6-5DE5-9CA6-F6E785A6898A.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-3EF88A1D-CCB6-5DE5-9CA6-F6E785A6898A.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,102 +1,102 @@ - - - - - -Communications -Framework Quick StartThis topic describes the activities that users can do to make use -of the Communications Framework. -
            Getting started -with Communications Framework
              -

            • To manage communications -connections and transfer data, use the client interfaces provided by the Sockets -Server, together with additional interfaces that are provided by implementations -of specific communications protocols. For example, to communicate over the -TCP protocol, use the Sockets Server together with the Internet Sockets libraries -provided by Networking Services.

              • -

            • To implement new communications -protocols, implement plug-ins that conform to the Comms Architecture.

              • -

            • To configure the communications -set up of a phone, use the Comms Database.

              • -

            • To communicate over -a serial port, such as RS232, and to access other communications protocols -that can be used in a similar way, use the Serial Communications Server.

              • -
            -
            Architecture

            The Communications Framework enables -communication in mobile devices. It allows the devices to connect to networks, -create and store network settings, manage memory used for communications, -and send and receive data.

            The Communications Framework comprises -the following collections:

              -

            • Communications Process -and Settings

              This collection contains the Comms Root Server and -Comms Root Server Configurator components. For more information see Root Server.

              • -

            • Communications Configuration

              This -collection contains the Comms Database. The Comms Database contains data about -all of the settings in the communication framework. For more information about -the Comms Database, see Comms -Database.

              • -

            • Data Communications -Server

              This collection contains the ESock Server and ESock Server -Configurator components. For more information, see Data -Communications Server.

              • -

            • Communications Framework -Utilities

              This collection contains the Comms framework, Comms -Elements and MBuf Manager. For more information, see Communications -Framework Utilities.

              • -

            • Serial Server and -Serial Comms Server Plug-ins

              These collections contain the C32 -Serial Server and the C32 Serial Server and the Serial Port CSY. For more -information, see Serial -Communications Server.

              • -

            The following diagram outlines the Communication Framework collections -and the components associated with each collection.

            - -
            -
            Technologies

            The Comms Framework defines the structure -and operations of the communications protocol stack in Symbian platform, -and allows applications to use the stack through a sockets type API. It defines -the concepts, roles, and rules that govern the function of the stack, but -does not itself implement specific protocols, such as TCP/IP, in that stack.

            This -section describes the key features and technologies implemented by the Communications -Framework.

              -

            • Comms Database

              The -Comms database comprises a series of tables which are used to store communications -settings. Each table is made up of a set of records. These records are in -turn made up of a series of fields. A field is the basic unit of information -in the Comms Database. For more information, see Comms -Database.

              • -

            • Root Server

              Root -Server manages the process in which all Communications Servers are loaded. -The process is called C32exe and is also known as C32. For more -information, see What -is Root Server and the C32exe Process?.

              • -

            • ESock Server

              ESock -Server provides a generic interface to communications protocols through communication -end points known as sockets. They provide a generic interface to network level -communications protocols for common operations involved in network computing. -These include sending data, receiving data, establishing connections, and -configuring network protocols.

              • -

            • Network Interface -Manager

              The Network Interface Manager (NifMan) creates and manages -network interfaces. The Network interfaces enable the devices to connect to -networks. For more information about NifMan, see Network -Interface Manager (NifMan).

              • -

            • MBufManager

              An -MBuf is part of the implementation of a buffer in the Comms Architecture and -represents a section of memory. The Communications framework creates a MBufs -when the device starts. The MBufManager provides memory management for the -Comms processes. For more information about buffers and MBufs, see Memory -Management.

              • -

            • C32 Serial Server

              The -Serial Communications Server provides a public API to access the serial ports -of the device. It provides functionality such as timeouts and port sharing -for all Serial Protocol Modules. For more information, see the Serial -Communications Server.

              • -
            + + + + + +Communications +Framework Quick StartThis topic describes the activities that users can do to make use +of the Communications Framework. +
            Getting started +with Communications Framework
              +

            • To manage communications +connections and transfer data, use the client interfaces provided by the Sockets +Server, together with additional interfaces that are provided by implementations +of specific communications protocols. For example, to communicate over the +TCP protocol, use the Sockets Server together with the Internet Sockets libraries +provided by Networking Services.

              • +

            • To implement new communications +protocols, implement plug-ins that conform to the Comms Architecture.

              • +

            • To configure the communications +set up of a phone, use the Comms Database.

              • +

            • To communicate over +a serial port, such as RS232, and to access other communications protocols +that can be used in a similar way, use the Serial Communications Server.

              • +
            +
            Architecture

            The Communications Framework enables +communication in mobile devices. It allows the devices to connect to networks, +create and store network settings, manage memory used for communications, +and send and receive data.

            The Communications Framework comprises +the following collections:

              +

            • Communications Process +and Settings

              This collection contains the Comms Root Server and +Comms Root Server Configurator components. For more information see Root Server.

              • +

            • Communications Configuration

              This +collection contains the Comms Database. The Comms Database contains data about +all of the settings in the communication framework. For more information about +the Comms Database, see Comms +Database.

              • +

            • Data Communications +Server

              This collection contains the ESock Server and ESock Server +Configurator components. For more information, see Data +Communications Server.

              • +

            • Communications Framework +Utilities

              This collection contains the Comms framework, Comms +Elements and MBuf Manager. For more information, see Communications +Framework Utilities.

              • +

            • Serial Server and +Serial Comms Server Plug-ins

              These collections contain the C32 +Serial Server and the C32 Serial Server and the Serial Port CSY. For more +information, see Serial +Communications Server.

              • +

            The following diagram outlines the Communication Framework collections +and the components associated with each collection.

            + +
            +
            Technologies

            The Comms Framework defines the structure +and operations of the communications protocol stack in Symbian platform, +and allows applications to use the stack through a sockets type API. It defines +the concepts, roles, and rules that govern the function of the stack, but +does not itself implement specific protocols, such as TCP/IP, in that stack.

            This +section describes the key features and technologies implemented by the Communications +Framework.

              +

            • Comms Database

              The +Comms database comprises a series of tables which are used to store communications +settings. Each table is made up of a set of records. These records are in +turn made up of a series of fields. A field is the basic unit of information +in the Comms Database. For more information, see Comms +Database.

              • +

            • Root Server

              Root +Server manages the process in which all Communications Servers are loaded. +The process is called C32exe and is also known as C32. For more +information, see What +is Root Server and the C32exe Process?.

              • +

            • ESock Server

              ESock +Server provides a generic interface to communications protocols through communication +end points known as sockets. They provide a generic interface to network level +communications protocols for common operations involved in network computing. +These include sending data, receiving data, establishing connections, and +configuring network protocols.

              • +

            • Network Interface +Manager

              The Network Interface Manager (NifMan) creates and manages +network interfaces. The Network interfaces enable the devices to connect to +networks. For more information about NifMan, see Network +Interface Manager (NifMan).

              • +

            • MBufManager

              An +MBuf is part of the implementation of a buffer in the Comms Architecture and +represents a section of memory. The Communications framework creates a MBufs +when the device starts. The MBufManager provides memory management for the +Comms processes. For more information about buffers and MBufs, see Memory +Management.

              • +

            • C32 Serial Server

              The +Serial Communications Server provides a public API to access the serial ports +of the device. It provides functionality such as timeouts and port sharing +for all Serial Protocol Modules. For more information, see the Serial +Communications Server.

              • +
             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3F0789DE-8455-5BA6-850C-45C60C581F18_d0e124947_href.png Binary file Symbian3/SDK/Source/GUID-3F0789DE-8455-5BA6-850C-45C60C581F18_d0e124947_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3F0789DE-8455-5BA6-850C-45C60C581F18_d0e131485_href.png Binary file Symbian3/SDK/Source/GUID-3F0789DE-8455-5BA6-850C-45C60C581F18_d0e131485_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3F172A97-8B96-5E1B-854C-F198D1334D2A_d0e260274_href.png Binary file Symbian3/SDK/Source/GUID-3F172A97-8B96-5E1B-854C-F198D1334D2A_d0e260274_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3F172A97-8B96-5E1B-854C-F198D1334D2A_d0e263982_href.png Binary file Symbian3/SDK/Source/GUID-3F172A97-8B96-5E1B-854C-F198D1334D2A_d0e263982_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3F69590C-B1FB-4E73-B3D3-FD09C894BC60_d0e64488_href.png Binary file Symbian3/SDK/Source/GUID-3F69590C-B1FB-4E73-B3D3-FD09C894BC60_d0e64488_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3F69590C-B1FB-4E73-B3D3-FD09C894BC60_d0e65436_href.png Binary file Symbian3/SDK/Source/GUID-3F69590C-B1FB-4E73-B3D3-FD09C894BC60_d0e65436_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3F7DA54D-28D5-4099-B4EF-728489DCEF2C.dita --- a/Symbian3/SDK/Source/GUID-3F7DA54D-28D5-4099-B4EF-728489DCEF2C.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-3F7DA54D-28D5-4099-B4EF-728489DCEF2C.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,23 +1,23 @@ - - - - - -Color -selection grid -

            Color selection grid consists of grid and may include None button.

            -

            Color selection grid pop-up works similar to regular pop-ups, except for -that dragging and flicking are disabled. The None field is not a part of the -color grid but a separate button. There is no initial focus in the color selection -grid.

            - -Example of color selection grid - - + + + + + +Color +selection grid +

            Color selection grid consists of grid and may include None button.

            +

            Color selection grid pop-up works similar to regular pop-ups, except for +that dragging and flicking are disabled. Note that the grid can also have +a None field but as a separate button. There is no initial focus in the color +selection grid.

            + +Example of color selection grid + +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3F938A76-3F27-56ED-BB3D-0E7EC4ACFB9C.dita --- a/Symbian3/SDK/Source/GUID-3F938A76-3F27-56ED-BB3D-0E7EC4ACFB9C.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-3F938A76-3F27-56ED-BB3D-0E7EC4ACFB9C.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,186 +1,186 @@ - - - - - -New -Search -

            This tutorial provides the steps to perform new search on messages (mainly, -on email messages).

            -
            Introduction

            You can perform the following types -of search on messages (mainly, on email messages):

              -

            • Simple search

              In -a simple search, you use only one message field as a search criteria in a -search request. The single message field can be: to, from, cc, size, time, -message type, message status, priority, attachment type or message body. For -example, search for all emails sent to Sam.

              • -

            • Combined search

              In -a combined search, you use more than one message field as a search criteria -in a search request. The message fields can be a combination of: to, from, -cc, size, time, message type, message status, priority, attachment type, and -message body.

              Note: You can use maximum of five message parts -as a search criteria in a combined search.

              For a combined search, -the CMsvSearchSortQuery::AddSearchOptionL() function can -be called more than once depending on the message fields you use in the search -query. For example, if you have to search all messages from sender Albert, -with subject Invitation, then you must call the AddSearchQueryOptions function -twice.

              However, you can use any functions of the TMsvSearchSortQuery class -only once in each combined search query.

              • -

            Iterative method

            You can enable an iterative method -in simple and combined searches:

              -

            • Iterative

              The -iterative method allows a client to access the search-sort results sequentially -one at a time. It is useful when a client cannot, or does not want to provide -the memory to receive an array of results.

              • -

            • Non-iterative

              This -method retrieves the complete results of the query in a single array. It requires -sufficient RAM on the client-side. This is particularly useful for queries -that return small subset of results.

              • -
            You specify the method with the TInt aIterator parameter -when the client sends a query to the Message Server. By default, the value -is zero (0) which indicates the non-iterative method. You -must set it to 1 to get specify the iterative method. - New search-sort request process - -
            -
            Simple search
              -

            1. Create a search-sort -query using the CMsvSearchSortQuery::NewL() function.

              2. -

            2. Configure the query -by setting parameters, such as the directory to search in, the format for -the results, whether to search for whole or part words, whether to use wild -cards, the case sensitivity, the values and fields to search and the sorting -options.

              3. -

            3. Add the search-sort -operation using the search query as a parameter using the CMsvSearchSortQuery::AddSearchOptionL() function. -There are three versions of the AddSearchOptionL() function, -each of which takes a different parameter type:

                -

              1. Descriptor: For searching -on sender, recipient list (cc, to, bcc), subject, date and date range.

                2. -

              2. Integer: For searching -message size and size range.

                3. -

              3. Boolean: For searching -on priority (high, medium and low), attachment types, message status.

                4. -

              Note: If necessary, enable sorting of search result in ascending -or descending order on the message part added in the query.

              4. -

            4. Create a session with -the Messaging server using the CMsvSession class.

              5. -

            5. Create a search-sort -operation using the CMsvSearchSortOperation class.

              6. -

            6. Start the search-sort -operation by calling the CMsvSearchSortOperation::RequestL() function -and passing the query as a parameter. Do not include an iterator parameter. -It will default to zero (non-iterative).

              7. -

            7. Wait for the Messaging -Server to perform the search.

              8. -

            8. Create an array for -storing the results of the search.

              9. -

            9. Retrieve the results -from the search into the array using the CMsvSearchSortOperation::GetResultsL() function.

              10. -

            10. Get the query ID of -the search from the Messaging server, if necessary, for later use using the CMsvSearchSortOperation::GetQueryId() function.

              11. -
            /** -Simple Seachsort request without iterator. -*/ -void CSearchsortExample::SeachSortRequestWithoutIteratorL() - { - //1. Create an instance of CMsvSearchSortQuery to create a - //search-sort query - CMsvSearchSortQuery* searchQuery = CMsvSearchSortQuery::NewL(); - CleanupStack::PushL(searchQuery); - - //2. Configure the query. - //Search-sort operation is performed on a specified folder. - //(e.g, on INBOX, SENT ITEMS, - //DRAFT, OUTBOX or any user created folder). Needs to set the value of the folder entry. - searchQuery->SetParentId(KMsvRootIndexEntryIdValue); - //Set the type of result expected out of the search-sort operation. - searchQuery->SetResultType(EMsvResultAsTMsvId); - searchQuery->SetWholeWord(ETrue); - searchQuery->SetCaseSensitiveOption(ETrue); - searchQuery->SetWildCardSearch(EFalse); - - //3. Add search option - _LIT( KMsgTo, “david@nokia.com”) ; - searchQuery->AddSearchOptionL(EMsvTo, KMsgTo, EMsvEqual); - // Add sort option - searchQuery->AddSortOptionL(EMsvSize, EMsvSortAscending); - - //4. Create a session with message server - // NOTE: CMsvSession::OpenSyncL requires a &MMsvObserver parameter. This example assumes that - // CSearchSortExample implements MMsvObserver. - CMsvSession* session = CMsvSession::OpenSyncL(*this); - CleanupStack::PushL(session); - - //5. Create an instance of CMsvSearchSortOperation to perform a - //search-sort operation - CMSvSearchSortOperation* search = CMSvSearchSortOperation::NewL(*session); - CleanupStack::PushL(search); - - //6. Start the search operation using the query as a parameter - TRequestStatus aStatus; - CleanupStack::Pop(searchQuery); - // ownership of searchQuery is passed to SearchSortOperation - search->RequestL(searchQuery, ETrue, aStatus); - - //7. Wait for the result - User::WaitForRequest(aStatus); - - //8. Create an array to hold Search-sort results - RArray<TMsvId> resultArray; - - //9. Retrieve the results of the search. The format for the results should be the same as - // what is configured in step 2. Else, will leave with the KErrMsvInvalidResultRequest - // error - TInt err = search->GetResultsL(resultArray); - if(ret == KErrNone) - { - TInt count = resultArray.Count(); - } - - //10. Get the query ID. This ID can be used in repetitive search queries. - iQueryId = search->GetQueryIdL(); - - CleanupStack::PopAndDestroy(2); //search, session - }
            -
            Combined search

            To -create a combined search, add an additional search options in step 3.

            //3. Add search option - _LIT( KMsgTo, “david@nokia.com”) ; - searchQuery->AddSearchOptionL(EMsvTo, KMsgTo, EMsvEqual); - //Add additional option(s) for combined search. - TInt size = 100; - searchQuery->AddSearchOptionL(EMsvSize, size, EMsvGreaterThanOrEqual); // Integer value search - searchQuery->AddSearchOptionL(EMsvAttachment, ETrue); // boolean value search -
            -
            Iterative search

            To -create an iterative search, specify an iterative parameter at step 6.

            // 6. Start the search operation using the query as a parameter - // Specify the iterative method - const TInt KIterativeSearch = 1 ; - TRequestStatus aStatus; - CleanupStack::Pop(searchQuery); - // ownership of searchQuery is passed to SearchSortOperation - search->RequestL(searchQuery, ETrue, aStatus, KIterativeSearch); - - // 9. The results of an iterative search must be retrieved from the message server one at a time - - // Retrieve the results of the search one at a time - - TMsvId result; - //GetNextResultL returns the number of results remaining in the search. - while( search->GetNextResultL( result ) ) - { - // process result - } -
            -Search-sort example

            SearchSortExample: -Enhanced Search and Sort for Message Store

            -
            See also

            For conceptual information on search-sort -APIs, see Searching -and Sorting Messages.

            + + + + + +New +Search +

            This tutorial provides the steps to perform new search on messages (mainly, +on email messages).

            +
            Introduction

            You can perform the following types +of search on messages (mainly, on email messages):

              +

            • Simple search

              In +a simple search, you use only one message field as a search criteria in a +search request. The single message field can be: to, from, cc, size, time, +message type, message status, priority, attachment type or message body. For +example, search for all emails sent to Sam.

              • +

            • Combined search

              In +a combined search, you use more than one message field as a search criteria +in a search request. The message fields can be a combination of: to, from, +cc, size, time, message type, message status, priority, attachment type, and +message body.

              Note: You can use maximum of five message parts +as a search criteria in a combined search.

              For a combined search, +the CMsvSearchSortQuery::AddSearchOptionL() function can +be called more than once depending on the message fields you use in the search +query. For example, if you have to search all messages from sender Albert, +with subject Invitation, then you must call the AddSearchQueryOptions function +twice.

              However, you can use any functions of the TMsvSearchSortQuery class +only once in each combined search query.

              • +

            Iterative method

            You can enable an iterative method +in simple and combined searches:

              +

            • Iterative

              The +iterative method allows a client to access the search-sort results sequentially +one at a time. It is useful when a client cannot, or does not want to provide +the memory to receive an array of results.

              • +

            • Non-iterative

              This +method retrieves the complete results of the query in a single array. It requires +sufficient RAM on the client-side. This is particularly useful for queries +that return small subset of results.

              • +
            You specify the method with the TInt aIterator parameter +when the client sends a query to the Message Server. By default, the value +is zero (0) which indicates the non-iterative method. You +must set it to 1 to get specify the iterative method. + New search-sort request process + +
            +
            Simple search
              +

            1. Create a search-sort +query using the CMsvSearchSortQuery::NewL() function.

              2. +

            2. Configure the query +by setting parameters, such as the directory to search in, the format for +the results, whether to search for whole or part words, whether to use wild +cards, the case sensitivity, the values and fields to search and the sorting +options.

              3. +

            3. Add the search-sort +operation using the search query as a parameter using the CMsvSearchSortQuery::AddSearchOptionL() function. +There are three versions of the AddSearchOptionL() function, +each of which takes a different parameter type:

                +

              1. Descriptor: For searching +on sender, recipient list (cc, to, bcc), subject, date and date range.

                2. +

              2. Integer: For searching +message size and size range.

                3. +

              3. Boolean: For searching +on priority (high, medium and low), attachment types, message status.

                4. +

              Note: If necessary, enable sorting of search result in ascending +or descending order on the message part added in the query.

              4. +

            4. Create a session with +the Messaging server using the CMsvSession class.

              5. +

            5. Create a search-sort +operation using the CMsvSearchSortOperation class.

              6. +

            6. Start the search-sort +operation by calling the CMsvSearchSortOperation::RequestL() function +and passing the query as a parameter. Do not include an iterator parameter. +It will default to zero (non-iterative).

              7. +

            7. Wait for the Messaging +Server to perform the search.

              8. +

            8. Create an array for +storing the results of the search.

              9. +

            9. Retrieve the results +from the search into the array using the CMsvSearchSortOperation::GetResultsL() function.

              10. +

            10. Get the query ID of +the search from the Messaging server, if necessary, for later use using the CMsvSearchSortOperation::GetQueryId() function.

              11. +
            /** +Simple Seachsort request without iterator. +*/ +void CSearchsortExample::SeachSortRequestWithoutIteratorL() + { + //1. Create an instance of CMsvSearchSortQuery to create a + //search-sort query + CMsvSearchSortQuery* searchQuery = CMsvSearchSortQuery::NewL(); + CleanupStack::PushL(searchQuery); + + //2. Configure the query. + //Search-sort operation is performed on a specified folder. + //(e.g, on INBOX, SENT ITEMS, + //DRAFT, OUTBOX or any user created folder). Needs to set the value of the folder entry. + searchQuery->SetParentId(KMsvRootIndexEntryIdValue); + //Set the type of result expected out of the search-sort operation. + searchQuery->SetResultType(EMsvResultAsTMsvId); + searchQuery->SetWholeWord(ETrue); + searchQuery->SetCaseSensitiveOption(ETrue); + searchQuery->SetWildCardSearch(EFalse); + + //3. Add search option + _LIT( KMsgTo, “david@nokia.com”) ; + searchQuery->AddSearchOptionL(EMsvTo, KMsgTo, EMsvEqual); + // Add sort option + searchQuery->AddSortOptionL(EMsvSize, EMsvSortAscending); + + //4. Create a session with message server + // NOTE: CMsvSession::OpenSyncL requires a &MMsvObserver parameter. This example assumes that + // CSearchSortExample implements MMsvObserver. + CMsvSession* session = CMsvSession::OpenSyncL(*this); + CleanupStack::PushL(session); + + //5. Create an instance of CMsvSearchSortOperation to perform a + //search-sort operation + CMSvSearchSortOperation* search = CMSvSearchSortOperation::NewL(*session); + CleanupStack::PushL(search); + + //6. Start the search operation using the query as a parameter + TRequestStatus aStatus; + CleanupStack::Pop(searchQuery); + // ownership of searchQuery is passed to SearchSortOperation + search->RequestL(searchQuery, ETrue, aStatus); + + //7. Wait for the result + User::WaitForRequest(aStatus); + + //8. Create an array to hold Search-sort results + RArray<TMsvId> resultArray; + + //9. Retrieve the results of the search. The format for the results should be the same as + // what is configured in step 2. Else, will leave with the KErrMsvInvalidResultRequest + // error + TInt err = search->GetResultsL(resultArray); + if(ret == KErrNone) + { + TInt count = resultArray.Count(); + } + + //10. Get the query ID. This ID can be used in repetitive search queries. + iQueryId = search->GetQueryIdL(); + + CleanupStack::PopAndDestroy(2); //search, session + }
            +
            Combined search

            To +create a combined search, add an additional search options in step 3.

            //3. Add search option + _LIT( KMsgTo, “david@nokia.com”) ; + searchQuery->AddSearchOptionL(EMsvTo, KMsgTo, EMsvEqual); + //Add additional option(s) for combined search. + TInt size = 100; + searchQuery->AddSearchOptionL(EMsvSize, size, EMsvGreaterThanOrEqual); // Integer value search + searchQuery->AddSearchOptionL(EMsvAttachment, ETrue); // boolean value search +
            +
            Iterative search

            To +create an iterative search, specify an iterative parameter at step 6.

            // 6. Start the search operation using the query as a parameter + // Specify the iterative method + const TInt KIterativeSearch = 1 ; + TRequestStatus aStatus; + CleanupStack::Pop(searchQuery); + // ownership of searchQuery is passed to SearchSortOperation + search->RequestL(searchQuery, ETrue, aStatus, KIterativeSearch); + + // 9. The results of an iterative search must be retrieved from the message server one at a time + + // Retrieve the results of the search one at a time + + TMsvId result; + //GetNextResultL returns the number of results remaining in the search. + while( search->GetNextResultL( result ) ) + { + // process result + } +
            +Search-sort example

            SearchSortExample: +Enhanced Search and Sort for Message Store

            +
            See also

            For conceptual information on search-sort +APIs, see Searching +and Sorting Messages.

            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3FB773BA-C648-5C0A-9022-3F9882C6724A.dita --- a/Symbian3/SDK/Source/GUID-3FB773BA-C648-5C0A-9022-3F9882C6724A.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-3FB773BA-C648-5C0A-9022-3F9882C6724A.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,14 +1,14 @@ - - - - - -Feature Manager Client Overview

            Provides the APIs required to communicate with the feature management server.

            Purpose

            Provides the complete set of functionality required for feature management.

            Required background

            A familiarity with the client/server framework is necessary because feature management uses the standard client/server architecture; the feature manager server actually does the work, the feature manager library provides the APIs to implement a client to that server.

            Architecture

            The relationship between the parts of the feature management system is :

            - Architecture of the feature management system -
            APIs

            This component provides one set of APIs that can be used to communicate with the feature management server.

            This dll file holds the APIs that are @publishedPartner.

            API Description

            RFeatMgrClient

            Base class of the client-side communication with the feature manager server.

            RFeatureControl

            Contains the full functionality of the feature manager.

            MFeatureObserver

            Provides a callback interface for handling feature change notifications.

            CFeatureNotifier

            This is the active object for obtaining the notification of changes in features.

            Typical uses

            • Connect to the feature management server.

            • Produce a list of the features that are present.

            • Check to see if a feature is supported.

            • Delete a feature.

            Feature Manager Overview Feature Discovery Overview Feature Manager Server Guide             \ No newline at end of file + + + + + +Feature Manager Client Overview

            Provides the APIs required to communicate with the feature management server.

            Purpose

            Provides the complete set of functionality required for feature management.

            Required background

            A familiarity with the client/server framework is necessary because feature management uses the standard client/server architecture; the feature manager server actually does the work, the feature manager library provides the APIs to implement a client to that server.

            Architecture

            The relationship between the parts of the feature management system is :

            + Architecture of the feature management system +
            APIs

            This component provides one set of APIs that can be used to communicate with the feature management server.

            This dll file holds the APIs that are @publishedPartner.

            API Description

            RFeatMgrClient

            Base class of the client-side communication with the feature manager server.

            RFeatureControl

            Contains the full functionality of the feature manager.

            MFeatureObserver

            Provides a callback interface for handling feature change notifications.

            CFeatureNotifier

            This is the active object for obtaining the notification of changes in features.

            Typical uses

            • Connect to the feature management server.

            • Produce a list of the features that are present.

            • Check to see if a feature is supported.

            • Delete a feature.

            Feature Manager Overview Feature Discovery Overview Feature Manager Server Guide             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3FB8AC96-209B-5B1E-8139-BA2D858CBF2F.dita --- a/Symbian3/SDK/Source/GUID-3FB8AC96-209B-5B1E-8139-BA2D858CBF2F.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,152 +0,0 @@ - - - - - -CryptoSPI -Overview (weak build) -
            Purpose

            This is an overview of the weak CryptoSPI -APIs. An overview and other documents for the strong CryptoSPI APIs are available -in the Security Supplement, which is delivered to device creators with the -CBR.

            -
            Introduction

            CryptoSPI (cryptospi.dll) -is a framework for implementing cryptographic algorithms, hash algorithms -and random number generation. It allows alternative implementations to be -added by Symbian platform device creators as plug-in DLLs.

            Weak -and strong builds

            The cryptography APIs are subject to export -control regulations. The export of cryptography refers to the transfer from -one country to another of technology related to cryptography. Export control -regulations are for national security considerations.

            Export control -applies to key sizes that are greater than a size specified by the UK Government. -Currently, symmetric algorithms with keys greater than 56 bits and asymmetric -algorithms with keys greater than 512 bits are export controlled. To comply -with government export control rules, the Cryptography library is delivered -in two builds:

              -

            • A weak build

              The -weak build (weak_cryptography.dll) includes cryptography algorithms that are -not export controlled. The weak build rejects requests to apply an encryption -scheme with key sizes greater than 56 bits for symmetric algorithms and 512 -bits for asymmetric algorithms.

              • -

            • A strong build

              The -strong build (strong_cryptography.dll) includes cryptography algorithms that -are export controlled.

              • -

            Note: The API guide and other documentation for cryptography -is broken up in the same way as the cryptography library. This document provides -information on the weak build. It also gives a brief summary of the algorithms -provided in the strong build. The strong cryptography API guide and other -documentation is not available from the Symbian Developer Library. It is delivered -to device creators with the CBR.

            -
            Architectural relationships

            Before the introduction -of CryptoSPI, features such as cryptographic algorithms, hash algorithms and -random number generation were provided by the Symbian platform in cryptography.dll, hash.dll and random.dll.

            softwarecrypto.dll is -a plug-in module (implemented in the Symbian platform) that provides software-based -implementations of all the cryptographic algorithms that were previously implemented -by the legacy components (cryptography.dll, hash.dll and random.dll). -The legacy APIs have been re-implemented internally to use the new framework -via shim classes. hardwarecrypto.dll is an arbitrary -name used in the diagram to represent a plug-in module provided by device -creators. The plug-ins and cryptospi.dll have a dependency -on cryptography.dll because it implements big integers.

            - CryptoSPI dependencies - -
            -
            API summary

            The CryptoSpi namespace -is defined for all CryptoSPI classes to differentiate them from the legacy -APIs with the same names.

            CryptoSPI scope

            CryptoSPI -provides equivalent implementations of all algorithms supported by the legacy -APIs, including hashing and random number generation. The following algorithms -are implemented in softwarecrypto.dll:

            This -section includes summary details of the following (For more information on -the strong APIs, see the Security Supplement, which is delivered to device -creators with the CBR):

              -

            • cryptographic algorithms

              • -

            • hash algorithms

              • -

            • random number generator

              • -

            Cryptographic algorithms

            Cryptographic -algorithms allow data to be encrypted and decrypted. They include:

              -

            • Symmetric ciphers — -algorithms that require communicating parties to hold a shared secret. They -are fast and are used for the transmission of bulk data.

              • -

            • Asymmetric ciphers — -algorithms which have two keys, one private to the keys' owner and one which -can be published. They are slow compared to symmetric ciphers and are used -to exchange a symmetric key before transmission of data encrypted using that -key.

              • -

            The Cryptography algorithms are part of the strong build. To access -details of how to implement them you need to access the Security Supplement, -which is delivered to device creators with the CBR.

            Hash -algorithms

            Hash -algorithms compact a message down to a short series of bytes from which -it is impossible to regenerate the message. They are used with an asymmetric -cipher to generate signatures.

            The following hash algorithms are supported:

            - - - -Hash algorithms -Specified in - - - - -

            MD2

            -

            RFC -1319

            -             - -

            MD4

            -

            RFC -1320

            -             - -

            MD5

            -

            RFC -1321

            -             - -

            SHA1

            -

            FIPS -180-1 and RFC -3174

            -             - - -

            Hashes in HMAC mode

              -

            • MD2

              • -

            • MD4

              • -

            • MD5

              • -

            • SHA1

              • -

            • SHA-224

              • -

            • SHA-256

              • -

            • SHA-384

              • -

            • SHA-512

              • -

            HMAC mode is specified in RFC 2104.

            Random -Number Generator (RNG)

            RNG is -the basis for the cryptographic key generation. It uses the RANROT algorithm -seeded by random data available on the target hardware (for example free running -counters available on ARM processers).

            Supporting -APIs

              -

            • Password Based Encryption -(PBE) — provides an API to encrypt and decrypt data with a user-supplied -password

              • -

            • Padding — is -extra bits concatenated with a key, password, or plaintext to make their length -equal to the block size. It defines the way blocks are filled with data when -the data to be encrypted is smaller than the block size. Padding is added -at encryption and checked on decryption.

              • -

            • Big integers — -arbitrarily large integers.

              Note that although some functions are -exported, the intent is that big integers are only for use by the Cryptography -library and not by application code. Big integers are implemented in cryptography.dll.

              • -

            Implementing CryptoSPI algorithms

            The guide to CryptoSPI -is not publicly available, but the following documents show how to use CryptoSPI -to generate random numbers and create a hash:

              -

            • Generating -random bytes

              • -
            -             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3FC6342D-D09C-5C7F-8E03-3DA7B29D2CC8.dita --- a/Symbian3/SDK/Source/GUID-3FC6342D-D09C-5C7F-8E03-3DA7B29D2CC8.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-3FC6342D-D09C-5C7F-8E03-3DA7B29D2CC8.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,12 +1,12 @@ - - - - - -Recording AudioThis tutorial describes how to start, pause and resume, stop and retrieve the audio samples for audio recording.

            Before you start, you must:

            • Understand the A3F DevSound Component to which the DevSound library belongs.

            • Understand the architectural relationship of the DevSound. For information see DevSound Overview.

            You can perform various functionality in DevSound audio recording that are listed in the below section.

            Starting Audio Record Pausing and Resuming Audio Record Stopping Audio Record Retrieving Audio Record Samples             Playing Audio             \ No newline at end of file + + + + + +Recording AudioThis tutorial describes how to start, pause and resume, stop and retrieve the audio samples for audio recording.

            Before you start, you must:

            • Understand the A3F DevSound Component to which the DevSound library belongs.

            • Understand the architectural relationship of the DevSound. For information see DevSound Overview.

            You can perform various functionality in DevSound audio recording that are listed in the below section.

            Starting Audio Record Pausing and Resuming Audio Record Stopping Audio Record Retrieving Audio Record Samples             Playing Audio             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3FE54688-2CDE-5359-9ABB-B83BFA025A81-GENID-1-8-1-3-1-1-7-1-7-1-3-1.dita --- a/Symbian3/SDK/Source/GUID-3FE54688-2CDE-5359-9ABB-B83BFA025A81-GENID-1-8-1-3-1-1-7-1-7-1-3-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,46 +0,0 @@ - - - - - -Window-owning -controls and non-window-owning controls -

            Controls are similar to windows in the Window Server in that they are both -bounded areas of the screen and both user interface elements. They are not -synonymous, however, as a control may take up the whole of a window’s area -or only part of it. For this reason controls are divided into two types: window-owning -controls and non-window-owning controls.

            -
            Window-owning controls

            A window-owning control -has the same size and position as a window in the Window Server. Window-owning -controls may overlap each other and may be moved around the screen within -the bounds of their parent window. Dialogs, menus, toolbars and top-level -controls are typically window-owning controls.

            -
            Non-window-owning controls (lodger controls)

            The -majority of controls are non-window-owning. A non-window-owning control’s extent typically -covers only part of a window on the screen: usually it is one of a number -of controls within a larger compound control which acts -as a container.

            Examples of non-window-owning controls include command -buttons, text boxes and labels.

            Non-window-owning controls give greater -efficiency as they require fewer resources in the Window Server and fewer -process switches. They can also result in faster intialisation and redrawing -because a compound control and all its non-window-owning components can be -drawn with a single flush to the window server.

            -
            Associated windows

            All controls have an associated -window, whether they are window-owning or not. For a window-owning -control the associated window is the window it owns. For a non-window-owning -control the associated window is the window owned by the nearest window-owning -control above it in the control hierarchy.

            -
            See also
              -

            • Window server

              • -

            • Run-time control -hierarchy

              • -

            • How to write -controls

              • -
            -             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3FE54688-2CDE-5359-9ABB-B83BFA025A81-GENID-1-8-1-6-1-1-4-1-6-1-7-1-3-1.dita --- a/Symbian3/SDK/Source/GUID-3FE54688-2CDE-5359-9ABB-B83BFA025A81-GENID-1-8-1-6-1-1-4-1-6-1-7-1-3-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,46 +0,0 @@ - - - - - -Window-owning -controls and non-window-owning controls -

            Controls are similar to windows in the Window Server in that they are both -bounded areas of the screen and both user interface elements. They are not -synonymous, however, as a control may take up the whole of a window’s area -or only part of it. For this reason controls are divided into two types: window-owning -controls and non-window-owning controls.

            -
            Window-owning controls

            A window-owning control -has the same size and position as a window in the Window Server. Window-owning -controls may overlap each other and may be moved around the screen within -the bounds of their parent window. Dialogs, menus, toolbars and top-level -controls are typically window-owning controls.

            -
            Non-window-owning controls (lodger controls)

            The -majority of controls are non-window-owning. A non-window-owning control’s extent typically -covers only part of a window on the screen: usually it is one of a number -of controls within a larger compound control which acts -as a container.

            Examples of non-window-owning controls include command -buttons, text boxes and labels.

            Non-window-owning controls give greater -efficiency as they require fewer resources in the Window Server and fewer -process switches. They can also result in faster intialisation and redrawing -because a compound control and all its non-window-owning components can be -drawn with a single flush to the window server.

            -
            Associated windows

            All controls have an associated -window, whether they are window-owning or not. For a window-owning -control the associated window is the window it owns. For a non-window-owning -control the associated window is the window owned by the nearest window-owning -control above it in the control hierarchy.

            -
            See also
              -

            • Window server

              • -

            • Run-time control -hierarchy

              • -

            • How to write -controls

              • -
            -             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3FE54688-2CDE-5359-9ABB-B83BFA025A81.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-3FE54688-2CDE-5359-9ABB-B83BFA025A81.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,46 @@ + + + + + +Window-owning +controls and non-window-owning controls +

            Controls are similar to windows in the Window Server in that they are both +bounded areas of the screen and both user interface elements. They are not +synonymous, however, as a control may take up the whole of a window’s area +or only part of it. For this reason controls are divided into two types: window-owning +controls and non-window-owning controls.

            +
            Window-owning controls

            A window-owning control +has the same size and position as a window in the Window Server. Window-owning +controls may overlap each other and may be moved around the screen within +the bounds of their parent window. Dialogs, menus, toolbars and top-level +controls are typically window-owning controls.

            +
            Non-window-owning controls (lodger controls)

            The +majority of controls are non-window-owning. A non-window-owning control’s extent typically +covers only part of a window on the screen: usually it is one of a number +of controls within a larger compound control which acts +as a container.

            Examples of non-window-owning controls include command +buttons, text boxes and labels.

            Non-window-owning controls give greater +efficiency as they require fewer resources in the Window Server and fewer +process switches. They can also result in faster intialisation and redrawing +because a compound control and all its non-window-owning components can be +drawn with a single flush to the window server.

            +
            Associated windows

            All controls have an associated +window, whether they are window-owning or not. For a window-owning +control the associated window is the window it owns. For a non-window-owning +control the associated window is the window owned by the nearest window-owning +control above it in the control hierarchy.

            +
            See also
              +

            • Window server

              • +

            • Run-time control +hierarchy

              • +

            • How to write +controls

              • +
            +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3FFF726B-D158-4EDF-B950-4B58467F210B_d0e3474_href.png Binary file Symbian3/SDK/Source/GUID-3FFF726B-D158-4EDF-B950-4B58467F210B_d0e3474_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-3FFF726B-D158-4EDF-B950-4B58467F210B_d0e4749_href.png Binary file Symbian3/SDK/Source/GUID-3FFF726B-D158-4EDF-B950-4B58467F210B_d0e4749_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4028CDCF-D2E8-5668-A751-A7CFA86CED46_d0e357820_href.png Binary file Symbian3/SDK/Source/GUID-4028CDCF-D2E8-5668-A751-A7CFA86CED46_d0e357820_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4028CDCF-D2E8-5668-A751-A7CFA86CED46_d0e363900_href.png Binary file Symbian3/SDK/Source/GUID-4028CDCF-D2E8-5668-A751-A7CFA86CED46_d0e363900_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-40437D9A-7503-5087-851A-D1269F0AF9A9_d0e196473_href.png Binary file Symbian3/SDK/Source/GUID-40437D9A-7503-5087-851A-D1269F0AF9A9_d0e196473_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-40437D9A-7503-5087-851A-D1269F0AF9A9_d0e201481_href.png Binary file Symbian3/SDK/Source/GUID-40437D9A-7503-5087-851A-D1269F0AF9A9_d0e201481_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-405F7AB8-0F0E-4171-95E6-3524D76917DE.dita --- a/Symbian3/SDK/Source/GUID-405F7AB8-0F0E-4171-95E6-3524D76917DE.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-405F7AB8-0F0E-4171-95E6-3524D76917DE.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,27 +1,44 @@ - - - - - -Handling -stylus pop-up menu events and commands -

            At the construction phase, CAknStylusPopUpMenu is given -a MEikMenuObserver object, which is usually a pointer to -the application’s UI (CAknAppUi) -or another class that implements the interface. The stylus pop up menu will -grab the stylus event when one of its items is tapped on and it will then -report the item’s command ID to the menu observer. It is then up to the application -to handle the command in the implementation of MEikMenuObserver::HandleCommandL().

            -

            When an item is tapped, the menu calls its observer's (iMenuObserver) -ProcessCommandL. Typically the observer is application's AppUi. It is then -the observer's responsibility to handle the command appropriately. The observer -is informed with KErrCancel if the menu is closed without making a selection.

            -

            Add sample code on event and command -handling here.

            + + + + + +Handling stylus pop-up menu events and commands +

            At the construction phase, CAknStylusPopUpMenu is given a MEikMenuObserver object, which is usually +a pointer to the application’s UI (CAknAppUi) or +another class that implements the interface. The stylus pop up menu +will grab the stylus event when one of its items is tapped on and +it will then report the item’s command ID to the menu observer. It +is then up to the application to handle the command in the implementation +of MEikMenuObserver::HandleCommandL().

            +

            When an item is tapped, the menu calls its observer's (iMenuObserver) ProcessCommandL() using:void ProcessCommandL(TInt aCommandId); where, aCommandID parameter is the command number recorded in +the resource file. You can also add it using AddMenuItemL() function as shown in the following code snippet:void AddMenuItemL( const TDesC& aItem, const TInt aCommandId );

            +

            The following code snippet illustrates how to handle the command:switch( aCommandId ) + { + case StylusMenuCommand1: + break; + case StylusMenuCommand2: + break; + case StylusMenuCommand3: + break; + case StylusMenuCommand4: + break; + case KErrCancel: + break; + default: + break; + } +

            +

            Typically the observer is application's AppUi. It is then the observer's +responsibility to handle the command appropriately. The observer is +informed with KErrCancel if the menu is closed without +making a selection.

            +

            Use the CAknStylusPopUpMenu::HandleControlEventL() method to handle events that occur when user selects a menu item.

            +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-40619192-8C2F-4267-BFCA-F53E10BF5A31_d0e11254_href.png Binary file Symbian3/SDK/Source/GUID-40619192-8C2F-4267-BFCA-F53E10BF5A31_d0e11254_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-40619192-8C2F-4267-BFCA-F53E10BF5A31_d0e12529_href.png Binary file Symbian3/SDK/Source/GUID-40619192-8C2F-4267-BFCA-F53E10BF5A31_d0e12529_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4067B0E6-9431-4325-95F7-78B143EED326.dita --- a/Symbian3/SDK/Source/GUID-4067B0E6-9431-4325-95F7-78B143EED326.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,36 +0,0 @@ - - - - - -Softkeys -and basic softkey configuration -

            The Symbian platform supports two softkeys and labels the Selection key -in the middle of the Control pane. This, in effect, looks like a "middle softkey". -Touch UI does not have the middle softkey label visible, refer to Touch -support for common UI components. The softkey labels are placed in -the control pane (the bottom area of the screen). The left and right softkeys -always have textual labels, but the Selection key can also have two icons -in certain situations.

            -

            The three softkey configurations supported in the Symbian UI style are -the following:

            -
              -

            • Basic Symbian portrait-oriented UI with softkeys immediately below -the screen (the middle softkey label is visible)

              • -

            • Symbian UI with side softkeys in landscape (both left and right rotation -possible, middle softkey label not possible)

              • -

            • Symbian UI with bottom softkeys in landscape (middle softkey label -not possible). Not available for Touch UI.

              • -
            -

            For more details on the functions assigned to softkeys, see Where -the Symbian user interface belongs and Typical -functions of the standard keys.

            -
            Using -softkeys in C++ applications

            The API to use for softkeys is the Buttons API. For implementation information, see Using the Buttons API.

            -             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-40A3938E-366E-5318-A7FA-146F9E5E23B1_d0e189180_href.png Binary file Symbian3/SDK/Source/GUID-40A3938E-366E-5318-A7FA-146F9E5E23B1_d0e189180_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-40A3938E-366E-5318-A7FA-146F9E5E23B1_d0e194242_href.png Binary file Symbian3/SDK/Source/GUID-40A3938E-366E-5318-A7FA-146F9E5E23B1_d0e194242_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-40B9136A-B91B-5FF4-A44D-CA6925F19B14.dita --- a/Symbian3/SDK/Source/GUID-40B9136A-B91B-5FF4-A44D-CA6925F19B14.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-40B9136A-B91B-5FF4-A44D-CA6925F19B14.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,15 +1,15 @@ - - - - - -Feature Discovery OverviewProvides a set of APIs that are used to initate a feature discovery operation.
            Purpose

            Feature discovery provides a set of APIs to discover if a feature or feature set is supported and available.

            Required background

            The feature management system uses the standard client server architecture that is the feature manager server does the work associated with the feature management functionality. Communication between the application and the server is undertaken by two dlls which contain the required API.

            Architecture

            The relationship between the parts of the feature management system is :

            - Architecture of the feature management system -
            APIs

            This component provides one set of APIs that can be used to communicate with the feature management server.

            API Description

            TFeatureSet

            Used to determine if multiple features are supported.

            CFeatureDiscovery

            Used to determine if a feature is supported.

            Typical uses

            The APIs provided by this dll are for use by third parties

            • A third party app wants to find out if the device can execute it : there is no point installing an application needing a camera, if one is not present on the device.

            • For the above, they would use the API provided by featmgr.dll.

            • Would be used to check if the required feature (and assumed framework) is present.

            Use cases:

            • Query a single feature.

            • Query multiple features.

            Feature Manager Overview Feature Manager Client + + + + + +Feature Discovery OverviewProvides a set of APIs that are used to initate a feature discovery operation.
            Purpose

            Feature discovery provides a set of APIs to discover if a feature or feature set is supported and available.

            Required background

            The feature management system uses the standard client server architecture that is the feature manager server does the work associated with the feature management functionality. Communication between the application and the server is undertaken by two dlls which contain the required API.

            Architecture

            The relationship between the parts of the feature management system is :

            + Architecture of the feature management system +
            APIs

            This component provides one set of APIs that can be used to communicate with the feature management server.

            API Description

            TFeatureSet

            Used to determine if multiple features are supported.

            CFeatureDiscovery

            Used to determine if a feature is supported.

            Typical uses

            The APIs provided by this dll are for use by third parties

            • A third party app wants to find out if the device can execute it : there is no point installing an application needing a camera, if one is not present on the device.

            • For the above, they would use the API provided by featmgr.dll.

            • Would be used to check if the required feature (and assumed framework) is present.

            Use cases:

            • Query a single feature.

            • Query multiple features.

            Feature Manager Overview Feature Manager Client Overview Feature Manager Server Guide             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-40BE9805-6CEC-557F-BAAC-4D328E181AC3_d0e196422_href.png Binary file Symbian3/SDK/Source/GUID-40BE9805-6CEC-557F-BAAC-4D328E181AC3_d0e196422_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-40BE9805-6CEC-557F-BAAC-4D328E181AC3_d0e201430_href.png Binary file Symbian3/SDK/Source/GUID-40BE9805-6CEC-557F-BAAC-4D328E181AC3_d0e201430_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-40C995CA-9906-59D8-A5E7-08F592031AEE_d0e247945_href.png Binary file Symbian3/SDK/Source/GUID-40C995CA-9906-59D8-A5E7-08F592031AEE_d0e247945_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-40C995CA-9906-59D8-A5E7-08F592031AEE_d0e251682_href.png Binary file Symbian3/SDK/Source/GUID-40C995CA-9906-59D8-A5E7-08F592031AEE_d0e251682_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-40E64445-CBA3-59E4-A777-937609B311C9.dita --- a/Symbian3/SDK/Source/GUID-40E64445-CBA3-59E4-A777-937609B311C9.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-40E64445-CBA3-59E4-A777-937609B311C9.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,49 +1,49 @@ - - - - - -Contacts -Model Overview -
            Purpose

            The purpose of this document is to give -guidelines on how to use the Contacts Model API most efficiently for a range -of typical operations. The Contacts Model is an engine component that provides -access to contact information stored on a device. Just like a real-world address -book it stores and organises names, telephone numbers, addresses and other -details of individuals and companies. It can be used to add, delete and edit -data as well as providing information to clients, and sorting and searching -contacts.

            -
            Architectural Relationships

            The Contacts Model -is primarily used by messaging, telephony, synchronisation and vCard viewer -clients on a device.

            - CONTACTS MODEL CLIENTS - -
            -
            Description

            The CContactDatabase class -allows clients access to the contact data stored on the device and has the -following functionality:

            Contact database management

            More than one Contact Database -can exist on a phone, but a default Contact Database is used if no other is -specified. Clients can open, close, alter and delete the Contact Database. -Extra databases can be added as required. The Contact Database can be moved -between drives, and can be compressed in order to save space.

            Contact items management

            Contact Items are made up of Contact -Fields and can be added to and removed from the database. Items in the database -can be opened, read, sorted and deleted. An item must be opened before it -can be edited. Editing an item often means altering data in one or more fields, -such as name or telephone number. To provide different sorting views Contact -Items can be grouped in categories such as ‘colleagues’ or ‘family’.

            Searching the database

            Searching CContactDatabase implements -searching and sorting and also provides separate phone number matching functions. -These provide a fast way of indexing and looking up phone numbers, for example, -for looking up caller IDs on incoming calls.

            Speed dial functionality

            The database owns speed dial information. -This is a mapping between a single digit integer and a telephone number. There -may be up to nine speed dial telephone numbers. If a Contact Item is deleted, -its speed dial mapping is removed.

            Notification of changes

            The database needs to be informed -of data changes made to it. Sometimes a UI-level application may need to respond -to updates made by other clients. The Contacts Model provides an observer -to transmit this information between CContactDatabase instances.

            + + + + + +Contacts +Model Overview +
            Purpose

            The purpose of this document is to give +guidelines on how to use the Contacts Model API most efficiently for a range +of typical operations. The Contacts Model is an engine component that provides +access to contact information stored on a device. Just like a real-world address +book it stores and organises names, telephone numbers, addresses and other +details of individuals and companies. It can be used to add, delete and edit +data as well as providing information to clients, and sorting and searching +contacts.

            +
            Architectural Relationships

            The Contacts Model +is primarily used by messaging, telephony, synchronisation and vCard viewer +clients on a device.

            + CONTACTS MODEL CLIENTS + +
            +
            Description

            The CContactDatabase class +allows clients access to the contact data stored on the device and has the +following functionality:

            Contact database management

            More than one Contact Database +can exist on a phone, but a default Contact Database is used if no other is +specified. Clients can open, close, alter and delete the Contact Database. +Extra databases can be added as required. The Contact Database can be moved +between drives, and can be compressed in order to save space.

            Contact items management

            Contact Items are made up of Contact +Fields and can be added to and removed from the database. Items in the database +can be opened, read, sorted and deleted. An item must be opened before it +can be edited. Editing an item often means altering data in one or more fields, +such as name or telephone number. To provide different sorting views Contact +Items can be grouped in categories such as ‘colleagues’ or ‘family’.

            Searching the database

            Searching CContactDatabase implements +searching and sorting and also provides separate phone number matching functions. +These provide a fast way of indexing and looking up phone numbers, for example, +for looking up caller IDs on incoming calls.

            Speed dial functionality

            The database owns speed dial information. +This is a mapping between a single digit integer and a telephone number. There +may be up to nine speed dial telephone numbers. If a Contact Item is deleted, +its speed dial mapping is removed.

            Notification of changes

            The database needs to be informed +of data changes made to it. Sometimes a UI-level application may need to respond +to updates made by other clients. The Contacts Model provides an observer +to transmit this information between CContactDatabase instances.

            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-40ED6F39-F8E2-5292-ADA5-C2507F256AE0_d0e244714_href.png Binary file Symbian3/SDK/Source/GUID-40ED6F39-F8E2-5292-ADA5-C2507F256AE0_d0e244714_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-40ED6F39-F8E2-5292-ADA5-C2507F256AE0_d0e248451_href.png Binary file Symbian3/SDK/Source/GUID-40ED6F39-F8E2-5292-ADA5-C2507F256AE0_d0e248451_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-40F5B725-A5D7-487F-BF5D-A616F768F40D.dita --- a/Symbian3/SDK/Source/GUID-40F5B725-A5D7-487F-BF5D-A616F768F40D.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-40F5B725-A5D7-487F-BF5D-A616F768F40D.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,140 +1,137 @@ - - - - - -Soft -notifications -

            Soft notifications are reminders that inform the user of events that have -occurred in the user's absence, or while the mobile device user was busy with -some application. Text and graphics, can be used to communicate the message -to the user. Soft notifications are displayed in pop-up windows in the Idle -state.

            -

            The user can respond to the soft notification by using the softkeys. The -left softkey is used for activating a function, for example opening a message -that has arrived. The right softkey is used to discard the notification without -taking any further action. In touch layout, the softkeys are placed inside -the pop-up component

            - -Soft notification indicating new messages - - -

            Soft notifications are displayed only in the Idle state. If an event that -causes a soft notification (for example, a missed call) occurs when an application -is active, it may cause other kinds of UI events to notify the user, but if -the user does not react to these, the soft notification appears only after -the phone is put in the Idle state if the event still requires it.

            -

            The application that launched a soft notification can control it and also -discard it. It is possible to use the S60 key during a soft notification; -in that case, the soft notification disappears, but reappears when the user -returns to the Idle state, unless the application responsible for the notification -has discarded it.

            -

            Soft notifications can be displayed for the user in two different appearances:

            -
              -

            • Ungrouped soft notification: These notifications contain one -piece of information each. The appearance of the notification window is the -same as that of a note. The example in the figure below is an ungrouped soft -notification.

              • -

            • Grouped soft notification: Many different items of information -can be combined into one soft notification where the items are displayed as -a list. The user can pick up one of the items at a time and react to it. The -appearance of this soft notification type is the same as the appearance of -a List query (see Queries).

              • -
            - -Grouped soft notification. The height of the window is dynamic and -depends on the number of lines in the list. - - -

            -Default touch -events for ungrouped soft notification - - - -

            User action

             -

            State change

             -

            Feedback

             -             - - - -

            Touch down and release on SK1 §KEY_SK1_SOFTKEY§

             -

            Confirms the operation.

            Attached application is activated, -and displayed notification disappears completely.

             -

            Tactile: Basic button effect and audio feedback is provided with -touch down and basic button effect with release events.

             -             - -

            Touch down and release on SK2 §KEY_SK2_SOFTKEY§

             -

            Discards operation.

            Attached application is discarded and -displayed notification disappears completely

             -

            Tactile: Basic button effect and audio feedback is provided with -touch down and basic button effect with release events.

             -             - -

            Touch down and release on notification

             -

            Confirms operation.

            Attached application is activated, and -displayed notification disappears completely.

             -

            Tactile: Basic button effect and audio feedback is provided with -touch down and basic button effect with release events.

             -             - -

            Touch down and release outside notification

             -

            Inactive

             -

            Tactile: No effect

             -             - - -
            -

            -Default touch -events for grouped soft notification - - - -

            User action

             -

            State change

             -

            Feedback

             -             - - - -

            Touch down and release on SK2 §KEY_SK2_SOFTKEY§

             -

            Discards the operation.

            Grouped soft notification is discarded

             -

            Tactile: Basic button effect and audio feedback is provided with -touch down and basic button effect with release events.

             -             - -

            Touch down and release on list item

             -

            Confirms the operation.

            Attached application is activated, -and selected choice item is removed from the soft notification list. The user -can return to the grouped soft notification list by returning to idle state.

             -

            Tactile: Basic button effect and audio feedback is provided with -touch down and basic button effect with release events.

             -             - -

            Touch down and release outside notification

             -

            Inactive

             -

            Tactile: No effect

             -             - -

            Touch down and move on list item

             -

            Refer to Dragging -and flicking events

             -

            Tactile: Refer to Dragging -and flicking events.

             -             - - -
            -

            Using -soft notifications in C++ applications

            The API to use for soft notifications -is the Notifiers API. For implementation information, see Using the Notifiers API.

            + + + + + +Soft notifications +

            Soft notifications are reminders that inform the user of events that have +occurred in the user's absence, or while the mobile device user was busy with +some application. Text and graphics, can be used to communicate the message +to the user. Soft notifications are displayed in pop-up windows in the home +screen.

            +

            The user can respond to the soft notification by using the softkeys. The +left softkey is used for activating a function, for example opening a message +that has arrived. The right softkey is used to discard the notification without +taking any further action. In touch layout, the softkeys are placed inside +the pop-up component

            +

            Soft notifications are displayed only in the home screen. If an event that +causes a soft notification (for example, a missed call) occurs when an application +is active, it may cause other kinds of UI events to notify the user, but if +the user does not react to these, the soft notification appears only after +the phone is put in the home screen if the event still requires it.

            +

            The application that launched a soft notification can control it and also +discard it. It is possible to use the Menu key during a soft notification; +in that case, the soft notification disappears, but reappears when the user +returns to the home screen, unless the application responsible for the notification +has discarded it.

            +

            Soft notifications can be displayed for the user in two different appearances:

            +
              +

            • Ungrouped soft notification: These notifications contain one +piece of information each. The appearance of the notification window is the +same as that of a note. The example in the figure below is an ungrouped soft +notification.

              +Soft notification indicating a new message + +
              • +

            • Grouped soft notification: Many different items of information +can be combined into one soft notification where the items are displayed as +a list. The user can pick up one of the items at a time and react to it. The +appearance of this soft notification type is the same as the appearance of +a List query (see Queries).

              +Grouped soft notification. The height of the window is dynamic and +depends on the number of lines in the list. + +
              • +
            +

            +Default touch +events for ungrouped soft notification + + + +

            User action

             +

            State change

             +

            Feedback

             +             + + + +

            Touch down and release on left softkey.

             +

            Confirms the operation.

            Attached application is activated, +and displayed notification disappears completely.

             +

            Tactile: Basic button effect and audio feedback is provided with +touch down and basic button effect with release events.

             +             + +

            Touch down and release on right softkey.

             +

            Discards operation.

            Attached application is discarded and +displayed notification disappears completely

             +

            Tactile: Basic button effect and audio feedback is provided with +touch down and basic button effect with release events.

             +             + +

            Touch down and release on notification

             +

            Confirms operation.

            Attached application is activated, and +displayed notification disappears completely.

             +

            Tactile: Basic button effect and audio feedback is provided with +touch down and basic button effect with release events.

             +             + +

            Touch down and release outside notification

             +

            Inactive

             +

            Tactile: No effect

             +             + + +
            +

            +Default touch +events for grouped soft notification + + + +

            User action

             +

            State change

             +

            Feedback

             +             + + + +

            Touch down and release on right softkey.

             +

            Discards the operation.

            Grouped soft notification is discarded

             +

            Tactile: Basic button effect and audio feedback is provided with +touch down and basic button effect with release events.

             +             + +

            Touch down and release on list item

             +

            Confirms the operation.

            Attached application is activated, +and selected choice item is removed from the soft notification list. The user +can return to the grouped soft notification list by returning to home screen.

             +

            Tactile: Basic button effect and audio feedback is provided with +touch down and basic button effect with release events.

             +             + +

            Touch down and release outside notification

             +

            Inactive

             +

            Tactile: No effect

             +             + +

            Touch down and move on list item

             +

            Refer to Dragging +and flicking events

             +

            Tactile: Refer to Dragging +and flicking events.

             +             + + +
            +

            Using +soft notifications in applications

            The API to use for soft notifications +is the Notifiers API. For implementation information, see Using the Notifiers API.

             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4119C4BD-ABBF-524B-B649-0F39EF58A7FB_d0e107311_href.png Binary file Symbian3/SDK/Source/GUID-4119C4BD-ABBF-524B-B649-0F39EF58A7FB_d0e107311_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4119C4BD-ABBF-524B-B649-0F39EF58A7FB_d0e113849_href.png Binary file Symbian3/SDK/Source/GUID-4119C4BD-ABBF-524B-B649-0F39EF58A7FB_d0e113849_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4120651F-E0B9-5927-96B9-2662C51F5A09.dita --- a/Symbian3/SDK/Source/GUID-4120651F-E0B9-5927-96B9-2662C51F5A09.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-4120651F-E0B9-5927-96B9-2662C51F5A09.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,268 +1,268 @@ - - - - - -SIP -High Level API -

            The SIP High Level API encapsulates the SIP call flows inside the RConnection and RSubConnection APIs. The following SIP functionality is supported using RConnection and RSubConnection APIs:

            -
              -

            • REGISTER - An application -that wants to start a SIP session must register to the SIP server. For more -information, see Registration.

              • -

            • INVITE - An invite session -is created for activities such as setting up a voice call, and a game session. -For more information, see Session -initiation.

              • -

            • SUBSCRIBE - SIP supports -subscription to events for example, message waiting, notifying the subscriber -about the current state of the event and any changes to its state. For more -information, see Initiating -a session using SUBSCRIBE.

              • -
            -

            The INVITE and SUBSCRIBE methods must -be registered. CSubConSIPInviteParamSet and CSubConSIPSubscribeParamSet classes -provide the parameters.

            -

            Note: SIP High Level API is included in the Symbian OS v9.2 onwards.

            -
            Registration

            An -endpoint, for example a SIP enabled phone, that wants to start a SIP session -must use RConnection to register with the SIP registrar. -For more information about RConnection, seeConnection -Management . ESOCK provides an interface for the -user to access the SIP high level API. ESOCK interacts -with the SIP high level API through the Connection and SubConnection providers. -Connection and SubConnection providers are ESOCK server side -components that are loaded and called when RConnection and RSubConnection APIs -are used.

            The following figure shows the architectural layer where -the application interacts with SIP connection providers using SIPPARAMS. The -second layer comprising RSocket, RSubConnection, -and RConnection constitute the SIPPARAMS.

            - Interface of Connection and Sub Connection. - - -

            The SIP high level API models the SIP with Connection and SubConnection -providers and makes it stackable against the unified comms-infras architecture. -This enables the future connection convergence.

            Initial setup

            A -profile data store is required to get registered with the SIP Registrar. A -SIP registration profile is a data store containing the information required -for registration such as AOR which is the IP address of registrar. The data -profile must contain the following fields:

              -

            • data profile type: Internet, -IMS, others

              • -

            • profile name IETF, IMS, -others

              • -

            • IAP name

              • -

            • profile AOR list (IP -address)

              • -

            • autoregistration

              • -

            • private ID

              • -

            • security negotiation

              • -

            • sigcomp

              • -

            • server (IP address of -registrar, outbound proxy)

              • -

            • server param (username, -realm, pwd)

              • -

            • default

              • -

            Manual registration by specifying parameters is not possible. If -connection details are not available, the connection is set up using the default profile.flag file.

            Creating an RConnection

            Create -an RConnection to register to the SIP Registrar using the -following steps. RConnection must be opened on an existing -socket server session, RSocketServ.

            RSocketServ socketServer; // Create a client interface object to the socket server -RConnection con; // Create an RConnection object -TRequestStatus status = KErrNone; // object to hold the request completion status - -// Establish the connection to the Socket server - -User::LeaveIfError(socketServer.Connect()); // Returns KErrorNone if the connection is successful -CleanupClosePushL(socketServer); - -TUint KAFSip = 0x10000; //SIP protocol family id -TInt err = con.Open (socketServer,KAFSip); //open the connection -TInt err1 = con.Start(); // Start Rconnection to initiate the registration -

            When registration to the SIP registrar is successful, RSubConnection is -used to establish the SIP Invite or SIP Subscribe session. The RConnection and RSubConnection that -is established and opened are used for either inviting a call session or subscribing -for the message status.

            -
            Session initiation

            SIP -Params

            SIPPARAMS is used to simplify the interaction with the -SIP stack by abstracting the SIP functionality using the RConnection and RSubConnection APIs.  It -supports the basic SIP functionality. The complete SIP functionality is made -available through the SIP stack APIs.

            Initiating -a session using INVITE

            RSubConnection is used -to establish a SIP Invite session. A SIP invitation starts when an endpoint -such as a VoIP Softphone or VoIP Hardware tries to establish a session with -a remote compliant endpoint. A successful SIP invitation consists of an INVITE-OK-ACK -triplet message exchange. The calling endpoint tries to start a session with -SIP INVITE. This is followed by OK from the called endpoint, and by ACK from -the calling endpoint that finally establishes the SIP session.

            A SIP -session can be terminated by using BYE-200OK message exchange. Either the -calling or the called party can initiate the termination.

            RSubConnection establishes -the SIP session using the three way communication of INVITE-OK-ACK and terminates -the call using BYE-200OK.

            RSubConnection when -used on behalf of the calling endpoint, handles the message exchange independently -and provides the status whether the session is established, denied or not -reachable. The calling endpoint must fill the necessary SIP session parameters -that are used to determine the target.

            RSubConnection when -used on behalf of the called endpoint alerts the user of an incoming call -such as a SIP invitation. The incoming call can be either accepted or rejected -using RSubConnection. The application is notified about -the outcome. The information about the calling endpoint is provided in a set -of specific parameters.

            The SIP parameters for an outgoing call is -set using CSubConSIPInviteParamSet class. The following -code shows how to initiate a call. It is assumed that you have already registered -with the SIP registrar by creating an RConnection object -and called Open(). For more information, see Creating an RConnection.

            RSubConnection subCon; // Create an RSubConnection object -err=subCon.Open(socketServer,RSubConnection::ECreateNew,con); // Open subconnection onto the Rconnection -

            Set the SIP Invite parameters. The following code shows how -to set the SIP Invite parameters.

            RSubConParameterBundle sipBundle; // create parameter bundle - -// create SIP parameter set family -CSubConParameterFamily * family = CSubConParameterFamily::NewL(sipBundle,KSubConnCallDescrParamsFamily); - -// create invite parameter set object -CSubConSIPInviteParamSet* sip = CSubConSIPInviteParamSet::NewL(*family,CSubConParameterFamily::ERequested);

            Set -the SIP header values to the parameter set. The following code shows how to -set the SIP header values to the parameter set.

            _LIT8(KTo,"Sip:user@10.112.165.91"); //'To' header, SIP URI of called endpoint -TPtrC8 ptrTo(KTo()); -sip->SetToL(ptrTo); //Set'To', the target SIP URI to the SIP parameter set - -_LIT8(KFrom, "Sip:user@10.112.165.62"); //'From' header, SIP URI of the calling endPoint -TPtrC8 ptrFrom(KFrom()); -sip->SetFromL(ptrFrom); //Set the 'From' header field to the SIP parameter set - -_LIT8(KContact,"Sip:user@10.112.165.62"); //'Contact' header, the actual location of the calling endpoint -TPtrC8 ptrContact (KContact()); -sip->SetContactL(ptrContact); //Set the 'Contact' to the SIP parameter set - -_LIT8(KRequestUri, "Sip:user@10.112.165.91"); //Request URI, the actual Next hop or the Target -TPtrC8 ptrRequestUri(KRequestUri()); -sip->SetRequestUriL(ptrRequestUri); //Set the 'RequestUri' to the SIP parameter set TInt err = SubCon.SetParameters(sipBundle); //Set The SIP parameters in the SubConnection -sipBundle.Close(); //close the parameter bundle

            Establishing the INVITE -session

            To establish the SIP Invite session, use RSubConnection to -start the subconnection. This initiates the Invite request.

            //Start the subconnection, effectively sending an Invite -TInt subConRet = subCon.Start(); -// Session is established

            Initiating -a session using SUBSCRIBE

            An endpoint subscribes to a specific -service using a SIP SUBSCRIBE-200OK message exchange. The end point is notified -by means of a NOTIFY-200OK message exchange. To send the subscription and -receive notifications use RSubConnection. RSubConnection is -also used to unsubscribe, which stops any further notifications.

            The -following code shows how you subscribe to a session and receive notifications. -It assumes that you have already registered with the SIP registrar by creating -an RConnection object and calling Open() on -it as explained in Creating -an RConnection section.

            RSubConnection subCon;// Create an RSubConnection object -// Open subconnection onto the Rconnection -err=subCon.Open(socketServer,RSubConnection::ECreateNew,con); -

            Set the SIP Subscribe parameters using CSubConSIPSubscribeParamSet. -This class provides the SIP subscribe parameters that are passed through the -subconnection to the SIP stack.

            RSubConParameterBundle sipBundle; // create parameter bundle - -//create SIP parameter set family -CSubConParameterFamily * family = CSubConParameterFamily::NewL(sipBundle,KSubConnCallDescrParamsFamily); - -// create subscribe parameter set object -CSubConSIPSubscribeParamSet* sip = CSubConSIPSubscribeParamSet::NewL(*family,CSubConParameterFamily::ERequested);

            Set the -required information that is, to, from, contact, and reqURI header -values to the SIP subscribe parameter set as explained in Initiating a session using INVITE section.

            // Set the required information -_LIT8(KEventType, "messagewaiting"); // subscription event type -TPtrC8 ptrEventType (KEventType()); -sip->SetEventTypeL(ptrEventType); //Set the subscription event type to 'messagewaiting' - -_LIT8(KAcceptType, "application"); //accept type -TPtrC8 ptrAcceptType(KAcceptType()); -sip->SetAcceptTypeL(ptrAcceptType); //set the accept type field to 'application' - -_LIT8(KAcceptSubType, "indication"); //accept subtype -TPtrC8 ptrAcceptSubType(KAcceptSubType()); -sip->SetAcceptSubTypeL(ptrAcceptSubType); //set the accept subtype - -sip->SetExpires(3600); // set the subscription Refresh timings - -sip->SetAutoRefresh(ETrue); // set Auto Refresh to 'on' - -// pass SIP subscribe parameters through the subconnection -Tint err = subCon.SetParameters(sipBundle); -sipBundle.Close(); //close the parameter bundle - -subCon.Start(); // Start the subscription -

            To receive notifications to the subscribed events, CSubConSIPNotificationEvent class -is used.

            // Wait and receive notifications to events -while(ETrue) -{ -TNotificationEventBuf evtBuf; // Sub-connection event notification object - - TRequestStatus reqStatus; // request status object - - User::WaitForRequest(reqStatus); - TInt eventId = evtBuf.Id(); // get sub-type id - TInt groupId = evtBuf.GroupId(); // get group id of the event - -if (eventId == KSubConSIPNotificationEventType && groupId == KSubConSIPEventsUid) - { - CSubConSIPNotificationEvent * evtRes = (CSubConSIPNotificationEvent*)CSubConNotificationEvent::NewL(evtBuf); - CleanupStack::PushL(evtRes); - .................... - .................... - CleanupStack::PopAndDestroy(evtRes); - - // Since We do not want to receive more notifications in this stage, break from the loop. - - break; - } - -// we can wait again for another notification -subCon.EventNotification( evtBuf,EFalse, reqStatus); //request for notification -}

            Unsubscribe to events and unregister, refer to steps in the Terminating -the session section.

            Setting authentication parameters

            A -remote party or a server may require authentication before it allows an endpoint -to establish a session with another endpoint. RSubConnection provides -an authentication mechanism where the authentication information such as realm, -username and password must be provided while initiating the call. If a challenge -is received then RSubConnection provides the realm and -initiates a new session with authentication parameters.

            Authentication -parameters are set in a subconnection parameter bundle as shown in the following -code fragment. Set the SIP authenticate parameter set using CSubConSIPAuthenticateParamSet. -This class provides the SIP authenticate parameter values that are passed -through the subconnection to the SIP stack.

            RSubConParameterBundle sipBundle; // create parameter bundle -// Add authorisation parameters as new family -CSubConParameterFamily * family1 = CSubConParameterFamily::NewL(sipBundle,KSubConAuthorisationFamily ); - -// create authenticate parameter set object -CSubConSIPAuthenticateParamSet * authParam = CSubConSIPAuthenticateParamSet::NewL(*family1,CSubConParameterFamily::ERequested); -

            Set the required information that is, to, from, contact, reqURI header field values to the SIP authenticate parameter set, similar to that -in Initiating -a session using INVITE section.

            _LIT8(KRealm, "SFTF"); -_LIT8(KUserName, "MyUserName"); -_LIT8(KPwd, "pass123"); - -authParam->SetRealmL(KRealm); //set the Realm parameter -authParam->SetUserNameL(KUserName); // set the username -authParam->SetPasswordL(KPwd); //set the password - -TInt err = subCon.SetParameters(sipBundle); //set the Authenticate parameters to the subconnection -sipBundle.Close(); //close the parameter bundle

            To -terminate the call session or unsubscribe to events and unregister, follow -the steps in Terminating -the session section.

            -
            Terminating -the session

            To terminate the SIP INVITE or SUBSCRIBE session:

              -

            • send BYE message by -closing the RSubConnection session

              • -

            • unregister with the -SIP registrar by closing the RConnection session.

              • -
            Int ret = subCon.Stop(); // Terminate the session, send BYE message - -subCon.Close(); // close the subconnection - -con.Stop(); // Terminate the connection - -con.Close(); // Close the connection
            -
            See also

            Socket Server Protocols Overview

            Sockets Client Overview

            Connection Management

            + + + + + +SIP +High Level API +

            The SIP High Level API encapsulates the SIP call flows inside the RConnection and RSubConnection APIs. The following SIP functionality is supported using RConnection and RSubConnection APIs:

            +
              +

            • REGISTER - An application +that wants to start a SIP session must register to the SIP server. For more +information, see Registration.

              • +

            • INVITE - An invite session +is created for activities such as setting up a voice call, and a game session. +For more information, see Session +initiation.

              • +

            • SUBSCRIBE - SIP supports +subscription to events for example, message waiting, notifying the subscriber +about the current state of the event and any changes to its state. For more +information, see Initiating +a session using SUBSCRIBE.

              • +
            +

            The INVITE and SUBSCRIBE methods must +be registered. CSubConSIPInviteParamSet and CSubConSIPSubscribeParamSet classes +provide the parameters.

            +

            Note: SIP High Level API is included in the Symbian OS v9.2 onwards.

            +
            Registration

            An +endpoint, for example a SIP enabled phone, that wants to start a SIP session +must use RConnection to register with the SIP registrar. +For more information about RConnection, seeConnection +Management . ESOCK provides an interface for the +user to access the SIP high level API. ESOCK interacts +with the SIP high level API through the Connection and SubConnection providers. +Connection and SubConnection providers are ESOCK server side +components that are loaded and called when RConnection and RSubConnection APIs +are used.

            The following figure shows the architectural layer where +the application interacts with SIP connection providers using SIPPARAMS. The +second layer comprising RSocket, RSubConnection, +and RConnection constitute the SIPPARAMS.

            + Interface of Connection and Sub Connection. + + +

            The SIP high level API models the SIP with Connection and SubConnection +providers and makes it stackable against the unified comms-infras architecture. +This enables the future connection convergence.

            Initial setup

            A +profile data store is required to get registered with the SIP Registrar. A +SIP registration profile is a data store containing the information required +for registration such as AOR which is the IP address of registrar. The data +profile must contain the following fields:

              +

            • data profile type: Internet, +IMS, others

              • +

            • profile name IETF, IMS, +others

              • +

            • IAP name

              • +

            • profile AOR list (IP +address)

              • +

            • autoregistration

              • +

            • private ID

              • +

            • security negotiation

              • +

            • sigcomp

              • +

            • server (IP address of +registrar, outbound proxy)

              • +

            • server param (username, +realm, pwd)

              • +

            • default

              • +

            Manual registration by specifying parameters is not possible. If +connection details are not available, the connection is set up using the default profile.flag file.

            Creating an RConnection

            Create +an RConnection to register to the SIP Registrar using the +following steps. RConnection must be opened on an existing +socket server session, RSocketServ.

            RSocketServ socketServer; // Create a client interface object to the socket server +RConnection con; // Create an RConnection object +TRequestStatus status = KErrNone; // object to hold the request completion status + +// Establish the connection to the Socket server + +User::LeaveIfError(socketServer.Connect()); // Returns KErrorNone if the connection is successful +CleanupClosePushL(socketServer); + +TUint KAFSip = 0x10000; //SIP protocol family id +TInt err = con.Open (socketServer,KAFSip); //open the connection +TInt err1 = con.Start(); // Start Rconnection to initiate the registration +

            When registration to the SIP registrar is successful, RSubConnection is +used to establish the SIP Invite or SIP Subscribe session. The RConnection and RSubConnection that +is established and opened are used for either inviting a call session or subscribing +for the message status.

            +
            Session initiation

            SIP +Params

            SIPPARAMS is used to simplify the interaction with the +SIP stack by abstracting the SIP functionality using the RConnection and RSubConnection APIs.  It +supports the basic SIP functionality. The complete SIP functionality is made +available through the SIP stack APIs.

            Initiating +a session using INVITE

            RSubConnection is used +to establish a SIP Invite session. A SIP invitation starts when an endpoint +such as a VoIP Softphone or VoIP Hardware tries to establish a session with +a remote compliant endpoint. A successful SIP invitation consists of an INVITE-OK-ACK +triplet message exchange. The calling endpoint tries to start a session with +SIP INVITE. This is followed by OK from the called endpoint, and by ACK from +the calling endpoint that finally establishes the SIP session.

            A SIP +session can be terminated by using BYE-200OK message exchange. Either the +calling or the called party can initiate the termination.

            RSubConnection establishes +the SIP session using the three way communication of INVITE-OK-ACK and terminates +the call using BYE-200OK.

            RSubConnection when +used on behalf of the calling endpoint, handles the message exchange independently +and provides the status whether the session is established, denied or not +reachable. The calling endpoint must fill the necessary SIP session parameters +that are used to determine the target.

            RSubConnection when +used on behalf of the called endpoint alerts the user of an incoming call +such as a SIP invitation. The incoming call can be either accepted or rejected +using RSubConnection. The application is notified about +the outcome. The information about the calling endpoint is provided in a set +of specific parameters.

            The SIP parameters for an outgoing call is +set using CSubConSIPInviteParamSet class. The following +code shows how to initiate a call. It is assumed that you have already registered +with the SIP registrar by creating an RConnection object +and called Open(). For more information, see Creating an RConnection.

            RSubConnection subCon; // Create an RSubConnection object +err=subCon.Open(socketServer,RSubConnection::ECreateNew,con); // Open subconnection onto the Rconnection +

            Set the SIP Invite parameters. The following code shows how +to set the SIP Invite parameters.

            RSubConParameterBundle sipBundle; // create parameter bundle + +// create SIP parameter set family +CSubConParameterFamily * family = CSubConParameterFamily::NewL(sipBundle,KSubConnCallDescrParamsFamily); + +// create invite parameter set object +CSubConSIPInviteParamSet* sip = CSubConSIPInviteParamSet::NewL(*family,CSubConParameterFamily::ERequested);

            Set +the SIP header values to the parameter set. The following code shows how to +set the SIP header values to the parameter set.

            _LIT8(KTo,"Sip:user@10.112.165.91"); //'To' header, SIP URI of called endpoint +TPtrC8 ptrTo(KTo()); +sip->SetToL(ptrTo); //Set'To', the target SIP URI to the SIP parameter set + +_LIT8(KFrom, "Sip:user@10.112.165.62"); //'From' header, SIP URI of the calling endPoint +TPtrC8 ptrFrom(KFrom()); +sip->SetFromL(ptrFrom); //Set the 'From' header field to the SIP parameter set + +_LIT8(KContact,"Sip:user@10.112.165.62"); //'Contact' header, the actual location of the calling endpoint +TPtrC8 ptrContact (KContact()); +sip->SetContactL(ptrContact); //Set the 'Contact' to the SIP parameter set + +_LIT8(KRequestUri, "Sip:user@10.112.165.91"); //Request URI, the actual Next hop or the Target +TPtrC8 ptrRequestUri(KRequestUri()); +sip->SetRequestUriL(ptrRequestUri); //Set the 'RequestUri' to the SIP parameter set TInt err = SubCon.SetParameters(sipBundle); //Set The SIP parameters in the SubConnection +sipBundle.Close(); //close the parameter bundle

            Establishing the INVITE +session

            To establish the SIP Invite session, use RSubConnection to +start the subconnection. This initiates the Invite request.

            //Start the subconnection, effectively sending an Invite +TInt subConRet = subCon.Start(); +// Session is established

            Initiating +a session using SUBSCRIBE

            An endpoint subscribes to a specific +service using a SIP SUBSCRIBE-200OK message exchange. The end point is notified +by means of a NOTIFY-200OK message exchange. To send the subscription and +receive notifications use RSubConnection. RSubConnection is +also used to unsubscribe, which stops any further notifications.

            The +following code shows how you subscribe to a session and receive notifications. +It assumes that you have already registered with the SIP registrar by creating +an RConnection object and calling Open() on +it as explained in Creating +an RConnection section.

            RSubConnection subCon;// Create an RSubConnection object +// Open subconnection onto the Rconnection +err=subCon.Open(socketServer,RSubConnection::ECreateNew,con); +

            Set the SIP Subscribe parameters using CSubConSIPSubscribeParamSet. +This class provides the SIP subscribe parameters that are passed through the +subconnection to the SIP stack.

            RSubConParameterBundle sipBundle; // create parameter bundle + +//create SIP parameter set family +CSubConParameterFamily * family = CSubConParameterFamily::NewL(sipBundle,KSubConnCallDescrParamsFamily); + +// create subscribe parameter set object +CSubConSIPSubscribeParamSet* sip = CSubConSIPSubscribeParamSet::NewL(*family,CSubConParameterFamily::ERequested);

            Set the +required information that is, to, from, contact, and reqURI header +values to the SIP subscribe parameter set as explained in Initiating a session using INVITE section.

            // Set the required information +_LIT8(KEventType, "messagewaiting"); // subscription event type +TPtrC8 ptrEventType (KEventType()); +sip->SetEventTypeL(ptrEventType); //Set the subscription event type to 'messagewaiting' + +_LIT8(KAcceptType, "application"); //accept type +TPtrC8 ptrAcceptType(KAcceptType()); +sip->SetAcceptTypeL(ptrAcceptType); //set the accept type field to 'application' + +_LIT8(KAcceptSubType, "indication"); //accept subtype +TPtrC8 ptrAcceptSubType(KAcceptSubType()); +sip->SetAcceptSubTypeL(ptrAcceptSubType); //set the accept subtype + +sip->SetExpires(3600); // set the subscription Refresh timings + +sip->SetAutoRefresh(ETrue); // set Auto Refresh to 'on' + +// pass SIP subscribe parameters through the subconnection +Tint err = subCon.SetParameters(sipBundle); +sipBundle.Close(); //close the parameter bundle + +subCon.Start(); // Start the subscription +

            To receive notifications to the subscribed events, CSubConSIPNotificationEvent class +is used.

            // Wait and receive notifications to events +while(ETrue) +{ +TNotificationEventBuf evtBuf; // Sub-connection event notification object + + TRequestStatus reqStatus; // request status object + + User::WaitForRequest(reqStatus); + TInt eventId = evtBuf.Id(); // get sub-type id + TInt groupId = evtBuf.GroupId(); // get group id of the event + +if (eventId == KSubConSIPNotificationEventType && groupId == KSubConSIPEventsUid) + { + CSubConSIPNotificationEvent * evtRes = (CSubConSIPNotificationEvent*)CSubConNotificationEvent::NewL(evtBuf); + CleanupStack::PushL(evtRes); + .................... + .................... + CleanupStack::PopAndDestroy(evtRes); + + // Since We do not want to receive more notifications in this stage, break from the loop. + + break; + } + +// we can wait again for another notification +subCon.EventNotification( evtBuf,EFalse, reqStatus); //request for notification +}

            Unsubscribe to events and unregister, refer to steps in the Terminating +the session section.

            Setting authentication parameters

            A +remote party or a server may require authentication before it allows an endpoint +to establish a session with another endpoint. RSubConnection provides +an authentication mechanism where the authentication information such as realm, +username and password must be provided while initiating the call. If a challenge +is received then RSubConnection provides the realm and +initiates a new session with authentication parameters.

            Authentication +parameters are set in a subconnection parameter bundle as shown in the following +code fragment. Set the SIP authenticate parameter set using CSubConSIPAuthenticateParamSet. +This class provides the SIP authenticate parameter values that are passed +through the subconnection to the SIP stack.

            RSubConParameterBundle sipBundle; // create parameter bundle +// Add authorisation parameters as new family +CSubConParameterFamily * family1 = CSubConParameterFamily::NewL(sipBundle,KSubConAuthorisationFamily ); + +// create authenticate parameter set object +CSubConSIPAuthenticateParamSet * authParam = CSubConSIPAuthenticateParamSet::NewL(*family1,CSubConParameterFamily::ERequested); +

            Set the required information that is, to, from, contact, reqURI header field values to the SIP authenticate parameter set, similar to that +in Initiating +a session using INVITE section.

            _LIT8(KRealm, "SFTF"); +_LIT8(KUserName, "MyUserName"); +_LIT8(KPwd, "pass123"); + +authParam->SetRealmL(KRealm); //set the Realm parameter +authParam->SetUserNameL(KUserName); // set the username +authParam->SetPasswordL(KPwd); //set the password + +TInt err = subCon.SetParameters(sipBundle); //set the Authenticate parameters to the subconnection +sipBundle.Close(); //close the parameter bundle

            To +terminate the call session or unsubscribe to events and unregister, follow +the steps in Terminating +the session section.

            +
            Terminating +the session

            To terminate the SIP INVITE or SUBSCRIBE session:

              +

            • send BYE message by +closing the RSubConnection session

              • +

            • unregister with the +SIP registrar by closing the RConnection session.

              • +
            Int ret = subCon.Stop(); // Terminate the session, send BYE message + +subCon.Close(); // close the subconnection + +con.Stop(); // Terminate the connection + +con.Close(); // Close the connection
            +
            See also

            Socket Server Protocols Overview

            Sockets Client Overview

            Connection Management

             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-416A3756-B5D5-5BCD-830E-2371C5F6B502.dita --- a/Symbian3/SDK/Source/GUID-416A3756-B5D5-5BCD-830E-2371C5F6B502.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-416A3756-B5D5-5BCD-830E-2371C5F6B502.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,16 +1,16 @@ - - - - - -Font Store Component OverviewThe Font Store contains all of the fonts and typefaces on a phone. It is encapsulated by the Font and Bitmap server which provides a client-side class that applications use to find which fonts are available and to find fonts to match their requirements.

            The Font Store component is sometimes called the Open Font System or Open Font Framework.

            Required background

            • You require no background knowledge or experience use the Font Store using the Font and Bitmap Server interfaces.

            • You require no background knowledge or experience to add new font files to the Font Store. You must simply copy the files to the appropriate location.

            • To create a font file or a font rasterizer, you require an in-depth knowledge of fonts and Symbian programming.

            Key concepts and terms

            See Concepts and Terms in the Font and Text Services Collection Overview.

            Architectural relationships

            The Font Store can contain three types of font: bitmap fonts, which are stored as fixed-size pixel definitions; open fonts, which may be stored in any format; and linked fonts, which use characters from two or more other fonts. Open fonts must be converted into bitmaps (rasterized) before they can be used so the Font Store must also contain a font rasterizer for each format of open font.

            Fonts are stored on Symbian phones as files. The Font Store maintains a list of font files along with specifications for each font that the file contains. When an application requests a font the Font Store searches its list for the best match. If the font is a bitmap font the Font Store loads it into the Font and Bitmap Server's shared heap (unless the font is in eXecute In Place (XIP) ROM, in which case it is accessed directly from ROM). If the font is an open font the Font Store uses the associated open font rasterizer to rasterize glyphs into the heap as they are required. Font rasterizers are ECOM plugins.

            - Font Store relationships -
            Font Store API summary

            The Font Store contains APIs for specifying and selecting fonts and for rasterizing open fonts.

            API Description

            CBitmapFont

            Bitmap-based font object

            CFontStore

            Central font storage class

            CLinkedTypefaceGroup

            Linked fonts typeface group

            CLinkedTypefaceSpecification

            Linked font creation

            CLinkedTypefaceElementSpec

            Linked font typeface element spec

            COpenFont

            Generic outline font object

            COpenFontFile

            Open font file

            COpenFontRasterizer

            Open font rasterizer

            COpenFontRasterizerContext

            Open font rasterizer context

            TAlgStyle

            Algorithmic style attributes

            TCharacterMetrics

            Character information

            TLinkedTypeface

            Linked fonts

            TOpenFontAttachment

            Diacritic attachment point information

            TOpenFontCharMetrics

            Open font character metrics

            TOpenFontFaceAttrib

            Open font typeface information

            TOpenFontFaceAttribBase

            Basic open font typeface information

            TOpenFontGlyphData

            Open font glyph information

            TOpenFontMetrics

            Open font information

            TOpenFontSpec

            Open font specification

            Font Store tasks

            The following functionality is provided by the fntstore subsystem component:

            • Font loading

              Font file loading using plug-in font rasterizers if required.

            • Font request matching

              Closest-fit matching of font requests.

            • Font linking

              The creation and use of Linked Fonts – virtual fonts that are made out of one or (usually) more physical fonts. These can be used to:

              • Combine multiple character ranges from individual fonts into a single font.

              • Allow an existing font containing a particular script to be customized to use regional variant characters.

              • Allow a comprehensive range of scripts to be built into a device ROM and multiple possible subsets to be defined and used by software configuration.

              Linked fonts are primarily used for system fonts. The fact that a font is a linked font is invisible to the user.

            Platform security information

            Font data files are installed in the read-only folder \resource\fonts.

            Font and Text Services Collection - Overview Font and Bitmap Server Component Overview + + + + + +Font Store Component OverviewThe Font Store contains all of the fonts and typefaces on a phone. It is encapsulated by the Font and Bitmap server which provides a client-side class that applications use to find which fonts are available and to find fonts to match their requirements.

            The Font Store component is sometimes called the Open Font System or Open Font Framework.

            Required background

            • You require no background knowledge or experience use the Font Store using the Font and Bitmap Server interfaces.

            • You require no background knowledge or experience to add new font files to the Font Store. You must simply copy the files to the appropriate location.

            • To create a font file or a font rasterizer, you require an in-depth knowledge of fonts and Symbian programming.

            Key concepts and terms

            See Concepts and Terms in the Font and Text Services Collection Overview.

            Architectural relationships

            The Font Store can contain three types of font: bitmap fonts, which are stored as fixed-size pixel definitions; open fonts, which may be stored in any format; and linked fonts, which use characters from two or more other fonts. Open fonts must be converted into bitmaps (rasterized) before they can be used so the Font Store must also contain a font rasterizer for each format of open font.

            Fonts are stored on Symbian phones as files. The Font Store maintains a list of font files along with specifications for each font that the file contains. When an application requests a font the Font Store searches its list for the best match. If the font is a bitmap font the Font Store loads it into the Font and Bitmap Server's shared heap (unless the font is in eXecute In Place (XIP) ROM, in which case it is accessed directly from ROM). If the font is an open font the Font Store uses the associated open font rasterizer to rasterize glyphs into the heap as they are required. Font rasterizers are ECOM plugins.

            + Font Store relationships +
            Font Store API summary

            The Font Store contains APIs for specifying and selecting fonts and for rasterizing open fonts.

            API Description

            CBitmapFont

            Bitmap-based font object

            CFontStore

            Central font storage class

            CLinkedTypefaceGroup

            Linked fonts typeface group

            CLinkedTypefaceSpecification

            Linked font creation

            CLinkedTypefaceElementSpec

            Linked font typeface element spec

            COpenFont

            Generic outline font object

            COpenFontFile

            Open font file

            COpenFontRasterizer

            Open font rasterizer

            COpenFontRasterizerContext

            Open font rasterizer context

            TAlgStyle

            Algorithmic style attributes

            TCharacterMetrics

            Character information

            TLinkedTypeface

            Linked fonts

            TOpenFontAttachment

            Diacritic attachment point information

            TOpenFontCharMetrics

            Open font character metrics

            TOpenFontFaceAttrib

            Open font typeface information

            TOpenFontFaceAttribBase

            Basic open font typeface information

            TOpenFontGlyphData

            Open font glyph information

            TOpenFontMetrics

            Open font information

            TOpenFontSpec

            Open font specification

            Font Store tasks

            The following functionality is provided by the fntstore subsystem component:

            • Font loading

              Font file loading using plug-in font rasterizers if required.

            • Font request matching

              Closest-fit matching of font requests.

            • Font linking

              The creation and use of Linked Fonts – virtual fonts that are made out of one or (usually) more physical fonts. These can be used to:

              • Combine multiple character ranges from individual fonts into a single font.

              • Allow an existing font containing a particular script to be customized to use regional variant characters.

              • Allow a comprehensive range of scripts to be built into a device ROM and multiple possible subsets to be defined and used by software configuration.

              Linked fonts are primarily used for system fonts. The fact that a font is a linked font is invisible to the user.

            Platform security information

            Font data files are installed in the read-only folder \resource\fonts.

            Font and Text Services Collection + Overview Font and Bitmap Server Component Overview             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4195F4EE-5A61-515D-A6EF-2E16E00E4AFF.dita --- a/Symbian3/SDK/Source/GUID-4195F4EE-5A61-515D-A6EF-2E16E00E4AFF.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-4195F4EE-5A61-515D-A6EF-2E16E00E4AFF.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,14 +1,14 @@ - - - - - -Recording media files

            You can use the MVS to record audio or video signals to media files. To record an audio signal, first connect a microphone; to record a video signal, connect a camera.

            To record a media file, choosing the plugin controller:

            1. In the File menu, click Open for Record. The Choose a plugin dialog box is displayed.

              - Choosing a format when recording audio -

              Note: If you don't want to choose a plugin controller manually, click Cancel in the Choose a plugin dialog box: the Save as dialog box is displayed. In the Save as dialog box, enter the target file name including its extension; the controller appropriate to the extension is loaded automatically. If there is no appropriate controller, a Not Supported message is displayed.

            2. Select the Media Type to record by clicking either the Audio or Video option button.

            3. Select the Supported Format from the drop-down list. The corresponding plugin Controller is selected automatically.

              Note: To check which controllers are supported by the system:

              • In the File menu, click System Info. The controllers are listed:

            4. Click Next. The Save as dialog box is displayed.

            5. In the dialog box, enter the names of the disk drive and folder to contain the file, or select them from the lists.

            6. In the dialog box, enter the name of the file, without an extension, to contain the recorded audio or video.

            7. Click OK to save the file.

            The next steps depend on whether you are Recording an audio file or Recording a video file.

            Recording an audio file

            If you are recording an audio file, the Configure Audio Format dialog box is displayed.

            1. In the dialog box, select:

              • the codec

              • the bit rate

              • the number of channels (1 = mono, 2 = stereo)

              • the sample rate in bits per second.

            2. If required, click the Restore Settings check box to restore the previous settings or - if there are none - the default settings.

            3. Click OK to save the settings.

            4. To start recording, click the tool bar Record button, or in the Controls menu, click Record.

            Recording a video file

            If you are recording a video file, the Standard Video Record format dialog box is displayed.

            1. In the dialog box, select:

              • the video mime type

              • the video frame rate

              • the video frame size in pixels (width, height).

            2. To record audio with the video signal, click the Enable Audio check box.

            3. If required, click the Restore Settings check box to restore the previous settings or - if there are none - the default settings.

            4. Click OK to save the settings.

            5. To start recording, click the tool bar Record button, or in the Controls menu, click Record.

              • To pause recording, click the tool bar Pause button, or in the Controls menu, click Pause. To un-pause the file and resume recording, click the tool bar Record button, or in the Controls menu, click Record.

              • To stop recording, click the tool bar Stop button, or in the Controls menu, click Stop.

            See Also

            Introduction to the MVS

            MVS GUI layout

            Playing media files

            Editing media files

            Configuring and clearing files

            \ No newline at end of file + + + + + +Recording media files

            You can use the MVS to record audio or video signals to media files. To record an audio signal, first connect a microphone; to record a video signal, connect a camera.

            To record a media file, choosing the plugin controller:

            1. In the File menu, click Open for Record. The Choose a plugin dialog box is displayed.

              + Choosing a format when recording audio +

              Note: If you don't want to choose a plugin controller manually, click Cancel in the Choose a plugin dialog box: the Save as dialog box is displayed. In the Save as dialog box, enter the target file name including its extension; the controller appropriate to the extension is loaded automatically. If there is no appropriate controller, a Not Supported message is displayed.

            2. Select the Media Type to record by clicking either the Audio or Video option button.

            3. Select the Supported Format from the drop-down list. The corresponding plugin Controller is selected automatically.

              Note: To check which controllers are supported by the system:

              • In the File menu, click System Info. The controllers are listed:

            4. Click Next. The Save as dialog box is displayed.

            5. In the dialog box, enter the names of the disk drive and folder to contain the file, or select them from the lists.

            6. In the dialog box, enter the name of the file, without an extension, to contain the recorded audio or video.

            7. Click OK to save the file.

            The next steps depend on whether you are Recording an audio file or Recording a video file.

            Recording an audio file

            If you are recording an audio file, the Configure Audio Format dialog box is displayed.

            1. In the dialog box, select:

              • the codec

              • the bit rate

              • the number of channels (1 = mono, 2 = stereo)

              • the sample rate in bits per second.

            2. If required, click the Restore Settings check box to restore the previous settings or - if there are none - the default settings.

            3. Click OK to save the settings.

            4. To start recording, click the tool bar Record button, or in the Controls menu, click Record.

            Recording a video file

            If you are recording a video file, the Standard Video Record format dialog box is displayed.

            1. In the dialog box, select:

              • the video mime type

              • the video frame rate

              • the video frame size in pixels (width, height).

            2. To record audio with the video signal, click the Enable Audio check box.

            3. If required, click the Restore Settings check box to restore the previous settings or - if there are none - the default settings.

            4. Click OK to save the settings.

            5. To start recording, click the tool bar Record button, or in the Controls menu, click Record.

              • To pause recording, click the tool bar Pause button, or in the Controls menu, click Pause. To un-pause the file and resume recording, click the tool bar Record button, or in the Controls menu, click Record.

              • To stop recording, click the tool bar Stop button, or in the Controls menu, click Stop.

            See Also

            Introduction to the MVS

            MVS GUI layout

            Playing media files

            Editing media files

            Configuring and clearing files

            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-41A53C1F-E9BF-420F-A967-83906299FE8B_d0e2777_href.png Binary file Symbian3/SDK/Source/GUID-41A53C1F-E9BF-420F-A967-83906299FE8B_d0e2777_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-41A53C1F-E9BF-420F-A967-83906299FE8B_d0e2879_href.png Binary file Symbian3/SDK/Source/GUID-41A53C1F-E9BF-420F-A967-83906299FE8B_d0e2879_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-41A70DFD-BADF-5B8F-8085-488F34F81561_d0e300969_href.png Binary file Symbian3/SDK/Source/GUID-41A70DFD-BADF-5B8F-8085-488F34F81561_d0e300969_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-41A70DFD-BADF-5B8F-8085-488F34F81561_d0e306996_href.png Binary file Symbian3/SDK/Source/GUID-41A70DFD-BADF-5B8F-8085-488F34F81561_d0e306996_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-422F37DF-F93F-443F-86EA-6A696A53E1E6.dita --- a/Symbian3/SDK/Source/GUID-422F37DF-F93F-443F-86EA-6A696A53E1E6.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-422F37DF-F93F-443F-86EA-6A696A53E1E6.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,79 +1,79 @@ - - - - - -Listening -for scrollbar touch eventsIf your custom control contains a scrollbar, you need to listen -for touch events in the scrollbar. -

            For custom controls that override CCoeControl::HandleScrollEventL(), -you must also call the base class implementation of the function.

            - -Scrollbar - - -

            For an implementation example, see below.

            -void CMyContainerControl::HandleScrollEventL( CEikScrollBar* aScrollBar, TEikScrollEvent aEventType ) - { - if( !aScrollBar ) - { - return; - } - - TInt newPosition = aScrollBar->ThumbPosition(); - - switch( aEventType ) - { - case EEikScrollUp: // Moving up one step - { - MoveFocusUpL(); - break; - } - case EEikScrollDown: // Moving down one step - { - MoveFocusDownL(); - break; - } - case EEikScrollThumbDragVert: // Drag started - case EEikScrollThumbReleaseVert: // Drag released - { - if( newPosition < iFocusedIndex ) - { - MoveFocusUpL(); - } - else if( newPosition > iFocusedIndex ) - { - MoveFocusDownL(); - } - break; - } - case EEikScrollPageUp: - { - while( newPosition < iFocusedIndex ) - { - MoveFocusUpL(); - } - break; - } - case EEikScrollPageDown: - { - while( newPosition > iFocusedIndex ) - { - MoveFocusDownL(); - } - break; - } - default: - { - break; - } - } - DrawNow(); - } + + + + + +Listening +for scrollbar touch eventsIf your custom control contains a scrollbar, you need to listen +for touch events in the scrollbar. +

            For custom controls that override CCoeControl::HandleScrollEventL(), +you must also call the base class implementation of the function.

            + +Scrollbar + + +

            For an implementation example, see below.

            +void CMyContainerControl::HandleScrollEventL( CEikScrollBar* aScrollBar, TEikScrollEvent aEventType ) + { + if( !aScrollBar ) + { + return; + } + + TInt newPosition = aScrollBar->ThumbPosition(); + + switch( aEventType ) + { + case EEikScrollUp: // Moving up one step + { + MoveFocusUpL(); + break; + } + case EEikScrollDown: // Moving down one step + { + MoveFocusDownL(); + break; + } + case EEikScrollThumbDragVert: // Drag started + case EEikScrollThumbReleaseVert: // Drag released + { + if( newPosition < iFocusedIndex ) + { + MoveFocusUpL(); + } + else if( newPosition > iFocusedIndex ) + { + MoveFocusDownL(); + } + break; + } + case EEikScrollPageUp: + { + while( newPosition < iFocusedIndex ) + { + MoveFocusUpL(); + } + break; + } + case EEikScrollPageDown: + { + while( newPosition > iFocusedIndex ) + { + MoveFocusDownL(); + } + break; + } + default: + { + break; + } + } + DrawNow(); + }             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-42609A21-CEDC-58E8-864C-0CF8458F6798_d0e287092_href.png Binary file Symbian3/SDK/Source/GUID-42609A21-CEDC-58E8-864C-0CF8458F6798_d0e287092_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-42609A21-CEDC-58E8-864C-0CF8458F6798_d0e290725_href.png Binary file Symbian3/SDK/Source/GUID-42609A21-CEDC-58E8-864C-0CF8458F6798_d0e290725_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-42833109-F8C2-57FC-9995-0461698A19FF.dita --- a/Symbian3/SDK/Source/GUID-42833109-F8C2-57FC-9995-0461698A19FF.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-42833109-F8C2-57FC-9995-0461698A19FF.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,45 +1,45 @@ - - - - - -IMAP4 -Concepts -

            This section describes the Internet Message Access Protocol (IMAP4) and -its implementation on the Symbian platform.

            -
            IMAP4 protocol

            IMAP4 -is one of the most common Internet standard protocols for retrieving emails. -It is an application layer Internet protocol operating on port 143 that allows -a local client to access email on a remote server.

            The current version, -IMAP version 4 revision 1 (IMAP4rev1), is defined by RFC 3501. Eariler, IMAP4 -was called Internet Mail Access Protocol, Interactive Mail Access Protocol -(RFC 1064), and Interim Mail Access Protocol.

            The default port for -IMAP4 to download messages is 143, but if a client establishes a secure connection -(over SSL or TLS) for IMAP4 to download message, the port is 993.

            Most -email clients support either POP3 or IMAP to retrieve messages; however, few -Internet Service Providers (ISPs) support IMAP. IMAP4 supports access to the -mail store in both modes of operation—connected (online) and disconnected -(offline).

            Emails are generally sent to an email server that stores -received messages in the recipient's email mailbox. The user later retrieves -these messages with either a web browser or an email client that uses one -of a number of email retrieval protocols.

            Email clients using IMAP4 -generally stores messages on the server until the user explicitly deletes -them. This allows multiple clients to access the same mailbox. However, the -client may store local copies of the messages, but these are considered to -be a temporary cache; the server's store is authoritative.

            -
            Symbian platform implementation of IMAP4

            The Messaging -Application module has implemented all the functionality of standard IMAP4 -and conforms to RFC3501.

            -
            IMAP4 example

            For more details on implementing -the IMAP4 MTM functions, see example -code.

            -             -IMAP4 MTM - + + + + + +IMAP4 +Concepts +

            This section describes the Internet Message Access Protocol (IMAP4) and +its implementation on the Symbian platform.

            +
            IMAP4 protocol

            IMAP4 +is one of the most common Internet standard protocols for retrieving emails. +It is an application layer Internet protocol operating on port 143 that allows +a local client to access email on a remote server.

            The current version, +IMAP version 4 revision 1 (IMAP4rev1), is defined by RFC 3501. Eariler, IMAP4 +was called Internet Mail Access Protocol, Interactive Mail Access Protocol +(RFC 1064), and Interim Mail Access Protocol.

            The default port for +IMAP4 to download messages is 143, but if a client establishes a secure connection +(over SSL or TLS) for IMAP4 to download message, the port is 993.

            Most +email clients support either POP3 or IMAP to retrieve messages; however, few +Internet Service Providers (ISPs) support IMAP. IMAP4 supports access to the +mail store in both modes of operation—connected (online) and disconnected +(offline).

            Emails are generally sent to an email server that stores +received messages in the recipient's email mailbox. The user later retrieves +these messages with either a web browser or an email client that uses one +of a number of email retrieval protocols.

            Email clients using IMAP4 +generally stores messages on the server until the user explicitly deletes +them. This allows multiple clients to access the same mailbox. However, the +client may store local copies of the messages, but these are considered to +be a temporary cache; the server's store is authoritative.

            +
            Symbian platform implementation of IMAP4

            The Messaging +Application module has implemented all the functionality of standard IMAP4 +and conforms to RFC3501.

            +
            IMAP4 example

            For more details on implementing +the IMAP4 MTM functions, see example +code.

            +             +IMAP4 MTM +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4303DBDB-3F67-54E6-AB24-5E1871053ED9_d0e15936_href.png Binary file Symbian3/SDK/Source/GUID-4303DBDB-3F67-54E6-AB24-5E1871053ED9_d0e15936_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4303DBDB-3F67-54E6-AB24-5E1871053ED9_d0e46282_href.png Binary file Symbian3/SDK/Source/GUID-4303DBDB-3F67-54E6-AB24-5E1871053ED9_d0e46282_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4303DBDB-3F67-54E6-AB24-5E1871053ED9_d0e51838_href.png Binary file Symbian3/SDK/Source/GUID-4303DBDB-3F67-54E6-AB24-5E1871053ED9_d0e51838_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-431119D1-1B55-4503-905E-6E290FA241CE-master.png Binary file Symbian3/SDK/Source/GUID-431119D1-1B55-4503-905E-6E290FA241CE-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-431119D1-1B55-4503-905E-6E290FA241CE_d0e63537_href.png Binary file Symbian3/SDK/Source/GUID-431119D1-1B55-4503-905E-6E290FA241CE_d0e63537_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-433698C1-C97D-5317-83C0-71A029E362E6_d0e303218_href.png Binary file Symbian3/SDK/Source/GUID-433698C1-C97D-5317-83C0-71A029E362E6_d0e303218_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-433698C1-C97D-5317-83C0-71A029E362E6_d0e309233_href.png Binary file Symbian3/SDK/Source/GUID-433698C1-C97D-5317-83C0-71A029E362E6_d0e309233_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-434F2412-59A1-4BCB-885D-5E708EAA6AB6.dita --- a/Symbian3/SDK/Source/GUID-434F2412-59A1-4BCB-885D-5E708EAA6AB6.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-434F2412-59A1-4BCB-885D-5E708EAA6AB6.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,23 +1,24 @@ - - - - - -Grid -query -

            Instead of a list, a grid can be used in a query. The Grid query function -is otherwise identical to a List -query.

            - -Grid query - - -
            Using grid queries in -C++ applications

            For implementation information, see Queries.

            + + + + + +Grid +query +

            Instead of a list, a grid can be used in a query. The Grid query function +is otherwise identical to a List +query.

            + +Grid query + + +
            Using +grid queries in applications

            For implementation information, +see Queries.

             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4352F2A7-2498-40AA-A335-4A8407497976.dita --- a/Symbian3/SDK/Source/GUID-4352F2A7-2498-40AA-A335-4A8407497976.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,27 +0,0 @@ - - - - - -Basic -interaction style -

            The basic interaction principles of the Symbian platform in the bottom -softkey style remain similar to the legacy Symbian UI style. This applies -to keypad functions, typical functions of the keys, navigation (both in terms -of hierarchies, and the scroll and select behavior), and so on.

            -

            As in the legacy UI style, the scrolling in the software follows the visual -direction of the respective scroll keys.

            -

            Similarly, other visual UI controls of scroll keys rotate together with -the UI. For example, this applies to the Volume Control component which is -vertical also in landscape mode.

            -

            In some product concepts, using the Numeric keys and some of the -navigation keys may be disabled while in the bottom softkey mode. This may -mean that some applications or features (such as editing) are not usable at -all in one of the modes.

             -             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4381EA7F-BE75-5B43-BE97-C97D71D04377_d0e332416_href.png Binary file Symbian3/SDK/Source/GUID-4381EA7F-BE75-5B43-BE97-C97D71D04377_d0e332416_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4381EA7F-BE75-5B43-BE97-C97D71D04377_d0e338573_href.png Binary file Symbian3/SDK/Source/GUID-4381EA7F-BE75-5B43-BE97-C97D71D04377_d0e338573_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-43A701DC-24FF-44F7-850B-AA6A79235B56_d0e36160_href.png Binary file Symbian3/SDK/Source/GUID-43A701DC-24FF-44F7-850B-AA6A79235B56_d0e36160_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-43A701DC-24FF-44F7-850B-AA6A79235B56_d0e36212_href.png Binary file Symbian3/SDK/Source/GUID-43A701DC-24FF-44F7-850B-AA6A79235B56_d0e36212_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-43A701DC-24FF-44F7-850B-AA6A79235B56_d0e41727_href.png Binary file Symbian3/SDK/Source/GUID-43A701DC-24FF-44F7-850B-AA6A79235B56_d0e41727_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-43A701DC-24FF-44F7-850B-AA6A79235B56_d0e41779_href.png Binary file Symbian3/SDK/Source/GUID-43A701DC-24FF-44F7-850B-AA6A79235B56_d0e41779_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4407F7CA-6D08-4B9C-A0CE-37AFC8BB20B2.dita --- a/Symbian3/SDK/Source/GUID-4407F7CA-6D08-4B9C-A0CE-37AFC8BB20B2.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-4407F7CA-6D08-4B9C-A0CE-37AFC8BB20B2.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,40 +1,40 @@ - - - - - -CEikListBox -

            CEikListBox provides flags that have to -be set for every list or grid that requires specific touch-related functionality.

            -Touch-related -flags in CEikListBox - - - -

            Flag

             -

            Functionality

             -             - - - -

            EAknListBoxStylusMultiselectionList

             -

            It enables touch for multi-selection lists.

             -             - -

            EAknListBoxStylusMarkableList

             -

            It enables touch for markable lists or markable grids (CAknGrid).

             -             - -

            EAknListBoxItemSpecificMenuDisabled

            -

            This flag has been introduced for single-click. It disables item-specific -menu for single-click.

             -             - - + + + + + +Touch support in lists +

            CEikListBox provides flags that have to be set +for every list or grid that requires specific touch-related functionality.

            +
            Touch-related +flags in CEikListBox + + + +

            Flag

             +

            Functionality

             +             + + + +

            EAknListBoxStylusMultiselectionList

             +

            It enables touch for multi-selection lists.

             +             + +

            EAknListBoxStylusMarkableList

             +

            It enables touch for markable lists or markable grids (CAknGrid).

             +             + +

            EAknListBoxItemSpecificMenuDisabled

            +

            This flag has been introduced for single tap. It disables +item-specific menu for single tap.

             +             + +
             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-442D216B-117E-538C-A51F-0775BF37673E_d0e244320_href.png Binary file Symbian3/SDK/Source/GUID-442D216B-117E-538C-A51F-0775BF37673E_d0e244320_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-442D216B-117E-538C-A51F-0775BF37673E_d0e248057_href.png Binary file Symbian3/SDK/Source/GUID-442D216B-117E-538C-A51F-0775BF37673E_d0e248057_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-44347376-702D-5648-8938-EB55AFA329EC_d0e406701_href.png Binary file Symbian3/SDK/Source/GUID-44347376-702D-5648-8938-EB55AFA329EC_d0e406701_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-44347376-702D-5648-8938-EB55AFA329EC_d0e406863_href.png Binary file Symbian3/SDK/Source/GUID-44347376-702D-5648-8938-EB55AFA329EC_d0e406863_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-44ADB485-69C2-5557-AB95-3B6D20870F73_d0e115760_href.png Binary file Symbian3/SDK/Source/GUID-44ADB485-69C2-5557-AB95-3B6D20870F73_d0e115760_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-44ADB485-69C2-5557-AB95-3B6D20870F73_d0e122298_href.png Binary file Symbian3/SDK/Source/GUID-44ADB485-69C2-5557-AB95-3B6D20870F73_d0e122298_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-44B0C58F-B938-4F69-B80A-1EB632EFD434.ditamap --- a/Symbian3/SDK/Source/GUID-44B0C58F-B938-4F69-B80A-1EB632EFD434.ditamap Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,6561 +0,0 @@ - - - - - - - -Symbian Developer Library for Application Developers -Symbian Developer Library for Application Developers - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Touch UI support -From S60 5th Edition, all GUI applications must work with devices -that have touch screens. This section describes how to use UI components with -touch support, and how applications can receive touch related events. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -API specifications -This section provides information on using the touch UI component -and tactile feedback APIs. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -API Specifications - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-44FDDA27-1A5D-42B5-8DE0-D9E88EB75C93.dita --- a/Symbian3/SDK/Source/GUID-44FDDA27-1A5D-42B5-8DE0-D9E88EB75C93.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-44FDDA27-1A5D-42B5-8DE0-D9E88EB75C93.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,74 +1,74 @@ - - - - - -Querying -for Sensor ChannelsYou can retrieve a list of sensor channels that are available for -a particular sensor type. Once you get the list of sensor channels that are -active, you can perform any required operations such as configuring sensor -channel properties, controlling sensor channels and so on. - -Create an instance -of TSensrvChannelInfo and set the required channel type as -the search criteria. For example, to query for all double tapping channels -provided by accelerometer sensor, set the channel type as KSensrvChannelTypeIdAccelerometerDoubleTappingData. -TSensrvChannelInfo channelInfo; -channelInfo.iChannelType = KSensrvChannelTypeIdAccelerometerDoubleTappingData; - -Create an instance -of CSensrvChannelFinder class and use the CSensrvChannelFinder::FindChannelsL() function -to query for available sensor channels. -CSensrvChannelFinder* finder = CSensrvChannelFinder::NewL(); -finder->FindChannelsL(channelList, searchParameters); - -Create an instance -of RSensrvChannelInfoList to store the list of sensor channels. -RSensrvChannelInfoList channelInfoList; - - -

            The channelInfoList contains -all the double tapping channels that are found. If several matching channels -are found, you can select the required channel by examining the content of -channel information objects inside channelInfoList.

            -             -

            This following code shows how to find double tapping channels -for accelerometer sensor:

            ..... -...... -/Construct a channel finder. - CSensrvChannelFinder* channelFinder; - channelFinder = CSensrvChannelFinder::NewL(); - CleanupStack::PushL( channelFinder ); - - // to store list of found channels. - RSensrvChannelInfoList channelInfoList; - - //Create and fill channel search criteria. - //In this example double tapping channel is searched. - TSensrvChannelInfo channelInfo; - channelInfo.iChannelType = KSensrvChannelTypeIdAccelerometerDoubleTappingData; - - //Find the double tapping channel - channelFinder->FindChannelsL( channelInfoList, channelInfo ); - - CleanupStack::PopAndDestroy( channelFinder ); // finder not needed any more - - if( channelInfoList.Count() != 1 ) - { - //The device does not support double tapping channel or - //there are several double tapping channels. - } - else - { - //double tapping channel found - } -..... -.... -             + + + + + +Querying +for Sensor ChannelsYou can retrieve a list of sensor channels that are available for +a particular sensor type. Once you get the list of sensor channels that are +active, you can perform any required operations such as configuring sensor +channel properties, controlling sensor channels and so on. + +Create an instance +of TSensrvChannelInfo and set the required channel type as +the search criteria. For example, to query for all double tapping channels +provided by accelerometer sensor, set the channel type as KSensrvChannelTypeIdAccelerometerDoubleTappingData. +TSensrvChannelInfo channelInfo; +channelInfo.iChannelType = KSensrvChannelTypeIdAccelerometerDoubleTappingData; + +Create an instance +of CSensrvChannelFinder class and use the CSensrvChannelFinder::FindChannelsL() function +to query for available sensor channels. +CSensrvChannelFinder* finder = CSensrvChannelFinder::NewL(); +finder->FindChannelsL(channelList, searchParameters); + +Create an instance +of RSensrvChannelInfoList to store the list of sensor channels. +RSensrvChannelInfoList channelInfoList; + + +

            The channelInfoList contains +all the double tapping channels that are found. If several matching channels +are found, you can select the required channel by examining the content of +channel information objects inside channelInfoList.

            +             +

            This following code shows how to find double tapping channels +for accelerometer sensor:

            ..... +...... +/Construct a channel finder. + CSensrvChannelFinder* channelFinder; + channelFinder = CSensrvChannelFinder::NewL(); + CleanupStack::PushL( channelFinder ); + + // to store list of found channels. + RSensrvChannelInfoList channelInfoList; + + //Create and fill channel search criteria. + //In this example double tapping channel is searched. + TSensrvChannelInfo channelInfo; + channelInfo.iChannelType = KSensrvChannelTypeIdAccelerometerDoubleTappingData; + + //Find the double tapping channel + channelFinder->FindChannelsL( channelInfoList, channelInfo ); + + CleanupStack::PopAndDestroy( channelFinder ); // finder not needed any more + + if( channelInfoList.Count() != 1 ) + { + //The device does not support double tapping channel or + //there are several double tapping channels. + } + else + { + //double tapping channel found + } +..... +.... +                         \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-45D4F2D1-A433-4289-A627-D0ECD97489DD_d0e64430_href.png Binary file Symbian3/SDK/Source/GUID-45D4F2D1-A433-4289-A627-D0ECD97489DD_d0e64430_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-45D4F2D1-A433-4289-A627-D0ECD97489DD_d0e64836_href.png Binary file Symbian3/SDK/Source/GUID-45D4F2D1-A433-4289-A627-D0ECD97489DD_d0e64836_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-45DD08DB-FCB3-5546-91B4-25868C8ABAE4_d0e115768_href.png Binary file Symbian3/SDK/Source/GUID-45DD08DB-FCB3-5546-91B4-25868C8ABAE4_d0e115768_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-45DD08DB-FCB3-5546-91B4-25868C8ABAE4_d0e122306_href.png Binary file Symbian3/SDK/Source/GUID-45DD08DB-FCB3-5546-91B4-25868C8ABAE4_d0e122306_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-46040A24-92C3-4B0B-88CC-BDD8DDA8F27C_d0e41397_href.png Binary file Symbian3/SDK/Source/GUID-46040A24-92C3-4B0B-88CC-BDD8DDA8F27C_d0e41397_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-46040A24-92C3-4B0B-88CC-BDD8DDA8F27C_d0e46954_href.png Binary file Symbian3/SDK/Source/GUID-46040A24-92C3-4B0B-88CC-BDD8DDA8F27C_d0e46954_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-46121F24-AB53-5B44-A082-EF13A72EB7FF.dita --- a/Symbian3/SDK/Source/GUID-46121F24-AB53-5B44-A082-EF13A72EB7FF.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-46121F24-AB53-5B44-A082-EF13A72EB7FF.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,52 +1,52 @@ - - - - - -Writing -a ConverterFile Converter Framework specifies a plug-in interface for file -format converters. Clients can convert from one data type to another using -file format converters, for example, HTML files to Word documents. - -
            Introduction

            The File Converter Framework provides -the following:

              -

            • An abstract interface -which all converters must implement.

              • -

            • APIs to list and search -for converters.

              • -

            • APIs to determine the -MIME types supported by the available converters.

              • -

            • An observer interface -through which the progress and success or failure of the conversion can be -reported.

              • -

            Converters are implemented as ECom -plug-ins, each of which can implement one or more converters. Like -all binaries, the plug-ins are installed in the \sys\bin\ directory. -Each plug-in must provide two resource files: one contains a CONARC_RESOURCE_FILE resource -to describe the converters implemented in the DLL, and the other is a registration -resource file required by the ECom framework.

            The following UML diagram -shows the key elements of the converter architecture, including an example -client and an example converter DLL that provides two converters, myConverter1 and myConverter2.

            - File Converter architecture - -
            -
            Procedure
              -

            1. Write -an interface implementation for a converter.

              2. -

            2. Implement -the ECom framework code.

              3. -

            3. Write -a resource file.

              4. -

            4. Write -a converter DLL project file.

              5. -
            -             -File Converter -Framework Overview + + + + + +Writing +a ConverterFile Converter Framework specifies a plug-in interface for file +format converters. Clients can convert from one data type to another using +file format converters, for example, HTML files to Word documents. + +
            Introduction

            The File Converter Framework provides +the following:

              +

            • An abstract interface +which all converters must implement.

              • +

            • APIs to list and search +for converters.

              • +

            • APIs to determine the +MIME types supported by the available converters.

              • +

            • An observer interface +through which the progress and success or failure of the conversion can be +reported.

              • +

            Converters are implemented as ECom +plug-ins, each of which can implement one or more converters. Like +all binaries, the plug-ins are installed in the \sys\bin\ directory. +Each plug-in must provide two resource files: one contains a CONARC_RESOURCE_FILE resource +to describe the converters implemented in the DLL, and the other is a registration +resource file required by the ECom framework.

            The following UML diagram +shows the key elements of the converter architecture, including an example +client and an example converter DLL that provides two converters, myConverter1 and myConverter2.

            + File Converter architecture + +
            +
            Procedure
              +

            1. Write +an interface implementation for a converter.

              2. +

            2. Implement +the ECom framework code.

              3. +

            3. Write +a resource file.

              4. +

            4. Write +a converter DLL project file.

              5. +
            +             +File Converter +Framework Overview             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4616CCC9-7BD3-5D91-873A-6027167329ED_d0e184851_href.png Binary file Symbian3/SDK/Source/GUID-4616CCC9-7BD3-5D91-873A-6027167329ED_d0e184851_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4616CCC9-7BD3-5D91-873A-6027167329ED_d0e191447_href.png Binary file Symbian3/SDK/Source/GUID-4616CCC9-7BD3-5D91-873A-6027167329ED_d0e191447_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-465F0DEF-935F-46D6-B711-A4D362DAD619.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-465F0DEF-935F-46D6-B711-A4D362DAD619.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,16 @@ + + + + + +Bearer +ManagementThe Bearer Management collection offers logic for +selection and re-selection (roaming) of an IP connection, functional implementation +of Mobility API, Contention management and error management related to IP +connection. \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-46673FC4-ADA9-59D1-A743-B4784425D240_d0e79385_href.png Binary file Symbian3/SDK/Source/GUID-46673FC4-ADA9-59D1-A743-B4784425D240_d0e79385_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-46673FC4-ADA9-59D1-A743-B4784425D240_d0e86097_href.png Binary file Symbian3/SDK/Source/GUID-46673FC4-ADA9-59D1-A743-B4784425D240_d0e86097_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-46A91D57-7864-53AD-903C-B978B0C61DAD_d0e336132_href.jpg Binary file Symbian3/SDK/Source/GUID-46A91D57-7864-53AD-903C-B978B0C61DAD_d0e336132_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-46A91D57-7864-53AD-903C-B978B0C61DAD_d0e342329_href.jpg Binary file Symbian3/SDK/Source/GUID-46A91D57-7864-53AD-903C-B978B0C61DAD_d0e342329_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-46E27DAF-B72D-5A86-91BB-1B3C0788C6A5_d0e341486_href.png Binary file Symbian3/SDK/Source/GUID-46E27DAF-B72D-5A86-91BB-1B3C0788C6A5_d0e341486_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-46E27DAF-B72D-5A86-91BB-1B3C0788C6A5_d0e347683_href.png Binary file Symbian3/SDK/Source/GUID-46E27DAF-B72D-5A86-91BB-1B3C0788C6A5_d0e347683_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-470FAFE8-2246-5E91-9F01-6CC95F975E54_d0e304255_href.jpg Binary file Symbian3/SDK/Source/GUID-470FAFE8-2246-5E91-9F01-6CC95F975E54_d0e304255_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-470FAFE8-2246-5E91-9F01-6CC95F975E54_d0e310270_href.jpg Binary file Symbian3/SDK/Source/GUID-470FAFE8-2246-5E91-9F01-6CC95F975E54_d0e310270_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-47511301-DFF9-52B0-9602-DD9D293D3044_d0e230623_href.png Binary file Symbian3/SDK/Source/GUID-47511301-DFF9-52B0-9602-DD9D293D3044_d0e230623_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-47511301-DFF9-52B0-9602-DD9D293D3044_d0e234360_href.png Binary file Symbian3/SDK/Source/GUID-47511301-DFF9-52B0-9602-DD9D293D3044_d0e234360_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-47587124-66D8-5128-BDBB-AF190E67CAF5_d0e201499_href.png Binary file Symbian3/SDK/Source/GUID-47587124-66D8-5128-BDBB-AF190E67CAF5_d0e201499_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-47587124-66D8-5128-BDBB-AF190E67CAF5_d0e206507_href.png Binary file Symbian3/SDK/Source/GUID-47587124-66D8-5128-BDBB-AF190E67CAF5_d0e206507_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-47851718-8DCA-57F5-8520-7044048A5852.dita --- a/Symbian3/SDK/Source/GUID-47851718-8DCA-57F5-8520-7044048A5852.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-47851718-8DCA-57F5-8520-7044048A5852.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,13 +1,24 @@ - - - - - -Graphics Example CodeExample code for the Graphics package. Font and Bitmap Server example code Graphics Device Interface example code Windowing example - code \ No newline at end of file + + + + + +Graphics Example +CodeExample code for the Graphics package. + + +Font and +Bitmap Server example code +Graphics +Device Interface example code +Windowing +example code +Coverflow +Example code + \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-479133EB-1154-554E-8CEA-C61EDA747B69_d0e76227_href.png Binary file Symbian3/SDK/Source/GUID-479133EB-1154-554E-8CEA-C61EDA747B69_d0e76227_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-479133EB-1154-554E-8CEA-C61EDA747B69_d0e82939_href.png Binary file Symbian3/SDK/Source/GUID-479133EB-1154-554E-8CEA-C61EDA747B69_d0e82939_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-47AA7F26-FF3F-4FEE-BBB4-F4E8A8E0E335_d0e70851_href.png Binary file Symbian3/SDK/Source/GUID-47AA7F26-FF3F-4FEE-BBB4-F4E8A8E0E335_d0e70851_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-47AA7F26-FF3F-4FEE-BBB4-F4E8A8E0E335_d0e75884_href.png Binary file Symbian3/SDK/Source/GUID-47AA7F26-FF3F-4FEE-BBB4-F4E8A8E0E335_d0e75884_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-47EF98E9-7833-5E94-ADFF-198401463A8C_d0e76342_href.png Binary file Symbian3/SDK/Source/GUID-47EF98E9-7833-5E94-ADFF-198401463A8C_d0e76342_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-47EF98E9-7833-5E94-ADFF-198401463A8C_d0e83054_href.png Binary file Symbian3/SDK/Source/GUID-47EF98E9-7833-5E94-ADFF-198401463A8C_d0e83054_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4820CA37-982D-57BC-8829-498192801B1E.dita --- a/Symbian3/SDK/Source/GUID-4820CA37-982D-57BC-8829-498192801B1E.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-4820CA37-982D-57BC-8829-498192801B1E.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,26 +1,24 @@ - - - - - -ReadData: -Reading from a Resource File -
            Download

            Click on the following link to download -the example: ReadData.zip

            Download some additional files required -by the example: CommonFramework.zip and CommonFile.zip

            Click: browse to view the example code.

            View the additional -files: browse CommonFramework and browse CommonFile
            -
            Description

            ReadData is an -example of how to load data from resource files into a class. It loads the -resource identified as resource FIRST from the resource file. This is a simple -resource of type DATA. The example constructs a CResData object -to hold the individual items corresponding to the items in a DATA structure.

            The CResData object -can also display the individual items at the test console. All WORD, BYTE -and LONG data is interpreted as signed values.

            -
            Class Summary

            RResourceFile

            TTResourceReader

            + + + + + +ReadData: Reading from a Resource File +
            Download

            Click on the following link to +download the example: ReadData.zip

            Download some additional files +required by the example: CommonFramework.zip and CommonFile.zip

            Click: browse to view the example code.

            View the +additional files: browse CommonFramework and browse CommonFile
            +
            Description

            ReadData is an example of how to load data from resource files into a class. +It loads the resource identified as resource FIRST from the resource +file. This is a simple resource of type DATA. The example constructs +a CResData object to hold the individual items corresponding +to the items in a DATA structure.

            The CResData object can also display the individual items at the test console. +All WORD, BYTE and LONG data is interpreted as signed values.

            +
            Class Summary

            RResourceFile

            TTResourceReader

             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-48363190-6FFB-4230-84B4-2E521EA51365.dita --- a/Symbian3/SDK/Source/GUID-48363190-6FFB-4230-84B4-2E521EA51365.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-48363190-6FFB-4230-84B4-2E521EA51365.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,112 +1,112 @@ - - - - - -Using -menu sections in menu bar resource statements -Menu sections in an Options menu -

            The use of menu sections provides a means of combining menu bar resource -declarations in Options menus. One example of how this could be used -would be an application with two views. Three MENU_BAR resources -could be defined as follows:

            -
              -

            • an application menu section, which would be common to both -views

              • -

            • a menu section for view 1, which would contain options items -unique to this view

              • -

            • a menu section for view 2, which would contain options items -unique to this view

              • -
            -
            Combining menu -sections -

            The menu sections that are combined for an Options menu are defined -in the MENU_BAR resource. This resource lists all the -sections that will be combined to form the menu. The menu sections are combined -from bottom to top (for example, system sections such as 'Edit' go at the -bottom of the menu while context sections such as 'Open' go at the top of -the menu). A menu bar is defined as follows:

            - -RESOURCE MENU_BAR r_menuapp_menu_bar - { - titles = - { - MENU_TITLE { menu_pane = r_system_menu; }, - MENU_TITLE { menu_pane = r_app_menu; }, - MENU_TITLE { menu_pane = r_view1_options_menu; }, - MENU_TITLE { menu_pane = r_context1_menu; } - }; - } - -

            The default MENU_BAR resource is declared in EIK_APP_INFO or AVKON_VIEW

            -
            -
            Changing menu -sections -

            You can use the following method to change the MENU_BAR resource -that is used by the application to change the menu sections at any time within -the application:

            -iEikonEnv->AppUiFactory()->MenuBar()-> - SetMenuTitleResourceId(MENU_BAR_RESOURCE_ID); - -

            This sets the whole menu bar and should be performed every time one -of the sections needs to change its contents. Therefore, you should define -as many MENU_BAR resources as there are possible combinations -of menu sections. That is, a menu bar should be defined for each combination -of view and context options. Note also that if view architecture is used, -and the view’s own menu system is in use, it is this menu bar’s contents that -need switching, as follows:

            -iMyView->MenuBar()-> - SetMenuTitleResourceId(MENU_BAR_RESOURCE_ID); - -
            -
            Changing menu -items in menu sections -

            Individual menu items in a menu section may be changed whenever the -menu is displayed. This allows the application to show and hide (or remove -and add) menu items in response to the application state. In the traditional -Symbian OS UI architecture, you should override MEikAutoMenuObserver::DynInitMenuPaneL() in the UI -controller. In the View -architecture, you should override MEikAutoMenuObserver::DynInitMenuPaneL() in -the view controller. An example of such an override is as follows:

            -void CMyAppUi::DynInitMenuPaneL(TInt aResourceId, - CEikMenuPane* aMenuPane) - { - if(aResourceId != R_SYSTEM_MENU_PANE) - return; // in this example only interest in system - // pane - - // First hide all - aMenuPane->SetItemDimmed(ECmdCut, ETrue); - aMenuPane->SetItemDimmed(ECmdCopy, ETrue); - aMenuPane->SetItemDimmed(ECmdPaste, ETrue); - - // Show according to application state - if(...) - { - aMenuPane->SetItemDimmed(ECmdCut, EFalse); - aMenuPane->SetItemDimmed(ECmdCopy, EFalse); - } - else - { - aMenuPane->SetItemDimmed(ECmdPaste, EFalse); - } - } - -

            This method is called by the framework after each of the sections has -been added to the menu, and is called with the resource ID of the section -that has just been added and the menu pane object that is being built.

            -

            You can also override MEikAutoMenuObserver::DynInitMenuBarL(TInt aResourceId, CEikMenuBar* aMenuBar) in -the UI -controller or view -controller, depending on your UI architecture. This gets called before -any sections are added to the menu, and can be used to dynamically change -the sections that will be added to the menu. This could be used to change -the resource ID of the context menu section for a certain application state.

            -
            + + + + + +Using +menu sections in menu bar resource statements +Menu sections in an Options menu +

            The use of menu sections provides a means of combining menu bar resource +declarations in Options menus. One example of how this could be used +would be an application with two views. Three MENU_BAR resources +could be defined as follows:

            +
              +

            • an application menu section, which would be common to both +views

              • +

            • a menu section for view 1, which would contain options items +unique to this view

              • +

            • a menu section for view 2, which would contain options items +unique to this view

              • +
            +
            Combining menu +sections +

            The menu sections that are combined for an Options menu are defined +in the MENU_BAR resource. This resource lists all the +sections that will be combined to form the menu. The menu sections are combined +from bottom to top (for example, system sections such as 'Edit' go at the +bottom of the menu while context sections such as 'Open' go at the top of +the menu). A menu bar is defined as follows:

            + +RESOURCE MENU_BAR r_menuapp_menu_bar + { + titles = + { + MENU_TITLE { menu_pane = r_system_menu; }, + MENU_TITLE { menu_pane = r_app_menu; }, + MENU_TITLE { menu_pane = r_view1_options_menu; }, + MENU_TITLE { menu_pane = r_context1_menu; } + }; + } + +

            The default MENU_BAR resource is declared in EIK_APP_INFO or AVKON_VIEW

            +
            +
            Changing menu +sections +

            You can use the following method to change the MENU_BAR resource +that is used by the application to change the menu sections at any time within +the application:

            +iEikonEnv->AppUiFactory()->MenuBar()-> + SetMenuTitleResourceId(MENU_BAR_RESOURCE_ID); + +

            This sets the whole menu bar and should be performed every time one +of the sections needs to change its contents. Therefore, you should define +as many MENU_BAR resources as there are possible combinations +of menu sections. That is, a menu bar should be defined for each combination +of view and context options. Note also that if view architecture is used, +and the view’s own menu system is in use, it is this menu bar’s contents that +need switching, as follows:

            +iMyView->MenuBar()-> + SetMenuTitleResourceId(MENU_BAR_RESOURCE_ID); + +
            +
            Changing menu +items in menu sections +

            Individual menu items in a menu section may be changed whenever the +menu is displayed. This allows the application to show and hide (or remove +and add) menu items in response to the application state. In the traditional +Symbian OS UI architecture, you should override MEikAutoMenuObserver::DynInitMenuPaneL() in the UI +controller. In the View +architecture, you should override MEikAutoMenuObserver::DynInitMenuPaneL() in +the view controller. An example of such an override is as follows:

            +void CMyAppUi::DynInitMenuPaneL(TInt aResourceId, + CEikMenuPane* aMenuPane) + { + if(aResourceId != R_SYSTEM_MENU_PANE) + return; // in this example only interest in system + // pane + + // First hide all + aMenuPane->SetItemDimmed(ECmdCut, ETrue); + aMenuPane->SetItemDimmed(ECmdCopy, ETrue); + aMenuPane->SetItemDimmed(ECmdPaste, ETrue); + + // Show according to application state + if(...) + { + aMenuPane->SetItemDimmed(ECmdCut, EFalse); + aMenuPane->SetItemDimmed(ECmdCopy, EFalse); + } + else + { + aMenuPane->SetItemDimmed(ECmdPaste, EFalse); + } + } + +

            This method is called by the framework after each of the sections has +been added to the menu, and is called with the resource ID of the section +that has just been added and the menu pane object that is being built.

            +

            You can also override MEikAutoMenuObserver::DynInitMenuBarL(TInt aResourceId, CEikMenuBar* aMenuBar) in +the UI +controller or view +controller, depending on your UI architecture. This gets called before +any sections are added to the menu, and can be used to dynamically change +the sections that will be added to the menu. This could be used to change +the resource ID of the context menu section for a certain application state.

            +
             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4841AEDF-D22C-57D0-872D-7BD8B6A29CF5.dita --- a/Symbian3/SDK/Source/GUID-4841AEDF-D22C-57D0-872D-7BD8B6A29CF5.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-4841AEDF-D22C-57D0-872D-7BD8B6A29CF5.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,14 +1,14 @@ - - - - - -What are Tiers?This topic describes the concepts of a Tier and a Tier Manager in the Communications Framework.

            A Tier is a group of Access Points (APs) related to one or more technologies sharing the same Selection and Availability monitoring logic. The Tier Manager provides the means for an application to connect to a communication service to send and receive data, or to check the current status of a communication service.

            When an application needs to contruct a stack either to request availability on a particular service or to establish a connection with a remote device or service, it will explicitly select a specific Tier Manager at the top of the stack to define the service. If the application does not explicitly select a specific Tier Manager, the default TM will be used. The selection process and connection preferences will define how the rest of the stack is constructed. Each Tier Manager is responsible for selecting the most appropriate AP from a range of alternatives and may also pass up availability information in some cases, depending on the Tier Manager.

            When a higher Layer wants to bind to a lower layer, it uses the supplied selection criteria to select a Tier and request a specific AP. Once the Tier has returned an AP and the stack has been bound together, the upper layer queries the availability to see if it is possible to connect at that moment.

            On a device there will be multiple Tier Managers, each responsible for a separate technology or group of technologies. Each Tier Manager will have distinct selection and availability logic and other technology specific algorithms.

            A single Tier Manager will be responsible for multiple instances of a layer, i.e. multiple APs of the same type. So the Wi-Fi Tier Manager would allow connection to multiple Wi-Fi Access Points, a Telephony Tier Manager will be responsible for connections to different APNs.

            Tier Managers (CTierManagerBase) are Comms Framework nodes created by their respective factories. Tier Managers respond to Node Messages sent across the Transport, in a similar way to Stack Nodes.

            The Tier Manager keeps track of the current Access Points that have been created through a query API, see Availability below. The Tier Manager responds to messages sent when an Access Point changes state. For example, when a Bearer stops being available, a message will be sent to the Tier Manager.

            In the diagram below, two Tier Managers are shown. The diagram shows that one Tier Manager can be responsible for more than one layer in a Stack.

            - Communications Architecture showing Tier Managers -

            When a client application wants to start a connection it will request an AP by calling RConnection::Open() with a Tier Identifier (the iTag field in the Tier table). This will cause a stack of APs that meet the selection and availability criteria to be returned. When the RConnection:Start() occurs, a specific AP will be selected at the top layer and the matching CPRs, SCPRs and Data Flows in each of the layers for the connection will be started (unless the connection is already active and this new RConnection can share the open connection).

            Configuration

            The configuration for a Tier Manager is held in a number of Comms Database tables: most importantly the Tier table, and the Access Point table.

            The Tier Table contains the ECom ID of the loaded module that processes Tier Manager requests, and the Default Access Point. The Default Access Point is the one used if the client makes no special requests, see Explicit and Implicit Selection below.

            The Access Point Table contains the identifiers of the MCPR, CPR and SCPR for this layer, the selection policy, the protocol, the Tier ID and a protocol identifier.

            It is recommended that all connections should specify a Tier in the RConnection::Start(), but for backward compatability, RConnection::Start() without a Tier identifier will use the Default Tier which is stored in the GlobalSettings table. Important note: for legacy code to function correctly, the Default Tier must be the "Network " Tier. See Explicit and Implicit Selection below for more information.

            Usage

            Selection

            A Tier Manager uses selection to decide which Access Points can be used for a connection. A top-level Tier Manager responds to selection requests that originate from RConnection or RConnectionServ.

            Selection selects a stack of APs that may be used to provide a service. The result is a stack or inverted tree showing potential APs at each layer. Remember that a higher layer AP provides a service, but there may be several options at each lower layer for supporting that service (Wi-Fi, 3G telephony etc.). For example, when a client asks for a service to provide a data socket, the list returned will include all the available APs at each layer. The Tier Manager for each layer decides which AP to use.

            Explicit and Implicit Selection

            If Freeway/Mobility is required it is required that communications clients explicitly open an RConnection on an AP. and associate the RSocket with it. But to for legacy applications or connections that don't require mobility, Implicit Selection is supported which uses the Default Connection.

            Explicit Selection occurs when an application specifies the top-level Access Point when calling RConnection::Start() with a parameter bundle that specifies an AP. Explicit selection selects the top-level AP and joins this connection to the stack.

            Implicit selection occurs when a user calls RSocket::Open() on a socket that is not associated with any connection. Implicit selection will associate the socket with the Default Connection. Implicit selection also occurs when an RConnection::Start() is called without specifying an AP in the connection preferences.

            For Implicit Selection, only the top layer of the stack is created by the RSocket::Open(), the remainder of the layers are created when a Data Plane event occurs such as RSocket::Connect() or RSocket::Send().

            When the Data Plane activation event occurs:

            • if there is no bearer (no AP for the next layer in the stack), the Control Plane will finish the selection and start the selected connection.

            • if there is a bearer, the Data Plane states it has found a flow in the Layer below by protocol-specific means, for example IP routing table.

            Availability

            When a client application wants to monitor a technology or existing connection, it can call RConnectionServ::AccessPointStatusQuery() for an immediate status, or RConnectionServ::AccessPointNotification() to be informed of each status change. As the format of the query bundle is configurable by the MCPR, each technology can specify what information will be returned in a query or notification. For example, the query bundle could contain Wi-Fi hotspot availability, maximum data rate supported, costs etc.

            Layers Planes Nodes             \ No newline at end of file + + + + + +What are Tiers?This topic describes the concepts of a Tier and a Tier Manager in the Communications Framework.

            A Tier is a group of Access Points (APs) related to one or more technologies sharing the same Selection and Availability monitoring logic. The Tier Manager provides the means for an application to connect to a communication service to send and receive data, or to check the current status of a communication service.

            When an application needs to contruct a stack either to request availability on a particular service or to establish a connection with a remote device or service, it will explicitly select a specific Tier Manager at the top of the stack to define the service. If the application does not explicitly select a specific Tier Manager, the default TM will be used. The selection process and connection preferences will define how the rest of the stack is constructed. Each Tier Manager is responsible for selecting the most appropriate AP from a range of alternatives and may also pass up availability information in some cases, depending on the Tier Manager.

            When a higher Layer wants to bind to a lower layer, it uses the supplied selection criteria to select a Tier and request a specific AP. Once the Tier has returned an AP and the stack has been bound together, the upper layer queries the availability to see if it is possible to connect at that moment.

            On a device there will be multiple Tier Managers, each responsible for a separate technology or group of technologies. Each Tier Manager will have distinct selection and availability logic and other technology specific algorithms.

            A single Tier Manager will be responsible for multiple instances of a layer, i.e. multiple APs of the same type. So the Wi-Fi Tier Manager would allow connection to multiple Wi-Fi Access Points, a Telephony Tier Manager will be responsible for connections to different APNs.

            Tier Managers (CTierManagerBase) are Comms Framework nodes created by their respective factories. Tier Managers respond to Node Messages sent across the Transport, in a similar way to Stack Nodes.

            The Tier Manager keeps track of the current Access Points that have been created through a query API, see Availability below. The Tier Manager responds to messages sent when an Access Point changes state. For example, when a Bearer stops being available, a message will be sent to the Tier Manager.

            In the diagram below, two Tier Managers are shown. The diagram shows that one Tier Manager can be responsible for more than one layer in a Stack.

            + Communications Architecture showing Tier Managers +

            When a client application wants to start a connection it will request an AP by calling RConnection::Open() with a Tier Identifier (the iTag field in the Tier table). This will cause a stack of APs that meet the selection and availability criteria to be returned. When the RConnection:Start() occurs, a specific AP will be selected at the top layer and the matching CPRs, SCPRs and Data Flows in each of the layers for the connection will be started (unless the connection is already active and this new RConnection can share the open connection).

            Configuration

            The configuration for a Tier Manager is held in a number of Comms Database tables: most importantly the Tier table, and the Access Point table.

            The Tier Table contains the ECom ID of the loaded module that processes Tier Manager requests, and the Default Access Point. The Default Access Point is the one used if the client makes no special requests, see Explicit and Implicit Selection below.

            The Access Point Table contains the identifiers of the MCPR, CPR and SCPR for this layer, the selection policy, the protocol, the Tier ID and a protocol identifier.

            It is recommended that all connections should specify a Tier in the RConnection::Start(), but for backward compatability, RConnection::Start() without a Tier identifier will use the Default Tier which is stored in the GlobalSettings table. Important note: for legacy code to function correctly, the Default Tier must be the "Network " Tier. See Explicit and Implicit Selection below for more information.

            Usage

            Selection

            A Tier Manager uses selection to decide which Access Points can be used for a connection. A top-level Tier Manager responds to selection requests that originate from RConnection or RConnectionServ.

            Selection selects a stack of APs that may be used to provide a service. The result is a stack or inverted tree showing potential APs at each layer. Remember that a higher layer AP provides a service, but there may be several options at each lower layer for supporting that service (Wi-Fi, 3G telephony etc.). For example, when a client asks for a service to provide a data socket, the list returned will include all the available APs at each layer. The Tier Manager for each layer decides which AP to use.

            Explicit and Implicit Selection

            If Freeway/Mobility is required it is required that communications clients explicitly open an RConnection on an AP. and associate the RSocket with it. But to for legacy applications or connections that don't require mobility, Implicit Selection is supported which uses the Default Connection.

            Explicit Selection occurs when an application specifies the top-level Access Point when calling RConnection::Start() with a parameter bundle that specifies an AP. Explicit selection selects the top-level AP and joins this connection to the stack.

            Implicit selection occurs when a user calls RSocket::Open() on a socket that is not associated with any connection. Implicit selection will associate the socket with the Default Connection. Implicit selection also occurs when an RConnection::Start() is called without specifying an AP in the connection preferences.

            For Implicit Selection, only the top layer of the stack is created by the RSocket::Open(), the remainder of the layers are created when a Data Plane event occurs such as RSocket::Connect() or RSocket::Send().

            When the Data Plane activation event occurs:

            • if there is no bearer (no AP for the next layer in the stack), the Control Plane will finish the selection and start the selected connection.

            • if there is a bearer, the Data Plane states it has found a flow in the Layer below by protocol-specific means, for example IP routing table.

            Availability

            When a client application wants to monitor a technology or existing connection, it can call RConnectionServ::AccessPointStatusQuery() for an immediate status, or RConnectionServ::AccessPointNotification() to be informed of each status change. As the format of the query bundle is configurable by the MCPR, each technology can specify what information will be returned in a query or notification. For example, the query bundle could contain Wi-Fi hotspot availability, maximum data rate supported, costs etc.

            Layers Planes Nodes             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-48482288-B60B-477A-8E28-132F7CBE2C94.dita --- a/Symbian3/SDK/Source/GUID-48482288-B60B-477A-8E28-132F7CBE2C94.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-48482288-B60B-477A-8E28-132F7CBE2C94.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,41 +1,43 @@ - - - - - -Confirmation -query -

            A confirmation query requests the user to confirm an operation, or asks -a Yes-No-type of question. It can be used e.g. to make sure that the user -does not accidentally delete important information or start an operation which -cannot be cancelled.

            -

            The layout for a Confirmation query is the same as the note layout, with -an optional graphic item.

            -

            One or two softkey labels can be used. In case the query can cause two -different consequences, the positive choice (Yes) is placed on the -left softkey, and the negative one (No) on the right softkey. In pure -confirmations, only one way to proceed is possible, and the response text -(for example OK) is placed on the left softkey.

            -

            The Selection key always causes the same action as the left softkey.

            - -Confirmation query - - -

            Guidelines for designing Confirmation queries:

            -
              -

            • When designing the prompt text, make sure that the positive answer -is also a safe one. Users tend to proceed pressing the left softkey or the -Selection key without thinking too much.

              • -

            • Redundant Confirmation queries should be avoided. Do not add a Confirmation -query if there already are other forms of feedback, unless it is crucial that -the user gets a certain piece of information.

              • -
            -
            Using confirmation queries -in C++ applications

            For implementation information, see Queries.

            + + + + + +Confirmation +query +

            A confirmation query requests the user to confirm an operation, or asks +a Yes-No-type of question. It can be used e.g. to make sure that the user +does not accidentally delete important information or start an operation which +cannot be cancelled. A touch down and release on the query has no effect. +Confirmation query cannot be dismissed by tapping outside.

            +

            The layout for a Confirmation query is the same as the note layout, with +an optional graphic item.

            +

            One or two softkey labels can be used. In case the query can cause two +different consequences, the positive choice (Yes) is placed on the +left softkey, and the negative one (No) on the right softkey. In pure +confirmations, only one way to proceed is possible, and the response text +(for example OK) is placed on the left softkey.

            +

            The Selection key always causes the same action as the left softkey.

            + +Confirmation query + + +

            Guidelines for designing Confirmation queries:

            +
              +

            • When designing the prompt text, make sure that the positive answer +is also a safe one. Users tend to proceed pressing the left softkey or the +Selection key without thinking too much.

              • +

            • Redundant Confirmation queries should be avoided. Do not add a Confirmation +query if there already are other forms of feedback, unless it is crucial that +the user gets a certain piece of information.

              • +
            +
            Using +confirmation queries in applications

            For implementation +information, see Queries.

             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-488F24B1-DC9B-5A5B-8B0D-47A428B9AA3C_d0e322748_href.jpg Binary file Symbian3/SDK/Source/GUID-488F24B1-DC9B-5A5B-8B0D-47A428B9AA3C_d0e322748_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-488F24B1-DC9B-5A5B-8B0D-47A428B9AA3C_d0e328905_href.jpg Binary file Symbian3/SDK/Source/GUID-488F24B1-DC9B-5A5B-8B0D-47A428B9AA3C_d0e328905_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-48B61662-0A11-4356-9882-7523B04FFD96.dita --- a/Symbian3/SDK/Source/GUID-48B61662-0A11-4356-9882-7523B04FFD96.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-48B61662-0A11-4356-9882-7523B04FFD96.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,70 +1,70 @@ - - - - - -Changing -PassphraseThis section explains how to change the passphrase. -

            The following steps explain the process of changing the passphrase:

             - -Create a file system -session using an RFs object. - - -Create an object of type CUnifiedKeyStore using CUnifiedKeyStore::NewL() or CUnifiedKeyStore::NewLC(). - - -Initialize the member functions and keystore using the asynchronous -function CUnifiedKeyStore::Initialize(). - - -Obtain the authentication object of a key using the CCTKeyInfo::Protector() function. - - -Invoke the ChangeReferenceData() function for the -authentication object obtained. The keystore prompts the user to enter the -old and new passphrases. - - -

            The passphrase is changed for the selected key, if the old passphrase -is entered correctly.

             -Example

            The -following code snippet shows how to set use policy for a key.

            // Create a file system session object -RFs iFs; -CleanupClosePushL(&iFs); - - -... - - -// Initialise the keystore and member functions -CUnifiedKeyStore* keyStore = CUnifiedKeyStore::NewL(fs); -keyStore->Initialize(iStatus); //iStatus is a TRequestStatus object - - -... - - - -// Change the passphrase -void ChangePassphraseL(CCTKeyInfo& aKey) -{ - MCTAuthenticationObject* authObject = aKey.Protector(); - if (authObject == NULL) - User::Leave(KErrNotSupported); - - authObject->ChangeReferenceData(iStatus); - iState = EChangePassphrase; - SetActive(); -} - - -// Clean up -CleanupStack::PopAndDestroy(); // iFs             + + + + + +Changing +PassphraseThis section explains how to change the passphrase. +

            The following steps explain the process of changing the passphrase:

             + +Create a file system +session using an RFs object. + + +Create an object of type CUnifiedKeyStore using CUnifiedKeyStore::NewL() or CUnifiedKeyStore::NewLC(). + + +Initialize the member functions and keystore using the asynchronous +function CUnifiedKeyStore::Initialize(). + + +Obtain the authentication object of a key using the CCTKeyInfo::Protector() function. + + +Invoke the ChangeReferenceData() function for the +authentication object obtained. The keystore prompts the user to enter the +old and new passphrases. + + +

            The passphrase is changed for the selected key, if the old passphrase +is entered correctly.

             +Example

            The +following code snippet shows how to set use policy for a key.

            // Create a file system session object +RFs iFs; +CleanupClosePushL(&iFs); + + +... + + +// Initialise the keystore and member functions +CUnifiedKeyStore* keyStore = CUnifiedKeyStore::NewL(fs); +keyStore->Initialize(iStatus); //iStatus is a TRequestStatus object + + +... + + + +// Change the passphrase +void ChangePassphraseL(CCTKeyInfo& aKey) +{ + MCTAuthenticationObject* authObject = aKey.Protector(); + if (authObject == NULL) + User::Leave(KErrNotSupported); + + authObject->ChangeReferenceData(iStatus); + iState = EChangePassphrase; + SetActive(); +} + + +// Clean up +CleanupStack::PopAndDestroy(); // iFs             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-48C764A2-378F-57CC-B7F2-EC866AE8F830.dita --- a/Symbian3/SDK/Source/GUID-48C764A2-378F-57CC-B7F2-EC866AE8F830.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-48C764A2-378F-57CC-B7F2-EC866AE8F830.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,12 +1,12 @@ - - - - - -The reference counting object

            A reference counting object is one which uses reference counting to track concurrent references to itself and which arranges for automatic destruction of itself when the final reference is removed. It is also an object which can be named.

            A reference counting object is any object which has CObject as its base class.

            Constructing a CObject derived type, or calling its CObject::Open() member function, adds a reference to that object by adding one to its reference count. Calling its CObject::Close() member function removes a reference by subtracting one from its reference count. When the last user of the object calls CObject::Close(), the reference count becomes zero and the object is automatically destroyed.

            The following drawing shows the idea.

            A CObject is always part of a class hierarchy. It is a base class; an explicit CObject type is never instantiated.

            The server side implementation of a client/server subsession uses a CObject.

            See also:

            • CObject

            • Subsessions within a session

            • Using client/server

            \ No newline at end of file + + + + + +The reference counting object

            A reference counting object is one which uses reference counting to track concurrent references to itself and which arranges for automatic destruction of itself when the final reference is removed. It is also an object which can be named.

            A reference counting object is any object which has CObject as its base class.

            Constructing a CObject derived type, or calling its CObject::Open() member function, adds a reference to that object by adding one to its reference count. Calling its CObject::Close() member function removes a reference by subtracting one from its reference count. When the last user of the object calls CObject::Close(), the reference count becomes zero and the object is automatically destroyed.

            The following drawing shows the idea.

            A CObject is always part of a class hierarchy. It is a base class; an explicit CObject type is never instantiated.

            The server side implementation of a client/server subsession uses a CObject.

            See also:

            • CObject

            • Subsessions within a session

            • Using client/server

            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-48D06D0E-C4D6-54F1-B603-7A75DEF669AA_d0e375455_href.png Binary file Symbian3/SDK/Source/GUID-48D06D0E-C4D6-54F1-B603-7A75DEF669AA_d0e375455_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-48D06D0E-C4D6-54F1-B603-7A75DEF669AA_d0e381534_href.png Binary file Symbian3/SDK/Source/GUID-48D06D0E-C4D6-54F1-B603-7A75DEF669AA_d0e381534_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-48ED7013-B1B7-5E86-AC09-599C4499191D.dita --- a/Symbian3/SDK/Source/GUID-48ED7013-B1B7-5E86-AC09-599C4499191D.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,12 +0,0 @@ - - - - - -Example Code

            An example application that demonstrates the use of the Multimedia Frameworks is shown below:

            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-49205F79-C17B-4126-BDB2-D759B91B5894.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-49205F79-C17B-4126-BDB2-D759B91B5894.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,109 @@ + + + + + +Enabling +Application Level RoamingApplication-level roaming (ALR) enables your application to roam +to use the best available data connection while operational. +

            To use application-level +roaming:

            + +Initiate an Internet +connection using the Connection Manager API and the Internet destination network. +In this example it is assumed that the best available access point for Internet +is GPRS. +

            RConnection handle is returned to the application.

            +             +             +Register for mobility +API sending NewL(RConnection handle, MMobilityProtocolResp&) to +the Connection Manager API. + +Use Sockets Client +API to open RSockets with RConnection handle. +

            RSocket handle is returned to the application.

             +             +Initiate normal +socket communication to the Sockets Client API. This data transfer uses GPRS. + A WLAN access point becomes available. The Connection Manager API sends PreferredCarrierAvailable(old +access point, new access point, is upgrade, not seamless) to the +application. The application decides to switch to the better access point. +It closes the old socket using the Sockets Client API. + +Send MigrateToPreferredCarrier() to +the Connection Manager API. Note: The application can also IgnorePreferredCarrier(). +In that case it would just keep using the existing socket. The connection +is moved in the Connection Manager API. The WLAN access point is activated +and RConnection handle is moved from the GPRS interface to WLAN. NewCarrierActive(new +IAP) is returned to the application. The WLAN access point is now +ready to be used. + +Use Sockets Client +API to open RSockets with RConnection handle. This data transfer uses WLAN. + +Transfer data using +the Sockets Client API to confirm that the connection works. + +Send NewCarrierAccepted() to +the Connection Manager API. This is the point of no return. + +Continue transferring +data using the Sockets Client API. This data transfer uses WLAN. + +             +

            ALR is enabled.

            +             +class CALRApplication : public CActive, public MMobilityProtocolResp + { +... + public: // From MMobilityProtocolResp + void PreferredCarrierAvailable( TAccessPointInfo aOldAPInfo, + TAccessPointInfo aNewAPInfo, + TBool aIsUpgrade, + TBool aIsSeamless ); + void NewCarrierActive( TAccessPointInfo aNewAPInfo, TBool aIsSeamless ); + void Error( TInt aError ); + private: // Data + RConnection iConnection; + CActiveCommsMobilityApiExt* iMobility; + }; +// When the connection starts, iMobility is created and it registers the connection to receive mobility messages. +iMobility = CActiveCommsMobilityApiExt::NewL( iConnection, *this );When apreferred access point becomes available, the implementation of CALRApplication::PreferredCarrierAvailable is called. MigrateToPreferredCarrier Mobility message is sent to the middleware in order to roam to this preferred access point. +void CALRApplication::PreferredCarrierAvailable( TAccessPointInfo aOldAPInfo,TAccessPointInfo aNewAPInfo,TBool aIsUpgrade,TBool aIsSeamless ){ + // aOldAPInfo contains the current IAP used by the connection. + // aNewAPInfo contains the newly available IAP that can be used by the connection. + if ( aIsSeamless ) + { + // It is Seamless. E.g. Mobile IP enabled. + } + else + { + // sockets used by the connection should be closed here. + // We ask to migrate to the Preferred Carrier. + iMobility->MigrateToPreferredCarrier(); + } + } +Once the connection roamed to the new access point, the implementation ofCALRApplication::NewCarrierActive is called. The application reopens its sockets on the connection. If the socket connection is fine, the application sends the NewCarrierAccepted Mobility message to the middleware. + +void CALRApplication::NewCarrierActive( TAccessPointInfo aNewAPInfo, TBool aIsSeamless ) + { + // aNewAPInfo contains the newly started IAP used now by the connection. + if ( aIsSeamless ) + { + // It is Seamless. E.g. Mobile IP enabled. + } + else + { + // sockets used by the connection should be reopened here. + // We accept the new IAP. + iMobility->NewCarrierAccepted(); + } + } +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4922D80F-009D-56CE-B255-FDAF9C247667_d0e215301_href.png Binary file Symbian3/SDK/Source/GUID-4922D80F-009D-56CE-B255-FDAF9C247667_d0e215301_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4922D80F-009D-56CE-B255-FDAF9C247667_d0e219038_href.png Binary file Symbian3/SDK/Source/GUID-4922D80F-009D-56CE-B255-FDAF9C247667_d0e219038_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4930A22F-EF80-5B08-A878-C0DB73929558_d0e266550_href.png Binary file Symbian3/SDK/Source/GUID-4930A22F-EF80-5B08-A878-C0DB73929558_d0e266550_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4930A22F-EF80-5B08-A878-C0DB73929558_d0e270258_href.png Binary file Symbian3/SDK/Source/GUID-4930A22F-EF80-5B08-A878-C0DB73929558_d0e270258_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-49363088-CE0B-558D-8E86-48400E4F7C2F.dita --- a/Symbian3/SDK/Source/GUID-49363088-CE0B-558D-8E86-48400E4F7C2F.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-49363088-CE0B-558D-8E86-48400E4F7C2F.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,89 +1,89 @@ - - - - - -Multiple -Alarm Notification Overview -
            Purpose and Scope

            This document provides a description -of the multiple alarm notification support in Symbian OS v9.2 and later. The -main feature is the ability of multiple alarms to expire simultaneously. UI -applications do not have to acknowledge an alarm event before the agenda server -generates the next alarm event. This document provides a configuration guide.

            -
            Definitions
            - -
            Alarm Server
            -

            This provides Symbian with alarm-related services. It communicates -with Uikon Alert Server to display the expired alarm to users.

            -             - -
            Uikon Alert Server
            -

            The Uikon Alert Server provides the interface for Alarm Server to interact -with Licensee UI Applications. It consists of a client interface in Alarm -Alert, and a server interface in Uikon.

            -             -
            -
            Description

            Alarm Server provides all alarm-related -services to the system. When an alarm expires, Alarm Server notifies the Alert -Server about the expired alarm to display to the user.

            The state properties -are the same for single and multiple alarm notification, but the condition -for moving to ‘notifying’ state is different. If multiple alarm notification -is supported, more than one alarm can move to ‘notifying’ state provided that -Alert Server can accept more than one alarm from Alarm Server. Even if a UI -application can accept multiple notifying alarms, it cannot accept an infinite -number of notifying alarms. Therefore, at Alarm Server startup, Alarm Server -will query Alert Server for the maximum number of notifying alarms allowed. -Alarm Server can use that information to determine if multiple alarm notification -is supported, and if so, how many alarms can be in ‘notifying’ state at the -same time.

            To support multiple alarm notification, Alarm Server notifies -Alert Server about multiple expired alarms without waiting for the first alarm -to be cleared or snoozed.

            - Alarm state diagram for multiple alarm notification - support - -

            In the diagram above, a queued alarm can change to the ‘waiting -to notify’ state if an alarm has expired but the maximum number of notifying -alarms has been reached. The state can also change if Alarm Server is waiting -for a reply from Alert Server. This second scenario may occur because even -though Alert Server can accept multiple alarms, the Alarm Server needs the -previous asynchronous request EASAltOpCodeSetAlarm to be -completed before sending the next one. As the UI application is implemented -by licensee, this scenario may or may not occur depending on how long the -UI application takes to register multiple alarms.

            If the Alert Server -can still accept more alarms the ‘waiting to notify’ alarm can change to ‘notifying’ -state after the asynchronous request EASAltOpCodeSetAlarm is -completed.

            As demonstrated above, a 'notifying' alarm can change to -‘snoozed’ state if:

              -

            1. The user requests ‘snooze’

              2. -

            2. Another alarm has expired -and the current alarm has sound playing paused. This scenario occurs if the -paused alarm is the only notifying alarm

              3. -

            3. The sound playing is -paused for the current notifying alarm. If this occurs and there are multiple -notifying alarms, the currently notifying alarm is snoozed instead of paused.

              4. -

            For single alarm notification, a notifying alarm has sound paused -when Alarm Server receives a EASAltAlertServerResponsePauseSound event -from Alert Server. If another alarm has expired while the notifying alarm -has sound paused, Alarm Server snoozes the paused alarm automatically and -plays the sound of the just expired alarm. In case of multiple alarm notification, -the ‘sound paused’ alarm automatically snoozes if other alarms notify at the -same time.

            It is a design decision to make the implementation compatible -with the existing implementation. That way if the maximum number of alarms -is set to one, the implementation is exactly that same as before.

            In -case of multiple alarm notification, pausing the playing alarm triggers the -Alarm Server to play sound for one of the other notifying alarms. This is -because the sound pause request only applies to the specified alarm.

            If -the user wants to silence the alarm while keeping the alarm in ‘notifying’ -state, the user can respond with ‘silent’ (EASAltAlertServerResponseSilence), -which will silence the alarm until the next alarm play interval re-starts -(an existing behaviour in single alarm notification). Alternatively, a global -silent command (EASAltAlertServerResponseQuietPeriod) will -pause sound for all alarms for a specified time while all expired alarms will -stay in ‘notifying’ state.

            + + + + + +Multiple +Alarm Notification Overview +
            Purpose and Scope

            This document provides a description +of the multiple alarm notification support in Symbian OS v9.2 and later. The +main feature is the ability of multiple alarms to expire simultaneously. UI +applications do not have to acknowledge an alarm event before the agenda server +generates the next alarm event. This document provides a configuration guide.

            +
            Definitions
            + +
            Alarm Server
            +

            This provides Symbian with alarm-related services. It communicates +with Uikon Alert Server to display the expired alarm to users.

            +             + +
            Uikon Alert Server
            +

            The Uikon Alert Server provides the interface for Alarm Server to interact +with Licensee UI Applications. It consists of a client interface in Alarm +Alert, and a server interface in Uikon.

            +             +
            +
            Description

            Alarm Server provides all alarm-related +services to the system. When an alarm expires, Alarm Server notifies the Alert +Server about the expired alarm to display to the user.

            The state properties +are the same for single and multiple alarm notification, but the condition +for moving to ‘notifying’ state is different. If multiple alarm notification +is supported, more than one alarm can move to ‘notifying’ state provided that +Alert Server can accept more than one alarm from Alarm Server. Even if a UI +application can accept multiple notifying alarms, it cannot accept an infinite +number of notifying alarms. Therefore, at Alarm Server startup, Alarm Server +will query Alert Server for the maximum number of notifying alarms allowed. +Alarm Server can use that information to determine if multiple alarm notification +is supported, and if so, how many alarms can be in ‘notifying’ state at the +same time.

            To support multiple alarm notification, Alarm Server notifies +Alert Server about multiple expired alarms without waiting for the first alarm +to be cleared or snoozed.

            + Alarm state diagram for multiple alarm notification + support + +

            In the diagram above, a queued alarm can change to the ‘waiting +to notify’ state if an alarm has expired but the maximum number of notifying +alarms has been reached. The state can also change if Alarm Server is waiting +for a reply from Alert Server. This second scenario may occur because even +though Alert Server can accept multiple alarms, the Alarm Server needs the +previous asynchronous request EASAltOpCodeSetAlarm to be +completed before sending the next one. As the UI application is implemented +by licensee, this scenario may or may not occur depending on how long the +UI application takes to register multiple alarms.

            If the Alert Server +can still accept more alarms the ‘waiting to notify’ alarm can change to ‘notifying’ +state after the asynchronous request EASAltOpCodeSetAlarm is +completed.

            As demonstrated above, a 'notifying' alarm can change to +‘snoozed’ state if:

              +

            1. The user requests ‘snooze’

              2. +

            2. Another alarm has expired +and the current alarm has sound playing paused. This scenario occurs if the +paused alarm is the only notifying alarm

              3. +

            3. The sound playing is +paused for the current notifying alarm. If this occurs and there are multiple +notifying alarms, the currently notifying alarm is snoozed instead of paused.

              4. +

            For single alarm notification, a notifying alarm has sound paused +when Alarm Server receives a EASAltAlertServerResponsePauseSound event +from Alert Server. If another alarm has expired while the notifying alarm +has sound paused, Alarm Server snoozes the paused alarm automatically and +plays the sound of the just expired alarm. In case of multiple alarm notification, +the ‘sound paused’ alarm automatically snoozes if other alarms notify at the +same time.

            It is a design decision to make the implementation compatible +with the existing implementation. That way if the maximum number of alarms +is set to one, the implementation is exactly that same as before.

            In +case of multiple alarm notification, pausing the playing alarm triggers the +Alarm Server to play sound for one of the other notifying alarms. This is +because the sound pause request only applies to the specified alarm.

            If +the user wants to silence the alarm while keeping the alarm in ‘notifying’ +state, the user can respond with ‘silent’ (EASAltAlertServerResponseSilence), +which will silence the alarm until the next alarm play interval re-starts +(an existing behaviour in single alarm notification). Alternatively, a global +silent command (EASAltAlertServerResponseQuietPeriod) will +pause sound for all alarms for a specified time while all expired alarms will +stay in ‘notifying’ state.

            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4941C035-C359-4968-9BD5-31F44EE5F810.dita --- a/Symbian3/SDK/Source/GUID-4941C035-C359-4968-9BD5-31F44EE5F810.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-4941C035-C359-4968-9BD5-31F44EE5F810.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,145 +1,145 @@ - - - - - -Commands -

            The term command refers to events that are received when a device user -selects an option in the Options menu or presses a softkey (for more -information, see UI concepts). -The device user input results in the application framework returning a command -ID that corresponds to the softkey or Options menu selection. Command -IDs are mapped to the selection options in the CBA and Menu bar resource -definitions. You can use either custom command IDs, which must be defined -in your application hrh resource -file, or precompiled -values available from the Symbian platform in your resource definitions. -At runtime, the application framework catches the command ID values and passes -them to the application that has focus for handling. The following commands -have special requirements:

            -
              -

            • EEikCmdExit, which is sent by the application -framework to exit open applications. This command ID must not be used in the -resource file definitions, as it is reserved for the application framework. -For more information on the special requirements for handling this command, -see Handling -EEikCmdExit.

              -
              • -

            • EAknSoftKeyBack, which is delivered -in response to a device user pressing the Back softkey. -The behavior required in response to this command depends on the context, -but if an exit is required it needs to be handled in the same manner as with -the EEikCmdExit command.

              • -

            • EAknSoftkeyOptions, which is associated -with the Options softkey, is handled by the application -framework directly and results in the Options menu being -presented to the device user.

              • -
            -

            For more information on resource files, see Managing -resource files.

            -

            For an example of a resource file, see Resource -management example: HelloWorldBasic.

            -Options menu -

            Commands are passed to the object with which the menu is associated. -The object that receives the command should handle the command if it is specific -to the object. If the command is relevant to another object, then it should -be passed onto the other application object. The actual implementation depends -on the design of your application.

            -

            If the application above uses an Symbian -view architecture, then the command handling functions as follows.

            -
              -

            • If a device user selects Create New, -then the application framework returns the command associated with that menu -item to the view controller for -the view indicated by the first tab.

              • -

            • Since this command is unique to this view, the command must -be handled in the view controller for this view.

              • -

            • If there was an Exit menu item that -was applicable for the application generally, then you must pass the command -for this menu item to the UI -controller and handle the command there.

              • -
            -

            To handle commands, you must override CEikAppUi::HandleCommandL() .

            -

            The options are as follows:

            -
              -

            • In a traditional -Symbian UI application architecture, the command needs to be handled -in the UI controller. -An example of an implementation is as follows:

              - -void CMyCommandHandlingAppUi::HandleCommandL(TInt aCommand) - { - switch(aCommand) - { - case EEikCmdExit: - case EAknSoftkeyExit: - { - Exit(); - break; - } - - case EMyCommandID1: - { - //do something - } - break; - - default: - break; - } - } -

              where EEikCmdExit is provided from the application -framework, EAknSoftkeyExit is the command ID that the -application framework returns when a device user presses the Back softkey, -and EMyCommandID1 is a command ID from your application hrh file.

              -

              For more information on the handling of the exit command IDs, see Handling -EEikCmdExit.

              -               -
              • -

            • In an Symbian -view architecture, the command is received by the active view. -It should be handled by the view if the command is view specific, otherwise -it should be passed to the UI controller CAknViewAppUi(-derived -class). For an example of view-specific command handling, see the following:

              - -void CMyCommandHandlingViewClass::HandleCommandL(TInt aCommand) - { - switch ( aCommand ) - { - case EAknSoftkeyExit: - { - AppUi()->HandleCommandL(EEikCmdExit); - break; - } - - case EMyCommandID1: - { - // Do something. - break; - } - - default: - { - AppUi()->HandleCommandL( aCommand ); - break; - } - } - } - -

              where EEikCmdExit is provided from the application -framework, EAknSoftkeyExit is the command ID that the -application framework returns when a device user presses the Back softkey, -and EMyCommandID1 is a command ID from your application hrh file.

              -

              In this example, the last case (default) hands over unhandled commands -to the UI controller.

              -

              For more information on the handling of the exit command IDs, see:

              -               -
              • -
            + + + + + +Commands +

            The term command refers to events that are received when a device user +selects an option in the Options menu or presses a softkey (for more +information, see UI concepts). +The device user input results in the application framework returning a command +ID that corresponds to the softkey or Options menu selection. Command +IDs are mapped to the selection options in the CBA and Menu bar resource +definitions. You can use either custom command IDs, which must be defined +in your application hrh resource +file, or precompiled +values available from the Symbian platform in your resource definitions. +At runtime, the application framework catches the command ID values and passes +them to the application that has focus for handling. The following commands +have special requirements:

            +
              +

            • EEikCmdExit, which is sent by the application +framework to exit open applications. This command ID must not be used in the +resource file definitions, as it is reserved for the application framework. +For more information on the special requirements for handling this command, +see Handling +EEikCmdExit.

              +
              • +

            • EAknSoftKeyBack, which is delivered +in response to a device user pressing the Back softkey. +The behavior required in response to this command depends on the context, +but if an exit is required it needs to be handled in the same manner as with +the EEikCmdExit command.

              • +

            • EAknSoftkeyOptions, which is associated +with the Options softkey, is handled by the application +framework directly and results in the Options menu being +presented to the device user.

              • +
            +

            For more information on resource files, see Managing +resource files.

            +

            For an example of a resource file, see Resource +management example: HelloWorldBasic.

            +Options menu +

            Commands are passed to the object with which the menu is associated. +The object that receives the command should handle the command if it is specific +to the object. If the command is relevant to another object, then it should +be passed onto the other application object. The actual implementation depends +on the design of your application.

            +

            If the application above uses an Symbian +view architecture, then the command handling functions as follows.

            +
              +

            • If a device user selects Create New, +then the application framework returns the command associated with that menu +item to the view controller for +the view indicated by the first tab.

              • +

            • Since this command is unique to this view, the command must +be handled in the view controller for this view.

              • +

            • If there was an Exit menu item that +was applicable for the application generally, then you must pass the command +for this menu item to the UI +controller and handle the command there.

              • +
            +

            To handle commands, you must override CEikAppUi::HandleCommandL() .

            +

            The options are as follows:

            +
              +

            • In a traditional +Symbian UI application architecture, the command needs to be handled +in the UI controller. +An example of an implementation is as follows:

              + +void CMyCommandHandlingAppUi::HandleCommandL(TInt aCommand) + { + switch(aCommand) + { + case EEikCmdExit: + case EAknSoftkeyExit: + { + Exit(); + break; + } + + case EMyCommandID1: + { + //do something + } + break; + + default: + break; + } + } +

              where EEikCmdExit is provided from the application +framework, EAknSoftkeyExit is the command ID that the +application framework returns when a device user presses the Back softkey, +and EMyCommandID1 is a command ID from your application hrh file.

              +

              For more information on the handling of the exit command IDs, see Handling +EEikCmdExit.

              +               +
              • +

            • In an Symbian +view architecture, the command is received by the active view. +It should be handled by the view if the command is view specific, otherwise +it should be passed to the UI controller CAknViewAppUi(-derived +class). For an example of view-specific command handling, see the following:

              + +void CMyCommandHandlingViewClass::HandleCommandL(TInt aCommand) + { + switch ( aCommand ) + { + case EAknSoftkeyExit: + { + AppUi()->HandleCommandL(EEikCmdExit); + break; + } + + case EMyCommandID1: + { + // Do something. + break; + } + + default: + { + AppUi()->HandleCommandL( aCommand ); + break; + } + } + } + +

              where EEikCmdExit is provided from the application +framework, EAknSoftkeyExit is the command ID that the +application framework returns when a device user presses the Back softkey, +and EMyCommandID1 is a command ID from your application hrh file.

              +

              In this example, the last case (default) hands over unhandled commands +to the UI controller.

              +

              For more information on the handling of the exit command IDs, see:

              +               +
              • +
             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-494AF38D-CE0C-4B4C-BE44-2FC7482F4B7B.dita --- a/Symbian3/SDK/Source/GUID-494AF38D-CE0C-4B4C-BE44-2FC7482F4B7B.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-494AF38D-CE0C-4B4C-BE44-2FC7482F4B7B.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,16 +1,23 @@ - - - - - -Hiding -and showing stylus pop-up menu items -

            To hide and show stylus pop-up menu items, use the method SetItemDimmed() in the class CAknStylusPopUpMenu.

            -

            Add sample code here.

            + + + + + +Hiding and showing stylus pop-up menu items +

            To hide and show stylus pop-up menu items, use the method CAknStylusPopUpMenu::SetItemDimmed() in the class.

            +// You can remove the menu item dynamically according to the command id. For example: +iPopupMenu->RemoveMenuItem( StylusMenuCommand1 ); + +// You can dim (hide) a menu item without removing it +iPopupMenu->SetItemDimmed( StylusMenuDynamicAdd, ETrue ); + +// You can un-dim(show) the menu item again: +iPopupMenu->SetItemDimmed( StylusMenuDynamicAdd, EFalse ); +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4957E6BB-C41D-52F1-94CD-68CF6D61C271.dita --- a/Symbian3/SDK/Source/GUID-4957E6BB-C41D-52F1-94CD-68CF6D61C271.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-4957E6BB-C41D-52F1-94CD-68CF6D61C271.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,48 +1,48 @@ - - - - - -Format -layering -

            The Symbian platform uses the principle of format layering -in which new formatting is added as a layer onto the previous layer of formatting. -The following diagram shows a less efficient technique for applying format -layering to text. The inefficiency arises because each format layer stores -not only the new attribute which it introduces, but also every attribute which -it inherits from the preceding format layer.

            - - - -

            The Symbian platform avoids this inefficiency by using the system of based-on -links. Here, each new layer adds attributes in a natural way without -restating all attributes previously set. A based-on link is a pointer to the -format layer whose attributes are inherited by another layer. For example, -when the italic attribute is applied to a region of bold text, the new layer -stores only the italic attribute and a pointer to the previous attribute layer. -Chains of format layers can thus be formed, with each layer based on the previous -one. In order to determine a character or paragraph’s effective format, -a chain of format layers must typically be examined. The final layer in the -chain of based on links is the one whose based on link is NULL and is not -therefore based upon any other layer.

            -

            This method is demonstrated in the following two diagrams, in which each -arrow represents a based-on link.

            - -Format layering - - -

            The following diagram demonstrates the system of based-on links when attributes -are applied to different parts of text rather than added on top of existing -attribute layers.

            - - - -

            In this case, several format layers are required, all of which are based -on the normal layer.

            + + + + + +Format +layering +

            The Symbian platform uses the principle of format layering +in which new formatting is added as a layer onto the previous layer of formatting. +The following diagram shows a less efficient technique for applying format +layering to text. The inefficiency arises because each format layer stores +not only the new attribute which it introduces, but also every attribute which +it inherits from the preceding format layer.

            + + + +

            The Symbian platform avoids this inefficiency by using the system of based-on +links. Here, each new layer adds attributes in a natural way without +restating all attributes previously set. A based-on link is a pointer to the +format layer whose attributes are inherited by another layer. For example, +when the italic attribute is applied to a region of bold text, the new layer +stores only the italic attribute and a pointer to the previous attribute layer. +Chains of format layers can thus be formed, with each layer based on the previous +one. In order to determine a character or paragraph’s effective format, +a chain of format layers must typically be examined. The final layer in the +chain of based on links is the one whose based on link is NULL and is not +therefore based upon any other layer.

            +

            This method is demonstrated in the following two diagrams, in which each +arrow represents a based-on link.

            + +Format layering + + +

            The following diagram demonstrates the system of based-on links when attributes +are applied to different parts of text rather than added on top of existing +attribute layers.

            + + + +

            In this case, several format layers are required, all of which are based +on the normal layer.

             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-495EA1C8-E95F-54AE-B4D1-0F463003C2D7.dita --- a/Symbian3/SDK/Source/GUID-495EA1C8-E95F-54AE-B4D1-0F463003C2D7.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-495EA1C8-E95F-54AE-B4D1-0F463003C2D7.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,218 +1,218 @@ - - - - - -External -Surfaces OverviewThis topic provides an introduction to displaying an external surface -on a window. The surface is then known as a background surface. This feature -is available in ScreenPlay only. -

            Variant: ScreenPlay. Target -audience: Device creators.

            -

            There are two main use cases for using external surfaces in this way. One -is to display a video, in which case DevVideo renders the content. The other -main use case is an OpenGL ES background surface, in which case the client -issues OpenGL ES rendering commands. This topic covers how to get the surface -onto the screen and not rendering the content to the surface.

            -
            Key concepts

            The following diagram illustrates -some of the key concepts that are used in the documentation of surfaces.

            -Composition of the UI surface and an external surface, showing the - viewport and extent - -
            - -
            Graphics surface
            -

            A graphics surface (usually simply called a surface) is a hardware-independent -memory buffer for holding an image or part of a scene. A surface has a set -of attributes, the most important of which is its ID (which is a TSurfaceId).

            -             - -
            UI surface
            -

            The UI surface is a special surface onto which the Window Server renders -all of the UI content. It is created automatically during system start up -and corresponds to the frame buffer in the non-ScreenPlay variant. The UI -surface is semi-transparent and is always the topmost layer.

            -             - -
            External surface
            -

            An external surface is any surface other than the UI surface—for example, -a surface that holds a video or to which OpenGL ES content is rendered. External -surfaces are always opaque. When an external surface is attached to a window, -the Window Server creates a transparent hole in the UI surface to reveal the -external surface.

            -             - -
            Viewport
            -

            The viewport is a rectangular area of an external surface all or part -of which is to be displayed. You can think of the viewport as the source.

            -             - -
            Extent
            -

            The extent is a rectangular area in the composition scene in which -all or part of the viewport is placed. The content of the viewport can be -scaled and rotated within the extent relative to its normal size and orientation. -The extent is normally a window to which the external surface is attached.

            -             -

            The following diagram provides a cross-section view through the surfaces -shown in the previous figure. Notice that the UI surface is the topmost layer -and that it contains a hole through which the external surface -can be seen.

            - A cross section through the surfaces, showing the display -output - -
            -
            Supported Uses

            You -can:

              -

            • Display an external -surface (for example, video content or a viewfinder image) within a window.

              • -

            • Dynamically set or remove -a background surface across multiple windows on the same screen without having -to register and unregister the surface. This reduces resource churn and content -transfer.

              • -

            • Reconfigure the attributes -of the surface such as its extent, viewport and orientation, after it is set -as a background.

              • -

            • Reposition the displayed -surface on the window.

              • -

            • Zoom in and out of the -contents of the surface.

              • -

            • Place the surface content -in a specified window area rather than filling the entire window.

              • -

            • Crop the surface content -rather than using the entire surface.

              • -

            • Rotate the contents -of the background surface by quadrant angles.

              • -

            • Flip the background -surface from top to bottom and rotate it by 180° to achieve a mirroring effect.

              • -

            The following diagrams shows some surface configuration use cases.

            - Surface configuration use cases - -
            -
            Configuration

            There -are a number of ways in which dynamically updated content can be configured -to appear on a window.

            A single content surface filling the window

            External -content can be fitted onto a Window Server window. Each axis of the surface -can be stretched independently of the other axis. The window must be a visible -client window: RWindow or RBlankWindow.

            Placement -of a single surface on a selected area of the window

            The position -and display size for the external content can be specified as an area within -the Window Server window, rather than filling the window. The window must -be a visible client (RWindow or RBlankWindow) -as before. You specify the area by using TSurfaceConfiguration::SetExtent(const -TRect& aExtent).

            After the extent is specified, -its size does not change if the window size changes but its position moves -to maintain its relative position on the window.

            Clipping of a -surface

            Video sometimes needs to appear cropped, so that a sub-area -of the video is displayed instead of the full image. The crop viewport is -specified in surface co-ordinates. The cropped viewport fills the output extent -(or the window when the extent is not specified). The content appears scaled -if the size of the viewport does not match the size of the extent (or the -window).

            Scaling

            It is possible to arbitrarily scale -a surface to user specifications using the extent and viewport features. Each -axis is scaled independently. When the extent and viewport are coincident, -no scaling occurs. Filtering can be applied by the implementation of stretching -and shrinking.

            Rotation

            The viewport can be displayed -rotated relative to its normal orientation. For example, if there is a fixed -camera on the front of a device and the device is rotated by 90°, the image -captured by the camera needs to be rotated by 90° in the other direction to -get the expected result. The orientation is always relative to the current -device orientation.

            Flipping

            An external surface can -be flipped from top to bottom around the x axis.

            Atomic combination -of these operations

            All the above mentioned configurations can -be specified and combined unambiguously for a particular content on a particular -window. You can specify parameters for a combination of these configurations -in a single operation.

            Changing surfaces

            The surface -assigned to a window can be changed.

            Reconfiguring

            It -is possible to change the configuration options applied to a surface without -re-assigning the surface.

            Sharing surfaces

            Content -surfaces are transferable and sharable between windows.

            The initial -registration step ensures that any resources allocated to the content surface -are held while the surface is removed from one window and added to another. -This reduces the likelihood of failure between operations.

            -
            API Summary

            This section provides a summary of -the classes and functions that you use to manage surfaces:

              -

            • RWindowBase

              • -

            • TSurfaceConfiguration

              • -

            • RWsSession

              • -
            -
            RWindowBase
              -

            • SetBackgroundSurface(const -TSurfaceConfiguration &,TBool) sets the background -of the window to be a given surface. The TSurfaceConfiguration argument -contains the surface ID and the configuration attributes. Another form of -the function simply takes a surface ID as an argument, which provides less -control and auto-stretches the surface to fill the window.

              • -

            • RemoveBackgroundSurface() removes -any background surface that has been set to the window.

              • -

            • GetBackgroundSurface() retrieves -a copy of the current configuration for the background surface attached to -the window.

              • -

            See RWindowBase.

            -
            TSurfaceConfiguration

            This -class encapsulates the surface configuration attributes that can be specified -while setting the background surface of a window. If the values for the attributes -are not set, the default values for the corresponding attribute are used.

            Symbian -recommends that the client validates the surface configuration data before -passing it on to the server. Invalid data that inadvertently slips through -the client-side validation mechanism, or maliciously bypasses it, causes a -panic.

            See TSurfaceConfiguration.

            -
            RWsSession
              -

            • RegisterSurface() registers -a surface for use in composition on the screen associated with this device -within this session.

              • -

            • UnregisterSurface() removes -the surface from the session’s register of surfaces that are used in composition -on the screen associated with this device.

              • -

            • PreferredSurfaceConfigurationSize() returns -the window server’s preferred size for the TSurfaceConfiguration object, -used for RWindow::SetBackgroundSurface().

              • -

            See RWsSession.

            -
            Example

            This code snippet is provided for illustrative -purposes only. A Window Server client application wants to run a 3D game full-screen -at the native physical resolution of the display (either current or selected -using a display controlling system application). This example assumes that -the MDisplayMapping interface has already been obtained, -as shown in Display -Control and Mapping in the Window Server Client.

            // Establish connection and get display mapping interface. -RWindowGroup group = RWindowGroup(iSession); -RWindow window(iSession); - -group.Construct(1, iScreenDevice); -window.Construct(group, 2); - -TRect winExtent; -iDisplayMapping.GetMaximumWindowExtent(winExtent); -window.SetExtent(winExtent); - -// Map window size to composition coordinates -TRect surfaceExtent; -iDisplayMapping.MapCoordinates(EApplicationSpace, winExtent, - ECompositionSpace, surfaceExtent); - -RSurfaceManager::TSurfaceCreationAttributes attribs; -attribs.iSize = surfaceExtent.Size(); - -// Set up other attributes and create surface - -window.SetBackgroundSurface(surface); - -window.Activate(); -

            A similar approach can be used by other surface content providers, -such as video.

            -             -Graphics -Composition - -Window Server -Client-Side Library Concepts -Dynamic Resolution -Switching -Flipping -and Rotating an External Surface + + + + + +External +Surfaces OverviewThis topic provides an introduction to displaying an external surface +on a window. The surface is then known as a background surface. This feature +is available in ScreenPlay only. +

            Variant: ScreenPlay. Target +audience: Device creators.

            +

            There are two main use cases for using external surfaces in this way. One +is to display a video, in which case DevVideo renders the content. The other +main use case is an OpenGL ES background surface, in which case the client +issues OpenGL ES rendering commands. This topic covers how to get the surface +onto the screen and not rendering the content to the surface.

            +
            Key concepts

            The following diagram illustrates +some of the key concepts that are used in the documentation of surfaces.

            +Composition of the UI surface and an external surface, showing the + viewport and extent + +
            + +
            Graphics surface
            +

            A graphics surface (usually simply called a surface) is a hardware-independent +memory buffer for holding an image or part of a scene. A surface has a set +of attributes, the most important of which is its ID (which is a TSurfaceId).

            +             + +
            UI surface
            +

            The UI surface is a special surface onto which the Window Server renders +all of the UI content. It is created automatically during system start up +and corresponds to the frame buffer in the non-ScreenPlay variant. The UI +surface is semi-transparent and is always the topmost layer.

            +             + +
            External surface
            +

            An external surface is any surface other than the UI surface—for example, +a surface that holds a video or to which OpenGL ES content is rendered. External +surfaces are always opaque. When an external surface is attached to a window, +the Window Server creates a transparent hole in the UI surface to reveal the +external surface.

            +             + +
            Viewport
            +

            The viewport is a rectangular area of an external surface all or part +of which is to be displayed. You can think of the viewport as the source.

            +             + +
            Extent
            +

            The extent is a rectangular area in the composition scene in which +all or part of the viewport is placed. The content of the viewport can be +scaled and rotated within the extent relative to its normal size and orientation. +The extent is normally a window to which the external surface is attached.

            +             +

            The following diagram provides a cross-section view through the surfaces +shown in the previous figure. Notice that the UI surface is the topmost layer +and that it contains a hole through which the external surface +can be seen.

            + A cross section through the surfaces, showing the display +output + +
            +
            Supported Uses

            You +can:

              +

            • Display an external +surface (for example, video content or a viewfinder image) within a window.

              • +

            • Dynamically set or remove +a background surface across multiple windows on the same screen without having +to register and unregister the surface. This reduces resource churn and content +transfer.

              • +

            • Reconfigure the attributes +of the surface such as its extent, viewport and orientation, after it is set +as a background.

              • +

            • Reposition the displayed +surface on the window.

              • +

            • Zoom in and out of the +contents of the surface.

              • +

            • Place the surface content +in a specified window area rather than filling the entire window.

              • +

            • Crop the surface content +rather than using the entire surface.

              • +

            • Rotate the contents +of the background surface by quadrant angles.

              • +

            • Flip the background +surface from top to bottom and rotate it by 180° to achieve a mirroring effect.

              • +

            The following diagrams shows some surface configuration use cases.

            + Surface configuration use cases + +
            +
            Configuration

            There +are a number of ways in which dynamically updated content can be configured +to appear on a window.

            A single content surface filling the window

            External +content can be fitted onto a Window Server window. Each axis of the surface +can be stretched independently of the other axis. The window must be a visible +client window: RWindow or RBlankWindow.

            Placement +of a single surface on a selected area of the window

            The position +and display size for the external content can be specified as an area within +the Window Server window, rather than filling the window. The window must +be a visible client (RWindow or RBlankWindow) +as before. You specify the area by using TSurfaceConfiguration::SetExtent(const +TRect& aExtent).

            After the extent is specified, +its size does not change if the window size changes but its position moves +to maintain its relative position on the window.

            Clipping of a +surface

            Video sometimes needs to appear cropped, so that a sub-area +of the video is displayed instead of the full image. The crop viewport is +specified in surface co-ordinates. The cropped viewport fills the output extent +(or the window when the extent is not specified). The content appears scaled +if the size of the viewport does not match the size of the extent (or the +window).

            Scaling

            It is possible to arbitrarily scale +a surface to user specifications using the extent and viewport features. Each +axis is scaled independently. When the extent and viewport are coincident, +no scaling occurs. Filtering can be applied by the implementation of stretching +and shrinking.

            Rotation

            The viewport can be displayed +rotated relative to its normal orientation. For example, if there is a fixed +camera on the front of a device and the device is rotated by 90°, the image +captured by the camera needs to be rotated by 90° in the other direction to +get the expected result. The orientation is always relative to the current +device orientation.

            Flipping

            An external surface can +be flipped from top to bottom around the x axis.

            Atomic combination +of these operations

            All the above mentioned configurations can +be specified and combined unambiguously for a particular content on a particular +window. You can specify parameters for a combination of these configurations +in a single operation.

            Changing surfaces

            The surface +assigned to a window can be changed.

            Reconfiguring

            It +is possible to change the configuration options applied to a surface without +re-assigning the surface.

            Sharing surfaces

            Content +surfaces are transferable and sharable between windows.

            The initial +registration step ensures that any resources allocated to the content surface +are held while the surface is removed from one window and added to another. +This reduces the likelihood of failure between operations.

            +
            API Summary

            This section provides a summary of +the classes and functions that you use to manage surfaces:

              +

            • RWindowBase

              • +

            • TSurfaceConfiguration

              • +

            • RWsSession

              • +
            +
            RWindowBase
              +

            • SetBackgroundSurface(const +TSurfaceConfiguration &,TBool) sets the background +of the window to be a given surface. The TSurfaceConfiguration argument +contains the surface ID and the configuration attributes. Another form of +the function simply takes a surface ID as an argument, which provides less +control and auto-stretches the surface to fill the window.

              • +

            • RemoveBackgroundSurface() removes +any background surface that has been set to the window.

              • +

            • GetBackgroundSurface() retrieves +a copy of the current configuration for the background surface attached to +the window.

              • +

            See RWindowBase.

            +
            TSurfaceConfiguration

            This +class encapsulates the surface configuration attributes that can be specified +while setting the background surface of a window. If the values for the attributes +are not set, the default values for the corresponding attribute are used.

            Symbian +recommends that the client validates the surface configuration data before +passing it on to the server. Invalid data that inadvertently slips through +the client-side validation mechanism, or maliciously bypasses it, causes a +panic.

            See TSurfaceConfiguration.

            +
            RWsSession
              +

            • RegisterSurface() registers +a surface for use in composition on the screen associated with this device +within this session.

              • +

            • UnregisterSurface() removes +the surface from the session’s register of surfaces that are used in composition +on the screen associated with this device.

              • +

            • PreferredSurfaceConfigurationSize() returns +the window server’s preferred size for the TSurfaceConfiguration object, +used for RWindow::SetBackgroundSurface().

              • +

            See RWsSession.

            +
            Example

            This code snippet is provided for illustrative +purposes only. A Window Server client application wants to run a 3D game full-screen +at the native physical resolution of the display (either current or selected +using a display controlling system application). This example assumes that +the MDisplayMapping interface has already been obtained, +as shown in Display +Control and Mapping in the Window Server Client.

            // Establish connection and get display mapping interface. +RWindowGroup group = RWindowGroup(iSession); +RWindow window(iSession); + +group.Construct(1, iScreenDevice); +window.Construct(group, 2); + +TRect winExtent; +iDisplayMapping.GetMaximumWindowExtent(winExtent); +window.SetExtent(winExtent); + +// Map window size to composition coordinates +TRect surfaceExtent; +iDisplayMapping.MapCoordinates(EApplicationSpace, winExtent, + ECompositionSpace, surfaceExtent); + +RSurfaceManager::TSurfaceCreationAttributes attribs; +attribs.iSize = surfaceExtent.Size(); + +// Set up other attributes and create surface + +window.SetBackgroundSurface(surface); + +window.Activate(); +

            A similar approach can be used by other surface content providers, +such as video.

            +             +Graphics +Composition + +Window Server +Client-Side Library Concepts +Dynamic Resolution +Switching +Flipping +and Rotating an External Surface             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-497AD33D-F6DC-52D4-85C8-B9E02978ACD4_d0e169416_href.jpg Binary file Symbian3/SDK/Source/GUID-497AD33D-F6DC-52D4-85C8-B9E02978ACD4_d0e169416_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-497AD33D-F6DC-52D4-85C8-B9E02978ACD4_d0e176017_href.jpg Binary file Symbian3/SDK/Source/GUID-497AD33D-F6DC-52D4-85C8-B9E02978ACD4_d0e176017_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4A5A50EB-261E-5739-904E-1D14D1A6BAD9_d0e177144_href.png Binary file Symbian3/SDK/Source/GUID-4A5A50EB-261E-5739-904E-1D14D1A6BAD9_d0e177144_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4A5A50EB-261E-5739-904E-1D14D1A6BAD9_d0e183738_href.png Binary file Symbian3/SDK/Source/GUID-4A5A50EB-261E-5739-904E-1D14D1A6BAD9_d0e183738_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4A66B46E-8A23-42E4-ADAD-B124A36B180A.dita --- a/Symbian3/SDK/Source/GUID-4A66B46E-8A23-42E4-ADAD-B124A36B180A.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-4A66B46E-8A23-42E4-ADAD-B124A36B180A.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,20 +1,41 @@ - - - - - -Showing -and hiding stylus pop-up menu -

            Use the method ShowMenu() in the class CAknStylusPopUpMenu to show the stylus pop-up menu.

            -

            How is the menu dismissed/hidden? -Automatically after a command has been selected or when the user taps outside -the menu?

            -

            Add sample code on showing and hiding -the menu here.

            + + + + + +Showing +and hiding stylus pop-up menu +

            Use the method ShowMenu() in the class CAknStylusPopUpMenu to show the stylus pop-up menu.

            +

            Usually, the pop-up menu must not be directly displayed in the HandlePointerEventL of +a CCoeControl. Use the CAknLongTapDetector +to handle the Llong Tap event and show the pop-up on the HandleLongTapEventL, +which is the implementation to the interface MAknLongTapDetectorCallBack.

            +

            The following code snippets illustrates how to show pop-up menu:

            +CAknLongTapDetector * iLongTapDetector; +// "this" implement the interface MAknLongTapDetectorCallBack +iLongTapDetector = CAknLongTapDetector::NewL( this ); + +// pass the process to the long tap detector +void XXXX::HandlePointerEventL( + const TPointerEvent& aPointerEvent) + { + iLongTapDetector->PointerEventL( aPointerEvent ); + // Call base class HandlePointerEventL() + CCoeControl::HandlePointerEventL(aPointerEvent); + } +// handle long tap detector event to show the stylus popup +void XXXX::HandleLongTapEventL( const TPoint& aPenEventLocation, const TPoint& aPenEventScreenLocation ) + { + iPopupMenu->SetPosition( + aPenEventScreenLocation , + CAknStylusPopUpMenu::EPositionTypeRightBottom ); + iPopupMenu->ShowMenu(); + } +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4AAABD77-C08E-5EE2-A02A-3B412EA6D23F.dita --- a/Symbian3/SDK/Source/GUID-4AAABD77-C08E-5EE2-A02A-3B412EA6D23F.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-4AAABD77-C08E-5EE2-A02A-3B412EA6D23F.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,76 +1,76 @@ - - - - - -Advanced -Audio Adaptation Framework Overview -

            This document introduces you to the Advanced Audio Adaptation Framework -(A3F) component.

            -
            Purpose

            A3F provides the interface between the -Symbian platform and the audio processing hardware for all audio functionality. -A3F is responsible for:

              -

            • Providing access to -all audio resources

              • -

            • Configuring audio hardware

              • -

            • Playing and recording -audio data

              • -

            • Playing tones.

              • -
            -
            Required background

            In order to use A3F, you should -be familiar with DevSound.

            -
            Architectural relationships

            A3F is a component -in the Sound Device collection. A3F provides a new standardised implementation -of DevSound which is configured by default from Symbian OS v9.5 onwards. A3F -interacts with a specially customised DevSound (configured as optional).

            Shown -below is a representation of how A3F interacts with DevSound and other components:

            - A3F and related components - -
            -
            Library summary

            A3F includes the following libraries:

            - - - -Library -Description - - - - -

            Audio Component Framework

            -

            The Audio Component Framework is responsible for creating audio -contexts.

            For more information, see Audio -Component Framework Overview.

            -             - -

            Audio Component Library

            -

            The Audio Component Library provides runtime control over audio -streams.

            For more information, see Audio -Component Library Overview.

            -             - - -
            -
            Typical uses

            You can use A3F to play tones, play -audio and record audio. The following list describes some of the steps involved -in playing and recording audio:

              -

            • Create a new audio context

              • -

            • Apply changes made to the audio processing units in a context

              • -

            • Configure hardware devices, for example, set sampling rate and channels to -use.

              • -

            • Play buffered audio data

              • -

            • Record audio data to buffers

              • -

            • Pause audio processing

              • -

            • Stop playing audio

              • -

            • Stop recording audio.

              • -
            -
            See also

            DevSound -Overview

            Multimedia -Framework Overview

            + + + + + +Advanced +Audio Adaptation Framework Overview +

            This document introduces you to the Advanced Audio Adaptation Framework +(A3F) component.

            +
            Purpose

            A3F provides the interface between the +Symbian platform and the audio processing hardware for all audio functionality. +A3F is responsible for:

              +

            • Providing access to +all audio resources

              • +

            • Configuring audio hardware

              • +

            • Playing and recording +audio data

              • +

            • Playing tones.

              • +
            +
            Required background

            In order to use A3F, you should +be familiar with DevSound.

            +
            Architectural relationships

            A3F is a component +in the Sound Device collection. A3F provides a new standardised implementation +of DevSound which is configured by default from Symbian OS v9.5 onwards. A3F +interacts with a specially customised DevSound (configured as optional).

            Shown +below is a representation of how A3F interacts with DevSound and other components:

            + A3F and related components + +
            +
            Library summary

            A3F includes the following libraries:

            + + + +Library +Description + + + + +

            Audio Component Framework

            +

            The Audio Component Framework is responsible for creating audio +contexts.

            For more information, see Audio +Component Framework Overview.

            +             + +

            Audio Component Library

            +

            The Audio Component Library provides runtime control over audio +streams.

            For more information, see Audio +Component Library Overview.

            +             + + +
            +
            Typical uses

            You can use A3F to play tones, play +audio and record audio. The following list describes some of the steps involved +in playing and recording audio:

              +

            • Create a new audio context

              • +

            • Apply changes made to the audio processing units in a context

              • +

            • Configure hardware devices, for example, set sampling rate and channels to +use.

              • +

            • Play buffered audio data

              • +

            • Record audio data to buffers

              • +

            • Pause audio processing

              • +

            • Stop playing audio

              • +

            • Stop recording audio.

              • +
            +
            See also

            DevSound +Overview

            Multimedia +Framework Overview

            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4ADD8234-4AFD-4E80-94A4-AC018FE83276.dita --- a/Symbian3/SDK/Source/GUID-4ADD8234-4AFD-4E80-94A4-AC018FE83276.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-4ADD8234-4AFD-4E80-94A4-AC018FE83276.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,121 +1,121 @@ - - - - - -Differences -between OSS and Symbian GLib -

            The three areas of difference between the way GLib is implemented in Symbian -platform and in OSS are as follows:

            -
              -

            • Memory allocation

              • -

            • Spawn APIs

              • -

            • Libgmodule APIs

              • -
            -
            Memory -allocation

            The Symbian GLib implementation does not follow -the default OSS behavior. The default OSS behavior is such that in the event -of a memory allocation failure the application, using g_malloc() and -not g_try_malloc(), will call abort() and -thus terminate the application.

            The Symbian implementation, on the -other hand will return NULL and not terminate the application in the event -of a memory allocation failure. Thus, it is the application’s responsibility -to check if the memory allocation failed due to the needed tasks.

            Generally, -all the application code written using GLib does not perform memory allocation -failure checks. Hence, for Symbian GLib it is the application programmer's -responsibility to check for memory allocation failures.

            -
            Spawn -APIs

            GLib has a set of APIs for process spawning. Since Symbian -platform does not support the fork() and exec() APIs, -the g_spawn* APIs have limitations in their functionality. -The limitations are explained per API in detail below.

            g_spawn_async_with_pipes

            The -signature of this API is:

            gboolean g_spawn_async_with_pipes ( - const gchar *working_directoy, - gchar **argv, - gchar **envp, - GSpawnFlags flags, - GSpawnChildSetupFunc child_setup, - gpointer user_data, - GPid *child_pid, - gint *standard_input, - gint *standard_output, - gint *standard_error, - GError **error);

            This API executes the program asynchronously: -that is, the caller does not block for the spawned process to complete. The -setting of the following parameters does not have any effect in Symbian GLib:

              -

            • working_directory

              • -

            • envp

              • -

            If a value other than NULL is passed for standard_input, standard_ouput, -or standard_error, the value at the location is set to -1.

            g_spawn_async

            The -signature of the API is:

            gboolean g_spawn_async ( - const gchar *working_directory, - gchar **argv, - gchar **envp, - GSpawnFlags flags, - GSpawnChildSetupFunc child_setup, - gpointer user_data, - GPid *child_pid, - GError **error);

            This API calls g_spawn_async_with_pipes without -any pipes. The setting of the following parameters does not have any effect -in Symbian GLib:

              -

            • working_directory

              • -

            • envp

              • -

            g_spawn_sync

            The signature of the API -is:

            gboolean g_spawn_sync( - const gchar *working_directory, - gchar **argv, - gchar **envp, - GSpawnFlags flags, - GSpawnChildSetupFunc child_setup, - gpointer user_data, - gchar **standard_output, - gchar **standard_error, - gint *exit_status, - GError **error);

            This API executes the program synchronously: -that is, the calling process waits for the spawned process to complete before -returning. The setting of the following parameters does not have any effect -on Symbian GLib:

              -

            • working_directory

              • -

            • envp

              • -

            If a value other than NULL is passed for standard_output or standard_error, -the value at the location is set to -1.

            g_spawn_command_line_sync

            The -signature of the API is:

            gboolean g_spawn_command_line_sync( - const gchar *command_line, - gchar **standard_output, - gchar **standard_error, - gint *exit_status, - GError **error);

            This API is a simple version of g_spawn_sync in -which there are fewer number of parameters involved, and it takes a command -line instead.

            If a value other than NULL is passed for standard_output or standard_error, -the value at the location is set to -1.

            In many spawn APIs a variable -of type GSpawnFlags is passed. The following flags have no -effect:

              -

            • G_SPAWN_LEAVE_DESCRIPTORS_OPEN

              • -

            • G_SPAWN_STDOUT_TO_DEV_NULL

              • -

            • G_SPAWN_STDERR_TO_DEV_NULL

              • -

            • G_SPAWN_CHILD_INHERITS_STDIN

              • -
            -
            Libgmodule -APIs

            Libgmodule has APIs that provide a portable method for dynamically -loading 'plug-ins' or, in other words, DLLs. There are some deviations in -the libgmodule APIs on Symbian platform as compared to the -OSS behavior. The APIs with their limitations are explained in detail below.

              -

            • g_module_open: The signature of the API is:

              GModule *g_module_open (const gchar *file_name, GModuleFlags flags);

              This API is used to open a module. The default OSS behavior when file_name -is passed as NULL such that it obtains a GModule representing -the main program. In Symbian GLib, NULL is returned instead. Of all the GModuleFlags only G_MODULE_BIND_LOCAL is -honored. If the user passes any other flags, the module is still opened using -the flag G_MODULE_BIND_LOCAL.

              • -

            • g_module_symbol: The signature of the API is:

              gboolean g_module_symbol (GModule *module, const gchar *symbol_name, gpointer *symbol);

              This API gets the symbol from the GModule opened using g_module_open. -In OSS, symbol_name is the name of the symbol that needs -to be queried from the GModule. In Symbian platform, the -ordinal number (passed as a string) of the symbol name must be passed and -not the symbol name.

              • -

            See also Introduction -to libgmodule for more details about libgmodule.

            + + + + + +Differences +between OSS and Symbian GLib +

            The three areas of difference between the way GLib is implemented in Symbian +platform and in OSS are as follows:

            +
              +

            • Memory allocation

              • +

            • Spawn APIs

              • +

            • Libgmodule APIs

              • +
            +
            Memory +allocation

            The Symbian GLib implementation does not follow +the default OSS behavior. The default OSS behavior is such that in the event +of a memory allocation failure the application, using g_malloc() and +not g_try_malloc(), will call abort() and +thus terminate the application.

            The Symbian implementation, on the +other hand will return NULL and not terminate the application in the event +of a memory allocation failure. Thus, it is the application’s responsibility +to check if the memory allocation failed due to the needed tasks.

            Generally, +all the application code written using GLib does not perform memory allocation +failure checks. Hence, for Symbian GLib it is the application programmer's +responsibility to check for memory allocation failures.

            +
            Spawn +APIs

            GLib has a set of APIs for process spawning. Since Symbian +platform does not support the fork() and exec() APIs, +the g_spawn* APIs have limitations in their functionality. +The limitations are explained per API in detail below.

            g_spawn_async_with_pipes

            The +signature of this API is:

            gboolean g_spawn_async_with_pipes ( + const gchar *working_directoy, + gchar **argv, + gchar **envp, + GSpawnFlags flags, + GSpawnChildSetupFunc child_setup, + gpointer user_data, + GPid *child_pid, + gint *standard_input, + gint *standard_output, + gint *standard_error, + GError **error);

            This API executes the program asynchronously: +that is, the caller does not block for the spawned process to complete. The +setting of the following parameters does not have any effect in Symbian GLib:

              +

            • working_directory

              • +

            • envp

              • +

            If a value other than NULL is passed for standard_input, standard_ouput, +or standard_error, the value at the location is set to -1.

            g_spawn_async

            The +signature of the API is:

            gboolean g_spawn_async ( + const gchar *working_directory, + gchar **argv, + gchar **envp, + GSpawnFlags flags, + GSpawnChildSetupFunc child_setup, + gpointer user_data, + GPid *child_pid, + GError **error);

            This API calls g_spawn_async_with_pipes without +any pipes. The setting of the following parameters does not have any effect +in Symbian GLib:

              +

            • working_directory

              • +

            • envp

              • +

            g_spawn_sync

            The signature of the API +is:

            gboolean g_spawn_sync( + const gchar *working_directory, + gchar **argv, + gchar **envp, + GSpawnFlags flags, + GSpawnChildSetupFunc child_setup, + gpointer user_data, + gchar **standard_output, + gchar **standard_error, + gint *exit_status, + GError **error);

            This API executes the program synchronously: +that is, the calling process waits for the spawned process to complete before +returning. The setting of the following parameters does not have any effect +on Symbian GLib:

              +

            • working_directory

              • +

            • envp

              • +

            If a value other than NULL is passed for standard_output or standard_error, +the value at the location is set to -1.

            g_spawn_command_line_sync

            The +signature of the API is:

            gboolean g_spawn_command_line_sync( + const gchar *command_line, + gchar **standard_output, + gchar **standard_error, + gint *exit_status, + GError **error);

            This API is a simple version of g_spawn_sync in +which there are fewer number of parameters involved, and it takes a command +line instead.

            If a value other than NULL is passed for standard_output or standard_error, +the value at the location is set to -1.

            In many spawn APIs a variable +of type GSpawnFlags is passed. The following flags have no +effect:

              +

            • G_SPAWN_LEAVE_DESCRIPTORS_OPEN

              • +

            • G_SPAWN_STDOUT_TO_DEV_NULL

              • +

            • G_SPAWN_STDERR_TO_DEV_NULL

              • +

            • G_SPAWN_CHILD_INHERITS_STDIN

              • +
            +
            Libgmodule +APIs

            Libgmodule has APIs that provide a portable method for dynamically +loading 'plug-ins' or, in other words, DLLs. There are some deviations in +the libgmodule APIs on Symbian platform as compared to the +OSS behavior. The APIs with their limitations are explained in detail below.

              +

            • g_module_open: The signature of the API is:

              GModule *g_module_open (const gchar *file_name, GModuleFlags flags);

              This API is used to open a module. The default OSS behavior when file_name +is passed as NULL such that it obtains a GModule representing +the main program. In Symbian GLib, NULL is returned instead. Of all the GModuleFlags only G_MODULE_BIND_LOCAL is +honored. If the user passes any other flags, the module is still opened using +the flag G_MODULE_BIND_LOCAL.

              • +

            • g_module_symbol: The signature of the API is:

              gboolean g_module_symbol (GModule *module, const gchar *symbol_name, gpointer *symbol);

              This API gets the symbol from the GModule opened using g_module_open. +In OSS, symbol_name is the name of the symbol that needs +to be queried from the GModule. In Symbian platform, the +ordinal number (passed as a string) of the symbol name must be passed and +not the symbol name.

              • +

            See also Introduction +to libgmodule for more details about libgmodule.

            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4B4110D9-0CAA-5CA1-A994-9DAF501119E4_d0e240294_href.png Binary file Symbian3/SDK/Source/GUID-4B4110D9-0CAA-5CA1-A994-9DAF501119E4_d0e240294_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4B4110D9-0CAA-5CA1-A994-9DAF501119E4_d0e244031_href.png Binary file Symbian3/SDK/Source/GUID-4B4110D9-0CAA-5CA1-A994-9DAF501119E4_d0e244031_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4B709839-8EEF-4AD2-9868-9AF0176B1E5B.dita --- a/Symbian3/SDK/Source/GUID-4B709839-8EEF-4AD2-9868-9AF0176B1E5B.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-4B709839-8EEF-4AD2-9868-9AF0176B1E5B.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,75 +1,75 @@ - - - - - -Using -Sensor Channels APIsThe Sensor Channel establishes a data exchange connection between -the sensor framework and hardware using the sensor channel APIs. - -Include the library SensrvClient.lib in -your .mmp file. - -Include the following -header files, as they are required for accessing sensor channels regardless -of the channel type: -
              -

            • sensrvchannel.h

              • -

            • sensrvchannelinfo.h

              • -

            • sensrvtypes.h

              • -

            • sensrvchannelfinder.h

              • -

            • sensrvdatalistener.h

              • -
             -             -Retrieve details -about the required sensor channel. For details. see Querying -for Sensor Channels. - -Connect to the sensor -by opening a connection with the sensor channel. - -Create an instance -of CSensrvChannel and specify the instance of TSensrvChannelInfo returned -by CSensrvChannelFinder::FindChannelsL(), as a parameter -in the NewL() constructor. - CSensrvChannel* sensorChannel; - sensorChannel = CSensrvChannel::NewL(channelInfoList[0]);// channelInfoList is -// returned by the CSensrvChannelFinder::FindChannelsL()funtion - -Open the sensor -channel using CSensrvChannel::OpenChannelL() function. -channel->OpenChannelL(); - - - -Perform any of the -following operations: -
              -
            • Receive data from -sensors
              • -
            • Listen for channel -changes
              • -
            • Retrieve channel -properties
              • -
            • Set channel properties
              • -
            • Listen for channel -property changes
              • -
            • Receive channel -data based on conditions
              • -
             -             -Close the channel. -channel->CloseChannel(); A -channel must be closed when not required, as it reduces power consumption -of the Symbian device. An open sensor channel keeps the device processor active -each time data arrives. Therefore, the processor does not change to idle state -even when the device user is not performing any operations on the device. - -             + + + + + +Using +Sensor Channels APIsThe Sensor Channel establishes a data exchange connection between +the sensor framework and hardware using the sensor channel APIs. + +Include the library SensrvClient.lib in +your .mmp file. + +Include the following +header files, as they are required for accessing sensor channels regardless +of the channel type: +
              +

            • sensrvchannel.h

              • +

            • sensrvchannelinfo.h

              • +

            • sensrvtypes.h

              • +

            • sensrvchannelfinder.h

              • +

            • sensrvdatalistener.h

              • +
             +             +Retrieve details +about the required sensor channel. For details. see Querying +for Sensor Channels. + +Connect to the sensor +by opening a connection with the sensor channel. + +Create an instance +of CSensrvChannel and specify the instance of TSensrvChannelInfo returned +by CSensrvChannelFinder::FindChannelsL(), as a parameter +in the NewL() constructor. + CSensrvChannel* sensorChannel; + sensorChannel = CSensrvChannel::NewL(channelInfoList[0]);// channelInfoList is +// returned by the CSensrvChannelFinder::FindChannelsL()funtion + +Open the sensor +channel using CSensrvChannel::OpenChannelL() function. +channel->OpenChannelL(); + + + +Perform any of the +following operations: +
              +
            • Receive data from +sensors
              • +
            • Listen for channel +changes
              • +
            • Retrieve channel +properties
              • +
            • Set channel properties
              • +
            • Listen for channel +property changes
              • +
            • Receive channel +data based on conditions
              • +
             +             +Close the channel. +channel->CloseChannel(); A +channel must be closed when not required, as it reduces power consumption +of the Symbian device. An open sensor channel keeps the device processor active +each time data arrives. Therefore, the processor does not change to idle state +even when the device user is not performing any operations on the device. + +                         \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4B7FA629-BFC9-594B-B253-AC920EAD6E67_d0e79196_href.png Binary file Symbian3/SDK/Source/GUID-4B7FA629-BFC9-594B-B253-AC920EAD6E67_d0e79196_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4B7FA629-BFC9-594B-B253-AC920EAD6E67_d0e85908_href.png Binary file Symbian3/SDK/Source/GUID-4B7FA629-BFC9-594B-B253-AC920EAD6E67_d0e85908_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4BC95F70-2F3F-5CFE-B057-0C5A97430573_d0e190311_href.png Binary file Symbian3/SDK/Source/GUID-4BC95F70-2F3F-5CFE-B057-0C5A97430573_d0e190311_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4BC95F70-2F3F-5CFE-B057-0C5A97430573_d0e195319_href.png Binary file Symbian3/SDK/Source/GUID-4BC95F70-2F3F-5CFE-B057-0C5A97430573_d0e195319_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4BCE7915-6BF9-5D83-9049-B7FA9725B406_d0e221356_href.png Binary file Symbian3/SDK/Source/GUID-4BCE7915-6BF9-5D83-9049-B7FA9725B406_d0e221356_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4BCE7915-6BF9-5D83-9049-B7FA9725B406_d0e225093_href.png Binary file Symbian3/SDK/Source/GUID-4BCE7915-6BF9-5D83-9049-B7FA9725B406_d0e225093_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4BDC9F63-83A1-53A5-91A0-B092AA821755.dita --- a/Symbian3/SDK/Source/GUID-4BDC9F63-83A1-53A5-91A0-B092AA821755.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-4BDC9F63-83A1-53A5-91A0-B092AA821755.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,106 +1,110 @@ - - - - - -MakeSIS

            The MakeSIS tool generates unsigned Software -Installation (SIS) files based on the information provided in package (PKG) -files.

             -Syntax

            makesis [OPTIONS] <ARGS>

            The -following table lists the options supported by the MakeSIS tool.

            - - - -Options -Description -Usage - - - - -

            -h

            -

            Displays the help for PKG file format.

            -

            makesis [-h]

            -             - -

            -i

            -

            Displays the Open SSL licence.

            -

            makesis [-i]

            -             - -

            -v

            -

            Displays verbose output.

            -

            makesis [-v]

            -             - -

            -s

            -

            Generates a ROM stub file. See Notes for more information.

            -

            makesis [-s] [-d directory] pkgfile

            -             - -

            -c

            -

            Reports an error if the generated SIS file is not compatible with -the InterpretSIS tool for preinstall.

            -

            makesis [-c] [-d directory] pkgfile

            -             - - -

            The following table lists the arguments to be specified with the MakeSIS tool.

            - - - -Arguments -Description - - - - -

            -d directory

            -

            Specifies absolute paths in PKG files or paths relative to the current -directory.

            -             - -

            pkgfile

            -

            Specifies the PKG file, for which a SIS file is generated.

            -             - -

            sisfile

            -

            Specifies the name of the generated SIS file.

            If not specified, -the output SIS filename is derived from the name of the PKG file, but with -a SIS file extension.

            -             - - -
             -
            Notes
              -

            • A stub SIS file is created -by the software installer on the Symbian device after a package has been installed. -It details which files were installed and where, and is used when uninstalling -and upgrading the package. For pre-installed applications in ROM, makesis --s can be used to create a stub SIS file.

              Stub files that -are created, contain a fixed date/time stamp of 2004/01/01 00:00.

              • -

            • You can use the –d argument -with the EPOCROOT environment variable to avoid using absolute -paths in PKG files or relative paths to the current directory.

              By -default, binaries are built to the epoc32 tree. So, if -files are described in the PKG file as, for example:

              "epoc32\release\armv5\urel\HelloWorld.exe"-"!:\sys\bin\HelloWorld.exe" -"epoc32\release\armv5\urel\z\resource\apps\HelloWorld.rsc"-"!:\resource\apps\HelloWorld.rsc"

              then MakeSIS can -be invoked from any location using:

              makesis -d%EPOCROOT% -HelloWorld.pkg

              • -
            -             -PKG Format - -SignSIS - -CreateSIS - -Creating -and Signing an Installation File + + + + + +MakeSIS

            The MakeSIS tool generates unsigned Software +Installation (SIS) files based on the information provided in package (PKG) +files.

             +Syntax

            makesis [OPTIONS] <ARGS>

            The following table lists the options supported by +the MakeSIS tool.

            + + + +Options +Description +Usage + + + + +

            -h

            +

            Displays the help for PKG file format.

            +

            makesis [-h]

            +             + +

            -i

            +

            Displays the Open SSL licence.

            +

            makesis [-i]

            +             + +

            -v

            +

            Displays verbose output.

            +

            makesis [-v]

            +             + +

            -s

            +

            Generates a ROM stub file. See Notes for more information.

            +

            makesis [-s] [-d directory] pkgfile

            +             + +

            -c

            +

            Reports an error if the generated SIS file is not compatible with +the InterpretSIS tool for preinstall.

            +

            makesis [-c] [-d directory] pkgfile

            +             + + +

            The following table lists the arguments to be specified with the MakeSIS tool.

            + + + +Arguments +Description + + + + +

            -d directory

            +

            Specifies absolute paths in PKG files or paths relative to the current +directory.

            +             + +

            pkgfile

            +

            Specifies the PKG file, for which a SIS file is generated.

            +             + +

            sisfile

            +

            Specifies the name of the generated SIS file.

            If not specified, +the output SIS filename is derived from the name of the PKG file, but with +a SIS file extension.

            +             + + +
             +
            Notes
              +

            • A stub SIS file is created +by the software installer on the Symbian device after a package has been installed. +It details which files were installed and where, and is used when uninstalling +and upgrading the package. For pre-installed applications in ROM, makesis +-s can be used to create a stub SIS file.

              Stub files that +are created, contain a fixed date/time stamp of 2004/01/01 00:00.

              • +

            • You can use the –d argument +with the EPOCROOT environment variable to avoid using absolute +paths in PKG files or relative paths to the current directory.

              By +default, binaries are built to the epoc32 tree. So, if +files are described in the PKG file as, for example:

              "epoc32\release\armv5\urel\HelloWorld.exe"-"!:\sys\bin\HelloWorld.exe" +"epoc32\release\armv5\urel\z\resource\apps\HelloWorld.rsc"-"!:\resource\apps\HelloWorld.rsc"

              then MakeSIS can +be invoked from any location using:

              makesis -d%EPOCROOT% +HelloWorld.pkg

              • +

            • MakeSIS can parse PKG files that are in UTF8 or UNICODE +formats. It supports both little-endian and big-endian UNICODE files.

              MakeSIS does +not convert text files to any other format; it packages them as-is into the +SIS files.
              • +
            +             +PKG Format + +SignSIS + +CreateSIS + +Creating +and Signing an Installation File             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4BEFF7BA-2A39-5601-919E-22AF08D06023.dita --- a/Symbian3/SDK/Source/GUID-4BEFF7BA-2A39-5601-919E-22AF08D06023.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-4BEFF7BA-2A39-5601-919E-22AF08D06023.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,189 +1,189 @@ - - - - - -Zip -Compression Library OverviewThe Zip Compression Library, EZLib, provides stream and file compression -and decompression functionality for the Symbian platforms. -

            EZLib provides classes to handle the file, stream and buffer requirements -of zlib. It provides native Symbian APIs that access the zlib compression -algorithms and it exports some zlib and gzio C APIs from libz.dll. EZLib can -operate on streams, flat zip files (zlib format) and gzip files.

            -
            Purpose

            EZLib facilitates:

              -

            • Compression and decompression -of memory streams

              • -

            • Compression and decompression -of files

              • -

            • Decompression of file -archives of gzip format

              • -
            -
            Required background

            You must be familiar with zlib, -gzip compression and decompression formats and Deflate algorithms. You can -find further information about each of these on the IETF (Internet Engineering -Task Force) website.

            RFC1950- zlib format

            RFC1951-Deflate algorithm

            RFC1952-gzip format

            -
            Key concepts and terms
            - -
            zlib
            -

            zlib format is an open standard for lossless compressed data. It can -be implemented using a number of alternative compression algorithms.

            -             - -
            Compression
            -

            Data compression is a process of encoding information using fewer bits -(or other information-bearing units) using specific encoding algorithms.

            -             - -
            Decompression
            -

            Decompression is the process of reconverting compressed data into its -original (or nearly original) form.

            -             - -
            Stream
            -

            A stream is an abstraction that represents a device on which input -and ouput operations are performed. A stream can be considered as a source -or destination of characters of indefinite length. A stream can be accessed -only in sequence.

            -             - -
            gzip File Format
            -

            gzip is normally used to compress single files. Deflate is the compression -algorithm used.

            -             - -
            gzio
            -

            gzio APIs are input amd output functions for gzip format.

            -             - -
            zip Format
            -

            The zip file format is both data compression and archive. A zip file -contains one or more files that have been compressed where possible to reduce -file size. The zip file format permits a number of compression algorithms -but only Deflate is widely used and supported.

            -             -
            -
            Architecture

            The Zip Compression Library (EZLib) -provides C++ wrapper classes that encapsulate the functionality of version -1.2.3 of the zlib library. zlib and gzio APIs are written in C. The core functionality -is performed by a core library (libzcore.dll).

            EZLib provides three -DLLs which encapsulate the core functionality in Symbian C++ and Open Environment -APIs.

              -

            • LIBZ.DLL: This is an -Open Environment library that provides the zlib and gzio C APIs. The APIs -can be used to compress and decompress zlib and gzip file formats.

              • -

            • EZLIB.DLL: This provides -Symbian C++ wrappers for the zlib compression and decompression APIs. It offers -buffer, stream and gzip file handling classes. It also exports the C API interface -provided by LIBZ.DLL with the exception of the gzio APIs. This library can -be used to compress and decompress zlib and gzip file formats and memory streams.

              • -

            • EZIP.DLL: This provides -Symbian C++ APIs for reading from and decompressing zip archives. It cannot -be used to compress archives to zip archives.

              • -
            - EZLib Architecture - -
            -
            APIs

            The classes exported from ezlib.dll are -tabulated below:

            - - - -API -Description - - - - -

            CEZCompressor

            -

            Provides wrapper for ‘compress’ and ‘Deflate’ zlib APIs.

            -             - -

            CEZDecompressor

            -

            Provides wrapper for ‘uncompress’ and ‘inflate’ zlib APIs.

            -             - -

            CEZFileBufferManager

            -

            Provides basic file handling for CEZCompressor and CEZDecompressor -classes.

            -             - -

            CEZFileToGZip

            -

            Provides implementation to compress an uncompressed file to a gzip -file.

            -             - -

            CEZFileToGzipBM

            -

            Provides buffer management class for CEZFileToGZip.

            -             - -

            CEZGZipToFile

            -

            Provides implementation to uncompress a gzip file to an output file.

            -             - -

            CEZGzipToFileBM

            -

            Provides buffer management class for CEZGzipToFile.

            -             - -

            CEZZStream

            -

            Provides stream handling.

            -             - -

            MEZBufferManager

            -

            Pure virtual interface class. CEZFileBufferManager derives from -this class.

            -             - - -

            The classes exported from ezip.dll are tabulated -below:

            - - - -API -Description - - - - -

            CZipArchive

            -

            Represents a zip archive and defines all relevant enumerations and -structures.

            -             - -

            CZipFile

            -

            Represents a zip archive contained in a single file.

            -             - -

            CZipFileMember

            -

            Represents a compressed file contained in a CZipFile archive file.

            -             - -

            CZipFileMemberIterator

            -

            Allows iteration through all the entries of an archive.

            -             - -

            RZipFileMemberReaderStream

            -

            Represents an input stream for compressed files in an archive.

            -             - - -

            libz.dll provides the C open environment -and hybrid applications to support the zlib library.

            -
            Typical uses

            The typical uses of -the ZIP Compression Library are:

              -

            • Compression -and decompression of files(gzip)

              • -

            • Compression -and decompression of files(zip)

              • -

            • Compression -and decompression of memory streams

              • -

            • Decompression -of file archives

              • -
            + + + + + +Zip +Compression Library OverviewThe Zip Compression Library, EZLib, provides stream and file compression +and decompression functionality for the Symbian platforms. +

            EZLib provides classes to handle the file, stream and buffer requirements +of zlib. It provides native Symbian APIs that access the zlib compression +algorithms and it exports some zlib and gzio C APIs from libz.dll. EZLib can +operate on streams, flat zip files (zlib format) and gzip files.

            +
            Purpose

            EZLib facilitates:

              +

            • Compression and decompression +of memory streams

              • +

            • Compression and decompression +of files

              • +

            • Decompression of file +archives of gzip format

              • +
            +
            Required background

            You must be familiar with zlib, +gzip compression and decompression formats and Deflate algorithms. You can +find further information about each of these on the IETF (Internet Engineering +Task Force) website.

            RFC1950- zlib format

            RFC1951-Deflate algorithm

            RFC1952-gzip format

            +
            Key concepts and terms
            + +
            zlib
            +

            zlib format is an open standard for lossless compressed data. It can +be implemented using a number of alternative compression algorithms.

            +             + +
            Compression
            +

            Data compression is a process of encoding information using fewer bits +(or other information-bearing units) using specific encoding algorithms.

            +             + +
            Decompression
            +

            Decompression is the process of reconverting compressed data into its +original (or nearly original) form.

            +             + +
            Stream
            +

            A stream is an abstraction that represents a device on which input +and ouput operations are performed. A stream can be considered as a source +or destination of characters of indefinite length. A stream can be accessed +only in sequence.

            +             + +
            gzip File Format
            +

            gzip is normally used to compress single files. Deflate is the compression +algorithm used.

            +             + +
            gzio
            +

            gzio APIs are input amd output functions for gzip format.

            +             + +
            zip Format
            +

            The zip file format is both data compression and archive. A zip file +contains one or more files that have been compressed where possible to reduce +file size. The zip file format permits a number of compression algorithms +but only Deflate is widely used and supported.

            +             +
            +
            Architecture

            The Zip Compression Library (EZLib) +provides C++ wrapper classes that encapsulate the functionality of version +1.2.3 of the zlib library. zlib and gzio APIs are written in C. The core functionality +is performed by a core library (libzcore.dll).

            EZLib provides three +DLLs which encapsulate the core functionality in Symbian C++ and Open Environment +APIs.

              +

            • LIBZ.DLL: This is an +Open Environment library that provides the zlib and gzio C APIs. The APIs +can be used to compress and decompress zlib and gzip file formats.

              • +

            • EZLIB.DLL: This provides +Symbian C++ wrappers for the zlib compression and decompression APIs. It offers +buffer, stream and gzip file handling classes. It also exports the C API interface +provided by LIBZ.DLL with the exception of the gzio APIs. This library can +be used to compress and decompress zlib and gzip file formats and memory streams.

              • +

            • EZIP.DLL: This provides +Symbian C++ APIs for reading from and decompressing zip archives. It cannot +be used to compress archives to zip archives.

              • +
            + EZLib Architecture + +
            +
            APIs

            The classes exported from ezlib.dll are +tabulated below:

            + + + +API +Description + + + + +

            CEZCompressor

            +

            Provides wrapper for ‘compress’ and ‘Deflate’ zlib APIs.

            +             + +

            CEZDecompressor

            +

            Provides wrapper for ‘uncompress’ and ‘inflate’ zlib APIs.

            +             + +

            CEZFileBufferManager

            +

            Provides basic file handling for CEZCompressor and CEZDecompressor +classes.

            +             + +

            CEZFileToGZip

            +

            Provides implementation to compress an uncompressed file to a gzip +file.

            +             + +

            CEZFileToGzipBM

            +

            Provides buffer management class for CEZFileToGZip.

            +             + +

            CEZGZipToFile

            +

            Provides implementation to uncompress a gzip file to an output file.

            +             + +

            CEZGzipToFileBM

            +

            Provides buffer management class for CEZGzipToFile.

            +             + +

            CEZZStream

            +

            Provides stream handling.

            +             + +

            MEZBufferManager

            +

            Pure virtual interface class. CEZFileBufferManager derives from +this class.

            +             + + +

            The classes exported from ezip.dll are tabulated +below:

            + + + +API +Description + + + + +

            CZipArchive

            +

            Represents a zip archive and defines all relevant enumerations and +structures.

            +             + +

            CZipFile

            +

            Represents a zip archive contained in a single file.

            +             + +

            CZipFileMember

            +

            Represents a compressed file contained in a CZipFile archive file.

            +             + +

            CZipFileMemberIterator

            +

            Allows iteration through all the entries of an archive.

            +             + +

            RZipFileMemberReaderStream

            +

            Represents an input stream for compressed files in an archive.

            +             + + +

            libz.dll provides the C open environment +and hybrid applications to support the zlib library.

            +
            Typical uses

            The typical uses of +the ZIP Compression Library are:

              +

            • Compression +and decompression of files(gzip)

              • +

            • Compression +and decompression of files(zip)

              • +

            • Compression +and decompression of memory streams

              • +

            • Decompression +of file archives

              • +
             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4BF48607-54F0-51C8-A3A8-F334454FAC9C_d0e195578_href.png Binary file Symbian3/SDK/Source/GUID-4BF48607-54F0-51C8-A3A8-F334454FAC9C_d0e195578_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4BF48607-54F0-51C8-A3A8-F334454FAC9C_d0e200586_href.png Binary file Symbian3/SDK/Source/GUID-4BF48607-54F0-51C8-A3A8-F334454FAC9C_d0e200586_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4C0590C6-11D5-494F-B985-A9D651A1D4E8.dita --- a/Symbian3/SDK/Source/GUID-4C0590C6-11D5-494F-B985-A9D651A1D4E8.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-4C0590C6-11D5-494F-B985-A9D651A1D4E8.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,30 +1,31 @@ - - - - - -Viewers -

            The scrolling indicators are used to provide information about possible -browsing directions (up and down) and position inside the document. Refer -to Scrollbar for -more information on scrolling.

            -

            Applications can choose to allow selecting text from viewers. This works -in any text selection with touch, touch down, move, and touch release over -a block of text. Touch release event launches stylus pop-up menu with text -copy §QTN_STYLUS_POPUP_COPY§ is displayed.

            -

            Tactile:

              -

            • Sensitive edit is provided with touch down event.

              • -

            • Text edit effect is given while selecting letters.

              • -

            • Blank edit effect given while selecting blank space.

              • -

            • Line edit given while selecting lines.

              • -

            • Empty line effect given while selecting empty line.

              • -

            • Pop-up open effect given with touch down after selecting.

              • -

            • Sensitive list effect given when user touches down Copy §QTN_STYLUS_POPUP_COPY

              • -

            + + + + + +Text +views +

            The scrolling indicators are used to provide information about possible +browsing directions (up and down) and position inside the document. Refer +to Scrollbar for +more information on scrolling.

            +

            Applications can choose to allow selecting text from viewers. This works +in any text selection with touch, touch down, move, and touch release over +a block of text. Touch release event launches stylus pop-up menu with copied +text being displayed.

            +

            Tactile:

              +

            • Sensitive edit is provided with touch down event.

              • +

            • Text edit effect is given while selecting letters.

              • +

            • Blank edit effect given while selecting blank space.

              • +

            • Line edit given while selecting lines.

              • +

            • Empty line effect given while selecting empty line.

              • +

            • Pop-up open effect given with touch down after selecting.

              • +

            • Sensitive list effect given when user touches down copy.

              • +

             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4C6B9697-B69C-49D5-AD23-D7C0053BED3A_d0e3498_href.png Binary file Symbian3/SDK/Source/GUID-4C6B9697-B69C-49D5-AD23-D7C0053BED3A_d0e3498_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4C6B9697-B69C-49D5-AD23-D7C0053BED3A_d0e4773_href.png Binary file Symbian3/SDK/Source/GUID-4C6B9697-B69C-49D5-AD23-D7C0053BED3A_d0e4773_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4C859177-7B45-4569-9E27-B207300A7A1C-master.png Binary file Symbian3/SDK/Source/GUID-4C859177-7B45-4569-9E27-B207300A7A1C-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4C859177-7B45-4569-9E27-B207300A7A1C_d0e40663_href.png Binary file Symbian3/SDK/Source/GUID-4C859177-7B45-4569-9E27-B207300A7A1C_d0e40663_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4C859177-7B45-4569-9E27-B207300A7A1C_d0e46220_href.png Binary file Symbian3/SDK/Source/GUID-4C859177-7B45-4569-9E27-B207300A7A1C_d0e46220_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4C9C236D-71A7-5A5D-8C1C-F574DA604AF6.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-4C9C236D-71A7-5A5D-8C1C-F574DA604AF6.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,89 @@ + + + + + + Asymmetric +ciphers -- HowTo +
            How do I use +the asymmetric cryptographic framework?

            The asymmetric cryptographic +framework consists of the following logically separate concepts:

              +

            1. Key storage classes +(For instance, CRSAPublicKey, CDSAPrivateKey)

              2. +

            2. Cipher transformation +classes (CRSAPKCS1v15Encryptor, CDSASigner)

              3. +

            3. Signature representative +classes (CRSASignature, CDSASignature)

              4. +

            The first and third are simply containers for their respective concepts. +Each implementation of item two is responsible for performing one of the four +primitive operations on some data using a key specified at construction. If +the operation is signing or verification, then the transformation outputs +a signature representative class. On the other hand, in the case of encryption +or decryption, input and output consist of binary descriptor data.

            Before +showing some example code, an important note about object ownership. In general, +unless otherwise stated, the following three rules apply.

              +

            1. All key storage and +signature representative constructors take ownership of objects given +to them (typically RInteger s).

              2. +

            2. All cipher transformation +classes only use objects given to them (typically key storage classes, +signature representatives, and descriptors).

              3. +

            3. Any functions that return +pointers to objects (typically the Signer classes) transfer ownership of +the returned object to the caller.

              4. +

            Sample +code for encryption/decryption

            The following code illustrates +how to encrypt data using an RSA PKCS#1 v1.5 encryptor. It assumes you already +have access to the CRSAPublicKey you wish to encrypt to.

            +CRSAPKCS1v15Encryptor* encryptor = CRSAPKCS1v15Encryptor::NewLC(rsaPublicKey); +//As per rules described above, encryptor does not own rsaPublicKey +HBufC8* encryptedMessage = HBufC8::NewLC(encryptor->MaxOutputLength()); +encryptor->EncryptL(messageToEncrypt, *encryptedMessage); +CleanupStack::Pop(encryptedMessage); +CleanupStack::PopAndDestroy(encryptor); +

            To subsequently decrypt, again presuming access to a CRSAPrivateKey.

            +CRSAPKCS1v15Decryptor* decryptor = CRSAPKCS1v15Decryptor::NewLC(rsaPrivateKey); +//As per rules described above, decryptor does not own rsaPrivateKey +HBufC8* decryptedMessage = HBufC8::NewLC(decryptor->MaxOutputLength()); +encryptor->EncryptL(*decryptedMessage, *encryptedMessage); +CleanupStack::Pop(decryptedMessage); +CleanupStack::PopAndDestroy(decryptor); +

            Sample code +for signing/verifying

            All implemented signature systems (both +signing and verifying) do not perform any manipulation of the input message +prior to performing their internal signing mechanism. For instance, both CRSAPKCS1v15Signer and CDSASigner do +not hash the data to be signed prior to signing it. Some people refer to this +as a "raw sign primitive". The decision to operate this way was taken because +large numbers of higher level standards dictate different ways for the data +to be hashed prior to signing (and similarly for verification) and accomadating +all of them significantly confused the api. Instead it is suggested a class +that handles specification specific (for example, RSA signatures for TLS or +X.509), pre-signing transformation is created. Upon calling a Final() -like +call on such a class, it shall return a descriptor that can be "raw signed" +by the implemented signing primitives.

            The following code illustrates +how to DSA sign an unhashed descriptor, messageToBeSigned given +a CDSAPrivateKey. In this case, the pre-signing transformation +required by the DSA is simply a SHA-1 hash. As a result, CSHA1 is +used as the specification specific, pre-signing transformation class.

            +CDSASigner* signer = CDSASigner::NewLC(dsaPrivateKey); +//As per rules described above, signer does not own dsaPrivateKey +CSHA1* sha1 = CSHA1::NewLC(); +CDSASignature* signature = signer->SignL(sha1->Final(messageToBeSigned)); +//Caller owns signature as per rules described above. +CleanupStack::PopAndDestroy(2, signer); //sha1, signer +CleanupStack::PushL(signature); +

            To subsequently verify given a CDSAPublicKey and +a CDSASignature:

            +CDSAVerifier* verifier = CDSAVerifier::NewLC(dsaPublicKey); +//As per rules described above, verifier does not own dsaPublicKey +CSHA1* sha1 = CSHA1::NewLC(); +TBool result = verifier->VerifyL(sha1->Final(messageToBeVerified), *signature); +CleanupStack::PopAndDestroy(2, verifier); //sha1, verifier +
            +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4CC4D912-810B-4542-AFCD-58CEE8E0128C.dita --- a/Symbian3/SDK/Source/GUID-4CC4D912-810B-4542-AFCD-58CEE8E0128C.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-4CC4D912-810B-4542-AFCD-58CEE8E0128C.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,66 +1,66 @@ - - - - - -Open -C libz Example -

            The example demonstrates how to use the libz library to compress a file -and decompress it. The library can compress and decompress any kind of file -(txt, doc, xls, xml, mpeg, ppt, mp3 etc).

            -
            Download

            Click -on the following link to download the example: openclibz.zip

            Click: browse to view the example code.

            -
            Design and -Implementation

            The following sections provide more information -about the steps that the example performs.

            Capabilities

            Program -capabilities are defined in openclibz.mmp: CAPABILITY -None

            Implementation details of EXE

            This example is a -console based application. This application can be launched from the icon -(openclibz) in installed folder and also from eshell. When we launch it through -icon it prompts the user to enter the mode to process. The strategy parameter -is used to select the compression algorithm. For compressing a file, it reads -the file and then compresses it using the API of the libz library and then -stores the compressed content in a (.gz) file. If you want to decompress, -type d. For decompressing a file, it opens the compressed (.gz) file using -libz API's and then reads the content and decompresses it . To check what -happens to the content of the string after compression then type s. Enter -the string you want and see the data in compressed format . This option -is to demonstrate compression of string using libz API's.

            To run this application -through eshell:

            Usage : openclibz [-d] [-f] [-h] [-r] [-1 to -9] [files...] - -d : decompress - -f : compress with Z_FILTERED - -h : compress with Huffman encoding - -r : compress with run-length encoding - -1 to -9 : compression level - files : absolute path of files -

            Some usage tips

            Once you choose compression -process, enter the file name. You should provide absolute path of the file -you want to compress. (drive letter):\[(folder name)\]filename. - To get : on phone you have to press 1 few times. To get on phone you have -to press 1 few times. To get on emulator is bit tricky. If you are lucky -then pressing 1 will get it for you, otherwise change the mode. using "\ BUTTON" -(Just above the enter button in the keyboard) and then try pressing 1. To -press enter on phone we are supposed to press 0 four times.

            Cross -platform usage

            We can compress the file on any platform and uncompress -it on any other platform. For example Unix's gzip files can be compressed -using the example application and decompressed using Unix's gunzip. Compression -can be done in a single step, if the buffers are large enough; or compression -can be done by repeated calls of the compression function. In the second scenario, -application must provide more input and consume the output (providing more -output space) before each call.

            -
            APIs Used

            compress, uncompress, gzopen, gzclose, gzread, gzwrite, gzerror from -libz library

            fopen, fclose, fread, fwrite, mmap, munmap, fstat, unlink, printf, scanf from -libc library

            -
            Building and -Using

            The Symbian -build process describes how to build this example application.

            To -build the example application, go to the openclibz\group directory and build -the application. The definition for the whole application can be found in -the bld.inf file in the group subdirectory of the applications main directory.
            + + + + + +Open +C libz Example +

            The example demonstrates how to use the libz library to compress a file +and decompress it. The library can compress and decompress any kind of file +(txt, doc, xls, xml, mpeg, ppt, mp3 etc).

            +
            Download

            Click +on the following link to download the example: openclibz.zip

            Click: browse to view the example code.

            +
            Design and +Implementation

            The following sections provide more information +about the steps that the example performs.

            Capabilities

            Program +capabilities are defined in openclibz.mmp: CAPABILITY +None

            Implementation details of EXE

            This example is a +console based application. This application can be launched from the icon +(openclibz) in installed folder and also from eshell. When we launch it through +icon it prompts the user to enter the mode to process. The strategy parameter +is used to select the compression algorithm. For compressing a file, it reads +the file and then compresses it using the API of the libz library and then +stores the compressed content in a (.gz) file. If you want to decompress, +type d. For decompressing a file, it opens the compressed (.gz) file using +libz API's and then reads the content and decompresses it . To check what +happens to the content of the string after compression then type s. Enter +the string you want and see the data in compressed format . This option +is to demonstrate compression of string using libz API's.

            To run this application +through eshell:

            Usage : openclibz [-d] [-f] [-h] [-r] [-1 to -9] [files...] + -d : decompress + -f : compress with Z_FILTERED + -h : compress with Huffman encoding + -r : compress with run-length encoding + -1 to -9 : compression level + files : absolute path of files +

            Some usage tips

            Once you choose compression +process, enter the file name. You should provide absolute path of the file +you want to compress. (drive letter):\[(folder name)\]filename. + To get : on phone you have to press 1 few times. To get on phone you have +to press 1 few times. To get on emulator is bit tricky. If you are lucky +then pressing 1 will get it for you, otherwise change the mode. using "\ BUTTON" +(Just above the enter button in the keyboard) and then try pressing 1. To +press enter on phone we are supposed to press 0 four times.

            Cross +platform usage

            We can compress the file on any platform and uncompress +it on any other platform. For example Unix's gzip files can be compressed +using the example application and decompressed using Unix's gunzip. Compression +can be done in a single step, if the buffers are large enough; or compression +can be done by repeated calls of the compression function. In the second scenario, +application must provide more input and consume the output (providing more +output space) before each call.

            +
            APIs Used

            compress, uncompress, gzopen, gzclose, gzread, gzwrite, gzerror from +libz library

            fopen, fclose, fread, fwrite, mmap, munmap, fstat, unlink, printf, scanf from +libc library

            +
            Building and +Using

            The Symbian +build process describes how to build this example application.

            To +build the example application, go to the openclibz\group directory and build +the application. The definition for the whole application can be found in +the bld.inf file in the group subdirectory of the applications main directory.
            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4CEB52EC-8F08-53B7-A900-AF163316D442.dita --- a/Symbian3/SDK/Source/GUID-4CEB52EC-8F08-53B7-A900-AF163316D442.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-4CEB52EC-8F08-53B7-A900-AF163316D442.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,46 +1,46 @@ - - - - - -Quick -Start -

            The Messaging Middleware module provides application-level APIs to handle -the storage and transport of different type of messages. The message types -that are currently supported are email (POP3, IMAP4 and SMTP), SMS, BIO and -OBEX messages.

            -
            Getting started with Messaging Middleware

            Messaging -Middleware provides APIs to build highly-featured message client applications -to manipulate messages in Message Store and to enable storage of messages -in the Message Store. It also provides support for creating plug-ins to handle -individual messaging protocols.

            -
            Architecture

            The Messaging Middleware architecture -comprises of many components to form the Messaging Framework. The framework -provides plug-ins (polymorphic MTMs) to manage different type of messages. -The set of components that make up a plug-in module is called an Message Type -Module (MTM). All interactions with lower-level communication protocols, such -as, TCP/IP, are performed by MTMs. The Messaging Framework provides APIs to -enable storage of messages in the Message Store. It also provides APIs to -manipulate messages in the Message Store.

            - -
            -
            Documentation and examples

            The following sections -list tutorials and example applications that can be referred while creating -messaging applications:

              -
            • Message Server -and Store Configuration Tutorial
              • -
            • MTM Implementation -Tutorial
              • -
            • Search-Sort Tutorial
              • -
            • Attachment Tutorial
              • -
            -             -Messaging -Middleware Concepts + + + + + +Quick +Start +

            The Messaging Middleware module provides application-level APIs to handle +the storage and transport of different type of messages. The message types +that are currently supported are email (POP3, IMAP4 and SMTP), SMS, BIO and +OBEX messages.

            +
            Getting started with Messaging Middleware

            Messaging +Middleware provides APIs to build highly-featured message client applications +to manipulate messages in Message Store and to enable storage of messages +in the Message Store. It also provides support for creating plug-ins to handle +individual messaging protocols.

            +
            Architecture

            The Messaging Middleware architecture +comprises of many components to form the Messaging Framework. The framework +provides plug-ins (polymorphic MTMs) to manage different type of messages. +The set of components that make up a plug-in module is called an Message Type +Module (MTM). All interactions with lower-level communication protocols, such +as, TCP/IP, are performed by MTMs. The Messaging Framework provides APIs to +enable storage of messages in the Message Store. It also provides APIs to +manipulate messages in the Message Store.

            + +
            +
            Documentation and examples

            The following sections +list tutorials and example applications that can be referred while creating +messaging applications:

              +
            • Message Server +and Store Configuration Tutorial
              • +
            • MTM Implementation +Tutorial
              • +
            • Search-Sort Tutorial
              • +
            • Attachment Tutorial
              • +
            +             +Messaging +Middleware Concepts             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4CFFD28E-25B5-5B3F-859F-DF8ADC1DC029_d0e201428_href.png Binary file Symbian3/SDK/Source/GUID-4CFFD28E-25B5-5B3F-859F-DF8ADC1DC029_d0e201428_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4CFFD28E-25B5-5B3F-859F-DF8ADC1DC029_d0e206436_href.png Binary file Symbian3/SDK/Source/GUID-4CFFD28E-25B5-5B3F-859F-DF8ADC1DC029_d0e206436_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4D6C478A-33BA-4D74-9B82-7133ABFFB0D2_d0e67039_href.png Binary file Symbian3/SDK/Source/GUID-4D6C478A-33BA-4D74-9B82-7133ABFFB0D2_d0e67039_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4D92E302-3145-4453-AFA1-F5C5BDF933F9.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-4D92E302-3145-4453-AFA1-F5C5BDF933F9.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,107 @@ + + + + + +Compatibility BreaksAll binary and source compatibility breaks in Symbian^3 +SDK are listed with supporting information on handling these breaks. +

            The following table summarizes the binary and source compatibility +breaks:

            + + + + +APIs/Header files/Libraries +Description + + + + + +RSocket::SendTo() and RSocket::RecvFrom() +In earlier Symbian platform releases, if an application attempts RSocket::SendTo() and RSocket::RecvFrom() operations on a UDP socket when the connection is closed, the socket +would start a new connection. This behavior has changed from Symbian^3 +onwards, and such an operation will return KErrTimedOut or KErrInet6NoRoute +to indicate that the connection has been closed. + + +Libc write() +Symbian^3 supports POSIX signals which allows standard C applications +to handle interrupts (hardware and software signals/events). The existing +standard C applications are not affected by this change, unless they +are recompiled against the updated libraries. Once the applications +are recompiled, they will receive a SIGPIPE signal when they try to +write to a broken pipe. Unless this signal is handled or is ignored +using signore() method, the application terminates. For more information +on handling POSIX signals on Symbian platform, refer to Using POSIX Signals. + + +CBitmapFont::OpenFont() and COpenFont +The Flexible Memory Model in Symbian^3 does not provide access +to the Open Font data in Font Bitmap Server global chunk. Rebuild +the application binary on Symbian^3 to get access to the Open Font +data. + + +RSocket::Open() +The overloaded RSocket::Open() method that +is meant for opening a socket without associating it with an RConnection object explicitly is called the default connection +scenario. This scenario is not supported from Sybmian^3 onwards, so +all code depending on default connection scenario has to be migrated +to explicit or implicit connection scenario. For more information +on explicit and implicit connection scenarios, refer to Starting a Socket +Server connection: Tutorial. + + +CRemoteGc::SetDrawMode() and CWindowGc::SetDrawMode() +These two APIs will not support the following draw modes:
              +

            • EDrawModeAND

              • +

            • EDrawModeNOTAND

              • +

            • EDrawModeANDNOT

              • +

            • EDrawModeXOR

              • +

            • EDrawModeOR

              • +

            • EDrawModeNOTANDNOT

              • +

            • EDrawModeNOTXOR

              • +

            • EDrawModeNOTSCREEN

              • +

            • EDrawModeNOTOR

              • +

            • EDrawModeNOTPEN

              • +

            • EDrawModeORNOT

              • +

            • EDrawModeNOTORNOT

              • +
            These two Graphics Context classes (CRemoteGc and CWindowGc) will support EDrawModePEN and +EDrawModeWriteAlpha only. To use any of the draw modes listed earlier, +use CFbsBitGc::SetDrawMode() and render their window +content into an off-screen bitmap, and use CRemoteGc to draw the bitmap to the screen.             +             + +CMMFDevSound, CMdaAudioPlayerUtility, CMdaAudioRecorderUtility, CMdaAudioInputStream, CMdaAudioOutputStream, and CMdaAudioToneUtility. +In earlier Symbian platform releases, an attempt to record +or play an audio file without setting the volume and gain values (using +SetVolume() and SetGain()) would result in silence. This behavior +has changed from Symbian^3 onwards, where an audio file can be played +or recorded without having to set the volume and gain values. With +this change, all applications using these APIs must be rebuilt on +Symbian^3. + + +CGraphicsContext::DrawTextExtended(classTDesC16const&, +classCGraphicsContext::TTextParametersconst*, classTPointconst&, +structCGraphicsContext::TDrawTextExtendedParamconst&) +The ordinal position for this API has changed. Rebuild all +the applications using this API. + + +CWsScreenDevice::SetPalette(), CWsScreenDevice::PaletteAttributes(), and CWsScreenDevice::GetPalette(). +These APIs are not supported. All calls to these +APIs will return KErrNotSupported. If the existing applications using +these APIs check for KErrNotSupported error, will continue to work +without any change. All other applications must be modified and rebuilt. + + + +
             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4DB70D45-1E74-5357-9824-566962316E12_d0e108913_href.png Binary file Symbian3/SDK/Source/GUID-4DB70D45-1E74-5357-9824-566962316E12_d0e108913_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4DB70D45-1E74-5357-9824-566962316E12_d0e115451_href.png Binary file Symbian3/SDK/Source/GUID-4DB70D45-1E74-5357-9824-566962316E12_d0e115451_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4DBE998D-9699-5770-8182-929FDCAA7E26_d0e276358_href.png Binary file Symbian3/SDK/Source/GUID-4DBE998D-9699-5770-8182-929FDCAA7E26_d0e276358_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4DBE998D-9699-5770-8182-929FDCAA7E26_d0e280044_href.png Binary file Symbian3/SDK/Source/GUID-4DBE998D-9699-5770-8182-929FDCAA7E26_d0e280044_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4E1D4E5D-7CE6-5A93-9170-BEF2937FC953_d0e192678_href.png Binary file Symbian3/SDK/Source/GUID-4E1D4E5D-7CE6-5A93-9170-BEF2937FC953_d0e192678_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4E1D4E5D-7CE6-5A93-9170-BEF2937FC953_d0e197686_href.png Binary file Symbian3/SDK/Source/GUID-4E1D4E5D-7CE6-5A93-9170-BEF2937FC953_d0e197686_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4E985144-C4E6-5114-B88F-B9C92F313D91-GENID-1-8-1-3-1-1-7-1-7-1-6-1.dita --- a/Symbian3/SDK/Source/GUID-4E985144-C4E6-5114-B88F-B9C92F313D91-GENID-1-8-1-3-1-1-7-1-7-1-6-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,75 +0,0 @@ - - - - - -The -control environment -

            The control environment packages the interface to the window server and -provides an environment for creating controls. It is implemented in a single -class, CCoeEnv, which encapsulates active objects and an -active scheduler for receiving events from the window server. Each application -has exactly one CCoeEnv object which is stored in Thread -Local Storage (TLS).

            -

            CCoeEnv also provides a number of utilities which are -useful to most applications. These utilities include:

            -
              -

            • creating a graphics -context, the system graphics context. This is the standard -graphics context which is normally used for drawing controls. It may be accessed -using CCoeEnv::SystemGc() but controls should get their -graphics context using CCoeControl::SystemGc() rather than -directly from the environment.

              • -

            • access to the window -server session

              • -

            • utilities for using -fonts

              • -

            • utilities for reading -resource values from resource files

              • -

            • Support for singleton -(static) objects

              • -
            -
            Resource readers and resource files

            CCoeEnv maintains -a list of the resource files used by the application. Files may be added to -the list using AddResourceFileL() and removed using DeleteResourceFile().

            The -utility functions provided by the control environment read resources and resource -data from the resource files in its list.

            A resource file consists -of a list of resources, each identified by a resource ID. Each resource consists -of a list of resource values in the form of binary data. The order and lengths -of the values for each resource type are defined in a resource definition -(generally stored in a file with an .rh extension).

            Reading -data from a resource file requires two stages:

              -

            • read a resource from -the resource file into a buffer

              • -

            • read values from the -resource using a resource reader

              • -

            CCoeEnv provides utility functions to perform the -first of these stages and functions to create resource readers.

            An -application's default resource file, one which has the same name as the application, -is loaded automatically.

            It should be noted that stage two can be -omitted if the resource contains only one value, or if it is read into a formatted -buffer. In both of these cases the resource data can be read straight from -the buffer.

            -
            Singletons - CCoeStatic

            The CCoeStatic base -class is closely associated with CCoeEnv. Between them -they allow singleton objects to be created and stored in Thread Local Storage -(TLS). By doing so they provide an equivalent to writeable global static data.

            Classes -derived from CCoeStatic are automatically added to the -environment when they are instantiated for the first time. Subsequent attempts -to instantiate an object of the same type will result in a panic (with error -code ECoePanicDuplicateObjectUid).

            Each singleton -requires a UID and may be given a destruction priority (relative to other -singletons and the AppUi) and a scope (EThread or EApp).

            Once -a singleton has been created it may be accessed through the CCoeEnv API.

            // Singleton access -IMPORT_C static CCoeStatic* Static( TUid aUid ) ; -IMPORT_C CCoeStatic* FindStatic( TUid aUid ) ;

            CCoeStatic has -no public functions.

            -
            See also

            How -to create a Singleton

            -             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4E985144-C4E6-5114-B88F-B9C92F313D91-GENID-1-8-1-6-1-1-4-1-6-1-7-1-6-1.dita --- a/Symbian3/SDK/Source/GUID-4E985144-C4E6-5114-B88F-B9C92F313D91-GENID-1-8-1-6-1-1-4-1-6-1-7-1-6-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,75 +0,0 @@ - - - - - -The -control environment -

            The control environment packages the interface to the window server and -provides an environment for creating controls. It is implemented in a single -class, CCoeEnv, which encapsulates active objects and an -active scheduler for receiving events from the window server. Each application -has exactly one CCoeEnv object which is stored in Thread -Local Storage (TLS).

            -

            CCoeEnv also provides a number of utilities which are -useful to most applications. These utilities include:

            -
              -

            • creating a graphics -context, the system graphics context. This is the standard -graphics context which is normally used for drawing controls. It may be accessed -using CCoeEnv::SystemGc() but controls should get their -graphics context using CCoeControl::SystemGc() rather than -directly from the environment.

              • -

            • access to the window -server session

              • -

            • utilities for using -fonts

              • -

            • utilities for reading -resource values from resource files

              • -

            • Support for singleton -(static) objects

              • -
            -
            Resource readers and resource files

            CCoeEnv maintains -a list of the resource files used by the application. Files may be added to -the list using AddResourceFileL() and removed using DeleteResourceFile().

            The -utility functions provided by the control environment read resources and resource -data from the resource files in its list.

            A resource file consists -of a list of resources, each identified by a resource ID. Each resource consists -of a list of resource values in the form of binary data. The order and lengths -of the values for each resource type are defined in a resource definition -(generally stored in a file with an .rh extension).

            Reading -data from a resource file requires two stages:

              -

            • read a resource from -the resource file into a buffer

              • -

            • read values from the -resource using a resource reader

              • -

            CCoeEnv provides utility functions to perform the -first of these stages and functions to create resource readers.

            An -application's default resource file, one which has the same name as the application, -is loaded automatically.

            It should be noted that stage two can be -omitted if the resource contains only one value, or if it is read into a formatted -buffer. In both of these cases the resource data can be read straight from -the buffer.

            -
            Singletons - CCoeStatic

            The CCoeStatic base -class is closely associated with CCoeEnv. Between them -they allow singleton objects to be created and stored in Thread Local Storage -(TLS). By doing so they provide an equivalent to writeable global static data.

            Classes -derived from CCoeStatic are automatically added to the -environment when they are instantiated for the first time. Subsequent attempts -to instantiate an object of the same type will result in a panic (with error -code ECoePanicDuplicateObjectUid).

            Each singleton -requires a UID and may be given a destruction priority (relative to other -singletons and the AppUi) and a scope (EThread or EApp).

            Once -a singleton has been created it may be accessed through the CCoeEnv API.

            // Singleton access -IMPORT_C static CCoeStatic* Static( TUid aUid ) ; -IMPORT_C CCoeStatic* FindStatic( TUid aUid ) ;

            CCoeStatic has -no public functions.

            -
            See also

            How -to create a Singleton

            -             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4E985144-C4E6-5114-B88F-B9C92F313D91.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-4E985144-C4E6-5114-B88F-B9C92F313D91.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,75 @@ + + + + + +The +control environment +

            The control environment packages the interface to the window server and +provides an environment for creating controls. It is implemented in a single +class, CCoeEnv, which encapsulates active objects and an +active scheduler for receiving events from the window server. Each application +has exactly one CCoeEnv object which is stored in Thread +Local Storage (TLS).

            +

            CCoeEnv also provides a number of utilities which are +useful to most applications. These utilities include:

            +
              +

            • creating a graphics +context, the system graphics context. This is the standard +graphics context which is normally used for drawing controls. It may be accessed +using CCoeEnv::SystemGc() but controls should get their +graphics context using CCoeControl::SystemGc() rather than +directly from the environment.

              • +

            • access to the window +server session

              • +

            • utilities for using +fonts

              • +

            • utilities for reading +resource values from resource files

              • +

            • Support for singleton +(static) objects

              • +
            +
            Resource readers and resource files

            CCoeEnv maintains +a list of the resource files used by the application. Files may be added to +the list using AddResourceFileL() and removed using DeleteResourceFile().

            The +utility functions provided by the control environment read resources and resource +data from the resource files in its list.

            A resource file consists +of a list of resources, each identified by a resource ID. Each resource consists +of a list of resource values in the form of binary data. The order and lengths +of the values for each resource type are defined in a resource definition +(generally stored in a file with an .rh extension).

            Reading +data from a resource file requires two stages:

              +

            • read a resource from +the resource file into a buffer

              • +

            • read values from the +resource using a resource reader

              • +

            CCoeEnv provides utility functions to perform the +first of these stages and functions to create resource readers.

            An +application's default resource file, one which has the same name as the application, +is loaded automatically.

            It should be noted that stage two can be +omitted if the resource contains only one value, or if it is read into a formatted +buffer. In both of these cases the resource data can be read straight from +the buffer.

            +
            Singletons - CCoeStatic

            The CCoeStatic base +class is closely associated with CCoeEnv. Between them +they allow singleton objects to be created and stored in Thread Local Storage +(TLS). By doing so they provide an equivalent to writeable global static data.

            Classes +derived from CCoeStatic are automatically added to the +environment when they are instantiated for the first time. Subsequent attempts +to instantiate an object of the same type will result in a panic (with error +code ECoePanicDuplicateObjectUid).

            Each singleton +requires a UID and may be given a destruction priority (relative to other +singletons and the AppUi) and a scope (EThread or EApp).

            Once +a singleton has been created it may be accessed through the CCoeEnv API.

            // Singleton access +IMPORT_C static CCoeStatic* Static( TUid aUid ) ; +IMPORT_C CCoeStatic* FindStatic( TUid aUid ) ;

            CCoeStatic has +no public functions.

            +
            See also

            How +to create a Singleton

            +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4EE4E79E-F6D5-5F14-BA8D-4DD10D229B74.dita --- a/Symbian3/SDK/Source/GUID-4EE4E79E-F6D5-5F14-BA8D-4DD10D229B74.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-4EE4E79E-F6D5-5F14-BA8D-4DD10D229B74.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,18 +1,18 @@ - - - - - -Handling BLOBs

            This document introduces you to Binary Large Objects (BLOB) in Symbian SQL.

            Purpose

            A BLOB is an SQL database container object for binary large objects, usually images or audio files but may also include other binary files such as an application executable.

            Features of SQL BLOB

            BLOBS offer the following features:

            • read from and write to BLOB objects in a RAM-efficient manner -- enables an overall reduction of RAM usage,

            • reduced read latency (compared to previous versions) -- improving the responsiveness of client applications,

            • larger BLOB objects can be stored and retrieved (>16Mb). Before version 9.5 there was a limit on the size of a BLOB object supported by Symbian SQL. This limit was dictated by the amount of server-side RAM available. Applications that needed to store large BLOB objects in their database (for example, MP3 files) are no longer restricted by this limit.

            • The maximum possible length for a blob is 2147483647 bytes.

            Streaming

            The classes RSqlBlobReadStream and RSqlBlobWriteStream allow direct access to BLOB content. These classes do not require the whole BLOB to be loaded into RAM before streaming can begin. These classes match the standard Symbian RReadStream /RWriteStream idiom.

            The server intelligently chooses the size of an internal buffer to incrementally read/write the requested blob data in blocks. The size of the buffer is calculated based on a combination of the size of the request and the value of aBlockSizeHint (if specified).

            aBlockSizeHint is provided by the client to provide a hint to the server about the size of block that it is intending to use to read/write the blob data. This is advance information about the intended behaviour of the client that the server may use to its benefit to read/write the blob data.

            Whole-blob access

            The class TSqlBlob allows one-shot storage and retrieval of whole blobs. This class avoids the need for double buffering of the blob in both the client and the server.

            there are two versions of the BLOB get functions. One is non-leaving and the other is leaving.

            Use the non-leaving variant when the client knows that the blob will either:

            • all be of a fixed size,

            • not exceed an upper size limit.

            In these situations the client can pre-allocate a buffer and avoid the overhead of memory allocation.

            Use the leaving variant when the client does not have prior knowledge of the BLOB size (or if the size varies wildly). In this situation the server allocates a buffer and passes ownership to the client.

            RAM benefits

            Symbian SQL has been improved to eliminate the need for a 2 MB server-side buffer. Data is transferred to the client in blocks so for example, the server-side buffer may be reduced to 32 KB.

            Previous to version 9.5, both whole-blob and streaming use cases require up to 3MB of server-side RAM. The page cache size is capped at 1MB due to a built-in limiting mechanism. But, a 2MB buffer must be allocated to hold the entire blob. A critical side-effect of this is that, due to heap exhaustion, there is a maximum limit on the size of a blob object that can be written to or read from a database.

            In the following diagram the top two sections illustrate whole-blob retrieval in which the entire blob is retrieved in one go using RSqlStatement. The bottom section illustrates streaming retrieval in which the blob is retrieved in blocks specified by the client using RSqlColumnReadStream.

            - Reading a 2MB blob. -
            SQL Security - Policies Database file - format SQLite - Modules Free Space + + + + + +Handling BLOBs

            This document introduces you to Binary Large Objects (BLOB) in Symbian SQL.

            Purpose

            A BLOB is an SQL database container object for binary large objects, usually images or audio files but may also include other binary files such as an application executable.

            Features of SQL BLOB

            BLOBS offer the following features:

            • read from and write to BLOB objects in a RAM-efficient manner -- enables an overall reduction of RAM usage,

            • reduced read latency (compared to previous versions) -- improving the responsiveness of client applications,

            • larger BLOB objects can be stored and retrieved (>16Mb). Before version 9.5 there was a limit on the size of a BLOB object supported by Symbian SQL. This limit was dictated by the amount of server-side RAM available. Applications that needed to store large BLOB objects in their database (for example, MP3 files) are no longer restricted by this limit.

            • The maximum possible length for a blob is 2147483647 bytes.

            Streaming

            The classes RSqlBlobReadStream and RSqlBlobWriteStream allow direct access to BLOB content. These classes do not require the whole BLOB to be loaded into RAM before streaming can begin. These classes match the standard Symbian RReadStream /RWriteStream idiom.

            The server intelligently chooses the size of an internal buffer to incrementally read/write the requested blob data in blocks. The size of the buffer is calculated based on a combination of the size of the request and the value of aBlockSizeHint (if specified).

            aBlockSizeHint is provided by the client to provide a hint to the server about the size of block that it is intending to use to read/write the blob data. This is advance information about the intended behaviour of the client that the server may use to its benefit to read/write the blob data.

            Whole-blob access

            The class TSqlBlob allows one-shot storage and retrieval of whole blobs. This class avoids the need for double buffering of the blob in both the client and the server.

            there are two versions of the BLOB get functions. One is non-leaving and the other is leaving.

            Use the non-leaving variant when the client knows that the blob will either:

            • all be of a fixed size,

            • not exceed an upper size limit.

            In these situations the client can pre-allocate a buffer and avoid the overhead of memory allocation.

            Use the leaving variant when the client does not have prior knowledge of the BLOB size (or if the size varies wildly). In this situation the server allocates a buffer and passes ownership to the client.

            RAM benefits

            Symbian SQL has been improved to eliminate the need for a 2 MB server-side buffer. Data is transferred to the client in blocks so for example, the server-side buffer may be reduced to 32 KB.

            Previous to version 9.5, both whole-blob and streaming use cases require up to 3MB of server-side RAM. The page cache size is capped at 1MB due to a built-in limiting mechanism. But, a 2MB buffer must be allocated to hold the entire blob. A critical side-effect of this is that, due to heap exhaustion, there is a maximum limit on the size of a blob object that can be written to or read from a database.

            In the following diagram the top two sections illustrate whole-blob retrieval in which the entire blob is retrieved in one go using RSqlStatement. The bottom section illustrates streaming retrieval in which the blob is retrieved in blocks specified by the client using RSqlColumnReadStream.

            + Reading a 2MB blob. +
            SQL Security + Policies Database file + format SQLite + Modules Free Space Reclaimation SQL Overview             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4F879832-8425-5C56-B3FE-4C4592EBB6A5_d0e306923_href.png Binary file Symbian3/SDK/Source/GUID-4F879832-8425-5C56-B3FE-4C4592EBB6A5_d0e306923_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4F879832-8425-5C56-B3FE-4C4592EBB6A5_d0e313317_href.png Binary file Symbian3/SDK/Source/GUID-4F879832-8425-5C56-B3FE-4C4592EBB6A5_d0e313317_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4FC82562-9163-45F5-9E14-DA0AB6B5E54C.dita --- a/Symbian3/SDK/Source/GUID-4FC82562-9163-45F5-9E14-DA0AB6B5E54C.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-4FC82562-9163-45F5-9E14-DA0AB6B5E54C.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,53 +1,54 @@ - - - - - -UI -themes -

            A UI theme is a customized graphical user interface (GUI) that replaces -the phone's default look, and it is used to change the appearance of the user -interface for the phone's applications. A phone with the Symbian user interface -may provide several UI themes of which the user can activate one theme at -a time. By activating a UI theme, the visual appearance of the user interface -is changed. Note that this setting only affects visual elements, e.g. functions, -the interaction style or language settings are not affected.

            - -Simplified illustration of the UI theme concept - - -

            UI themes give the UI theme designer a freedom to design a unique GUI, -and by designing backgrounds and icons, the result can be very different from -the default settings.

            -

            A good GUI has consistent metaphor. When designing UI themes, the UI theme -designer should make sure that the user interface supports the user's aim -and does not mislead the user. It is also good to remember that even though -the new look and feel offered by a UI theme would be fancy and exciting, the -general positive user experience will fade if the performance of the terminal -suffers because of a too large UI theme package file size.

            -

            To ensure a consistent look and feel in all applications, it is recommended -for the application UI designer to use the UI components that support UI themes. -In case application uses UI components that the UI theme does not support, -the factory default of the missing items is used.

            -

            A UI theme designer can decide which elements belong to a UI theme package. -It is possible to design a UI theme that uses the default UI components of -the phone together with components belonging to the UI theme.

            -
            Using -UI themes in C++ applications

            The API to use for UI themes is the Skins API. For implementation information, see Using the Skins API.

            The UI controls -that support themes using the Skins API include:

              -

            • Status pane, -including its sub-panes

              • -

            • Control pane

              • -

            • Lists and grids

              • -

            • Find pane

              • -

            • Forms

              • -

            • Setting lists

              • -

            • Pop-up windows

              • -
            + + + + + +UI +themes +

            A UI theme is a customized graphical user interface (GUI) that replaces +the phone's default look, and it is used to change the appearance of the user +interface for the phone's applications. A phone with the Symbian user interface +may provide several UI themes of which the user can activate one theme at +a time. By activating a UI theme, the visual appearance of the user interface +is changed. Note that this setting only affects visual elements, e.g. functions, +the interaction style or language settings are not affected.

            + +Simplified illustration of the UI theme concept + + +

            UI themes give the UI theme designer a freedom to design a unique GUI, +and by designing backgrounds and icons, the result can be very different from +the default settings.

            +

            A good GUI has consistent metaphor. When designing UI themes, the UI theme +designer should make sure that the user interface supports the user's aim +and does not mislead the user. It is also good to remember that even though +the new look and feel offered by a UI theme would be fancy and exciting, the +general positive user experience will fade if the performance of the terminal +suffers because of a too large UI theme package file size.

            +

            To ensure a consistent look and feel in all applications, it is recommended +for the application UI designer to use the UI components that support UI themes. +In case application uses UI components that the UI theme does not support, +the factory default of the missing items is used.

            +

            A UI theme designer can decide which elements belong to a UI theme package. +It is possible to design a UI theme that uses the default UI components of +the phone together with components belonging to the UI theme.

            +
            Using +UI themes in applications

            The API to use for UI themes +is the Skins API. For implementation information, see Using the Skins API.

            The UI controls that support +themes using the Skins API include:

              +

            • Status pane, +including its sub-panes

              • +

            • Control pane

              • +

            • Lists and grids

              • +

            • Find pane

              • +

            • Forms

              • +

            • Setting lists

              • +

            • Pop-up windows

              • +
             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-4FE5CA06-8C3A-4AC1-80CE-4418AC55937A.dita --- a/Symbian3/SDK/Source/GUID-4FE5CA06-8C3A-4AC1-80CE-4418AC55937A.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-4FE5CA06-8C3A-4AC1-80CE-4418AC55937A.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,74 +1,74 @@ - - - - - -Reading -headers in a WSP bufferTWspField object holds the name and value pair -of the WSP header field. TWspHeaderSegmenter pulls the header -/ value pair out of the WSP buffer (into TWspField). Call TWspHeaderSegmenter::NextL() to -iterate through the WSP buffer. It calls TWspPrimitiveDecoder. -

            CWspHeaderEncoder allows you to encode -the values and parameters of the header field. It creates one header at a -time from the name / value pairs.

             -

            The following are the steps to encode the WSP header:

            -             - - -Create a header encoder object. -//creates a pointer to CWspHeaderEncoder object -CWspHeaderEncoder* primEncoder = CWspHeaderEncoder::NewLC(); - - -Start a new encoded header to encode the parameter value. -// start a new encoded header -primEncoder->StartHeaderL(0x27); - - -Call CWspHeaderEncoder::StartValueLengthL() to calculate -the length of encodings that are added subsequently. The value calculated, -is stored as part of the encoded string, as specified in the WSP standard. -primEncoder->StartValueLengthL(); - - -Encode the header field and add it to the encoded field. - Note: The appropriate WSP method is used for encoding the header -field of a data type such as integer, date, text string and so on. -primEncoder->AddIntegerL(0x7F); -primEncoder->AddUintVarL(0xff); -primEncoder->AddLongIntL(999999); -_LIT8(KString, "WSP Encode: String"); -primEncoder->AddTextStringL(KString); -TDateTime time(2006,EMarch,20,06,36,30,000000); //create a date time object -primEncoder->AddDateL(time); // add -TUInt intVal=489; -primEncoder->AddLTokenL(intVal); -_LIT8(KTokenText, "WSP Encode: Token Text"); -primEncoder->AddLTokenTextL(KTokenText); - - -Call CWspHeaderEncoder::EndValuesLengthL() at the -time of header construction when ValueLength can be calculated. - - -Assuming that the length of the header encodings has been calculated -and added to the encoder field, call CWspHeaderEncoder::EndValuesLengthL(). -primEncoder->EndValueLengthL(); - - -Call CWspHeaderEncoder::EndHeaderL(), to complete -the header encoding. This completes and returns the encoded header field's -8 bit buffer. EndHeaderL() panics if EndValueLengthL() is -not called after CWspHeaderEncoder::StartValueLengthL(). -HBufC8* buf = primEncoder->EndHeaderL(); -

            This returns a pointer to the buffer containing the encoded -field.

            -             -             + + + + + +Reading +headers in a WSP bufferTWspField object holds the name and value pair +of the WSP header field. TWspHeaderSegmenter pulls the header +/ value pair out of the WSP buffer (into TWspField). Call TWspHeaderSegmenter::NextL() to +iterate through the WSP buffer. It calls TWspPrimitiveDecoder. +

            CWspHeaderEncoder allows you to encode +the values and parameters of the header field. It creates one header at a +time from the name / value pairs.

             +

            The following are the steps to encode the WSP header:

            +             + + +Create a header encoder object. +//creates a pointer to CWspHeaderEncoder object +CWspHeaderEncoder* primEncoder = CWspHeaderEncoder::NewLC(); + + +Start a new encoded header to encode the parameter value. +// start a new encoded header +primEncoder->StartHeaderL(0x27); + + +Call CWspHeaderEncoder::StartValueLengthL() to calculate +the length of encodings that are added subsequently. The value calculated, +is stored as part of the encoded string, as specified in the WSP standard. +primEncoder->StartValueLengthL(); + + +Encode the header field and add it to the encoded field. + Note: The appropriate WSP method is used for encoding the header +field of a data type such as integer, date, text string and so on. +primEncoder->AddIntegerL(0x7F); +primEncoder->AddUintVarL(0xff); +primEncoder->AddLongIntL(999999); +_LIT8(KString, "WSP Encode: String"); +primEncoder->AddTextStringL(KString); +TDateTime time(2006,EMarch,20,06,36,30,000000); //create a date time object +primEncoder->AddDateL(time); // add +TUInt intVal=489; +primEncoder->AddLTokenL(intVal); +_LIT8(KTokenText, "WSP Encode: Token Text"); +primEncoder->AddLTokenTextL(KTokenText); + + +Call CWspHeaderEncoder::EndValuesLengthL() at the +time of header construction when ValueLength can be calculated. + + +Assuming that the length of the header encodings has been calculated +and added to the encoder field, call CWspHeaderEncoder::EndValuesLengthL(). +primEncoder->EndValueLengthL(); + + +Call CWspHeaderEncoder::EndHeaderL(), to complete +the header encoding. This completes and returns the encoded header field's +8 bit buffer. EndHeaderL() panics if EndValueLengthL() is +not called after CWspHeaderEncoder::StartValueLengthL(). +HBufC8* buf = primEncoder->EndHeaderL(); +

            This returns a pointer to the buffer containing the encoded +field.

            +             +                         \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-50254C2F-57B6-58C4-911F-294EF2B79C04.dita --- a/Symbian3/SDK/Source/GUID-50254C2F-57B6-58C4-911F-294EF2B79C04.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-50254C2F-57B6-58C4-911F-294EF2B79C04.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,53 +1,53 @@ - - - - - -Khronos -API Support The Symbian platform provides support for a number of APIs created -by the Khronos Group (www.khronos.org). This is a member-funded industry consortium -focused on the creation of open standard, royalty-free APIs to enable the -authoring and accelerated playback of dynamic media on a wide variety of platforms -and devices. This topic provides a brief summary of the Khronos APIs that -are supported in the Symbian platform. -
            Supported APIs

            OpenGL ES

            OpenGL -is a 2D and 3D graphics API that provides a broad set of rendering, texture -mapping, special effects, and other visualization functions. It gives software -developers access to geometric and image primitives, display lists, modeling -transformations, lighting and texturing, anti-aliasing and blending. OpenGL -ES is a subset of OpenGL optimized for 2D and 3D graphics on embedded devices -such as mobile phones.

            See: OpenGLES -Collection

            OpenVG

            OpenVG is an API that provides -a low-level hardware acceleration interface for rendering vector graphics -libraries such as Flash and Scalable Vector Graphics (SVG). OpenVG is targeted -primarily at handheld devices that require portable acceleration of high-quality -vector graphics for user interfaces and text on small screen devices. It does -this while enabling hardware acceleration to provide smooth interactive performance -at low power levels.

            See: OpenVG -Collection.

            EGL

            EGL is an interface between -Khronos rendering APIs such as OpenGL ES or OpenVG and the underlying native -platform window system.

            See: EGL -Collection

            OpenWF Composition

            OpenWF Composition -(OpenWF-C) provides a hardware abstraction layer that allows power-efficient -hardware-accelerated composition on a wide variety of hardware platforms. -OpenWF-C is particularly aimed at systems with limited memory bandwidth, such -as mobile devices. OpenWF-C enables the UI and the window system stack to -be independent of the hardware used to achieve the composition. OpenWF-C is -a system-level API that can be ignored by application developers.

            -
            Architectural relationships

            The following diagram -shows the relationships between the Khronos rendering APIs.

            -Dependencies between the Khronos rendering components - -
            -             -Graphics -Concepts -http://www.khronos.org/ - + + + + + +Khronos +API Support The Symbian platform provides support for a number of APIs created +by the Khronos Group (www.khronos.org). This is a member-funded industry consortium +focused on the creation of open standard, royalty-free APIs to enable the +authoring and accelerated playback of dynamic media on a wide variety of platforms +and devices. This topic provides a brief summary of the Khronos APIs that +are supported in the Symbian platform. +
            Supported APIs

            OpenGL ES

            OpenGL +is a 2D and 3D graphics API that provides a broad set of rendering, texture +mapping, special effects, and other visualization functions. It gives software +developers access to geometric and image primitives, display lists, modeling +transformations, lighting and texturing, anti-aliasing and blending. OpenGL +ES is a subset of OpenGL optimized for 2D and 3D graphics on embedded devices +such as mobile phones.

            See: OpenGLES +Collection

            OpenVG

            OpenVG is an API that provides +a low-level hardware acceleration interface for rendering vector graphics +libraries such as Flash and Scalable Vector Graphics (SVG). OpenVG is targeted +primarily at handheld devices that require portable acceleration of high-quality +vector graphics for user interfaces and text on small screen devices. It does +this while enabling hardware acceleration to provide smooth interactive performance +at low power levels.

            See: OpenVG +Collection.

            EGL

            EGL is an interface between +Khronos rendering APIs such as OpenGL ES or OpenVG and the underlying native +platform window system.

            See: EGL +Collection

            OpenWF Composition

            OpenWF Composition +(OpenWF-C) provides a hardware abstraction layer that allows power-efficient +hardware-accelerated composition on a wide variety of hardware platforms. +OpenWF-C is particularly aimed at systems with limited memory bandwidth, such +as mobile devices. OpenWF-C enables the UI and the window system stack to +be independent of the hardware used to achieve the composition. OpenWF-C is +a system-level API that can be ignored by application developers.

            +
            Architectural relationships

            The following diagram +shows the relationships between the Khronos rendering APIs.

            +Dependencies between the Khronos rendering components + +
            +             +Graphics +Concepts +http://www.khronos.org/ +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-504E4334-FDA9-5982-8BF7-509D019AFD4C_d0e323870_href.jpg Binary file Symbian3/SDK/Source/GUID-504E4334-FDA9-5982-8BF7-509D019AFD4C_d0e323870_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-504E4334-FDA9-5982-8BF7-509D019AFD4C_d0e330027_href.jpg Binary file Symbian3/SDK/Source/GUID-504E4334-FDA9-5982-8BF7-509D019AFD4C_d0e330027_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-504EB40B-AC98-5AB2-9263-185887C29A7E.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-504EB40B-AC98-5AB2-9263-185887C29A7E.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,161 @@ + + + + + +Searching +for an IAP Record by Name and Loading the Associated Service and the Bearer +Table: TutorialThis tutorial shows you how to search for a Symbian platform defined +Internet Access Points Configuration (IAP) record by name. The tutorial, then +shows you how load the connected service and the bearer table. + + +

            Before you start, +you must understand:

              +

            • the general concept +of the Comms Database

              • +

            • the specific concept +of fields, records, links and tables

              • +

            • how to write and build +application code to run on Symbian platform

              • +
             +

            This tutorial shows +you:

              +

            • how to search the Internet +Access Points Configuration table for a record defined by name. This table +is also called the IAP table

              • +

            • how to load the connected +service.

              • +

            • how to load the connected +bearer table.

              • +

            The principles that apply here also apply to the other Symbian platform +defined tables.

            + +Make sure that you +have created a session. + +Create an empty +IAP record in the tool or application process. + +You create a CMDBRecordSet <T> object +and specify CCDIAPRecord as the template +parameter. + +Symbian platform defines the CCDIAPRecord class to +represent a IAP record. The class is a schema for the record. The class defines +the fields and links that make a IAP record. +Symbian platform defines unique +numeric Id s for Symbian platform defined tables. The symbol KCDTIdIAPRecord also defines the value of this +Id for records in the IAP table. The Id allows the CommsDat API to get the +record from the Comms Database. +To work with other Symbian platform defined tables, use the correct +class name and the correct unique numeric Id values. The Reference section +contains a list of all Symbian platform defined tables. +... + +// This code fragment assumes that a session with the Comms Database has been created. +// iDb is a pointer to a CMDBSession object +... + +// When we search by Name or Id, there can be only one record to be returned +// Create an empty IAP record. +// +// Note: +// 1. the template parameter CCDIAPRecord defines +// the "IAP" record type. +// 2. to create a record, you use a factory function and pass the unique +// numeric Id KCDTIdIAPRecord as a parameter to the constructor. +// + +CCDIAPRecord* ptrIAPRecord = + static_cast<CCDIAPRecord *>(CCDRecordBase::RecordFactoryL(KCDTIdIAPRecord)); +... + +Define the name +of the IAP record to be found and set the name in IAP record. Do the search +for the record in the Comms Database. + +In this tutorial, the name of the IAP record is NTRas with Null Modem. + +Use the assignment operator to add the data to a field. A field that +has type T accepts a type T item as the right-hand argument +of an assignment call. + +A descriptor field needs an additional call to set the size of the descriptor. +Call SetMaxLengthL() to set the size of the descriptor. This +function is a member of the field class CMDBField <TDesC>. +Internally, the function causes the allocation of a descriptor. You must set +the size of the descriptor before you assign the data. You can also use the SetL() function. +This function sets the length and assigns the data. The function is a member +of the field class CMDBField <TDesC>. +... +// Define the name of the IAP record. +_LIT(KMyIap, "NTRas with Null Modem"); + +// Either +ptrIAPRecord->iRecordName.SetMaxLengthL(KMyIap().Length()); +ptrIAPRecord->iRecordName = KMyIap; + +// Or +ptrIAPRecord->iRecordName.SetL(KMyIap); + + +// Search the Comms Database +if(ptrIAPRecord->FindL(*iDb)) + { + // Found a matching record + ... + } + +... + +Load the NTRas with +Null Modem service and the associated bearer table. +... +// Search the Comms Database +if(ptrIAPRecord->FindL(*iDb)) + { + // Found a matching record + + // Now load the the associated service and bearer tables, + // The variables iService,iBearer, etc + // are links that point to other records. These links have a "Value" and + // "iLinkedRecord". + // + // The "Value" represent the id of the target field,and gets initialized along with the + // parent record(ptrIAPRecord). When we explictly call load on these LinkedFields, + // the "iLinkedRecord" pointer points to the appropriate object. + // + // The "iLinkedRecord" pointer is owned by the parent record and gets + // deleted along with it.THis means that it must be set to NULL + // if the user wants to take ownership. + + ptrIAPRecord->iService.LoadL(*iDb); + ptrIAPRecord->iBearer.LoadL(*iDb); + + // Take ownership of the loaded service record cache + CCDServiceRecordBase* ptrService = + static_cast< CCDServiceRecordBase *> (ptrIAPRecord->iService.iLinkedRecord); + (ptrIAPRecord->iService).iLinkedRecord = NULL; + + // Deleting ptrIAPRecord also deletes all the loaded iLinkedRecord + // pointers it owns unless set to null. + + delete ptrIAPRecord; + + //delete the service view. + delete ptrService; + } +... + + +             +Comms Database + concepts +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5059C3F9-1CEA-5DF3-914A-B99376570242_d0e278106_href.jpg Binary file Symbian3/SDK/Source/GUID-5059C3F9-1CEA-5DF3-914A-B99376570242_d0e278106_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5059C3F9-1CEA-5DF3-914A-B99376570242_d0e281792_href.jpg Binary file Symbian3/SDK/Source/GUID-5059C3F9-1CEA-5DF3-914A-B99376570242_d0e281792_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-50AB1B77-1912-5C73-A1B5-41220E7A2EA5.dita --- a/Symbian3/SDK/Source/GUID-50AB1B77-1912-5C73-A1B5-41220E7A2EA5.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-50AB1B77-1912-5C73-A1B5-41220E7A2EA5.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,39 +1,39 @@ - - - - - -Store -map as repository for Swizzles and associated stream IDsThis document describes using a store map as a repository for Swizzles -and associated stream IDs. -

            A store map is a table of entries where each entry consists of a Swizzle -and a stream ID.

            -

            When the in-memory object represented by a Swizzle is externalised, the -resulting stream ID and the associated Swizzle can be added to a store map. -The effect is to create an entry in the store map table containing the stream -ID and the associated Swizzle; the Swizzle is said to be bound to the stream -ID. Creating this entry in the store map is done using CStoreMap::BindL().

            -

            For a container type class CCompound, the diagram below -shows the result of:

            -
              -

            • streaming out the in-memory -objects represented by the Swizzles iA, iB and iC.

              • -

            • binding the swizzles -with the resulting stream IDs

              • -
            -

            The other characteristics of a store map follow from this.

            - - -<image href="GUID-4028CDCF-D2E8-5668-A751-A7CFA86CED46_d0e363900_href.png" placement="inline"/> -</fig> -<p>Entries in the store map can be deleted. An entry can be identified either -by Swizzle or by stream ID. <codeph>CStoreMap::Unbind()</codeph> deletes an -entry identified by Swizzle; <codeph>CStoreMap::Forget()</codeph> deletes -an entry identified by stream ID.</p> +<?xml version="1.0" encoding="utf-8"?> +<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> +<!-- This component and the accompanying materials are made available under the terms of the License +"Eclipse Public License v1.0" which accompanies this distribution, +and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> +<!-- Initial Contributors: + Nokia Corporation - initial contribution. +Contributors: +--> +<!DOCTYPE concept + PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> +<concept id="GUID-50AB1B77-1912-5C73-A1B5-41220E7A2EA5" xml:lang="en"><title>Store +map as repository for Swizzles and associated stream IDsThis document describes using a store map as a repository for Swizzles +and associated stream IDs. +

            A store map is a table of entries where each entry consists of a Swizzle +and a stream ID.

            +

            When the in-memory object represented by a Swizzle is externalised, the +resulting stream ID and the associated Swizzle can be added to a store map. +The effect is to create an entry in the store map table containing the stream +ID and the associated Swizzle; the Swizzle is said to be bound to the stream +ID. Creating this entry in the store map is done using CStoreMap::BindL().

            +

            For a container type class CCompound, the diagram below +shows the result of:

            +
              +

            • streaming out the in-memory +objects represented by the Swizzles iA, iB and iC.

              • +

            • binding the swizzles +with the resulting stream IDs

              • +
            +

            The other characteristics of a store map follow from this.

            + + +<image href="GUID-4028CDCF-D2E8-5668-A751-A7CFA86CED46_d0e357820_href.png" placement="inline"/> +</fig> +<p>Entries in the store map can be deleted. An entry can be identified either +by Swizzle or by stream ID. <codeph>CStoreMap::Unbind()</codeph> deletes an +entry identified by Swizzle; <codeph>CStoreMap::Forget()</codeph> deletes +an entry identified by stream ID.</p> </conbody></concept> \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-50BBCB9C-F234-5813-A42E-3FCFB0F14B66.dita --- a/Symbian3/SDK/Source/GUID-50BBCB9C-F234-5813-A42E-3FCFB0F14B66.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-50BBCB9C-F234-5813-A42E-3FCFB0F14B66.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,96 +1,96 @@ -<?xml version="1.0" encoding="utf-8"?> -<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> -<!-- This component and the accompanying materials are made available under the terms of the License -"Eclipse Public License v1.0" which accompanies this distribution, -and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> -<!-- Initial Contributors: - Nokia Corporation - initial contribution. -Contributors: ---> -<!DOCTYPE concept - PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> -<concept id="GUID-50BBCB9C-F234-5813-A42E-3FCFB0F14B66" xml:lang="en"><title>HTTP Client -overview -
            Purpose

            The -HTTP (Hypertext Transfer Protocol) Client API provides a client interface -for Internet applications to use the HTTP protocol for communication with -HTTP servers on the Internet. Using the API correctly enables the application -to be a conditionally HTTP 1.1 compliant client, as defined in RFC 2616.

            The -HTTP protocol is a request and response protocol. A client sends a request -to the server. This request consists of a request method, URI, and protocol -version, including a Multipurpose Internet Mail Extensions (MIME)-like message -containing request modifiers, client information, and body content over a -server connection. The server responds with a status, which includes the message's -protocol version and a success or error code, and a MIME-like message containing -server information, meta information, and body content. The following image -illustrates a simple HTTP session between a client and a server.

            - Simple HTTP Interaction - -

            See Hypertext -Transfer Protocol -- HTTP/1.1, RFC 2616 for more details.

            -
            Architectural -relationships

            The HTTP Client architecture provides a generalised -mechanism for HTTP-like protocols that operate over various transports. Using -a single API, a client can choose an HTTP protocol, encoding, and transport, -and need not implement these in its own code. The default operation provides -plain-text HTTP (as defined in RFC 2616) operating over a TCP/IP connection. -This transport pipelines requests by default.

            -
            Description

            There -are five key concepts used in the API: sessions, transactions, headers, data -suppliers, and filters.

            Sessions

            A session encapsulates -the client's HTTP activity over the duration of the client's execution. Typicallly, -one HTTP session runs in one active scheduler.

            Note: An active -scheduler must be installed when a session is opened.

            Usually, one -session is used at a time. However, the client may use several concurrently, -if required. Each session has an associated set of properties, which define -the HTTP protocol, encoding, and transport used. Those properties apply to -all HTTP transactions within the life of that session. The session also has -an associated set of filters that provide additional automatic behaviours -on the client's behalf.

            The session class is provided by RHTTPSession.

            Transactions

            A -transaction represents an interaction between a HTTP client and an HTTP origin -server. Normally a transaction consists of a single exchange of messages between -client and server: a client request and a server response. However, the transaction -may be extended or altered by filters that operate on it. See Filters for -more details.

            Transactions execute asychronously within the client's -process. The client is notified when events are available for each outstanding -transaction.

            Both the request and response portion of a transaction -consist of a header and an optional body. The request portion of the transaction -also specifies an HTTP Method that describes the type of operation that the -client wants to invoke at the origin server, together with a URI that specifies -the resource held at the server on which the method is to be invoked. The -response portion of a transaction contains an HTTP status code and message, -which indicate the success of the method or the state of the resource following -the method. The use of request and response bodies is determined by the HTTP -method in use. For example, in error conditions, some servers may just return -a status code and message, providing no entity body.

            The transaction -class is provided by RHTTPTransaction.

            Headers

            The -header portion of requests and responses may have zero or more fields, which -are used to convey information between the HTTP client and server. The information -might relate to the data conveyed in body of the message, to the actual connection -between the client and server, or might be used to convey data describing -the client or server themselves. Typically, headers can contain content encoding -and transfer encoding information. Since the HTTP API gives clients implementation -independence from these choices, a generic form is used to represent header -data in the API.

            The headers class is provided by RHTTPHeaders.

            Data -suppliers

            The body portion of requests and responses is represented -in the API as a mix-in interface, allowing the real implementation of the -classes that generate body data to be fully hidden. The API enables signalling -between the client and the transport in use, to ensure that body data is only -used or released at a rate the client can support. This means that clients -can assemble the body of their requests piece-by-piece, have each piece transmitted -only when it is ready, and be signalled when transmission is complete so the -next piece may be prepared and the old one released.

            Data supplier -classes must implement MHTTPDataSupplier.

            Filters

            Filters -are add-on modules that provide additional behaviours to a session beyond -the simple request-response transaction described earlier. Behaviours may -be triggered by the presence of particular headers in a request or a response, -by status codes in a response, or by particular events that occur on a transaction. -RFC 2616 describes a number of standard behaviours that occur over a series -of request-response exchanges: client authentication, redirection, and caching. -Client authentication and redirection are implemented as individual filters.

            Filter -classes must implement MHTTPFilter.

            Refer to Filters for more information.

            -
            Example code

            Example -code used throughout this guide is taken from HTTPEXAMPLECLIENT, -a simple console application that provides a menu-driven interface to the -HTTP API.

            + + + + + +HTTP Client +overview +
            Purpose

            The +HTTP (Hypertext Transfer Protocol) Client API provides a client interface +for Internet applications to use the HTTP protocol for communication with +HTTP servers on the Internet. Using the API correctly enables the application +to be a conditionally HTTP 1.1 compliant client, as defined in RFC 2616.

            The +HTTP protocol is a request and response protocol. A client sends a request +to the server. This request consists of a request method, URI, and protocol +version, including a Multipurpose Internet Mail Extensions (MIME)-like message +containing request modifiers, client information, and body content over a +server connection. The server responds with a status, which includes the message's +protocol version and a success or error code, and a MIME-like message containing +server information, meta information, and body content. The following image +illustrates a simple HTTP session between a client and a server.

            + Simple HTTP Interaction + +

            See Hypertext +Transfer Protocol -- HTTP/1.1, RFC 2616 for more details.

            +
            Architectural +relationships

            The HTTP Client architecture provides a generalised +mechanism for HTTP-like protocols that operate over various transports. Using +a single API, a client can choose an HTTP protocol, encoding, and transport, +and need not implement these in its own code. The default operation provides +plain-text HTTP (as defined in RFC 2616) operating over a TCP/IP connection. +This transport pipelines requests by default.

            +
            Description

            There +are five key concepts used in the API: sessions, transactions, headers, data +suppliers, and filters.

            Sessions

            A session encapsulates +the client's HTTP activity over the duration of the client's execution. Typicallly, +one HTTP session runs in one active scheduler.

            Note: An active +scheduler must be installed when a session is opened.

            Usually, one +session is used at a time. However, the client may use several concurrently, +if required. Each session has an associated set of properties, which define +the HTTP protocol, encoding, and transport used. Those properties apply to +all HTTP transactions within the life of that session. The session also has +an associated set of filters that provide additional automatic behaviours +on the client's behalf.

            The session class is provided by RHTTPSession.

            Transactions

            A +transaction represents an interaction between a HTTP client and an HTTP origin +server. Normally a transaction consists of a single exchange of messages between +client and server: a client request and a server response. However, the transaction +may be extended or altered by filters that operate on it. See Filters for +more details.

            Transactions execute asychronously within the client's +process. The client is notified when events are available for each outstanding +transaction.

            Both the request and response portion of a transaction +consist of a header and an optional body. The request portion of the transaction +also specifies an HTTP Method that describes the type of operation that the +client wants to invoke at the origin server, together with a URI that specifies +the resource held at the server on which the method is to be invoked. The +response portion of a transaction contains an HTTP status code and message, +which indicate the success of the method or the state of the resource following +the method. The use of request and response bodies is determined by the HTTP +method in use. For example, in error conditions, some servers may just return +a status code and message, providing no entity body.

            The transaction +class is provided by RHTTPTransaction.

            Headers

            The +header portion of requests and responses may have zero or more fields, which +are used to convey information between the HTTP client and server. The information +might relate to the data conveyed in body of the message, to the actual connection +between the client and server, or might be used to convey data describing +the client or server themselves. Typically, headers can contain content encoding +and transfer encoding information. Since the HTTP API gives clients implementation +independence from these choices, a generic form is used to represent header +data in the API.

            The headers class is provided by RHTTPHeaders.

            Data +suppliers

            The body portion of requests and responses is represented +in the API as a mix-in interface, allowing the real implementation of the +classes that generate body data to be fully hidden. The API enables signalling +between the client and the transport in use, to ensure that body data is only +used or released at a rate the client can support. This means that clients +can assemble the body of their requests piece-by-piece, have each piece transmitted +only when it is ready, and be signalled when transmission is complete so the +next piece may be prepared and the old one released.

            Data supplier +classes must implement MHTTPDataSupplier.

            Filters

            Filters +are add-on modules that provide additional behaviours to a session beyond +the simple request-response transaction described earlier. Behaviours may +be triggered by the presence of particular headers in a request or a response, +by status codes in a response, or by particular events that occur on a transaction. +RFC 2616 describes a number of standard behaviours that occur over a series +of request-response exchanges: client authentication, redirection, and caching. +Client authentication and redirection are implemented as individual filters.

            Filter +classes must implement MHTTPFilter.

            Refer to Filters for more information.

            +
            Example code

            Example +code used throughout this guide is taken from HTTPEXAMPLECLIENT, +a simple console application that provides a menu-driven interface to the +HTTP API.

            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-50BE8F1A-513A-433C-B045-66658FC226D7.dita --- a/Symbian3/SDK/Source/GUID-50BE8F1A-513A-433C-B045-66658FC226D7.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-50BE8F1A-513A-433C-B045-66658FC226D7.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,40 +1,40 @@ - - - - - -Client/server -communication -

            Inter Process -Communication (IPC) is the basis for client/server architecture. Clients -and servers run in different threads, although not necessarily in different -processes, and communicate through message passing protocol. There are no -direct pointers between the parties, leaving the integrity of the server and -its resources untouched by clients. For more information, see Introduction -to the client/server architecture.

            -

            Communication between the client and the server is managed by Inter-thread data transfer. -Only the server and its clients can decode the parameters of the message. -This is also a security feature, because process boundaries are separators -of memory space, direct pointers to the client's data structures cannot be -delivered. All data not fitting in the provided integers must be represented -as a descriptor, -and an address to the descriptor (or actually a TPckg object) -is delivered within the message. The server then uses safe inter-thread read -and write functions to access the provided descriptor.

            -

            The following figure shows the relationship of the TDesC and TPckg classes.

            -Relationship of a message package and a descriptor class -

            Consider the following issues when implementing the client-side API:

            -
              -

            • Determine if the server is already running with the TFindServer class. If not, then it should be launched.

              • -

            • Once the server is running, create the connection with RSessionBase::CreateSession and make sure there are free message slots available to avoid lost -messages.

              • -

            • When packaging message arguments, make sure they are in a -format that the server understands. For more information, see TIpcArgs.

              • -
            + + + + + +Client/server +communication +

            Inter Process +Communication (IPC) is the basis for client/server architecture. Clients +and servers run in different threads, although not necessarily in different +processes, and communicate through message passing protocol. There are no +direct pointers between the parties, leaving the integrity of the server and +its resources untouched by clients. For more information, see Introduction +to the client/server architecture.

            +

            Communication between the client and the server is managed by Inter-thread data transfer. +Only the server and its clients can decode the parameters of the message. +This is also a security feature, because process boundaries are separators +of memory space, direct pointers to the client's data structures cannot be +delivered. All data not fitting in the provided integers must be represented +as a descriptor, +and an address to the descriptor (or actually a TPckg object) +is delivered within the message. The server then uses safe inter-thread read +and write functions to access the provided descriptor.

            +

            The following figure shows the relationship of the TDesC and TPckg classes.

            +Relationship of a message package and a descriptor class +

            Consider the following issues when implementing the client-side API:

            +
              +

            • Determine if the server is already running with the TFindServer class. If not, then it should be launched.

              • +

            • Once the server is running, create the connection with RSessionBase::CreateSession and make sure there are free message slots available to avoid lost +messages.

              • +

            • When packaging message arguments, make sure they are in a +format that the server understands. For more information, see TIpcArgs.

              • +
             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-50CA5439-29A1-426C-83BA-EC048FE86CDE.dita --- a/Symbian3/SDK/Source/GUID-50CA5439-29A1-426C-83BA-EC048FE86CDE.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-50CA5439-29A1-426C-83BA-EC048FE86CDE.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,52 +1,52 @@ - - - - - -Allowing -Large Memory AllocationThis section describes how an application can request for free -memory from OOM Monitor for large amount of RAM allocation. -

            An application -can allocate RAM without seeking the permission from the OOM Monitor if the -amount of RAM is not over KOomMaxAllocationWithoutPermission limit. -

            If an application needs to allocate more RAM than allocated by KOomMaxAllocationWithoutPermission, -it must request the OOM Monitor using the ROomMonitorSession::RequestFreeMemory() method.

            An -application can request for free RAM either synchronously or asynchronously.

            -             - -Create an OOM Monitor -session -ROomMonitorSession ioomMonitorSession; -CleanUpClosePushL(ioomMonitorSession); -User::LeaveIfError(ioomMonitorSession.Connect()); - - -Request for free -memory can be done in two ways: - - -

            The OOM Monitor -allows the client application to allocate memory, if the free RAM level is -above the LOW_RAM_THRESHOLD value.

            If the free RAM -level is below the LOW_RAM_THRESHOLD value, -the OOM Monitor releases RAM using ROomMonitorSession::RequestFreeMemory() method. -This method returns the following values:

              -

            • Requested amount of RAM is available then aStatus is -set to KErrNone.

              • -

            • Requested amount of RAM is not available then aStatus is -set to KErrNoMemory.

              • -

             -             -OOM Monitor -Concepts -OOM Monitor -Overview -OOM Monitor -Reference + + + + + +Allowing +Large Memory AllocationThis section describes how an application can request for free +memory from OOM Monitor for large amount of RAM allocation. +

            An application +can allocate RAM without seeking the permission from the OOM Monitor if the +amount of RAM is not over KOomMaxAllocationWithoutPermission limit. +

            If an application needs to allocate more RAM than allocated by KOomMaxAllocationWithoutPermission, +it must request the OOM Monitor using the ROomMonitorSession::RequestFreeMemory() method.

            An +application can request for free RAM either synchronously or asynchronously.

            +             + +Create an OOM Monitor +session +ROomMonitorSession ioomMonitorSession; +CleanUpClosePushL(ioomMonitorSession); +User::LeaveIfError(ioomMonitorSession.Connect()); + + +Request for free +memory can be done in two ways: + + +

            The OOM Monitor +allows the client application to allocate memory, if the free RAM level is +above the LOW_RAM_THRESHOLD value.

            If the free RAM +level is below the LOW_RAM_THRESHOLD value, +the OOM Monitor releases RAM using ROomMonitorSession::RequestFreeMemory() method. +This method returns the following values:

              +

            • Requested amount of RAM is available then aStatus is +set to KErrNone.

              • +

            • Requested amount of RAM is not available then aStatus is +set to KErrNoMemory.

              • +

             +             +OOM Monitor +Concepts +OOM Monitor +Overview +OOM Monitor +Reference             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5107ABD8-6408-5501-8073-ACAF3719247B.dita --- a/Symbian3/SDK/Source/GUID-5107ABD8-6408-5501-8073-ACAF3719247B.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-5107ABD8-6408-5501-8073-ACAF3719247B.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,89 +1,89 @@ - - - - - -Resizable -buffer descriptorsDescribes descriptor behaviour and resizable buffer descriptors. -

            A resizable buffer descriptor provides a buffer, allocated on the heap, -to contain and access data. The data is not part of the descriptor object.

            -

            The data represented by this descriptor can be both accessed and changed -through the descriptor itself. Data is accessed through functions provided -by the base class. The size of the buffer used by this descriptor can also -be changed. Note that unlike dynamic buffers, reallocation is not done automatically; -the descriptor provides an API that allows you to do reallocation.

            -

            The descriptor has similarities to the standard heap descriptor,HBufC, -but is easier to use. The standard heap descriptor is recommended for -use when the data it represents rarely changes. The resizable buffer descriptor -is recommended for use when the data changes frequently.

            -

            This descriptor also has the following additional useful behaviour:

            -
              -

            • ownership of an existing -heap descriptor can be transferred to a resizable buffer descriptor.

              • -

            • ownership of memory -that has already been allocated elsewhere can be transferred to a resizable -buffer descriptor; this memory becomes the buffer used by the descriptor.

              • -

            • ownership of memory -owned by a resizable buffer descriptor can be transferred to another resizable -buffer descriptor.

              • -
            -

            The important point is that the user of the class need not be concerned -about the 'origins' of the memory.

            -

            A resizable buffer descriptor is supplied in two variants:

            -
              -

            • a 16-bit variant, a RBuf16, -to contain wide strings, and 16-bit wide data.

              • -

            • an 8-bit variant, a RBuf8, -to contain narrow strings and binary data.

              • -
            -

            There is also a build independent type, RBuf. This is -the type that is most commonly used in program code; this is set (i.e. typedef) -to the appropriate 'real' variant at build time, and by default equates to RBuf16.

            -

            You would use an explicit 8-bit variant for binary data. An explicit 16-bit -variant is rarely used.

            -

            When discussing a resizable buffer descriptor, we normally refer to RBuf, -rather than RBuf8 or RBuf16. We only -refer to RBuf8 or RBuf16 when they explicitly -need to be used.

            -

            The following drawing shows how an RBuf type is constructed. -It is derived from TDes and TDesC; the -member data of these base classes hold the length and maximum length for the -descriptor data. RBuf itself only contains a single pointer. -The pointer is interpreted in one of two ways, depending on how its buffer -has been set up:

            -
              -

            • as a simple pointer -to memory on the heap.

              • -

            • as a pointer to a previously -created HBufC heap descriptor; ownership of the HBufC descriptor -buffer will have been transferred to the RBuf.

              • -
            -

            The way descriptors in Symbian platform are implemented allows RBuf to -distinguish between the two.

            -

            The following drawing shows the internal representation of an RBuf object -initialised with a string of five characters representing the English word -"Hello". There are two possibilities:

            -
              -

            • the case where the buffer -consists of simple memory, either allocated directly by the object itself, -or assigned to it after having been allocated elsewhere.

              • -

            • the case where the buffer -was originally allocated as a standard heap descriptor, a HBufC type, -and whose ownership has been transferred.

              • -
            -

            Remember that RBuf is derived from both TDes and TDesC, -and these classes provide the data members the contain the maximum length -and the current length of the data.

            - - - -

            While an RBuf descriptor has similarities to a heap descriptor, -it behaves more like a standard 'R' type resource class, i.e. as a handle -to a real resource maintained elsewhere.

            + + + + + +Resizable +buffer descriptorsDescribes descriptor behaviour and resizable buffer descriptors. +

            A resizable buffer descriptor provides a buffer, allocated on the heap, +to contain and access data. The data is not part of the descriptor object.

            +

            The data represented by this descriptor can be both accessed and changed +through the descriptor itself. Data is accessed through functions provided +by the base class. The size of the buffer used by this descriptor can also +be changed. Note that unlike dynamic buffers, reallocation is not done automatically; +the descriptor provides an API that allows you to do reallocation.

            +

            The descriptor has similarities to the standard heap descriptor,HBufC, +but is easier to use. The standard heap descriptor is recommended for +use when the data it represents rarely changes. The resizable buffer descriptor +is recommended for use when the data changes frequently.

            +

            This descriptor also has the following additional useful behaviour:

            +
              +

            • ownership of an existing +heap descriptor can be transferred to a resizable buffer descriptor.

              • +

            • ownership of memory +that has already been allocated elsewhere can be transferred to a resizable +buffer descriptor; this memory becomes the buffer used by the descriptor.

              • +

            • ownership of memory +owned by a resizable buffer descriptor can be transferred to another resizable +buffer descriptor.

              • +
            +

            The important point is that the user of the class need not be concerned +about the 'origins' of the memory.

            +

            A resizable buffer descriptor is supplied in two variants:

            +
              +

            • a 16-bit variant, a RBuf16, +to contain wide strings, and 16-bit wide data.

              • +

            • an 8-bit variant, a RBuf8, +to contain narrow strings and binary data.

              • +
            +

            There is also a build independent type, RBuf. This is +the type that is most commonly used in program code; this is set (i.e. typedef) +to the appropriate 'real' variant at build time, and by default equates to RBuf16.

            +

            You would use an explicit 8-bit variant for binary data. An explicit 16-bit +variant is rarely used.

            +

            When discussing a resizable buffer descriptor, we normally refer to RBuf, +rather than RBuf8 or RBuf16. We only +refer to RBuf8 or RBuf16 when they explicitly +need to be used.

            +

            The following drawing shows how an RBuf type is constructed. +It is derived from TDes and TDesC; the +member data of these base classes hold the length and maximum length for the +descriptor data. RBuf itself only contains a single pointer. +The pointer is interpreted in one of two ways, depending on how its buffer +has been set up:

            +
              +

            • as a simple pointer +to memory on the heap.

              • +

            • as a pointer to a previously +created HBufC heap descriptor; ownership of the HBufC descriptor +buffer will have been transferred to the RBuf.

              • +
            +

            The way descriptors in Symbian platform are implemented allows RBuf to +distinguish between the two.

            +

            The following drawing shows the internal representation of an RBuf object +initialised with a string of five characters representing the English word +"Hello". There are two possibilities:

            +
              +

            • the case where the buffer +consists of simple memory, either allocated directly by the object itself, +or assigned to it after having been allocated elsewhere.

              • +

            • the case where the buffer +was originally allocated as a standard heap descriptor, a HBufC type, +and whose ownership has been transferred.

              • +
            +

            Remember that RBuf is derived from both TDes and TDesC, +and these classes provide the data members the contain the maximum length +and the current length of the data.

            + + + +

            While an RBuf descriptor has similarities to a heap descriptor, +it behaves more like a standard 'R' type resource class, i.e. as a handle +to a real resource maintained elsewhere.

            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5127C80E-EACE-5524-9A75-A0EFB41C2226.dita --- a/Symbian3/SDK/Source/GUID-5127C80E-EACE-5524-9A75-A0EFB41C2226.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-5127C80E-EACE-5524-9A75-A0EFB41C2226.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,40 +1,40 @@ - - - - - -Circular -Buffer structureThis document describes the structure of circular buffers. -

            "Circular Buffers" is a sub-API of the "Buffers and strings" API.

            -

            A circular buffer provides a simple way of implementing a fixed length -queue of fixed size objects where objects are added to the head of the queue -while items are removed from the tail of the queue.

            -

            Logically, the buffer is circular with no defined start or end. Objects -are always added to the buffer head and are always removed from the buffer -tail. The buffer head is always the next vacant slot into which an object -is added. The buffer tail is always the slot from which the next object is -removed. The tail always logically follows the head and the implementation -ensures that the tail never overtakes the head.

            - - - -

            Physically, the buffer is a contiguous block of memory. The implementation -provides the appearance of circularity.

            -

            A circular buffer has a maximum capacity which must be set before the circular -buffer can be used. The maximum capacity can be changed at any time but any -existing data within the buffer is lost.

            -

            The sub-API consists of three classes, two of which can be instantiated:

            -
              -

            • the templated class CCirBuf<class -T> builds a circular buffer of general objects.

              • -

            • the CCirBuffer class -builds a circular buffer of unsigned integers with values ranging from -128 -to +128.

              • -
            + + + + + +Circular +Buffer structureThis document describes the structure of circular buffers. +

            "Circular Buffers" is a sub-API of the "Buffers and strings" API.

            +

            A circular buffer provides a simple way of implementing a fixed length +queue of fixed size objects where objects are added to the head of the queue +while items are removed from the tail of the queue.

            +

            Logically, the buffer is circular with no defined start or end. Objects +are always added to the buffer head and are always removed from the buffer +tail. The buffer head is always the next vacant slot into which an object +is added. The buffer tail is always the slot from which the next object is +removed. The tail always logically follows the head and the implementation +ensures that the tail never overtakes the head.

            + + + +

            Physically, the buffer is a contiguous block of memory. The implementation +provides the appearance of circularity.

            +

            A circular buffer has a maximum capacity which must be set before the circular +buffer can be used. The maximum capacity can be changed at any time but any +existing data within the buffer is lost.

            +

            The sub-API consists of three classes, two of which can be instantiated:

            +
              +

            • the templated class CCirBuf<class +T> builds a circular buffer of general objects.

              • +

            • the CCirBuffer class +builds a circular buffer of unsigned integers with values ranging from -128 +to +128.

              • +
             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-512D0DA7-0BC2-534F-9233-11F46D285CA6_d0e5873_href.png Binary file Symbian3/SDK/Source/GUID-512D0DA7-0BC2-534F-9233-11F46D285CA6_d0e5873_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-512D0DA7-0BC2-534F-9233-11F46D285CA6_d0e7148_href.png Binary file Symbian3/SDK/Source/GUID-512D0DA7-0BC2-534F-9233-11F46D285CA6_d0e7148_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-516D2E22-F5C0-56FE-ABDA-948F01CD50DB_d0e215568_href.png Binary file Symbian3/SDK/Source/GUID-516D2E22-F5C0-56FE-ABDA-948F01CD50DB_d0e215568_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-516D2E22-F5C0-56FE-ABDA-948F01CD50DB_d0e219305_href.png Binary file Symbian3/SDK/Source/GUID-516D2E22-F5C0-56FE-ABDA-948F01CD50DB_d0e219305_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-517D9795-88BC-5959-9384-36F132AE634C_d0e135615_href.png Binary file Symbian3/SDK/Source/GUID-517D9795-88BC-5959-9384-36F132AE634C_d0e135615_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-517D9795-88BC-5959-9384-36F132AE634C_d0e142149_href.png Binary file Symbian3/SDK/Source/GUID-517D9795-88BC-5959-9384-36F132AE634C_d0e142149_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-51B0D0A9-C9FA-59DA-82B1-5834980CB35D_d0e271836_href.jpg Binary file Symbian3/SDK/Source/GUID-51B0D0A9-C9FA-59DA-82B1-5834980CB35D_d0e271836_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-51B0D0A9-C9FA-59DA-82B1-5834980CB35D_d0e275517_href.jpg Binary file Symbian3/SDK/Source/GUID-51B0D0A9-C9FA-59DA-82B1-5834980CB35D_d0e275517_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-51D6F328-82C4-5224-A51B-3EB9D4FF7B4C_d0e336843_href.png Binary file Symbian3/SDK/Source/GUID-51D6F328-82C4-5224-A51B-3EB9D4FF7B4C_d0e336843_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-51D6F328-82C4-5224-A51B-3EB9D4FF7B4C_d0e343040_href.png Binary file Symbian3/SDK/Source/GUID-51D6F328-82C4-5224-A51B-3EB9D4FF7B4C_d0e343040_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-51DDCDA8-8B26-4016-8CBA-BDBF82447096-master.png Binary file Symbian3/SDK/Source/GUID-51DDCDA8-8B26-4016-8CBA-BDBF82447096-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-51DDCDA8-8B26-4016-8CBA-BDBF82447096_d0e52712_href.png Binary file Symbian3/SDK/Source/GUID-51DDCDA8-8B26-4016-8CBA-BDBF82447096_d0e52712_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-51DDCDA8-8B26-4016-8CBA-BDBF82447096_d0e58798_href.png Binary file Symbian3/SDK/Source/GUID-51DDCDA8-8B26-4016-8CBA-BDBF82447096_d0e58798_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-51E0F9C6-CFAF-5113-8516-30045B1269C7_d0e108759_href.png Binary file Symbian3/SDK/Source/GUID-51E0F9C6-CFAF-5113-8516-30045B1269C7_d0e108759_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-51E0F9C6-CFAF-5113-8516-30045B1269C7_d0e115297_href.png Binary file Symbian3/SDK/Source/GUID-51E0F9C6-CFAF-5113-8516-30045B1269C7_d0e115297_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-51F43258-B3D8-5EC9-85EF-67F09499C253.dita --- a/Symbian3/SDK/Source/GUID-51F43258-B3D8-5EC9-85EF-67F09499C253.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-51F43258-B3D8-5EC9-85EF-67F09499C253.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,14 +1,14 @@ - - - - - -Alarm States

            This section explains the various states of an alarm.

            At a given point of time, alarms can be in only one state, which is represented by TAlarmState. The following diagram is self-explanatory and represents the state transition of alarms:

            - State Transition of Alarms -

            See Also

            Types of Alarm

            \ No newline at end of file + + + + + +Alarm States

            This section explains the various states of an alarm.

            At a given point of time, alarms can be in only one state, which is represented by TAlarmState. The following diagram is self-explanatory and represents the state transition of alarms:

            + State Transition of Alarms +

            See Also

            Types of Alarm

            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-51F63BFF-CD62-4FFC-929D-ED778642044E_d0e63705_href.png Binary file Symbian3/SDK/Source/GUID-51F63BFF-CD62-4FFC-929D-ED778642044E_d0e63705_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-51F63BFF-CD62-4FFC-929D-ED778642044E_d0e68930_href.png Binary file Symbian3/SDK/Source/GUID-51F63BFF-CD62-4FFC-929D-ED778642044E_d0e68930_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5223D1C1-CBBE-551A-AC57-CD94F9D1B9B6_d0e273833_href.png Binary file Symbian3/SDK/Source/GUID-5223D1C1-CBBE-551A-AC57-CD94F9D1B9B6_d0e273833_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5223D1C1-CBBE-551A-AC57-CD94F9D1B9B6_d0e277514_href.png Binary file Symbian3/SDK/Source/GUID-5223D1C1-CBBE-551A-AC57-CD94F9D1B9B6_d0e277514_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-52743192-B1E0-5B71-B85B-43487F18F412_d0e427403_href.png Binary file Symbian3/SDK/Source/GUID-52743192-B1E0-5B71-B85B-43487F18F412_d0e427403_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-52743192-B1E0-5B71-B85B-43487F18F412_d0e427565_href.png Binary file Symbian3/SDK/Source/GUID-52743192-B1E0-5B71-B85B-43487F18F412_d0e427565_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-52783B69-09FC-4123-849A-79FF61406129_d0e38122_href.png Binary file Symbian3/SDK/Source/GUID-52783B69-09FC-4123-849A-79FF61406129_d0e38122_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-52783B69-09FC-4123-849A-79FF61406129_d0e43689_href.png Binary file Symbian3/SDK/Source/GUID-52783B69-09FC-4123-849A-79FF61406129_d0e43689_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-530AB0D9-BE70-5892-BFBA-213687CA62D1_d0e357398_href.png Binary file Symbian3/SDK/Source/GUID-530AB0D9-BE70-5892-BFBA-213687CA62D1_d0e357398_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-530AB0D9-BE70-5892-BFBA-213687CA62D1_d0e363478_href.png Binary file Symbian3/SDK/Source/GUID-530AB0D9-BE70-5892-BFBA-213687CA62D1_d0e363478_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-53212F7A-938B-48F6-BC82-30F7494FF8A7-master.png Binary file Symbian3/SDK/Source/GUID-53212F7A-938B-48F6-BC82-30F7494FF8A7-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-53212F7A-938B-48F6-BC82-30F7494FF8A7_d0e82132_href.png Binary file Symbian3/SDK/Source/GUID-53212F7A-938B-48F6-BC82-30F7494FF8A7_d0e82132_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-53313E89-3E23-4004-BD10-771858657DAD-master.png Binary file Symbian3/SDK/Source/GUID-53313E89-3E23-4004-BD10-771858657DAD-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-53313E89-3E23-4004-BD10-771858657DAD_d0e57718_href.png Binary file Symbian3/SDK/Source/GUID-53313E89-3E23-4004-BD10-771858657DAD_d0e57718_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-53313E89-3E23-4004-BD10-771858657DAD_d0e67159_href.png Binary file Symbian3/SDK/Source/GUID-53313E89-3E23-4004-BD10-771858657DAD_d0e67159_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-534C1D1A-9450-5A1B-933F-5157039BF069_d0e309152_href.png Binary file Symbian3/SDK/Source/GUID-534C1D1A-9450-5A1B-933F-5157039BF069_d0e309152_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-534C1D1A-9450-5A1B-933F-5157039BF069_d0e315546_href.png Binary file Symbian3/SDK/Source/GUID-534C1D1A-9450-5A1B-933F-5157039BF069_d0e315546_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5357F135-46B1-5C3F-BD2D-2E71D7BD0046_d0e76242_href.png Binary file Symbian3/SDK/Source/GUID-5357F135-46B1-5C3F-BD2D-2E71D7BD0046_d0e76242_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5357F135-46B1-5C3F-BD2D-2E71D7BD0046_d0e82954_href.png Binary file Symbian3/SDK/Source/GUID-5357F135-46B1-5C3F-BD2D-2E71D7BD0046_d0e82954_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-535954FD-2501-5C80-AD86-AC73A86B18B5.dita --- a/Symbian3/SDK/Source/GUID-535954FD-2501-5C80-AD86-AC73A86B18B5.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-535954FD-2501-5C80-AD86-AC73A86B18B5.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,29 +1,29 @@ - - - - - -Internalising a Swizzle

            Internalising a Swizzle from a stream has assignment semantics.

            The process of internalisation assumes that the current position within the stream contains the external representation of a stream ID. The stream which corresponds to this ID contains the external representation of some object.

            The result is a Swizzle which represents the object by stream ID.

            The following code fragments illustrate the process.

            iB is a CClassB type component of a class CClassABC, and is represented by a Swizzle. The data member is defined as:

            class CCClassABC : public CBase - { - ... - TSwizzle<CClassB> iB; - ... - } -

            The example assumes that the stream ID of the swizzled object has been externalised as in Externalizing a Swizzle.

            CClassB's RestoreL() and InternalizeL() functions are implemented as:

            void CClassABC::RestoreL() - { - RStoreReadStream stream; - stream.OpenLC(iStore,iId); - InternalizeL(stream); - CleanupStack::PopAndDestroy(); - } void CClassABC::InternalizeL(RReadStream& aStream) - { - ... - aStream >> iB; // internalises Swizzle from stream - ... - }

            Here, iId is the stream ID containing CClassABC data.

             \ No newline at end of file + + + + + +Internalising a Swizzle

            Internalising a Swizzle from a stream has assignment semantics.

            The process of internalisation assumes that the current position within the stream contains the external representation of a stream ID. The stream which corresponds to this ID contains the external representation of some object.

            The result is a Swizzle which represents the object by stream ID.

            The following code fragments illustrate the process.

            iB is a CClassB type component of a class CClassABC, and is represented by a Swizzle. The data member is defined as:

            class CCClassABC : public CBase + { + ... + TSwizzle<CClassB> iB; + ... + } +

            The example assumes that the stream ID of the swizzled object has been externalised as in Externalizing a Swizzle.

            CClassB's RestoreL() and InternalizeL() functions are implemented as:

            void CClassABC::RestoreL() + { + RStoreReadStream stream; + stream.OpenLC(iStore,iId); + InternalizeL(stream); + CleanupStack::PopAndDestroy(); + } void CClassABC::InternalizeL(RReadStream& aStream) + { + ... + aStream >> iB; // internalises Swizzle from stream + ... + }

            Here, iId is the stream ID containing CClassABC data.

             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-536B2F20-DB19-595C-A465-25CF2E421050_d0e107147_href.png Binary file Symbian3/SDK/Source/GUID-536B2F20-DB19-595C-A465-25CF2E421050_d0e107147_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-536B2F20-DB19-595C-A465-25CF2E421050_d0e113685_href.png Binary file Symbian3/SDK/Source/GUID-536B2F20-DB19-595C-A465-25CF2E421050_d0e113685_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-53707903-9A88-409B-80F8-FDF7EF47ACBF.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-53707903-9A88-409B-80F8-FDF7EF47ACBF.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,102 @@ + + + + + +CoverFlow: using ScreenPlayThis example application demonstrates creating semi-transparent +UI content over OpenVG content that is rendered to a composition surface. +This is only possible when ScreenPlay is enabled. +
            Download

            Click on the following link to download the example: GraphicsShell.zip

            Click: browse to view the example code.

            The example +is located in the examples\Graphics\CoverFlow directory.

            +
            Description This code implements a 'coverflow' application. It uses OpenVG to +display images while semi-transparent or transparent windows and controls +are used to display overlaid content. The application does the following: +
              +
            • Creates an EGL drawing surface by calling the eglCreateWindowSurface() function.
              • +
            • Converts bitmap cover images to OpenVG images.
              • +
            • Applies OpenVG transformations on the converted OpenVG images.
              • +
            • Draws the transformed images on the EGL surface by calling the vgDrawImage() function.
              • +
            • Draws the mirror image of bitmap cover images on the surface.
              • +
            • Displays an incoming call animation and a moving ticker window +in a separate active object. These are activated when relevant key +press events are detected. It uses the invalidate and re-draw pattern +of the window server to draw the contents on the window.
              • +
            The ScreenPlay graphics architecture uses a composition +engine to display multiple overlaid windows. The composition engine +takes multiple overlaid surfaces as input and creates a single screen +buffer. For more information, see Graphics Composition and The ScreenPlay +Graphics Architecture.
            +
            Screenshots + Basic Screenshot + + +Screenshot showing ticker and incoming call animation + + +Screenshot showing the absence of the mirror surface + +
            +
            Class +Summary

            These are the principal classes used in this example:

              +
            • CCoverFlowAppUi
              • +
            • CEGLRendering
              • +
            • MEngine
              • +
            • CDialogBox
              • +
            • COpenVGEngine
              • +
            • CTicker
              • +
            • CLoader
              • +

            +
            Design +and Implementation

            +UML class diagram + + +

            +
            Building +and running

            The Symbian build +process describes how to build an application.

            +
            Configuration +settings for running the example on an Emulator or H4 board
              +

            1. Change the WINDOWMODE parameter to Color16MAP in epoc32\release\winscw\<udeb/urel>\z\system\data\wsini.ini (epoc32\data\z\system\data\wsini.ini on the H4 board).

              2. +

            2. The application +cannot run if ScreenPlay is disabled. If it is not already enabled, +you need to enable it. See Enabling the Graphics +Architecture Variants for more information.

              3. +

            3. (Emulator only): +Copy all .mbm (image) files from the coverflow\gfx\call directory to the epoc32\release\winscw\<udeb/urel>\z\resource\apps directory.

              4. +

            4. Performance +can be boosted significantly by switching to portrait mode, which +is the native mode for the LCD controller. To enable portrait mode, +uncomment the following line in the coverflowapp.mmp:

              // MACRO PORTRAIT_MODE
              5. +

            5. Add the following +configuration statements to the epoc32\data\epoc.ini to run the example in portrait mode.

              screenwidth 240 +screenheight 320 +fasciabitmap null.bmp +screenoffsetx 0 +screenoffsety 0
              6. +
            + + +
            Running +and using the example

              +
            1. Run coverflowapp.exe.
              2. +
            2. Press the Left +or the Right arrow key to navigate through the covers.
              3. +
            3. Press the Down +arrow key to show or hide the Ticker at the bottom of the screen.
              4. +
            4. Press the Up arrow +key to show or hide the incoming call animation.
              5. +
            5. Press the Tab key +to show or hide the semi-transparent green window around the incoming +call animation.
              6. +
            6. Press the Backspace +key to show or hide mirror images of the covers.
              7. +

            + +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5398C2DC-9AFA-5517-BCBF-5964970B9656_d0e230704_href.png Binary file Symbian3/SDK/Source/GUID-5398C2DC-9AFA-5517-BCBF-5964970B9656_d0e230704_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5398C2DC-9AFA-5517-BCBF-5964970B9656_d0e234441_href.png Binary file Symbian3/SDK/Source/GUID-5398C2DC-9AFA-5517-BCBF-5964970B9656_d0e234441_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-53A2CA11-2ABF-5ED7-A26C-7BE9FD9A1D22_d0e281197_href.png Binary file Symbian3/SDK/Source/GUID-53A2CA11-2ABF-5ED7-A26C-7BE9FD9A1D22_d0e281197_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-53A2CA11-2ABF-5ED7-A26C-7BE9FD9A1D22_d0e284883_href.png Binary file Symbian3/SDK/Source/GUID-53A2CA11-2ABF-5ED7-A26C-7BE9FD9A1D22_d0e284883_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-53A5AC8D-8A43-505F-A0B6-9E34F3CF23BE.dita --- a/Symbian3/SDK/Source/GUID-53A5AC8D-8A43-505F-A0B6-9E34F3CF23BE.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-53A5AC8D-8A43-505F-A0B6-9E34F3CF23BE.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,12 +1,12 @@ - - - - - -Playing AudioThis tutorial describes you how to start playing, pausing and resuming, stopping, retrieving the number of samples in the audio data.

            Before you start, you must:

            • Understand the A3F DevSound Component to which the DevSound library belongs.

            • Understand the architectural relationship of the DevSound. For information see DevSound Overview.

            You can perform various functionality in DevSound audio playing that are listed in the below section.

            Starting Audio Play Pausing and Resuming Audio Play Stopping Audio Play Retrieving Audio Play Samples             Recording Audio Playing Tones             \ No newline at end of file + + + + + +Playing AudioThis tutorial describes you how to start playing, pausing and resuming, stopping, retrieving the number of samples in the audio data.

            Before you start, you must:

            • Understand the A3F DevSound Component to which the DevSound library belongs.

            • Understand the architectural relationship of the DevSound. For information see DevSound Overview.

            You can perform various functionality in DevSound audio playing that are listed in the below section.

            Starting Audio Play Pausing and Resuming Audio Play Stopping Audio Play Retrieving Audio Play Samples             Recording Audio Playing Tones             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-53C71C87-BFD9-4C9A-8A90-6735494F300C.dita --- a/Symbian3/SDK/Source/GUID-53C71C87-BFD9-4C9A-8A90-6735494F300C.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-53C71C87-BFD9-4C9A-8A90-6735494F300C.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,23 +1,23 @@ - - - - - -Always-editable -forms -

            In case the View state is not useful, the form can be specified as Edit-state -only. Then the user can edit the fields right away when entering the form, -and accepting the form returns into a state outside the form instead of the -View state.

            - -Form in the Edit state - - -

            + + + + + +Always-editable +forms +

            In case the View state is not useful, the form can be specified as Edit-state +only. Then the user can edit the fields right away when entering the form, +and accepting the form returns into a state outside the form instead of the +View state.

            + +Form in the Edit state + + +

            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-541C8505-335F-5C93-8C0E-96BCEE39D1E6_d0e228979_href.png Binary file Symbian3/SDK/Source/GUID-541C8505-335F-5C93-8C0E-96BCEE39D1E6_d0e228979_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-541C8505-335F-5C93-8C0E-96BCEE39D1E6_d0e232716_href.png Binary file Symbian3/SDK/Source/GUID-541C8505-335F-5C93-8C0E-96BCEE39D1E6_d0e232716_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-54401E25-31F5-58E8-AE8A-276DE5E9C072_d0e164369_href.jpg Binary file Symbian3/SDK/Source/GUID-54401E25-31F5-58E8-AE8A-276DE5E9C072_d0e164369_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-54401E25-31F5-58E8-AE8A-276DE5E9C072_d0e170970_href.jpg Binary file Symbian3/SDK/Source/GUID-54401E25-31F5-58E8-AE8A-276DE5E9C072_d0e170970_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5486EFD3-4660-4C19-A007-286DE48F6EEF.dita --- a/Symbian3/SDK/Source/GUID-5486EFD3-4660-4C19-A007-286DE48F6EEF.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-5486EFD3-4660-4C19-A007-286DE48F6EEF.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,42 +1,67 @@ - - - - - -Scaling -and positioning of controls -

            Interface elements -a user has to select and manipulate should not be smaller than the smallest -average finger pad, that is, no smaller than 1 cm (0.4") in diameter or a -1 cm × 1 cm square.

            In the Symbian platform, UI style defines the minimum -sizes for a UI element considered as finger usable:

              -

            • 7 x 7 mm with 1 mm gaps for index finger usage

              • -

            • 8 x 8 mm with 2 mm gaps for thumb usage

              • -

            • List type of components should have minimum of 5 mm line spacing

              • -

            The width of a finger limits the density of items on screen. If the -items are too close, the user will not be able to choose a single one.

            As -the probability of the user touching the higher end of the button (than on -the either side of the key) is high, button and icon sizes can be increased -vertically.

            Essential information or features, such as a label, instructions, -or sub-controls should never be placed below an interface element that can -be touched, as it may be hidden by the user's finger.

            - -Following are some useful tips that can be used while placing essential -information or features on interface element:
              -

            • With interfaces having input devices, it makes sense to place targets -like menu items on the edges of screens because the cursor movement stops -at the edge of the screen.

              • -

            • When using a touch screen, a user seldom drags the finger across the -screen like a cursor. Instead, they most likely lift their finger and place -it on a new target. Users may have difficulties in reaching the objects located -on the edges of the screen, especially if the physical device has protruding -edges around the touch screen panel. Additionally, with some devices, the -screen edges may be less sensitive to register the touch input.

              • -
            + + + + + +Scaling +and positioning of controls +

            Interface elements +a user has to select and manipulate should not be smaller than the smallest +average finger pad, that is, no smaller than 1 cm (0.4") in diameter or a +1 cm × 1 cm square.

            In the Symbian platform, UI style defines the minimum +sizes for a UI element considered as finger usable:

              +

            • 7 x 7 mm with 1 mm gaps for index finger usage

              • +

            • 8 x 8 mm with 2 mm gaps for thumb usage

              • +

            • List type of components should have minimum of 5 mm line spacing

              • +

            The width of a finger limits the density of items on screen. If the +items are too close, the user will not be able to choose a single one.

            As +the probability of the user touching the higher end of the button (than on +the either side of the key) is high, button and icon sizes can be increased +vertically.

            Essential information or features, such as a label, instructions, +or sub-controls should never be placed below an interface element that can +be touched, as it may be hidden by the user's finger.

            + +Following are some useful tips that can be used while placing essential +information or features on interface element:
              +

            • With interfaces having input devices, it makes sense to place targets +like menu items on the edges of screens because the cursor movement stops +at the edge of the screen.

              • +

            • When using a touch screen, a user seldom drags the finger across the +screen like a cursor. Instead, they most likely lift their finger and place +it on a new target. Users may have difficulties in reaching the objects located +on the edges of the screen, especially if the physical device has protruding +edges around the touch screen panel. Additionally, with some devices, the +screen edges may be less sensitive to register the touch input.

              • +
            +
            Finger usable UI

            Sylus can be used as +the input method with touch UI, but events apply to finger use also. However, +in some cases the components may not be finger optimized due to the size of +objects, for example, virtual keyboard or text field.

            In Symbian, UI +style defines the target minimum sizes for a UI element considered as finger +usable:

              +

            • 7 x 7 mm with 1 mm gaps for index finger usage

              • +

            • 8 x 8 mm with 2 mm gaps for thumb usage

              • +

            • List type of components should have minimum of 5 mm line spacing

              • +

            Targets are general as in practice sizes can be use case dependent, +for example, due to frequency of use, efficiency vs. error criticality or +ease of error correction, location of the button (edge of screen vs. center).

            The +visible area of the component and the component's active area should be identical. +There are exception cases to this rule though:

              +

            • When components are located near the edge of the display, the touchable +area should extend fully to the edge of the display (beyond the components +visible graphics).

              • +

            • Visible area is smaller than the active area in order to keep the balance +in look and feel of the UI. For example, scrollbar has wider touch area than +visible area.

              • +

            • Active area is smaller than the visible area in order to avoid unwanted +presses to contiguous active areas. In this case, there it should be graphically +indicated where the user should tap. Example: fixed toolbar buttons in landscape +layout.

              • +
             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-54EB6658-D2C1-514B-B9F1-BAB541A2972D.dita --- a/Symbian3/SDK/Source/GUID-54EB6658-D2C1-514B-B9F1-BAB541A2972D.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-54EB6658-D2C1-514B-B9F1-BAB541A2972D.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,12 +1,12 @@ - - - - - -Bitmap Devices and Contexts

            The BitGDI API provides extensions for bitmap devices of the abstract drawing device and context interfaces defined in the GDI API. The key interfaces defined by it, used for drawing on the screen, are in fact abstract. The Window Server provides concrete classes for on-screen drawing which derive from these interfaces. The concrete device and context classes that the API does provide are normally only used by applications to draw to in-memory bitmaps.

            Bitmap graphics context

            CBitmapContext specializes a GDI context (CGraphicsContext) for bitmap graphics. It provides extra functionality for:

            • clearing and copying rectangular areas

            • bitmap block transfer

            • setting pen color to a grey level

            • setting the shadow mode

            • resetting the GC settings to their default values

            The Window Server client-side API provides one implementation, CWindowGc, used for screen drawing. Another implementation, CFbsBitGc, is used for drawing to in-memory bitmaps.

            Bitmap graphics device

            CBitmapDevice specializes a graphics device (CGraphicsDevice) for bitmap graphics.

            The Window Server client-side API provides one implementation, CWsScreenDevice, for screen drawing. Another implementation, CFbsBitmapDevice, is used for drawing to in-memory bitmaps. A third, CFbsScreenDevice, is used (rarely) to access the screen directly, without the mediation of the window server.

            Screen driver information

            The screen width and height must be a multiple of four. In certain cases where the screen mode would result in a scanline (the scanline runs in the current horizontal direction of the screen) not being divisible by a whole word (32 bits) the screen width must also be a multiple of 16. This restriction will also apply to the height if there is a screen-size mode with a rotation of 90 or 270 (or both)

            For example, the screen mode EGray4 is 2 bits per pixel, therefore one word would be 16 pixels, so in order for the scanline to be a whole number of words the width must be a multiple of 16.

            The vertical height is unrestricted unless there is at least one screen-size mode with a rotation of 90 or 270 (or both).

            Bitmaps BitGDI Component             \ No newline at end of file + + + + + +Bitmap Devices and Contexts

            The BitGDI API provides extensions for bitmap devices of the abstract drawing device and context interfaces defined in the GDI API. The key interfaces defined by it, used for drawing on the screen, are in fact abstract. The Window Server provides concrete classes for on-screen drawing which derive from these interfaces. The concrete device and context classes that the API does provide are normally only used by applications to draw to in-memory bitmaps.

            Bitmap graphics context

            CBitmapContext specializes a GDI context (CGraphicsContext) for bitmap graphics. It provides extra functionality for:

            • clearing and copying rectangular areas

            • bitmap block transfer

            • setting pen color to a grey level

            • setting the shadow mode

            • resetting the GC settings to their default values

            The Window Server client-side API provides one implementation, CWindowGc, used for screen drawing. Another implementation, CFbsBitGc, is used for drawing to in-memory bitmaps.

            Bitmap graphics device

            CBitmapDevice specializes a graphics device (CGraphicsDevice) for bitmap graphics.

            The Window Server client-side API provides one implementation, CWsScreenDevice, for screen drawing. Another implementation, CFbsBitmapDevice, is used for drawing to in-memory bitmaps. A third, CFbsScreenDevice, is used (rarely) to access the screen directly, without the mediation of the window server.

            Screen driver information

            The screen width and height must be a multiple of four. In certain cases where the screen mode would result in a scanline (the scanline runs in the current horizontal direction of the screen) not being divisible by a whole word (32 bits) the screen width must also be a multiple of 16. This restriction will also apply to the height if there is a screen-size mode with a rotation of 90 or 270 (or both)

            For example, the screen mode EGray4 is 2 bits per pixel, therefore one word would be 16 pixels, so in order for the scanline to be a whole number of words the width must be a multiple of 16.

            The vertical height is unrestricted unless there is at least one screen-size mode with a rotation of 90 or 270 (or both).

            Bitmaps BitGDI Component             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5503ACC5-1C78-5EF6-AAD2-4B6FFA8890B9_d0e191959_href.png Binary file Symbian3/SDK/Source/GUID-5503ACC5-1C78-5EF6-AAD2-4B6FFA8890B9_d0e191959_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5503ACC5-1C78-5EF6-AAD2-4B6FFA8890B9_d0e196967_href.png Binary file Symbian3/SDK/Source/GUID-5503ACC5-1C78-5EF6-AAD2-4B6FFA8890B9_d0e196967_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5546C1F6-2110-5031-99BC-66E6958D513B.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-5546C1F6-2110-5031-99BC-66E6958D513B.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,24 @@ + + + + + +EchoClientEngine: +TCP/IP Echo Client Engine +
            Download

            Example download as well as source +code located at: EchoClientUI.

            +
            Description

            The TCP example is a client for the +simple Echo protocol. A server implementing this protocol, defined in RFC862, +simply listens on port 7 for incoming data, and returns it to the client. +EchoClientEngine is a DLL that implements the engine component of the client. +It contains active object classes that encapsulate reading, writing and connect +operations. The related example project EchoClientUI provides +a GUI interface to drive the engine.

            +
            Class summary

            RSocketServ RHostResolver TNameEntry TNameRecord CTimer

            +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-55754EF4-EC25-5CE3-9B38-79F278BCF19F_d0e336970_href.png Binary file Symbian3/SDK/Source/GUID-55754EF4-EC25-5CE3-9B38-79F278BCF19F_d0e336970_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-55754EF4-EC25-5CE3-9B38-79F278BCF19F_d0e343167_href.png Binary file Symbian3/SDK/Source/GUID-55754EF4-EC25-5CE3-9B38-79F278BCF19F_d0e343167_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5598B53F-2A6D-5813-913C-94B2AB36134E_d0e75879_href.png Binary file Symbian3/SDK/Source/GUID-5598B53F-2A6D-5813-913C-94B2AB36134E_d0e75879_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5598B53F-2A6D-5813-913C-94B2AB36134E_d0e82591_href.png Binary file Symbian3/SDK/Source/GUID-5598B53F-2A6D-5813-913C-94B2AB36134E_d0e82591_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-55A1A47A-A7DD-5B1A-88E1-4818CB65B782.dita --- a/Symbian3/SDK/Source/GUID-55A1A47A-A7DD-5B1A-88E1-4818CB65B782.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-55A1A47A-A7DD-5B1A-88E1-4818CB65B782.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,12 +1,22 @@ - - - - - -Tutorials \ No newline at end of file + + + + + +TutorialsThe tutorials in this section show you how to use the Camera API. +

            The Camera API allows your application to use the device camera to capture +still images and video clips, and store them in the internal memory or on +removable media. You can implement applications that make use of the camera +to capture images, record videos, or use the display as a viewfinder. To capture +images or to record videos, you need a combination of Symbian APIs and classes, +and device-specific components.

            +

            Note: The functionality that can be obtained through +the Camera API is hardware dependent. The API includes functions you can call +to check if functionality is available before using it.

            +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-55BF8452-F9FF-5CF3-9D74-3BC7F5447551-GENID-1-8-1-18-1-1-4-1-5-1.dita --- a/Symbian3/SDK/Source/GUID-55BF8452-F9FF-5CF3-9D74-3BC7F5447551-GENID-1-8-1-18-1-1-4-1-5-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,29 +0,0 @@ - - - - - -S60 -Platform: Camera Example -
            Description

            This -Symbian C++ code example demonstrates how to easily use the onboard camera -with zoom and autofocus, utilising an accompanying CameraWrapper made by Forum -Nokia. The Camera Wrapper supports all Nokia's S60 devices based on S60 3rd -Edition and newer, providing a unified interface for various Symbian and S60 -camera APIs some of which have previously been Feature Pack specific or only -available via an SDK plug-in. The example application supports the use of -both the keypad and touch UI. The application can be self-signed, but it also -provides an option to use the dedicated camera key (Symbian signing required). -The example application replaces the separate examples published for S60 3rd -Edition, FP1 (S60 Platform: Camera Example with AutoFocus Support v2.2) and -FP2 (S60 Camera Example AutoFocus 3rd Ed FP2). For more detils, click this -link :CameraExample.zip file

            -
            Download

            Click -on the following link to download the example: CameraExample.zip file

            Click: browse to view the example code.

            -             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-55BF8452-F9FF-5CF3-9D74-3BC7F5447551-GENID-1-8-1-18-1-1-5-1-5-1-4-1-3-1.dita --- a/Symbian3/SDK/Source/GUID-55BF8452-F9FF-5CF3-9D74-3BC7F5447551-GENID-1-8-1-18-1-1-5-1-5-1-4-1-3-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,29 +0,0 @@ - - - - - -S60 -Platform: Camera Example -
            Description

            This -Symbian C++ code example demonstrates how to easily use the onboard camera -with zoom and autofocus, utilising an accompanying CameraWrapper made by Forum -Nokia. The Camera Wrapper supports all Nokia's S60 devices based on S60 3rd -Edition and newer, providing a unified interface for various Symbian and S60 -camera APIs some of which have previously been Feature Pack specific or only -available via an SDK plug-in. The example application supports the use of -both the keypad and touch UI. The application can be self-signed, but it also -provides an option to use the dedicated camera key (Symbian signing required). -The example application replaces the separate examples published for S60 3rd -Edition, FP1 (S60 Platform: Camera Example with AutoFocus Support v2.2) and -FP2 (S60 Camera Example AutoFocus 3rd Ed FP2). For more detils, click this -link :CameraExample.zip file

            -
            Download

            Click -on the following link to download the example: CameraExample.zip file

            Click: browse to view the example code.

            -             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-55BF8452-F9FF-5CF3-9D74-3BC7F5447551.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-55BF8452-F9FF-5CF3-9D74-3BC7F5447551.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,22 @@ + + + + + +Camera +Example +
            Description

            This +Symbian C++ code example demonstrates how to easily use the onboard camera +with zoom and autofocus, utilising an accompanying CameraWrapper made by the +example. The example application supports the use of both the +keypad and touch UI. The application can be self-signed, but it also provides +an option to use the dedicated camera key (Symbian signing required).

            +
            Download

            Click +on the following link to download the example: CameraExample.zip file

            Click: browse to view the example code.

            +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-55E4D84B-1B90-5BA4-9CE0-6D26EA208F13.dita --- a/Symbian3/SDK/Source/GUID-55E4D84B-1B90-5BA4-9CE0-6D26EA208F13.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-55E4D84B-1B90-5BA4-9CE0-6D26EA208F13.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,18 +1,18 @@ - - - - - -OverviewThis topic describes memory management in the Communications Framework.
            Introduction

            The Communications Framework preallocates memory area buffers to increase the performance of its Data Plane. When a Comms Data Plane component needs a buffer, it asks for one from its pond. The pond contains pools of buffers : each pool contains buffers of a different size, and all the buffers in a pool have the same size. If the pond doesn't have a big enough buffer, it will string together a chain of smaller buffers to meet the request.

            The Communications Framework uses shared buffers. The Data Plane has strong performance requirements, and using shared buffers helps to avoid the memory copy that occurs between the kernel memory context and the Communications stack.

            Definitions
            Comms buffer (MBuf)

            A Comms buffer, or MBuf, is a contiguous memory area used to store data on the Data Plane. It is represented by an RMBuf object, which combines a shared buffer with metadata. See Shared buffers and Comms Buffers (MBuf) and Comms Chains.

            - Comms buffer -
            Comms buffer chain

            A Comms buffer chain links together one or more Comms buffers. This decreases memory consumption because there is no need to reserve space for temporary large buffers, which can be created from a chain of smaller buffers. The chain is represented by a RMBufChain object. For more information, see Comms Buffers (MBuf) and Comms Chains.

            Pool

            Pre-allocated collection of shared buffers. See Shared buffers.

            The buffers of a pool all have the same size. Depending on the amount of used buffers, the pool dynamically grows and shrinks by a set number of buffers, which reduces the frequency of expensive memory allocation and reduces memory usage when possible.

            Pond

            The pond is a collection of pools. It is an RCommsBufPond object which keeps track of the memory available in the pools and allocates all the Comms buffer chains by taking buffers from the appropriate pools.

            The memory provided by the pond is available to all the layers of the Comms Framework as well as to the drivers underneath the lower layer. Therefore, the Comms Framework components and the drivers can exchange data without additional memory copies.

            At the moment, there is only one pond in the Comms Framework.

            For more information, see Advanced Pond Guide.

            - Pond contents -
            Typical usage

            Depending on where your component is in the Data Plane, you handle Comms buffers in a different way:

            • Protocol plugins manipulate the data plane flow represented by buffer chains. They obtain a buffer chain from another layer (up or down), process the chain, and send the chain to the next layer in the stack. Link layer components belong to that category.

              See Data Access Example.

            • Data source components, either at the top or at the bottom of the Comms Framework, create buffer chains and send them through the Data Plane. Device drivers belong to that category.

              See Allocation Tutorial and TLS Look-up Reduction Tutorial.

            In order to increase performance and decrease memory consumption with Comms buffers, you need to configure the pond according to your memory usage. For more information, see Advanced Pond Guide and Pond Configuration Reference.

            To monitor the pond and its available memory, see Memory Metrics.

            Shared Buffers Comms Buffers (MBuf) - and Comms Chains Advanced Pond + + + + + +OverviewThis topic describes memory management in the Communications Framework.
            Introduction

            The Communications Framework preallocates memory area buffers to increase the performance of its Data Plane. When a Comms Data Plane component needs a buffer, it asks for one from its pond. The pond contains pools of buffers : each pool contains buffers of a different size, and all the buffers in a pool have the same size. If the pond doesn't have a big enough buffer, it will string together a chain of smaller buffers to meet the request.

            The Communications Framework uses shared buffers. The Data Plane has strong performance requirements, and using shared buffers helps to avoid the memory copy that occurs between the kernel memory context and the Communications stack.

            Definitions
            Comms buffer (MBuf)

            A Comms buffer, or MBuf, is a contiguous memory area used to store data on the Data Plane. It is represented by an RMBuf object, which combines a shared buffer with metadata. See Shared buffers and Comms Buffers (MBuf) and Comms Chains.

            + Comms buffer +
            Comms buffer chain

            A Comms buffer chain links together one or more Comms buffers. This decreases memory consumption because there is no need to reserve space for temporary large buffers, which can be created from a chain of smaller buffers. The chain is represented by a RMBufChain object. For more information, see Comms Buffers (MBuf) and Comms Chains.

            Pool

            Pre-allocated collection of shared buffers. See Shared buffers.

            The buffers of a pool all have the same size. Depending on the amount of used buffers, the pool dynamically grows and shrinks by a set number of buffers, which reduces the frequency of expensive memory allocation and reduces memory usage when possible.

            Pond

            The pond is a collection of pools. It is an RCommsBufPond object which keeps track of the memory available in the pools and allocates all the Comms buffer chains by taking buffers from the appropriate pools.

            The memory provided by the pond is available to all the layers of the Comms Framework as well as to the drivers underneath the lower layer. Therefore, the Comms Framework components and the drivers can exchange data without additional memory copies.

            At the moment, there is only one pond in the Comms Framework.

            For more information, see Advanced Pond Guide.

            + Pond contents +
            Typical usage

            Depending on where your component is in the Data Plane, you handle Comms buffers in a different way:

            • Protocol plugins manipulate the data plane flow represented by buffer chains. They obtain a buffer chain from another layer (up or down), process the chain, and send the chain to the next layer in the stack. Link layer components belong to that category.

              See Data Access Example.

            • Data source components, either at the top or at the bottom of the Comms Framework, create buffer chains and send them through the Data Plane. Device drivers belong to that category.

              See Allocation Tutorial and TLS Look-up Reduction Tutorial.

            In order to increase performance and decrease memory consumption with Comms buffers, you need to configure the pond according to your memory usage. For more information, see Advanced Pond Guide and Pond Configuration Reference.

            To monitor the pond and its available memory, see Memory Metrics.

            Shared Buffers Comms Buffers (MBuf) + and Comms Chains Advanced Pond Guide             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5673347B-DA7B-563A-AB2B-615BF7C19F92_d0e324956_href.png Binary file Symbian3/SDK/Source/GUID-5673347B-DA7B-563A-AB2B-615BF7C19F92_d0e324956_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5673347B-DA7B-563A-AB2B-615BF7C19F92_d0e331113_href.png Binary file Symbian3/SDK/Source/GUID-5673347B-DA7B-563A-AB2B-615BF7C19F92_d0e331113_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-567718E7-0267-4641-A9E3-538D893362D2.dita --- a/Symbian3/SDK/Source/GUID-567718E7-0267-4641-A9E3-538D893362D2.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-567718E7-0267-4641-A9E3-538D893362D2.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,86 +1,88 @@ - - - - - -Item-specific -options menu -

            Item-specific options are placed in the stylus pop-up menu that is activated -with touch down and hold on an item. Menu can be attached to almost all the -items. Opening of the pop-up is indicated to the user via animation during -the touch down and hold. If the finger is released before the touch down and -hold time-out (0.5 seconds) is full, item’s touch down and release activity -is initiated. If the stylus pop-up menu is launched from an item that can -hold focus (for example, list item), the focus is displayed on the item while -the stylus pop-up menu is open.

            - -An example of Item-specific options menu within stylus pop-up menu. - - -Default touch -events for Item-specific options menu. - - - - - - -

            User action

             -

            State change

             -

            Feedback

             -             - - - -

            Touch down

             -

            No effect

             -

            Highlight is shown.

            Tactile: Basic list effect and audio -feedback are provided with touch down event.

             -             - -

            Touch release

             -

            The item is activated.

             -

            Highlight disappears and stylus pop-up is closed.

            Tactile: -Basic list effect is provided with touch release event.

             -             - -

            Touch down and hold

             -

            Inactive

             -

            Tactile: No effect

             -             - -

            Touch down and move inside the stylus pop-up

             -

            Refer to Dragging -and flicking events.

             -

            Tactile: Refer to Dragging -and flicking events.

             -             - -

            Touch down and move out of the stylus pop-up menu

             -

            Refer to Dragging -and flicking events.

             -

            Tactile: Refer to Dragging -and flicking events.

             -             - -

            Touch down and release outside menu area

             -

            Stylus pop-up menu disappears. No selection is made.

             -

            Tactile: Opens via long touch. Provides only the increasing long -touch effect during the touch down and hold event and no additional pop-up -effect when the menu opens.

             -             - -

            Touch down and move horizontally

             -

            Inactive

             -

            Highlight stays on the item that was touched down before moving -horizontally.

            Tactile: No effect

             -             - - + + + + + +Item-specific +options menu +

            Item-specific options are placed in the stylus pop-up menu that is activated +with touch down and hold on an item. Menu can be attached to almost all the +items. Opening of the pop-up is indicated to the user via animation during +the touch down and hold. If the finger is released before the touch down and +hold time-out (0.5 seconds) is full, item’s touch down and release activity +is initiated. If the stylus pop-up menu is launched from an item that can +hold focus (for example, list item), the focus is displayed on the item while +the stylus pop-up menu is open.

            + The application only needs to tag items to be item-specific. The application +framework will handle the remaining tasks. + +An example of Item-specific options menu within stylus pop-up menu. + + +
            Default touch +events for Item-specific options menu. + + + + + + +

            User action

             +

            State change

             +

            Feedback

             +             + + + +

            Touch down

             +

            No effect

             +

            Highlight is shown.

            Tactile: Basic list effect and audio +feedback are provided with touch down event.

             +             + +

            Touch release

             +

            The item is activated.

             +

            Highlight disappears and stylus pop-up is closed.

            Tactile: +Basic list effect is provided with touch release event.

             +             + +

            Touch down and hold

             +

            Inactive

             +

            Tactile: No effect

             +             + +

            Touch down and move inside the stylus pop-up

             +

            Refer to Dragging +and flicking events.

             +

            Tactile: Refer to Dragging +and flicking events.

             +             + +

            Touch down and move out of the stylus pop-up menu

             +

            Refer to Dragging +and flicking events.

             +

            Tactile: Refer to Dragging +and flicking events.

             +             + +

            Touch down and release outside menu area

             +

            Stylus pop-up menu disappears. No selection is made.

             +

            Tactile: Opens via long touch. Provides only the increasing long +touch effect during the touch down and hold event and no additional pop-up +effect when the menu opens.

             +             + +

            Touch down and move horizontally

             +

            Inactive

             +

            Highlight stays on the item that was touched down before moving +horizontally.

            Tactile: No effect

             +             + +
             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5696BEC1-51F5-5062-A4E6-C6CF48C7C95A_d0e132911_href.png Binary file Symbian3/SDK/Source/GUID-5696BEC1-51F5-5062-A4E6-C6CF48C7C95A_d0e132911_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5696BEC1-51F5-5062-A4E6-C6CF48C7C95A_d0e139445_href.png Binary file Symbian3/SDK/Source/GUID-5696BEC1-51F5-5062-A4E6-C6CF48C7C95A_d0e139445_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-56DF9711-1EFA-5A07-A92B-3F3D6FBD17A8.dita --- a/Symbian3/SDK/Source/GUID-56DF9711-1EFA-5A07-A92B-3F3D6FBD17A8.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-56DF9711-1EFA-5A07-A92B-3F3D6FBD17A8.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,18 +1,18 @@ - - - - - -Sockets Server Client API

            This topic introduces the Sockets Server API and discusses the main classes.

            The Sockets Server Client interfaces make asynchronous calls to the Sockets Server. The Server co-ordinates client access to socket services, and manages communications with the protocol plug-ins that provide support for the particular networking protocols.

            Each protocol plug-in may contain a number of protocols. The term ‘protocol’ may also be used to describe a suite of protocols. For example, the TCP/IP protocol plug-in contains UDP, TCP, ICMP, IP, and DNS. Sockets can access UDP and TCP to transfer data over IP. Another example of a protocol plug-in is the IrDA plug-in. the IrDA plug-in is used for communicating over infrared.

            The Sockets Server loads protocols plug-ins at runtime either explicitly or on demand. When the server starts, the server scans \private\101f7989\esock for .esk files to see which protocols and services are defined, and which protocols to load.

            The Sockets Server Client API implements the idea of transport independence: different protocols are accessed through the same API. However, individual protocols exhibit different properties and semantics regarding socket behaviour. The semantics implemented by any given protocol can be found by interrogating the system using RSocketServ::GetProtocolInfo(), which describes the protocol semantics encapsulated in a TProtocolDesc.

            APIs

            Five main classes provide the Sockets Server Client API functionality:

            • RSocketServ

            • RSocket

            • RHostResolver

            • RConnection

            • RSubConnection

            The RSocketServ class establishes and reserves resources for the base communication session to the Sockets Server. The RSocketServ hosts other Sockets Server Client APIs as subsessions inside the RSocketServ session. The Sockets Server Client APIs which are hosted as subsessions inside RSocketServ are RSocket, RHostResolver, RConnection and RSubConnection. The RSocketServ class provides functions to load and query protocols.

            - Figure 1 - Class diagram of RSocketServ inheritance - - Figure 2 - Class diagram of classes which make up the subsession APIs - to RSocketServ -

            The RSocket class provides a client endpoint to a protocol. It provides the following services:

            • socket creation

            • reading from and writing to a protocol

            • binding to addresses

            • active connecting

            • passive connection through the listen/accept model

            The RConnection class provides access to the Connection Management functionality of a socket. See Connection Management.

            The RSubConnection API provides functions to specify Quality of Service parameters for a channel. See SubConnection Client API.

            ESK Files Reading from a Socket: + + + + + +Sockets Server Client API

            This topic introduces the Sockets Server API and discusses the main classes.

            The Sockets Server Client interfaces make asynchronous calls to the Sockets Server. The Server co-ordinates client access to socket services, and manages communications with the protocol plug-ins that provide support for the particular networking protocols.

            Each protocol plug-in may contain a number of protocols. The term ‘protocol’ may also be used to describe a suite of protocols. For example, the TCP/IP protocol plug-in contains UDP, TCP, ICMP, IP, and DNS. Sockets can access UDP and TCP to transfer data over IP. Another example of a protocol plug-in is the IrDA plug-in. the IrDA plug-in is used for communicating over infrared.

            The Sockets Server loads protocols plug-ins at runtime either explicitly or on demand. When the server starts, the server scans \private\101f7989\esock for .esk files to see which protocols and services are defined, and which protocols to load.

            The Sockets Server Client API implements the idea of transport independence: different protocols are accessed through the same API. However, individual protocols exhibit different properties and semantics regarding socket behaviour. The semantics implemented by any given protocol can be found by interrogating the system using RSocketServ::GetProtocolInfo(), which describes the protocol semantics encapsulated in a TProtocolDesc.

            APIs

            Five main classes provide the Sockets Server Client API functionality:

            • RSocketServ

            • RSocket

            • RHostResolver

            • RConnection

            • RSubConnection

            The RSocketServ class establishes and reserves resources for the base communication session to the Sockets Server. The RSocketServ hosts other Sockets Server Client APIs as subsessions inside the RSocketServ session. The Sockets Server Client APIs which are hosted as subsessions inside RSocketServ are RSocket, RHostResolver, RConnection and RSubConnection. The RSocketServ class provides functions to load and query protocols.

            + Figure 1 - Class diagram of RSocketServ inheritance + + Figure 2 - Class diagram of classes which make up the subsession APIs + to RSocketServ +

            The RSocket class provides a client endpoint to a protocol. It provides the following services:

            • socket creation

            • reading from and writing to a protocol

            • binding to addresses

            • active connecting

            • passive connection through the listen/accept model

            The RConnection class provides access to the Connection Management functionality of a socket. See Connection Management.

            The RSubConnection API provides functions to specify Quality of Service parameters for a channel. See SubConnection Client API.

            ESK Files Reading from a Socket: Tutorial             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-56E67157-08EE-414A-9EC5-ADAF27E0D36A-master.png Binary file Symbian3/SDK/Source/GUID-56E67157-08EE-414A-9EC5-ADAF27E0D36A-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-56E67157-08EE-414A-9EC5-ADAF27E0D36A_d0e63781_href.png Binary file Symbian3/SDK/Source/GUID-56E67157-08EE-414A-9EC5-ADAF27E0D36A_d0e63781_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-56E67157-08EE-414A-9EC5-ADAF27E0D36A_d0e69003_href.png Binary file Symbian3/SDK/Source/GUID-56E67157-08EE-414A-9EC5-ADAF27E0D36A_d0e69003_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5746BC4A-E8D2-51DE-B101-4BA68F0E1769_d0e148577_href.png Binary file Symbian3/SDK/Source/GUID-5746BC4A-E8D2-51DE-B101-4BA68F0E1769_d0e148577_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5746BC4A-E8D2-51DE-B101-4BA68F0E1769_d0e155098_href.png Binary file Symbian3/SDK/Source/GUID-5746BC4A-E8D2-51DE-B101-4BA68F0E1769_d0e155098_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-575CDD9C-ED6E-510E-AE11-46CA7EB7B74C_d0e132621_href.png Binary file Symbian3/SDK/Source/GUID-575CDD9C-ED6E-510E-AE11-46CA7EB7B74C_d0e132621_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-575CDD9C-ED6E-510E-AE11-46CA7EB7B74C_d0e139155_href.png Binary file Symbian3/SDK/Source/GUID-575CDD9C-ED6E-510E-AE11-46CA7EB7B74C_d0e139155_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-57B7DA8C-A62F-4C65-B754-47D9F5E76416.dita --- a/Symbian3/SDK/Source/GUID-57B7DA8C-A62F-4C65-B754-47D9F5E76416.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-57B7DA8C-A62F-4C65-B754-47D9F5E76416.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,56 +1,56 @@ - - - - - -Text -input -

            There are several finger-optimized text input methods available for touch-enabled -devices. The available methods depend on the orientation of the device. The -following methods are available in the portrait orientation:

            -
              -

            • Virtual ITU-T keyboard with text prediction

              • -

            • Handwriting recognition (HWR) for some language variants. Not available -for Latin languages.

              • -
            -

            The following methods are available in the landscape orientation:

            -
              -

            • Virtual QWERTY opened in full screen with input preview

              • -

            • Handwriting recognition

              • -
            -

            The input methods that are available to mobile device users depend on the -product. Users can select the suitable input method for each situation from -the input methods that are included in the product. The device recalls the -last used method and offers it the next time when the user wants to input -something.

            - -Virtual ITU-T keypad - - - -Virtual QWERTY keyboard - - -

            The virtual QWERTY keyboard displays a keyboard that has a collection of -basic keyboard functions (Shift, Caps lock, punctuation marks, and so on) -and a text field where the user can see the given input without having to -follow it from the editor field. The handwriting recognition allows user to -write characters on the screen with a finger.

            -

            If touch input has been launched from an editor, pressing any hardware -character key closes the touch input. This also applies to hybrid devices -having both a hardware and virtual keyboard. Activating the hardware keyboard -character key closes the virtual keyboard. Touch input never starts up automatically -(that is, a change of view does not launch it), but the user has to launch -it by tapping the editing field. Moving the focus onto an editing field with -the hardware keys does not launch touch input.

            -
            Using -touch-based text input in C++ applications

            AVKON editor components -support touch-based text input.

            The API to use for providing touch-based -text input is the Editors API. For implementation information, see Using the Editors API.

            + + + + + +Text +input +

            There are several finger-optimized text input methods available for touch-enabled +devices. The available methods depend on the orientation of the device. The +following methods are available in the portrait orientation:

            +
              +

            • Virtual ITU-T keyboard with text prediction

              • +

            • Handwriting recognition (HWR) for some language variants. Not available +for Latin languages.

              • +
            +

            The following methods are available in the landscape orientation:

            +
              +

            • Virtual QWERTY opened in full screen with input preview

              • +

            • Handwriting recognition

              • +
            +

            The input methods that are available to mobile device users depend on the +product. Users can select the suitable input method for each situation from +the input methods that are included in the product. The device recalls the +last used method and offers it the next time when the user wants to input +something.

            + +Virtual ITU-T keypad + + + +Virtual QWERTY keyboard + + +

            The virtual QWERTY keyboard displays a keyboard that has a collection of +basic keyboard functions (Shift, Caps lock, punctuation marks, and so on) +and a text field where the user can see the given input without having to +follow it from the editor field. The handwriting recognition allows user to +write characters on the screen with a finger.

            +

            If touch input has been launched from an editor, pressing any hardware +character key closes the touch input. This also applies to hybrid devices +having both a hardware and virtual keyboard. Activating the hardware keyboard +character key closes the virtual keyboard. Touch input never starts up automatically +(that is, a change of view does not launch it), but the user has to launch +it by tapping the editing field. Moving the focus onto an editing field with +the hardware keys does not launch touch input.

            +
            Using +touch-based text input in applications

            AVKON editor +components support touch-based text input.

            The API to use for providing +touch-based text input is the Editors API. For implementation information, see Using the Editors API.

             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-57C10E91-F0CD-494E-96CE-92FB1E06CB53_d0e292667_href.png Binary file Symbian3/SDK/Source/GUID-57C10E91-F0CD-494E-96CE-92FB1E06CB53_d0e292667_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-57C10E91-F0CD-494E-96CE-92FB1E06CB53_d0e293517_href.png Binary file Symbian3/SDK/Source/GUID-57C10E91-F0CD-494E-96CE-92FB1E06CB53_d0e293517_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-57CC6419-2800-4E54-8DF6-36EC2617D2FD_d0e3231_href.png Binary file Symbian3/SDK/Source/GUID-57CC6419-2800-4E54-8DF6-36EC2617D2FD_d0e3231_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-57CC6419-2800-4E54-8DF6-36EC2617D2FD_d0e4506_href.png Binary file Symbian3/SDK/Source/GUID-57CC6419-2800-4E54-8DF6-36EC2617D2FD_d0e4506_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-57F38146-1DA3-5657-ADF4-76DF740363C5.dita --- a/Symbian3/SDK/Source/GUID-57F38146-1DA3-5657-ADF4-76DF740363C5.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-57F38146-1DA3-5657-ADF4-76DF740363C5.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,12 +1,12 @@ - - - - - -Static Startup Configuration

            The System Starter is invoked by the Base Starter as part of the boot process once the file system has been mounted. It works by processing a list of instructions in sequence. The list is referred to as a Static Startup Configuration, or SSC. In practical terms the SSC is defined in a resource file and is built into the ROM.

            A fundamental feature of the SSC is that it allows the start up procedure to be optimised. Though the commands are processed in sequence their effect is to perform tasks not only in sequence (wait for the application or process to initialise before continuing) but also in parallel (do not wait for initialisation) and at the optimum time (wait until conditions are right).

            In the diagram above each vertical bar represents a process or application started during the startup procedure. The list on the left shows the SSC command for each process. An application may ‘rendezvous’ with the starter when its initialisation (shown in dark blue) is complete and it is ready to be used by dependent applications. A rendezvous is simply a signal from the appliation to the starter that it has reached a designated point.

            \ No newline at end of file + + + + + +Static Startup Configuration

            The System Starter is invoked by the Base Starter as part of the boot process once the file system has been mounted. It works by processing a list of instructions in sequence. The list is referred to as a Static Startup Configuration, or SSC. In practical terms the SSC is defined in a resource file and is built into the ROM.

            A fundamental feature of the SSC is that it allows the start up procedure to be optimised. Though the commands are processed in sequence their effect is to perform tasks not only in sequence (wait for the application or process to initialise before continuing) but also in parallel (do not wait for initialisation) and at the optimum time (wait until conditions are right).

            In the diagram above each vertical bar represents a process or application started during the startup procedure. The list on the left shows the SSC command for each process. An application may ‘rendezvous’ with the starter when its initialisation (shown in dark blue) is complete and it is ready to be used by dependent applications. A rendezvous is simply a signal from the appliation to the starter that it has reached a designated point.

            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-581A8E4B-12BE-41C0-A20E-3087A80FEECF.dita --- a/Symbian3/SDK/Source/GUID-581A8E4B-12BE-41C0-A20E-3087A80FEECF.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-581A8E4B-12BE-41C0-A20E-3087A80FEECF.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,298 +1,253 @@ - - - - - -Tactile -feedback -

            There are two methods where vibration or audio of the device is used as -an output method (when mobile device users interact with the device touch -screen):

            -
              -

            • As a tacticon to inform users through physical feedback, that -an important event is occurring in the device. For example, when a new message -arrives or a warning note is displayed.

              • -

            • As tactile feedback to indicate to the user that an interaction -event has been successful. For example, users receive tactile feedback when -they press a button on the touch screen.

              • -
            -

            As with sounds, tactile feedback must be used carefully so as not to desensitize -the user to the vibration; the attention grabbing quality remains and functions -so long as the feedback is not too frequent.

            -

            Tactile feedback is enabled for all the Symbian platform UI components. -Tactile feedback can be disabled for the common UI components in an application. -However, this is acceptable only if tactile feedback causes interference with -other device functions.

            -

            The user can choose the level of tactile feedback and turn tacticons ON -and OFF.

            -

            The following table lists the tactile feedback effects:

            -

            Tactile feedback -effects - - - -

            Effects

             -

            Description

             -             - - - -

            Sensitive button

             -

            It provides single pulse effect on repeated key presses with buttons. -It is also possible with other similar components.

             -             - -

            Basic button

             -

            It provides stronger single pulse effect to buttons. It is also -possible with other similar components.

             -             - -

            Sensitive list

             -

            It provides single pulse effect to lists and grids. Effect is used -with move (drag and flick) when new item appears on the screen.

             -             - -

            Basic list

             -

            It provides stronger single pulse effect to lists and grids. Effect -is used with touch down and release when tap makes an action.

            In hierarchical -list, collapsing/expanding item provides basic list effect with touch down -and release.

             -             - -

            Bounce effect

             -

            It provides pulse effect when list returns to its normal state after -boundary effect.

             -             - -

            Sensitive slider

             -

            It provides pulse effect with scrollbar and slider thumbs. Effect -is provided with touch down and release in thumb area.

             -             - -

            Smooth slider

             -

            It provides continuous smooth feedback when dragging scrollbar or -slider thumb. This can also be increasing or decreasing depending of the slider -type.

             -             - -

            Hold slider

             -

            It provides sensitive pulse effect when touch down and hold on the -slider or scrollbar area. Slider thumb starts moving step by step towards -the touch point. Every step gives one sensitive pulse. If slider thumb moves -directly to the touch point, then basic slider effect is provided.

             -             - -

            Pop-up

             -

            It provides sensitive pulse effect when pop-up is opened or closed. -If the theme animations are ON, then pop-up effect is used with opening event -after increasing long touch effect. In this scenario, there is no pop-up effect -while closing. All pop-ups does not have theme animation.

             -             - -

            Pop-up close

             -

            It provides decreasing smooth feedback while closing pop-up and -when theme animations are ON.

             -             - -

            Increasing long touch

             -

            It provides increasing smooth feedback. This can be used with either -long tap animation or pop-up opening theme effects. If the theme effects are -ON and long tap opens a pop-up, then feedback is provided only with long tap. -This is followed by pop-up.

             -             - -

            Basic tab

             -

            It provides strong pulse effect with touch down event in tab area.

             -             - -

            Smooth flick

             -

            It provides smooth feedback with drag when horizontal movement is -possible.

             -             - -

            Sensitive flick

             -

            It provides sensitive pulse effect with touch release when horizontal -movement is possible.

             -             - -

            Sensitive edit

             -

            It provides sensitive pulse effect in editors with touch down and -release.

             -             - -

            Text edit

             -

            It provides pulse effect when painting the text. Effect is provided -with every character while painting the text.

             -             - -

            Blank edit

             -

            It provides pulse effect when painting blank character. By default, -it is none.

             -             - -

            Line edit

             -

            It provides pulse effect when painting a line.

             -             - -

            Empty line

             -

            It provides pulse effect when painting an empty line. By default, -it is none.

             -             - -

            Check box

             -

            It provides pulse effect when marking/unmarking a check box.

             -             - -

            Multi-touch recognition

             -

            It provides double pulse (sensitive + sensitive) effect when multi-touch -is recognized (generally, when second finger is touched down).

             -             - -

            Smooth pinch

             -

            It provides smooth continuous feedback while moving fingers in multi-touch -pinch situation.

             -             - -

            Smooth rotate

             -

            It provides smooth continuous feedback while moving fingers in -multi-touch rotate situation.

             -             - - -

            -
            Characteristics -of haptics related APIs

            You can use the following APIs to create -haptic effects:

              -

            • Tactile Feedback -Client API

                -

              • It is available from S60 5th Edition onwards

                • -

              • It can be used on all S60 5th Edition or later mobile devices. However, -the feedback is played only on touch enabled layouts.

                • -

              • It provides simple functions for triggering various predefined tactile -feedback (vibration or audio) effects.

                • -

              • It enables a consistent user experience in all applications of the -mobile device (an application gives a logical feedback type as an input and -the actual physical effect depends on the mobile device configuration and -end user settings).

                • -

              • When the area feedback is used, latency is low for the feedback triggering -(a tactile feedback can already be triggered at the window server level prior -to the corresponding pointer event being delivered to the visible application).

                • -

              • Direct feedback can be easily integrated into CCoeControl::HandlePointerEventL() .

                • -

              • An application can select the logical tactile feedback from certain -types. The produced effect may be different on various mobile devices.

                • -
              • -

            • Haptics -API

                -

              • It is available from S60 5.2 Edition onwards.

                • -

              • It can be used in touch and hybrid mobile devices.

                • -

              • It provides an interface for accessing Haptics player that can control -different actuator types.

                • -

              • It enables producing of complex vibrator effects, such as an explosion -or machine gun effect in a game, bass boost for a music player, advanced ringing -tone vibration, and so on.

                • -

              • It enables simultaneous playing of different kinds of basis effects -and modifying them when played.

                • -

              • It allows for designing complex effects (using a separate PC application) -that can be loaded on Haptics player for playing.

                • -

              • It may require a special license key for third-party applications -(to be set at runtime) to enable the Haptics player functionality.

                • -
              • -

            • Vibra API

                -

              • It available from S60 3.0 onwards

                • -

              • It can be used for running device vibrator with given intensity for -a given period of time

                • -

              • It can be used by a privileged client application to play pulse effects, -which have a very short duration (as the ones used for tactile feedback)

                • -
              • -
            -
            When to use -Tactile Feedback Client API, Haptics API, and Vibra API

            You must -use

              -

            • Tactile Feedback Client API for providing tactile feedback in custom -controls (grids, lists, and so on) which will comply with the style of Core -UI components to ensure a uniform user experience among applications

              • -

            • Haptics API on touch and hybrid mobile devices for producing complex -vibration feedback which cannot be achieved with Tactile Framework (games, -simulations, demos, and so on.)

              • -

            • Vibra API for producing haptic effects such as ringing tone vibration -in those mobile devices where Haptics API is not available or functional

              • -

            -
            Using -tactile feedback in C++ applications

            The API to use for tactile -feedback is the Tactile -feedback client API.

            The Symbian platform includes a tactile -feedback interface to add, modify and remove feedback areas in the registry. -There is also an option to trigger direct feedback and bypass the registry. - MTouchFeedback::Instance() is used for acquiring a pointer -to a touch feedback instance. When touch feedback is activated, the mobile -device users get a slight vibration when the control with the feedback interface -is touched.

            Tactile feedback can be set and disabled in a client -application or a mobile device in some scenarios, for example, during phone -calls.

            Client applications cannot determine the actual physical -feedback that is generated. It depends on device configuration and current -settings. In current devices, the user changeable settings include vibration -and audio feedback intensity level.

            In your application, you can use -the following feedback types, defined in TTouchLogicalFeedback:

            - - - -

            ETouchFeedbackNone

             -

            It is used for disabling feedback in some areas of the application -window while using the area registry.

             -             - -

            ETouchFeedbackBasic

             -

            It is used as a default feedback for stylus touch down events. For -example, when the mobile device user taps a button or tab.

             -             - -

            ETouchFeedbackSensitive

             -

            It provides sensitive feedback in situations when:

              -

            • the triggering action is not very important (for example, change of -focus in a list)

              • -

            • there can be a large number of feedback instances within a short time -(for example, text selection which gives feedback on every new selected character).

              • -
            It is also used for scrolling and dragging.

             -             - - -

            To use vibration or audio feedback in your application:

              -

            1. Include touchfeedback.lib in -your .mmp file.

              2. -

            2. Include touchfeedback.h.

              3. -

            3. To enable -tactile feedback for your application, add the following code.

              MTouchFeedback* feedback = MTouchFeedback::Instance(); -feedback->SetFeedbackEnabledForThisApp(ETrue); // enabling feedback is optional

              Do -not delete the pointer in the controller destructor.

              4. -

            4. To use tactile -feedback when a mobile device user points at a control, add the following -code.

              void CMyContainerControl::HandlePointerEventL(const TPointerEvent& aPointerEvent) - { - // Feedback is always played at pointer down event - if(aPointerEvent.iType == TPointerEvent::EButton1Down) - { - MTouchFeedback* feedback = MTouchFeedback::Instance(); - if (feedback) - { - feedback->InstantFeedback(ETouchFeedbackBasic); - } - } - - // Your other pointer event handling code here -
              5. -

            5. To enable -automatic feedback triggering in a specific area of a UI component, add

              feedback->SetFeedbackArea( this, - 1, // area Id - TRect( 0,0,20,20 ), - ETouchFeedbackBasic, - ETouchEventStylusDown ); -
              6. -

            To use tactile feedback in an application, additional platform -security capabilities are not required.

            + + + + + +Tactile +feedback +

            There are two cases where vibration or audio of the device is used as an +output method:

            +
              +

            • As a tacticon to inform users through physical feedback, that +an important event is occurring in the device. For example, when a new message +arrives or a warning note is displayed.

              • +

            • As tactile feedback to indicate to the user that an interaction +event has been made. For example, users receive tactile feedback when they +press a button on the touch screen.

              • +
            +

            As with sounds, tactile feedback must be used carefully so as not to desensitize +the user to the vibration; the attention grabbing quality remains and functions +so long as the feedback is not too frequent.

            +

            Tactile feedback is enabled for all the Symbian platform UI components. +Tactile feedback can be disabled for the common UI components in an application. +However, this is acceptable only if tactile feedback causes interference with +other device functions.

            +

            The user can choose the level of tactile feedback and turn tacticons ON +and OFF.

            +

            The following table lists the tactile feedback effects:

            +

            Tactile feedback +effects + + + +

            Effects

             +

            Description

             +             + + + +

            Sensitive button

             +

            Provides single pulse effect on repeated key presses with buttons. +It is also possible with other similar components.

             +             + +

            Basic button

             +

            Provides stronger single pulse effect to buttons. It is also possible +with other similar components.

             +             + +

            Sensitive list

             +

            Provides single pulse effect to lists and grids. Effect is used +with move (drag and flick) when new item appears on the screen.

             +             + +

            Basic list

             +

            Provides stronger single pulse effect to lists and grids. Effect +is used with touch down and release when tap makes an action.

            In hierarchical +list, collapsing/expanding item provides basic list effect with touch down +and release.

             +             + +

            Bounce effect

             +

            Provides pulse effect when list returns to its normal state after +boundary effect.

             +             + +

            Sensitive slider

             +

            Provides pulse effect with scrollbar and slider thumbs. Effect is +provided with touch down and release in thumb area.

             +             + +

            Smooth slider

             +

            Provides continuous smooth feedback when dragging scrollbar or slider +thumb. This can also be increasing or decreasing depending of the slider type.

             +             + +

            Hold slider

             +

            Provides sensitive pulse effect when touch down and hold on the +slider or scrollbar area. Slider thumb starts moving step by step towards +the touch point. Every step gives one sensitive pulse. If slider thumb moves +directly to the touch point, then basic slider effect is provided.

             +             + +

            Pop-up

             +

            Provides sensitive pulse effect when pop-up is opened or closed. +If the theme animations are ON, then pop-up effect is used with opening event +after increasing long touch effect. In this scenario, there is no pop-up effect +. All pop-ups do not have theme animation.

             +             + +

            Pop-up close

             +

            Provides decreasing smooth feedback a pop-up and when theme animations +are ON.

             +             + +

            Increasing long touch

             +

            Provides increasing smooth feedback. This can be used with either +long tap animation or pop-up opening theme effects. If the theme effects are +ON and long tap opens a pop-up, then feedback is provided only with long tap. +This is followed by pop-up.

             +             + +

            Basic tab

             +

            Provides strong pulse effect with touch down event in tab area.

             +             + +

            Smooth flick

             +

            Provides smooth feedback with drag when horizontal movement is possible.

             +             + +

            Sensitive flick

             +

            Provides sensitive pulse effect with touch release when horizontal +movement is possible.

             +             + +

            Sensitive edit

             +

            Provides sensitive pulse effect in editors with touch down and release.

             +             + +

            Text edit

             +

            Provides pulse effect when painting the text. Effect is provided +with every character while painting the text.

             +             + +

            Blank edit

             +

            Provides pulse effect when painting blank character. By default, +it is none.

             +             + +

            Line edit

             +

            Provides pulse effect when painting a line.

             +             + +

            Empty line

             +

            Provides pulse effect when painting an empty line. By default, it +is none.

             +             + +

            Check box

             +

            Provides pulse effect when marking/unmarking a check box.

             +             + +

            Multi-touch recognition

             +

            Provides double pulse (sensitive + sensitive) effect when multi-touch +is recognized (generally, when second finger is touched down).

             +             + +

            Smooth pinch

             +

            Provides smooth continuous feedback while moving fingers in multi-touch +pinch situation.

             +             + +

            Smooth rotate

             +

            Provides smooth continuous feedback while moving fingers in multi-touch +rotate situation.

             +             + + +

            +
            Haptics concept

            The different senses associated +to the skin are called cutaneous senses. These senses are temperature, pressure +(touch itself), pain, tickle, itch and vibration senses. We can characterize +touch as passive or active. Passive touch means the sense of touch itself, +whereas active touch means the touch action.

            To communicate through +the sense of touch, we have to stimulate some of the cutaneous senses or the +movement sense. The stimulation of the cutaneous senses or one of them by +a product is called tactile stimulation. Respectively, the stimulation of +the movement sense by a product is called haptic stimulation or just haptics. +Haptics is also used as general term for all issues related to sense of touch, +both human and machine.

            Haptic feedback, often referred to as "Haptics", +is the use of the sense of touch in a user interface design to provide information +to an end user. In mobile phones, this generally means the use of vibrations +from the device's vibration alarm to denote that a touch screen button has +been pressed. In this particular example, the phone would vibrate slightly +in response to the user's activation of an on-screen control, making up for +the lack of a normal tactile response that the user would experience when +pressing a physical button.

            +
            Characteristics +of haptics related APIs

            You can use the following APIs to create +haptic effects:

              +

            • Tactile Feedback +Client API

                +

              • Available from S60 5th Edition onwards.

                • +

              • It can be used on all S60 5th Edition or later mobile devices. However, +the feedback is played only on touch enabled layouts.

                • +

              • Provides simple functions for triggering various predefined tactile +feedback (vibration or audio) effects.

                • +

              • Enables a consistent user experience in all applications of the mobile +device (an application gives a logical feedback type as an input and the actual +physical effect depends on the mobile device configuration and end user settings).

                • +

              • When the area feedback is used, latency is low for the feedback triggering +(a tactile feedback can already be triggered at the window server level prior +to the corresponding pointer event being delivered to the visible application).

                • +

              • Direct feedback can be easily integrated into CCoeControl::HandlePointerEventL().

                • +

              • An application can select the logical tactile feedback from certain +types. The produced effect may be different on various mobile devices.

                • +
              • +

            • Haptics +API

                +

              • Available from S60 5th Edition, FP2 onwards.

                • +

              • It can be used in touch and hybrid mobile devices.

                • +

              • Provides an interface for accessing Haptics player that can control +different actuator types.

                • +

              • Enables producing of complex vibrator effects, such as an explosion +or machine gun effect in a game, bass boost for a music player, advanced ringing +tone vibration, and so on.

                • +

              • Enables simultaneous playing of different kinds of basis effects and +modifying them when played.

                • +

              • Allows the design of complex effects (using a separate PC application) +that can be loaded on Haptics player for playing.

                • +

              • It may require a special license key for third-party applications +(to be set at runtime) to enable the Haptics player functionality.

                • +
              • +

            • Vibra API

                +

              • Available from S60 3.0 onwards.

                • +

              • It can be used for running device vibrator with given intensity for +a given period of time.

                • +

              • It can be used by a privileged client application to play pulse effects, +which have a very short duration (as the ones used for tactile feedback).

                • +
              • +
            +
            When to use +Tactile Feedback Client API, Haptics API, and Vibra API

              +

            • Tactile Feedback Client API for providing tactile feedback in custom +controls (grids, lists, and so on), which will comply with the style of Core +UI components to ensure a uniform user experience among applications.

              • +

            • Haptics API on touch and hybrid mobile devices for producing complex +vibration feedback, which cannot be achieved with Tactile Framework (games, +simulations, demos, and so on).

              • +

            • Vibra API for producing haptic effects such as ringing tone vibration +in those mobile devices where Haptics API is not available or functional.

              • +

            +
            Using +tactile feedback in applications

            The API to use for tactile feedback +is the Tactile feedback +client API.

            The Symbian platform includes a tactile feedback +interface to add, modify and remove feedback areas in the registry. There +is also an option to trigger direct feedback and bypass the registry. MTouchFeedback::Instance() is +used for acquiring a pointer to a touch feedback instance. When touch feedback +is activated, the mobile device users get a slight vibration when the control +with the feedback interface is touched.

            Tactile feedback can +be set and disabled in a client application or a mobile device in some scenarios, +for example, during phone calls.

            Client applications cannot determine +the actual physical feedback that is generated. It depends on device configuration +and current settings. In current devices, the user changeable settings include +vibration and audio feedback intensity level.

            For more information, +see Feedback.

             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-581FB79B-2DB9-5AB8-AB32-997B05A62070_d0e107534_href.png Binary file Symbian3/SDK/Source/GUID-581FB79B-2DB9-5AB8-AB32-997B05A62070_d0e107534_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-581FB79B-2DB9-5AB8-AB32-997B05A62070_d0e114072_href.png Binary file Symbian3/SDK/Source/GUID-581FB79B-2DB9-5AB8-AB32-997B05A62070_d0e114072_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5857377F-B90D-5149-9485-5919C12B8F13.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-5857377F-B90D-5149-9485-5919C12B8F13.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,124 @@ + + + + + +How +to use a rule-based selector +

            The following example demonstrates the use of the rule selector and the +inclusion of a selection rule to retrieve the characteristics of a symmetric +cipher object.

            +#include <ruleselector.h> +#include <cryptosymmetriccipherapi.h> +#include <cryptospistateapi.h> +#include <cryptospidef.h> +#include <keys.h> + +using namespace CryptoSpi; + +// Create a CSelectionRules collection object which is used to store the rules +// that influence the choice of plug-in implementation selected + +CSelectionRules* rules = CSelectionRules::NewL(); +CleanupStack::PushL(rules); + +// Add a selection rule selecting symmetric ciphers with a key length of 64 bytes + +TInt ruleValue = 64; + +// Create and initialise one or more crypto parameters +// to store the contents of the rule value +CCryptoParam* ruleValueParam = CCryptoIntParam::NewL(ruleValue,KMaximumKeyLengthTypeUid); + +// Create a selection rule for each crypto parameter (CSelectionRuleContent +// takes ownership of the crypto parameter), by passing in the following parameters: +// *InterfaceScope The Interface scope of which the rule should be applied +// *AlgorithmScope The Algorithm scope of which the rule should be applied +// *CharacteristicValue The parameter type and value of the rule +// *Operator The operator of the rule +// *IsOptional Whether this rule is optional (ETrue) or mandatory (EFalse) +CSelectionRuleContent* rule = CSelectionRuleContent::NewL(KSymmetricCipherInterfaceUid, + KNoneUid, + ruleValueParam, + EOpEqual, + EFalse); + +// Add the newly created selection rule to the CSelectionRules collection by calling +// the 'AddSelectionRuleL' method and passing in a pointer to the constructed rule. +// AddSelectionRuleL() checks that the type of the crypto parameters is correct and +// leaves with KErrNotSupported if not. For instance, a creator name parameter must +// be stored using a CCryptoDesC16Param. + +rules->AddSelectionRuleL(rule); + +// Create an instance of the rule selector, passing in the selection rules +// object previously instantiated +CRuleSelector* ruleSelector = CRuleSelector::NewL(rules); + +// Ownership of the rule collection object is passed to the rule selector, therefore +// the CSelectionRules object needs to be popped off the cleanup stack before pushing on +// the rule selector +CleanupStack::Pop(rules); +CleanupStack::PushL(ruleSelector); + +// The legacy selector is set within the framework by default. In order to set the rule +// selector, the 'SetSelector' method of CryptoSpiStateApi needs to be called, +//passing a pointer to the initialized rule selector +CCryptoSpiStateApi::SetSelector(ruleSelector); + +// Create a new CryptoParams object to encapsulate the secret key string for the +// Symmetric Cipher implementation +CCryptoParams* keyParams = CCryptoParams::NewLC(); + +// Add the secret key to the CCryptoParams object by calling the AddL method, passing in +// the key string and appropriate key parameter UID +keyParams->AddL(_L8("12345678"), KSymmetricKeyParameterUid); + +// Create a CKey object by passing in an instance of TKeyProperty and the previously +// created CCryptoParams object containing the secret key +TKeyProperty keyProperty; +CKey* key=CKey::NewL(keyProperty,*keyParams); +CleanupStack::PushL(key); + +// Create and initialise a pointer for the Symmetric Cipher implementation object +CSymmetricCipher* symmetricCipherImpl = NULL; + +// If successful, the 'CreateSymmetricCipherL' method returns KErrNone and the framework +// creates an instance of the selected Symmetric Cipher implementation, as chosen by the +// rule selector. The CSymmetricCipher pointer is passed by reference and set to point to +// the new symmetric cipher object +TRAPD(err,CSymmetricCipherFactory::CreateSymmetricCipherL(symmetricCipherImpl, + KDesUid, + *key, + KCryptoModeEncryptUid, + KOperationModeNoneUid, + KPaddingModeNoneUid, + NULL)); + +// Having successfully constructed the symmetric cipher implementation object, it is +// possible to retrieve the plug-in characteristics associated with it +if (symmetricCipherImpl && (err == KErrNone)) + { + CleanupStack::PushL(symmetricCipherImpl); + // Use cipher + CleanupStack::PopAndDestroy(symmetricCipherImpl); + } + +CleanupStack::PopAndDestroy(2, keyParams); //key, keyParams + +// Unselect rule selector before destruction. This causes CryptoSPI to use the +// legacy selector again. After calling SetSelector(), the caller +// keeps ownership of the selector, so after calling UnsetSelector(), the +// caller needs to delete the selector +CCryptoSpiStateApi::UnsetSelector(); + +// Pop and destroy the rule selector +CleanupStack::PopAndDestroy(ruleSelector); + +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5918ED8A-B26B-41A0-94A6-AB6D51BF80A1.dita --- a/Symbian3/SDK/Source/GUID-5918ED8A-B26B-41A0-94A6-AB6D51BF80A1.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-5918ED8A-B26B-41A0-94A6-AB6D51BF80A1.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,29 +1,28 @@ - - - - - -Menu -bars -Menu bar configuration -

            The Symbian platform uses MENU_BAR resources to -create the Options menu, when a mobile device user selects -the Options softkey. The options that appear above the -softkeys are determined by CBA -resources. The MENU_BAR resources map the text -that appears in the Options menu with commands that are -collected by the event loop of the application framework and delivered to -your application for command -handling.

            -

            As the above figure illustrates, in menu bars, different elements in -the Options menu are declared in a series of resource -statements. For information on declaring resources for menu bars, see Menu -bar resource statements.

            -

            Access to menus is provided through the Options Menu API.

            + + + + + +Menu bars +Menu bar configuration +

            The Symbian platform uses MENU_BAR resources to +create the Options menu, when a mobile device user selects +the Options softkey. The options that appear above the +softkeys are determined by CBA +resources. The MENU_BAR resources map the text +that appears in the Options menu with commands that are +collected by the event loop of the application framework and delivered to +your application for command +handling.

            +

            As the above figure illustrates, in menu bars, different elements in +the Options menu are declared in a series of resource +statements. For information on declaring resources for menu bars, see Menu +bar resource statements.

            +

            Access to menus is provided through the Options Menu API.

             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-59217FA7-3078-53CA-88B3-78D6FB788271.dita --- a/Symbian3/SDK/Source/GUID-59217FA7-3078-53CA-88B3-78D6FB788271.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-59217FA7-3078-53CA-88B3-78D6FB788271.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,109 +1,109 @@ - - - - - -Message -Type Module Overview -

            Message Type Modules (MTMs) are polymorphic DLL plug-ins that implement -the interfaces defined by the Message Server framework to handle various message -types—such as, IMAP4, POP3, SMTP, SMS and MMS.

            -
            Purpose

            Client applications can access different -types of message and every message type must handled in a specific way. To -support a new message type within the client applications, MTMs to implement -that type must be provided. The following points are specific to each message -type, and so must be implemented in an MTM:

              -

            • Message structure

              • -

            • User interface requirements

              • -

            • Addressing mechanism

              • -

            • Error handling mechanism

              • -

            • MTM DLL information

              • -

            A Message Server abstraction that is used to locate and load particular -MTM components.

            -
            Description

            The MTM architecture is the plug-in -scheme provided by the Messaging Framework to integrate different message -transports to the Message Server. The plug-in scheme consists of four interfaces, -the UI MTM, UI Data MTM, Client MTM and Server MTM.

              -

            • Client MTM manages the -message type’s data model, providing the UI MTM and client applications with -interfaces to access and to search for messages.

              • -

            • User Interface (UI) -Data MTM provides icons, menu text and a list of capabilities for a message -type.

              • -

            • User Interface (UI) -MTM implements the user interface required for the message type, including -a viewer, editor and dialog settings.

              • -

            • Server MTM provides -message transport over the network and manages a queue of outstanding client -requests, and ensures that more than one message of a given type is sent simultaneously.

              • -

            Each of the MTM DLLs is a polymorphic DLL that exports an instance -of a system-defined base class. The Message Server and client applications -use these base class interfaces to access MTM functionality in a generic and -extensible way. The MTM in turn implements a specialized version of the class -to provide specific message type functionality.

            Client applications -can load and use the UI MTM, UI Data MTM and Client MTM DLLs. The DLLs are -loaded within the client’s process space. The Server MTM DLLs are loaded within -the Message Server process. The Messaging Middleware architecture allows clients -to access the combined functionality of the Message Server and the Server -MTMs through a single server interface. The following figure shows the MTM -architecture.

            - MTM architecture - -
            -
            Message Server and MTMs

            The following figure shows -the relationship between the Message Server and MTMs. The grey classes are -realisations of the MTM interfaces defined by the Messaging Framework. The -Message Server depends on the Server MTM interface and controls access to -message data and delegates protocol-specific requests to Server side MTMs. -Messaging clients depend on the Client, UI and UI Data MTM interfaces and -the Message Server client API.

            - Relationship between Message Server and MTMs - - -
            -
            MTM class summary

            Messaging Middleware provides -the following base classes, which defines the component interfaces for MTM -implementations.

              -

            • The base class for UI -MTMs is CBaseMtmUi.

              • -

            • The base class for UI -Data MTMs is CBaseMtmUiData.

              • -

            • The base class for Client -MTMs is CBaseMtm.

              • -

            • The base class for Server -MTMs is CBaseServerMtm.

              • -

            Important: MTMs can also provide message type-specific functionality -that is not defined by the base class interfaces. For example, for IMAP4, -perform a full synchronization with a remote service; for POP3, connect to -a remote server and download messages. The APIs for the client interfaces -are extensible through run time type information provided by the QueryCapability API, -and the InvokeAsyncFunction and InvokeSyncFunction APIs.

            For -information on how to implement the base classes, see the Implementing -MTMs.

            -
            MTM functions

            The MTM DLLs provide the following -functions. MTMs implement them according to the requirements for the message -type:

              -

            • Querying functionality

              Allow -the client applications to query the supported functionality for the message -type. For example, the maximum message size or whether attachments are supported.

              • -

            • Message management functionality

              Allow -the client applications to manage the messages, for example, to send, reply -and forward messages.

              • -

            • Attachment management -functionality

              Allow the client applications to handle attachments. -For example, to add, remove or create an attachment for a particular message.

              • -
            -             -Message Server -and Store -Types of -MTM -Implementing -MTMs + + + + + +Message +Type Module Overview +

            Message Type Modules (MTMs) are polymorphic DLL plug-ins that implement +the interfaces defined by the Message Server framework to handle various message +types—such as, IMAP4, POP3, SMTP, SMS and MMS.

            +
            Purpose

            Client applications can access different +types of message and every message type must handled in a specific way. To +support a new message type within the client applications, MTMs to implement +that type must be provided. The following points are specific to each message +type, and so must be implemented in an MTM:

              +

            • Message structure

              • +

            • User interface requirements

              • +

            • Addressing mechanism

              • +

            • Error handling mechanism

              • +

            • MTM DLL information

              • +

            A Message Server abstraction that is used to locate and load particular +MTM components.

            +
            Description

            The MTM architecture is the plug-in +scheme provided by the Messaging Framework to integrate different message +transports to the Message Server. The plug-in scheme consists of four interfaces, +the UI MTM, UI Data MTM, Client MTM and Server MTM.

              +

            • Client MTM manages the +message type’s data model, providing the UI MTM and client applications with +interfaces to access and to search for messages.

              • +

            • User Interface (UI) +Data MTM provides icons, menu text and a list of capabilities for a message +type.

              • +

            • User Interface (UI) +MTM implements the user interface required for the message type, including +a viewer, editor and dialog settings.

              • +

            • Server MTM provides +message transport over the network and manages a queue of outstanding client +requests, and ensures that more than one message of a given type is sent simultaneously.

              • +

            Each of the MTM DLLs is a polymorphic DLL that exports an instance +of a system-defined base class. The Message Server and client applications +use these base class interfaces to access MTM functionality in a generic and +extensible way. The MTM in turn implements a specialized version of the class +to provide specific message type functionality.

            Client applications +can load and use the UI MTM, UI Data MTM and Client MTM DLLs. The DLLs are +loaded within the client’s process space. The Server MTM DLLs are loaded within +the Message Server process. The Messaging Middleware architecture allows clients +to access the combined functionality of the Message Server and the Server +MTMs through a single server interface. The following figure shows the MTM +architecture.

            + MTM architecture + +
            +
            Message Server and MTMs

            The following figure shows +the relationship between the Message Server and MTMs. The grey classes are +realisations of the MTM interfaces defined by the Messaging Framework. The +Message Server depends on the Server MTM interface and controls access to +message data and delegates protocol-specific requests to Server side MTMs. +Messaging clients depend on the Client, UI and UI Data MTM interfaces and +the Message Server client API.

            + Relationship between Message Server and MTMs + + +
            +
            MTM class summary

            Messaging Middleware provides +the following base classes, which defines the component interfaces for MTM +implementations.

              +

            • The base class for UI +MTMs is CBaseMtmUi.

              • +

            • The base class for UI +Data MTMs is CBaseMtmUiData.

              • +

            • The base class for Client +MTMs is CBaseMtm.

              • +

            • The base class for Server +MTMs is CBaseServerMtm.

              • +

            Important: MTMs can also provide message type-specific functionality +that is not defined by the base class interfaces. For example, for IMAP4, +perform a full synchronization with a remote service; for POP3, connect to +a remote server and download messages. The APIs for the client interfaces +are extensible through run time type information provided by the QueryCapability API, +and the InvokeAsyncFunction and InvokeSyncFunction APIs.

            For +information on how to implement the base classes, see the Implementing +MTMs.

            +
            MTM functions

            The MTM DLLs provide the following +functions. MTMs implement them according to the requirements for the message +type:

              +

            • Querying functionality

              Allow +the client applications to query the supported functionality for the message +type. For example, the maximum message size or whether attachments are supported.

              • +

            • Message management functionality

              Allow +the client applications to manage the messages, for example, to send, reply +and forward messages.

              • +

            • Attachment management +functionality

              Allow the client applications to handle attachments. +For example, to add, remove or create an attachment for a particular message.

              • +
            +             +Message Server +and Store +Types of +MTM +Implementing +MTMs             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5944FFF1-79C6-4F5E-95C8-F4833AFC64AB.dita --- a/Symbian3/SDK/Source/GUID-5944FFF1-79C6-4F5E-95C8-F4833AFC64AB.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-5944FFF1-79C6-4F5E-95C8-F4833AFC64AB.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,50 +1,50 @@ - - - - - -Controls -

            The term control refers to a rectangular area of the display -that may respond to user input events. A control provides a means of access -to a window, which means it can be drawn onto the window and receive input.

            -

            Controls are derived from CCoeControl.

            -

            Examples of controls include:

            -
              -

            • buttons

              • -

            • menus

              • -

            • text edit boxes

              • -

            • main panes that display application specific data

              -
              • -
            -

            For more information on controls, see:

            -
              -

            • Window-owning -controls and non-window-owning controls

              • -

            • The -run-time control hierarchy

              • -

            • UI -Control Framework overview

              • -
            -

            For information on controls and event handling, see Window -server events.

            -

            For more information on implementing controls in different architecture -approaches see:

            -
              -

            • Traditional -Symbian UI application architecture

              -
              • -

            • View -architecture

              -
              • -

            • Dialog -architecture

              -
              • -
            -

            This section comprises:

            + + + + + +Controls +

            The term control refers to a rectangular area of the display +that may respond to user input events. A control provides a means of access +to a window, which means it can be drawn onto the window and receive input.

            +

            Controls are derived from CCoeControl.

            +

            Examples of controls include:

            +
              +

            • buttons

              • +

            • menus

              • +

            • text edit boxes

              • +

            • main panes that display application specific data

              +
              • +
            +

            For more information on controls, see:

            +
              +

            • Window-owning +controls and non-window-owning controls

              • +

            • The +run-time control hierarchy

              • +

            • UI +Control Framework overview

              • +
            +

            For information on controls and event handling, see Window +server events.

            +

            For more information on implementing controls in different architecture +approaches see:

            +
              +

            • Traditional +Symbian UI application architecture

              +
              • +

            • View +architecture

              +
              • +

            • Dialog +architecture

              +
              • +
            +

            This section comprises:

             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5971E713-9CA1-5D75-AE9F-2EF9CBDE39F4_d0e220630_href.png Binary file Symbian3/SDK/Source/GUID-5971E713-9CA1-5D75-AE9F-2EF9CBDE39F4_d0e220630_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5971E713-9CA1-5D75-AE9F-2EF9CBDE39F4_d0e224367_href.png Binary file Symbian3/SDK/Source/GUID-5971E713-9CA1-5D75-AE9F-2EF9CBDE39F4_d0e224367_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-598140D3-6C92-5D8E-B204-C7197C6E404D-master.png Binary file Symbian3/SDK/Source/GUID-598140D3-6C92-5D8E-B204-C7197C6E404D-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-598140D3-6C92-5D8E-B204-C7197C6E404D_d0e384680_href.png Binary file Symbian3/SDK/Source/GUID-598140D3-6C92-5D8E-B204-C7197C6E404D_d0e384680_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-598B6698-3518-50CA-98DE-D85CB255BA2D.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-598B6698-3518-50CA-98DE-D85CB255BA2D.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,74 @@ + + + + + +Secure stream encryption example code

            This example covers:

            • Encrypting some data with a password and writing it to a file

            • Reading the data back from the file and decrypting it with the same password.

            Also, see:

            • PBE example code

            • Secure store example code

            Encrypting data with a password and writing it to a file

            • Supporting code for this example

            +void CSecureStreamExample::WriteEncryptedDataL(const TDesC8& aInput, const TDesC& aFilename, const TDesC& aPassword) + { + // Open a stream to the output file + RFileWriteStream writeStream; + User::LeaveIfError(writeStream.Replace(iFs, aFilename, EFileShareExclusive | EFileWrite)); + CleanupClosePushL(writeStream); + + // Create a CPBEncryptElement object, passing details of the encryption we + // are using and the user's password + CPBEncryptElement* encryption = CPBEncryptElement::NewLC(aPassword, ECipherDES_CBC); + + // Store encryption data as the first thing in the stream + writeStream << encryption->EncryptionData(); + + // Create an REncryptStream - this wraps the write stream and encrypts + // everything written to it + REncryptStream encStream; + encStream.OpenL(writeStream, *encryption); + CleanupClosePushL(encStream); + + // Now we can simply write the plaintext to the encrypt stream - it gets + // encrypted automatically + encStream << aInput; + + // Commit the stream + encStream.CommitL(); + + // Free memory (writeStream, encryption, encStream) + CleanupStack::PopAndDestroy(3, &writeStream); + } +
            Reading data from a file and decrypting it

            • Supporting code for this example

            +HBufC8* CSecureStreamExample::ReadEncryptedDataLC(const TDesC& aFilename, const TDesC& aPassword) + { + // Open a stream to the input file + RFileReadStream readStream; + User::LeaveIfError(readStream.Open(iFs, aFilename, EFileRead)); + CleanupClosePushL(readStream); + + // Read the encryption data from the stream + CPBEncryptionData* encryptionData = CPBEncryptionData::NewLC(readStream); + + // Recreate the CPBEncryptElement object, using the encryption data from the + // file and the user's password + CPBEncryptElement* encryption = CPBEncryptElement::NewLC(*encryptionData, aPassword); + + // Create an RDecryptStream based on the read stream - this decrypts + // everything we read from it + RDecryptStream decStream; + decStream.OpenL(readStream, *encryption); + CleanupClosePushL(decStream); + + // Now we can read the plaintext straight from the stream + HBufC8* plaintext = HBufC8::NewL(decStream, KMaxTInt); + + // Free memory (readStream, encryptionData, encryption, decStream) + CleanupStack::PopAndDestroy(4, &readStream); + CleanupStack::PushL(plaintext); + + // Return plaintext to the caller + return plaintext; + } +
            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-59A9871D-B0F3-54E2-A5BA-38790C109797_d0e16785_href.png Binary file Symbian3/SDK/Source/GUID-59A9871D-B0F3-54E2-A5BA-38790C109797_d0e16785_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-59A9871D-B0F3-54E2-A5BA-38790C109797_d0e47131_href.png Binary file Symbian3/SDK/Source/GUID-59A9871D-B0F3-54E2-A5BA-38790C109797_d0e47131_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-59A9871D-B0F3-54E2-A5BA-38790C109797_d0e52687_href.png Binary file Symbian3/SDK/Source/GUID-59A9871D-B0F3-54E2-A5BA-38790C109797_d0e52687_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-59C143F6-3A0C-5C37-9351-A72FE45AFFC9_d0e240099_href.png Binary file Symbian3/SDK/Source/GUID-59C143F6-3A0C-5C37-9351-A72FE45AFFC9_d0e240099_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-59C143F6-3A0C-5C37-9351-A72FE45AFFC9_d0e243836_href.png Binary file Symbian3/SDK/Source/GUID-59C143F6-3A0C-5C37-9351-A72FE45AFFC9_d0e243836_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-59D86225-4727-5B3F-9117-7815B4900445-master.jpg Binary file Symbian3/SDK/Source/GUID-59D86225-4727-5B3F-9117-7815B4900445-master.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-59D86225-4727-5B3F-9117-7815B4900445_d0e185535_href.jpg Binary file Symbian3/SDK/Source/GUID-59D86225-4727-5B3F-9117-7815B4900445_d0e185535_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-59ED6D14-0976-58AE-8DDC-73F051866406.dita --- a/Symbian3/SDK/Source/GUID-59ED6D14-0976-58AE-8DDC-73F051866406.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-59ED6D14-0976-58AE-8DDC-73F051866406.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,46 +1,46 @@ - - - - - -How -to construct a headerThe header of a linked list needs to know the type of data for -each list element, and where in each element the pointer to the next element -can be found. -

            In order to construct a header, two important pieces of information are -needed:

            -
              -

            • the type of object -which forms the elements.

              • -

            • the offset of -the link object from the start of the element.

              • -
            -

            To create a header for a singly linked list of CMyClass elements, -defined as:

            -class CMyClass : public CBase - { - ... - TSglQueLink iSlink; - ... - }; -

            construct a TSglQue as follows:

            -TSglQue<CMyClass> queHeader(_FOFF(CMyClass,iSlink)); -

            The TSglQue class takes a class template parameter which -defines the type of object which is to form an element of the list. In this -example, objects of type CMyClass form the elements of the -list.

            -

            The _FOFF macro (i.e. the "field offset" macro) calculates -the offset of the component link object within the element. In this example, -the required value is the offset of the iSlink data member -from the start of CMyClass.

            - -Links in singly linked lists - - + + + + + +How +to construct a headerThe header of a linked list needs to know the type of data for +each list element, and where in each element the pointer to the next element +can be found. +

            In order to construct a header, two important pieces of information are +needed:

            +
              +

            • the type of object +which forms the elements.

              • +

            • the offset of +the link object from the start of the element.

              • +
            +

            To create a header for a singly linked list of CMyClass elements, +defined as:

            +class CMyClass : public CBase + { + ... + TSglQueLink iSlink; + ... + }; +

            construct a TSglQue as follows:

            +TSglQue<CMyClass> queHeader(_FOFF(CMyClass,iSlink)); +

            The TSglQue class takes a class template parameter which +defines the type of object which is to form an element of the list. In this +example, objects of type CMyClass form the elements of the +list.

            +

            The _FOFF macro (i.e. the "field offset" macro) calculates +the offset of the component link object within the element. In this example, +the required value is the offset of the iSlink data member +from the start of CMyClass.

            + +Links in singly linked lists + +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-59F26729-3FFB-48AE-91FB-4B9AC2955A06_d0e69489_href.png Binary file Symbian3/SDK/Source/GUID-59F26729-3FFB-48AE-91FB-4B9AC2955A06_d0e69489_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-59F26729-3FFB-48AE-91FB-4B9AC2955A06_d0e74654_href.png Binary file Symbian3/SDK/Source/GUID-59F26729-3FFB-48AE-91FB-4B9AC2955A06_d0e74654_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5ACFA8E4-3C4B-5851-A43E-9FA72D0B8403.dita --- a/Symbian3/SDK/Source/GUID-5ACFA8E4-3C4B-5851-A43E-9FA72D0B8403.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-5ACFA8E4-3C4B-5851-A43E-9FA72D0B8403.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,241 +1,241 @@ - - - - - -XML -DOM Engine OverviewThe XML DOM Engine implements the standard DOM API (tree-based -XML parsing and editing), including XPath and serialization extensions. -
            Purpose

            The XML DOM Engine provides APIs to achieve -the following:

              -

            • Parse XML content: create -a DOM tree from XML streams or files

              • -

            • Create an empty DOM -tree

              • -

            • Modify a DOM tree by -adding or removing nodes and changing their properties (attributes?)

              • -

            • Save a DOM tree to a -buffer or a file (in regular XML, XOP or compressed format)

              • -

            • Explore a DOM tree with -XPath expressions

              • -
            -
            Required background

            The XML DOM engine is based -on the libxml2 component. -It provides a Level-3-like implementation of the DOM standard from W3C, along with XPath and serialisation extensions.

            -
            Key concepts and terms

            The following concepts are -related to generic XML understanding:

            XPath Extension Functions

            XML -Path Language (or XPath) is a W3C standard designed to address parts of an -XML document. A subset of XPath is also used for matching: that is, checking -that a node matches a pattern. Extension Functions are not part of the W3C -standard: you can implement them to add functionalities to XPath.

            Serialise

            Serialising -means converting binary data to a persistent format that can be stored (to -a buffer or a file) or transmitted over a data link. The reverse operation -is called deserialising.

            The RChunk and RHeap classes -are standard Symbian platform classes. For more information, -see Memory allocation -concepts.

            -
            Architecture

            The XML DOM Engine component relies -on the libxml2 component for most of its operations. For more information, -see libxml2 Overview.

            It -also relies on the libxml2 SAX parser plugin of the XML -Framework and on the multi-part parser of the BAFL component -for deserialisation.

            The following package diagram summarises the -dependencies of the XML DOM Engine and shows the three functionality groups -that are described in the following section.

            - Package diagram for the XML DOM Engine component - - -
            -
            Description

            The XML DOM Engine is an object-oriented -provider of the DOM services included in the standard libxml2 library: tree-based -parsing with validation and random access to the XML elements. If you need -event-based parsing, use the XML -Framework instead.

            DOM Parsing

            Parsing an XML -document creates two parallel trees: the regular DOM tree containing generic -Node objects and an RXmlEngDocument object which contains -type-specific nodes. Use these type-specific nodes to avoid type-checking -and casting the Nodes as well as to improve performance. Some of these node -types are shown in the following diagram.

            - Extract of the class diagram for the XML DOM Engine -parser - -

            Serialisation

            Serialisation transforms the DOM tree -(including binary data) into one of the following formats:

              -

            • Default (standard XML)

              • -

            • XOP (XML-binary Optimized -Packaging)

              • -

            • XOP Infoset (original -Infoset with any optimized content replaced by xop:Include items)

              • -

            • gzip (compressed XML)

              • -

            The result can be returned as a file, a buffer or both.

            XPath -Extension Function

            XPath can be extended at run-time by registering -a new extension function. To call the new function, include it in an XPath -expression evaluated by the XML DOM Engine.

            The XPath Extension Function -API provides two interfaces: MXPathExtensionFunction for -the XPath function and MXmlEngXpathEvaluationContext for -its configuration. The static TXmlEngXPathConfiguration class -performs the registration of the extension function within the XML DOM Engine.

            -
            APIs

            DOM Parser API

            The most relevant -classes for parsing and editing a DOM tree are listed in the following table. -See Implementation -of W3C Types for correspondance between this API and the W3C standard.

            - - - -DOM Parser API -Description - - - - -

            RXMLEngDOMImplementation

            -

            This class is the entry-point for the DOM Engine. It provides methods -for creating a new document or an instance of the DOM parser.

            -             - -

            RXMLEngDomParser

            -

            This class provides methods for parsing an XML document and building -a DOM tree.

            -             - -

            RXMLEngDocument

            -

            This class represents a DOM tree. It stores the document properties -and provides methods for modifying the tree, such as adding or deleting nodes.

            -             - -

            TXMLEngNode

            -

            This class represents a DOM node. It stores the node type and properties, -and provides the DOM methods related to it.

            Specialisations of this -class are detailed in XML -DOM Engine Node Reference.

            -             - - -

            The DOM API relies on Descriptor objects for string manipulation, -and on RFile handles for filesystem input and output. To -store RFile in a DOM tree, use the TXmlEngFileContainer class. -To store RChunk in a DOM tree, use the TXmlEngChunkContainer class.

            Serialisation -API

            The most relevant classes for DOM serialisation and deserialisation -are listed in the following table. Other classes can be found in the reference -documentation.

            - - - -Serialisation API -Description - - - - -

            CXmlEngSerializer

            -

            This class provides methods to save a DOM tree to a file or a buffer.

            -             - -

            CXmlEngDeserializer

            -

            This class provides methods to read serialised XOP or GZIP and create -DOM or SAX representations of it.

            -             - - -

            XPath APIs

            The DOM Parsing classes related to XPath -are listed in the following table. Other classes can be found in the reference -documentation.

            - - - -XPath API -Description - - - - -

            RXmlEngXPathExpression

            -

            This class represents an XPath expression.

            -             - -

            TXmlEmgXPathEvaluator

            -

            This class evaluates an XPath expression and returns the result -in an RXmlEngXPathResult instance.

            -             - -

            XmlEngXPathConfiguration

            -

            This class contains static methods for XPath configuration and registration -of extension functions.

            -             - - -

            The most relevant classes of the Extension Function API for XPath -are listed in the following table. Other classes can be found in the reference -documentation.

            - - - - XPath Extension Function API -Description - - - - -

            MXmlEngXPathExtensionFunction

            -

            This interface must be implemented by your extension function.

            -             - -

            MXmlEngXpathEvaluationContext

            -

            This interface must be implemented by your evaluation function, -which processes the arguments of the extension function and stores the result -of the evalutation.

            -             - - -
            -
            Typical uses

            The XML DOM Engine is used by client -applications to process XML documents:

              -

            • The most common clients -are web browsers and associated software, which parse and validate XML streams -or files.

              • -

            • Applications can also -use the XML DOM Engine to organize and store their data, or to transfer their -XML objects over a network connection.

              • -

            • Middleware providers -can extend XPath with new functions with the XPath Extension Function API.

              • -

            To port an existing application that uses the standard libxml2 library, -use the libxml2 component and call the C++ wrappers of the -standard library.

            Here are some of the common tasks that applications -perform through the XML DOM Engine:

              -

            • Read an XML file by -one of the following means:

                -

              • Use the RXMLEngDOMParser class -to parse a regular XML file and get a DOM tree, as explained in the XML DOM Parsing Tutorial.

                • -

              • Use the CXMLEngineSaxPlugin class -to parse a regular XML file and get SAX events, as explained in the XML -SAX Parsing Tutorial.

                • -

              • Use the DeserializeL()</codeph> -method of the TXmlEngDeserializer class to deserialise -a compressed XML file and get SAX events.

                • -

              • Use the UseDOMImplementation() and DeserializeL() methods -of the TXmlEngDeserializer class to deserialise a compressed -XML file and get a DOM tree.

                • -
              • -

            • Save an XML object to -a file by using the TXmlEngSerializer class, as explained -in the XML Serialisation -Tutorial.

              • -

            • Search through an XML -document with XPath, as explained in the XPath -Tutorial.

              • -

            • Add extension functions -to XPath, as explained in the XPath -Extension Tutorial.

              • -
            -             -XML Framework - -libxml2 - + + + + + +XML +DOM Engine OverviewThe XML DOM Engine implements the standard DOM API (tree-based +XML parsing and editing), including XPath and serialization extensions. +
            Purpose

            The XML DOM Engine provides APIs to achieve +the following:

              +

            • Parse XML content: create +a DOM tree from XML streams or files

              • +

            • Create an empty DOM +tree

              • +

            • Modify a DOM tree by +adding or removing nodes and changing their properties (attributes?)

              • +

            • Save a DOM tree to a +buffer or a file (in regular XML, XOP or compressed format)

              • +

            • Explore a DOM tree with +XPath expressions

              • +
            +
            Required background

            The XML DOM engine is based +on the libxml2 component. +It provides a Level-3-like implementation of the DOM standard from W3C, along with XPath and serialisation extensions.

            +
            Key concepts and terms

            The following concepts are +related to generic XML understanding:

            XPath Extension Functions

            XML +Path Language (or XPath) is a W3C standard designed to address parts of an +XML document. A subset of XPath is also used for matching: that is, checking +that a node matches a pattern. Extension Functions are not part of the W3C +standard: you can implement them to add functionalities to XPath.

            Serialise

            Serialising +means converting binary data to a persistent format that can be stored (to +a buffer or a file) or transmitted over a data link. The reverse operation +is called deserialising.

            The RChunk and RHeap classes +are standard Symbian platform classes. For more information, +see Memory allocation +concepts.

            +
            Architecture

            The XML DOM Engine component relies +on the libxml2 component for most of its operations. For more information, +see libxml2 Overview.

            It +also relies on the libxml2 SAX parser plugin of the XML +Framework and on the multi-part parser of the BAFL component +for deserialisation.

            The following package diagram summarises the +dependencies of the XML DOM Engine and shows the three functionality groups +that are described in the following section.

            + Package diagram for the XML DOM Engine component + + +
            +
            Description

            The XML DOM Engine is an object-oriented +provider of the DOM services included in the standard libxml2 library: tree-based +parsing with validation and random access to the XML elements. If you need +event-based parsing, use the XML +Framework instead.

            DOM Parsing

            Parsing an XML +document creates two parallel trees: the regular DOM tree containing generic +Node objects and an RXmlEngDocument object which contains +type-specific nodes. Use these type-specific nodes to avoid type-checking +and casting the Nodes as well as to improve performance. Some of these node +types are shown in the following diagram.

            + Extract of the class diagram for the XML DOM Engine +parser + +

            Serialisation

            Serialisation transforms the DOM tree +(including binary data) into one of the following formats:

              +

            • Default (standard XML)

              • +

            • XOP (XML-binary Optimized +Packaging)

              • +

            • XOP Infoset (original +Infoset with any optimized content replaced by xop:Include items)

              • +

            • gzip (compressed XML)

              • +

            The result can be returned as a file, a buffer or both.

            XPath +Extension Function

            XPath can be extended at run-time by registering +a new extension function. To call the new function, include it in an XPath +expression evaluated by the XML DOM Engine.

            The XPath Extension Function +API provides two interfaces: MXPathExtensionFunction for +the XPath function and MXmlEngXpathEvaluationContext for +its configuration. The static TXmlEngXPathConfiguration class +performs the registration of the extension function within the XML DOM Engine.

            +
            APIs

            DOM Parser API

            The most relevant +classes for parsing and editing a DOM tree are listed in the following table. +See Implementation +of W3C Types for correspondance between this API and the W3C standard.

            + + + +DOM Parser API +Description + + + + +

            RXMLEngDOMImplementation

            +

            This class is the entry-point for the DOM Engine. It provides methods +for creating a new document or an instance of the DOM parser.

            +             + +

            RXMLEngDomParser

            +

            This class provides methods for parsing an XML document and building +a DOM tree.

            +             + +

            RXMLEngDocument

            +

            This class represents a DOM tree. It stores the document properties +and provides methods for modifying the tree, such as adding or deleting nodes.

            +             + +

            TXMLEngNode

            +

            This class represents a DOM node. It stores the node type and properties, +and provides the DOM methods related to it.

            Specialisations of this +class are detailed in XML +DOM Engine Node Reference.

            +             + + +

            The DOM API relies on Descriptor objects for string manipulation, +and on RFile handles for filesystem input and output. To +store RFile in a DOM tree, use the TXmlEngFileContainer class. +To store RChunk in a DOM tree, use the TXmlEngChunkContainer class.

            Serialisation +API

            The most relevant classes for DOM serialisation and deserialisation +are listed in the following table. Other classes can be found in the reference +documentation.

            + + + +Serialisation API +Description + + + + +

            CXmlEngSerializer

            +

            This class provides methods to save a DOM tree to a file or a buffer.

            +             + +

            CXmlEngDeserializer

            +

            This class provides methods to read serialised XOP or GZIP and create +DOM or SAX representations of it.

            +             + + +

            XPath APIs

            The DOM Parsing classes related to XPath +are listed in the following table. Other classes can be found in the reference +documentation.

            + + + +XPath API +Description + + + + +

            RXmlEngXPathExpression

            +

            This class represents an XPath expression.

            +             + +

            TXmlEmgXPathEvaluator

            +

            This class evaluates an XPath expression and returns the result +in an RXmlEngXPathResult instance.

            +             + +

            XmlEngXPathConfiguration

            +

            This class contains static methods for XPath configuration and registration +of extension functions.

            +             + + +

            The most relevant classes of the Extension Function API for XPath +are listed in the following table. Other classes can be found in the reference +documentation.

            + + + + XPath Extension Function API +Description + + + + +

            MXmlEngXPathExtensionFunction

            +

            This interface must be implemented by your extension function.

            +             + +

            MXmlEngXpathEvaluationContext

            +

            This interface must be implemented by your evaluation function, +which processes the arguments of the extension function and stores the result +of the evalutation.

            +             + + +
            +
            Typical uses

            The XML DOM Engine is used by client +applications to process XML documents:

              +

            • The most common clients +are web browsers and associated software, which parse and validate XML streams +or files.

              • +

            • Applications can also +use the XML DOM Engine to organize and store their data, or to transfer their +XML objects over a network connection.

              • +

            • Middleware providers +can extend XPath with new functions with the XPath Extension Function API.

              • +

            To port an existing application that uses the standard libxml2 library, +use the libxml2 component and call the C++ wrappers of the +standard library.

            Here are some of the common tasks that applications +perform through the XML DOM Engine:

              +

            • Read an XML file by +one of the following means:

                +

              • Use the RXMLEngDOMParser class +to parse a regular XML file and get a DOM tree, as explained in the XML DOM Parsing Tutorial.

                • +

              • Use the CXMLEngineSaxPlugin class +to parse a regular XML file and get SAX events, as explained in the XML +SAX Parsing Tutorial.

                • +

              • Use the DeserializeL()</codeph> +method of the TXmlEngDeserializer class to deserialise +a compressed XML file and get SAX events.

                • +

              • Use the UseDOMImplementation() and DeserializeL() methods +of the TXmlEngDeserializer class to deserialise a compressed +XML file and get a DOM tree.

                • +
              • +

            • Save an XML object to +a file by using the TXmlEngSerializer class, as explained +in the XML Serialisation +Tutorial.

              • +

            • Search through an XML +document with XPath, as explained in the XPath +Tutorial.

              • +

            • Add extension functions +to XPath, as explained in the XPath +Extension Tutorial.

              • +
            +             +XML Framework + +libxml2 +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5B112A34-1CBA-5B28-A941-27847FC1D30A.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-5B112A34-1CBA-5B28-A941-27847FC1D30A.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,75 @@ + + + + + +Cryptography +overview +
            Purpose

            The +Cryptography module is the basis of the Symbian platform Security system. +The services provided by this module are used by the following components: +Certman (Certificate Management), Software Installation, Secure Communication +Protocols (for example, SSL, TLS, IPSEC), and WTLS.

            These services +include:

              +

            • symmetric encryption-decryption

              • +

            • asymmetric encryption-decryption

              • +

            • integrity checking and +signature verification

              • +

            • key exchange

              • +

            • message digests

              • +

            The interface for the cryptographic services hides the implementation +details of particular algorithms. No detailed knowledge of the cryptographic +algorithms is needed to use the cryptographic services.

            +
            Description

            The +Cryptography module encapsulates the following significant components:

              +

            • Cryptographic algorithms

              • +

            • Hash algorithms

              • +

            • Random Number Generator (RNG)

              • +

            • Supporting APIs

              • +

            Cryptographic algorithms

            These +algorithms allow data to be encrypted and decrypted. They include:

              +

            • Symmetric +ciphers — algorithms that require communicating parties to hold a shared +secret. They are fast and used for the transmission of bulk data.

              • +

            • Asymmetric +ciphers — algorithms which have two keys, one private to the keys' +owner and one which can be published. They are slow compared to symmetric +ciphers and are used to exchange a symmetric key before transmission of data +encrypted using that key.

              • +

            The classes implementing the symmetric and asymmetric ciphers are +provided in cryptography.dll (see Cryptography +library).

            Hash +algorithms

            Hash algorithms compact a message down to a short series +of bytes from which it is impossible to regenerate the message. They are used +with an asymmetric cipher to generate signatures.

            The classes implementing +the hash algorithms are provided in hash.dll.

            Hash +algorithms are documented in the mainstream Symbian platform library.

            Random Number Generator +(RNG)

            RNG is the basis for the cryptographic key generation. It +uses the RANROT algorithm seeded by random data available on the target hardware +(for example, free running counters available on ARM processors).

            The +Random number library is provided by random.dll.

            The +Random Number Generator API is documented in the mainstream Symbian OS Library.

            Supporting APIs

              +

            • Password +Based Encryption (PBE) — provides an API to encrypt and decrypt data +with a user-supplied password.

              The classes implementing PBE (for example, +for secure stream encryption) are provided in pbe.dll.

              • +

            • Padding — is extra bits +concatenated with a key, password, or plaintext to make their length equal +to the block size. It defines the way blocks are filled with data when the +data to be encrypted is smaller than the block size. Padding is added at encryption +and checked on decryption. (See Block +and stream ciphers and CPadding +class relationships.)

              The Cryptography library supports PKCS#1 public +and private padding, and PKCS#7 style padding (see RFC 2315 section 10.3).

              • +

            • Big +integers — Implementation of arbitrarily large integers.

              Note +that although some methods are exported, the intent is that this library is +only for use by the Cryptography library and not by application code.

              • +
            +             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5B6634EA-EB78-504E-BC5D-ABA67EEA06DF_d0e371630_href.png Binary file Symbian3/SDK/Source/GUID-5B6634EA-EB78-504E-BC5D-ABA67EEA06DF_d0e371630_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5B6634EA-EB78-504E-BC5D-ABA67EEA06DF_d0e377700_href.png Binary file Symbian3/SDK/Source/GUID-5B6634EA-EB78-504E-BC5D-ABA67EEA06DF_d0e377700_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5B8061C3-3BED-51D7-9919-5BA16EA6C6FE_d0e317563_href.png Binary file Symbian3/SDK/Source/GUID-5B8061C3-3BED-51D7-9919-5BA16EA6C6FE_d0e317563_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5B8061C3-3BED-51D7-9919-5BA16EA6C6FE_d0e323720_href.png Binary file Symbian3/SDK/Source/GUID-5B8061C3-3BED-51D7-9919-5BA16EA6C6FE_d0e323720_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5B8FEDA0-624E-44D6-BF70-C5228234BD15_d0e128056_href.png Binary file Symbian3/SDK/Source/GUID-5B8FEDA0-624E-44D6-BF70-C5228234BD15_d0e128056_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5B8FEDA0-624E-44D6-BF70-C5228234BD15_d0e134594_href.png Binary file Symbian3/SDK/Source/GUID-5B8FEDA0-624E-44D6-BF70-C5228234BD15_d0e134594_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5BABDDEC-1D81-5847-9ADB-65DF8E404BFA_d0e230759_href.png Binary file Symbian3/SDK/Source/GUID-5BABDDEC-1D81-5847-9ADB-65DF8E404BFA_d0e230759_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5BABDDEC-1D81-5847-9ADB-65DF8E404BFA_d0e234496_href.png Binary file Symbian3/SDK/Source/GUID-5BABDDEC-1D81-5847-9ADB-65DF8E404BFA_d0e234496_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5BB017AA-46AE-5461-9184-98CE7FA898B9_d0e389217_href.jpg Binary file Symbian3/SDK/Source/GUID-5BB017AA-46AE-5461-9184-98CE7FA898B9_d0e389217_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5BB017AA-46AE-5461-9184-98CE7FA898B9_d0e389379_href.jpg Binary file Symbian3/SDK/Source/GUID-5BB017AA-46AE-5461-9184-98CE7FA898B9_d0e389379_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5BD8EE4B-3149-4331-91E0-7813DF4994E1_d0e74056_href.png Binary file Symbian3/SDK/Source/GUID-5BD8EE4B-3149-4331-91E0-7813DF4994E1_d0e74056_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5BD8EE4B-3149-4331-91E0-7813DF4994E1_d0e79176_href.png Binary file Symbian3/SDK/Source/GUID-5BD8EE4B-3149-4331-91E0-7813DF4994E1_d0e79176_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5C1E776D-5AEF-5326-BEA6-F2108F42CB71.dita --- a/Symbian3/SDK/Source/GUID-5C1E776D-5AEF-5326-BEA6-F2108F42CB71.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-5C1E776D-5AEF-5326-BEA6-F2108F42CB71.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,104 +1,104 @@ - - - - - -condvar: -Using Condition VariablesExamples that explains how to use condition variables. -

            -

              -

            • condvarglobal

              • -

            • condvarlocal

              • -
            -
            condvarglobal

            This -example shows the use of the global condition variable IPC mechanism. The -scope of a global condition variable is inter-process. It can be shared by -threads of any process in the system.

            Download

            Click -on the following link to download the example: condvarglobal .zip

            Click browse to view the example code

            Class summary

            RCondVar RMutex RChunk CPeriodic

            Description

            This -example uses an adder and subtractor pattern to show the use of a global condition -variable. Two processes, the adder and the subtractor, modify a shared variable -by adding and subtracting random amounts. The condition variable ensures that -the value remains within given limits, KMaxValue and KMinValue, -by blocking one of the processes if the value crosses a warning threshold.

            The -adder program creates a global shared memory chunk. It also creates a global -mutex to control access to the chunk and a global condition variable to signal -that the value in the chunk is 'ready for use'. It then initialises -the value in the chunk to zero and periodically tries to add a random value -between 1 and 10 . If, having added a value, it finds that the value of the -chunk is greater than KUpperThreshold, it waits for a signal -from the condition variable before adding another value.

            The subtractor -program periodically tries to subtract a random value between 1 and 10 from -the global shared memory chunk. If, having subtracted a value, it finds that -the value of the chunk is less than KLowerThreshold, it waits -for a signal from the condition variable before subtracting another value.

            Design -and implementation

            - -

            Build

            The -Symbian build process describes how to build this example. The ConditionVariable -example builds the following binary files in the standard location (\epoc32\release\winscw\ - <build_variant>) for Carbide.c++.

              -

            • adder.exe: Demonstrates -the use of the global condition variable. It creates a global shared memory -chunk and periodically adds random values to the chunk.

              • -

            • subtractor.exe: Demonstrates -the use of the global condition variable. It periodically subtracts random -values from the chunk created by adder.exe.

              • -

            How to run the Example

            To run the example, perform -the following steps:

              -

            1. Run adder.exe.

              2. -

            2. Run eshell.

              3. -

            3. Run subtract.exe in -your new eshell.

              4. -

            4. Switch between eshells -by pressing CTRL+ALT+SHIFT+T.

              5. -

            5. To finish, stop each -application by pressing any key.

              6. -
            -
            condvarlocal

            This -example shows the use of the local condition variable IPC mechanism. The scope -of a local condition variable is intra-process. It can be shared by threads -of the process that creates the condition variable.

            Download

            Click -on the following link to download the example: condvarlocal .zip

            Click browse to view the example.

            Class summary

            RMutex RThread CPeriodic RCondVar

            Description

            This -example uses the producer and the consumer model to show the use of the local -condition variable.

            The example creates two local threads: a producer -and a consumer. The two threads share a buffer, which is an object of the CQueue class. -The CQueue object creates a local condition variable using the RCondVar::CreateLocal() function. -It also defines the methods to insert and remove a token from the queue. The CQueue::Insert() function -inserts a token into the queue and signals the condition variable. The CQueue::Remove() function -tries to remove a token from the queue. If the queue is empty, it must wait -for a signal from the condition variable.

            An object of the CProducer class -creates and calls the producer thread. The producer thread is called once -every two seconds using an object of the CPeriodic class. -This thread inserts a token into the queue when it is called. It calls the CQueue::Insert() function -on the shared CQueue object.

            An object of the CConsumer class -creates and calls the consumer thread. The consumer thread is called once -a second using an object of the CPeriodic class. This thread -removes a token from the queue when it is called. It calls the CQueue::Remove() function -on the shared CQueue object.

            For more information, -refer to Condition Variables.

            Symbian -is not responsible for the content of external websites.

            Design -and implementation

            - -

            Build

            The -Symbian build process describes how to build this example. The ConditionVariable -example builds the following binary files in the standard location (\epoc32\release\winscw\ - <build_variant>) for Carbide.c++.

            condvarlocal.exe: -Demonstrates the use of the local condition variable.

            How to run -the Example

            To run the example, perform the following steps:

              -

            1. Run condvarlocal.exe. -The program calls the producer and the consumer threads periodically as shown -in the description section. It also displays a menu.

              2. -

            2. Press ‘d’ to -display the contents of the queue.

              3. -

            3. Press ‘p’ to -insert a token into the queue.

              4. -

            4. Press any key to stop -the program.

              5. -
            + + + + + +condvar: +Using Condition VariablesExamples that explains how to use condition variables. +

            +

              +

            • condvarglobal

              • +

            • condvarlocal

              • +
            +
            condvarglobal

            This +example shows the use of the global condition variable IPC mechanism. The +scope of a global condition variable is inter-process. It can be shared by +threads of any process in the system.

            Download

            Click +on the following link to download the example: condvarglobal .zip

            Click browse to view the example code

            Class summary

            RCondVar RMutex RChunk CPeriodic

            Description

            This +example uses an adder and subtractor pattern to show the use of a global condition +variable. Two processes, the adder and the subtractor, modify a shared variable +by adding and subtracting random amounts. The condition variable ensures that +the value remains within given limits, KMaxValue and KMinValue, +by blocking one of the processes if the value crosses a warning threshold.

            The +adder program creates a global shared memory chunk. It also creates a global +mutex to control access to the chunk and a global condition variable to signal +that the value in the chunk is 'ready for use'. It then initialises +the value in the chunk to zero and periodically tries to add a random value +between 1 and 10 . If, having added a value, it finds that the value of the +chunk is greater than KUpperThreshold, it waits for a signal +from the condition variable before adding another value.

            The subtractor +program periodically tries to subtract a random value between 1 and 10 from +the global shared memory chunk. If, having subtracted a value, it finds that +the value of the chunk is less than KLowerThreshold, it waits +for a signal from the condition variable before subtracting another value.

            Design +and implementation

            + +

            Build

            The +Symbian build process describes how to build this example. The ConditionVariable +example builds the following binary files in the standard location (\epoc32\release\winscw\ + <build_variant>) for Carbide.c++.

              +

            • adder.exe: Demonstrates +the use of the global condition variable. It creates a global shared memory +chunk and periodically adds random values to the chunk.

              • +

            • subtractor.exe: Demonstrates +the use of the global condition variable. It periodically subtracts random +values from the chunk created by adder.exe.

              • +

            How to run the Example

            To run the example, perform +the following steps:

              +

            1. Run adder.exe.

              2. +

            2. Run eshell.

              3. +

            3. Run subtract.exe in +your new eshell.

              4. +

            4. Switch between eshells +by pressing CTRL+ALT+SHIFT+T.

              5. +

            5. To finish, stop each +application by pressing any key.

              6. +
            +
            condvarlocal

            This +example shows the use of the local condition variable IPC mechanism. The scope +of a local condition variable is intra-process. It can be shared by threads +of the process that creates the condition variable.

            Download

            Click +on the following link to download the example: condvarlocal .zip

            Click browse to view the example.

            Class summary

            RMutex RThread CPeriodic RCondVar

            Description

            This +example uses the producer and the consumer model to show the use of the local +condition variable.

            The example creates two local threads: a producer +and a consumer. The two threads share a buffer, which is an object of the CQueue class. +The CQueue object creates a local condition variable using the RCondVar::CreateLocal() function. +It also defines the methods to insert and remove a token from the queue. The CQueue::Insert() function +inserts a token into the queue and signals the condition variable. The CQueue::Remove() function +tries to remove a token from the queue. If the queue is empty, it must wait +for a signal from the condition variable.

            An object of the CProducer class +creates and calls the producer thread. The producer thread is called once +every two seconds using an object of the CPeriodic class. +This thread inserts a token into the queue when it is called. It calls the CQueue::Insert() function +on the shared CQueue object.

            An object of the CConsumer class +creates and calls the consumer thread. The consumer thread is called once +a second using an object of the CPeriodic class. This thread +removes a token from the queue when it is called. It calls the CQueue::Remove() function +on the shared CQueue object.

            For more information, +refer to Condition Variables.

            Symbian +is not responsible for the content of external websites.

            Design +and implementation

            + +

            Build

            The +Symbian build process describes how to build this example. The ConditionVariable +example builds the following binary files in the standard location (\epoc32\release\winscw\ + <build_variant>) for Carbide.c++.

            condvarlocal.exe: +Demonstrates the use of the local condition variable.

            How to run +the Example

            To run the example, perform the following steps:

              +

            1. Run condvarlocal.exe. +The program calls the producer and the consumer threads periodically as shown +in the description section. It also displays a menu.

              2. +

            2. Press ‘d’ to +display the contents of the queue.

              3. +

            3. Press ‘p’ to +insert a token into the queue.

              4. +

            4. Press any key to stop +the program.

              5. +
             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5C1EC237-EBC3-474D-B58D-502B82911DCA_d0e75346_href.png Binary file Symbian3/SDK/Source/GUID-5C1EC237-EBC3-474D-B58D-502B82911DCA_d0e75346_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5C1EC237-EBC3-474D-B58D-502B82911DCA_d0e80478_href.png Binary file Symbian3/SDK/Source/GUID-5C1EC237-EBC3-474D-B58D-502B82911DCA_d0e80478_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5C215C64-5D3D-5B65-A11F-BE6F8C306CF4.dita --- a/Symbian3/SDK/Source/GUID-5C215C64-5D3D-5B65-A11F-BE6F8C306CF4.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-5C215C64-5D3D-5B65-A11F-BE6F8C306CF4.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,82 +1,82 @@ - - - - - -How the Target Client is Resolved using CSIPResolvedClient

            SIP Client Resolver determines the target clients by comparing the Request-URI of the incoming SIP request to the information provided in the ECOM plug-in resource file. This resource file is an XML file. All client applications using Client Resolver must be implemented as ECOM plug-ins and must have capabilities.

            An application must declare capabilities, that are the supported content types and media formats that use the SIP headers and SDP m-lines. The capabilities must be declared in the code of the plug-in, in the XML file, or in the opaque_data field of the resource file.

            The following is the DTD for the ECOM plug-in’s resource file:

            <!-- SIP_CLIENT --> -<!ELEMENT SIP_CLIENT (SIP_HEADERS, SDP_LINES?)> - -<!-- ALLOW_STARTING determines if a client can be started by the SIP stack. --> -<!ATTLIST SIP_CLIENT ALLOW_STARTING (YES|NO) #REQUIRED> - -<!-- SIP_HEADERS --> -<!ELEMENT SIP_HEADERS (ACCEPT+, ALLOW_EVENTS*, ACCEPT_CONTACT*)> - -<!-- ACCEPT: Accept-header as specified in RFC 3261. - Indicates Content-Types supported by the client. - Note that support for application/sdp must be announced as well, - especially when the application aims to indicate capabilities based - on SDP. Otherwise the SDP-based rules will not be taken into account. - An empty value means that the application is willing - to receive SIP requests without content. ---> -<!ELEMENT ACCEPT EMPTY> -<!ATTLIST ACCEPT value CDATA #REQUIRED> - -<!-- ALLOW_EVENTS: Allow-Events-header as specified in RFC 3265 - Indicates events supported by the client. - Compared to the event-package part of a Event-header - in an incoming SIP request if present. ---> -<!ELEMENT ALLOW_EVENTS EMPTY> -<!ATTLIST ALLOW_EVENTS value CDATA #REQUIRED> - -<!-- ACCEPT_CONTACT: Accept-Contact-header as specified in RFC 3841 - Indicates caller preferences supported by the client. - All the parameters must match to a Accept-Contact header - in an incoming SIP request if present. ---> -<!ELEMENT ACCEPT_CONTACT EMPTY> -<!ATTLIST ACCEPT_CONTACT value CDATA #REQUIRED> - -<!-- SDP_LINES --> -<!ELEMENT SDP_LINES (LINE+)> - -<!-- SDP Lines - Can be used to indicate supported media by the client. - If defined the application must announce the capability of - receiving content of type application/sdp. - Only M-line is supported currently as follows: - - supported values of media field - - port is rendered useless, - but is mandatory in M-Line's BNF (should be set to zero) - - supported values of proto field - - name of the application in fmt field if the - value of media field is 'application' - BNF for the value of the M-Line: - media space port ["/" integer] space proto 1*(space fmt) - media = 1*(alpha-numeric) - port = 1*(DIGIT) - proto = 1*(alpha-numeric) - fmt = 1*(alpha-numeric) - alpha-numeric = ALPHA | DIGIT - ALPHA = "a"|"b"|"c"|"d"|"e"|"f"|"g"|"h"|"I"|"j"|"k"| - "l"|"m"|"n"|"o "|"p"|"q"|"r"|"s"|"t"|"u"|"v"| - "w"|"x"|"y"|"z"|"A"|"B"|"C "|"D"|"E"|"F"|"G"| - "H"|"I"|"J"|"K"|"L"|"M"|"N"|"O"|"P"|" Q"|"R"| - "S"|"T"|"U"|"V"|"W"|"X"|"Y"|"Z" - DIGIT = "0"|"1"|"2"|"3"|"4"|"5"|"6"|"7"|"8"|"9" ---> -<!ELEMENT LINE EMPTY> -<!ATTLIST LINE name CDATA #REQUIRED> -<!ATTLIST LINE value CDATA #REQUIRED> -

            The resource (.rss) file contains the XML file and the following information:

            • dll_uid and implementation_uid: These UIDs are supplied on request to Symbian Signed.

              Note: These UIDs can be the same.

            • interface_uid: This must have the value 0x102010DD.

            • default_data: The application UID (without 0x).

            • opaque_data: The application capabilities in XML format. This field is empty if application capabilities are defined in the implementation.

            Resolving the target client using CSIPResolvedClient

            The following illustration shows how the SIP Client Resolver subsystem resolves the target client implementation and requests the resolved client to connect to the SIP implementation. In this plan, the default resolution logic is applied.

            - Call flow of resolving a target client implementation using - CSIPResolvedClient -

            The following list describes how the target client is resolved using CSIPResolvedClient.

            1. The user receives a SIP request and the target client is defined using CSIPResolvedClient.

            2. The user requests the SIP Client Resolver API implementation for a channel UI to connect to the user.

            3. The user requests the target client to connect to SIP with the resolved UID if there is no connection with the resolved channel UID.

            4. The SIP Client Resolver API implementation starts the target client.

            See also

            Example of a SIP client resolver plug-in

            \ No newline at end of file + + + + + +How the Target Client is Resolved using CSIPResolvedClient

            SIP Client Resolver determines the target clients by comparing the Request-URI of the incoming SIP request to the information provided in the ECOM plug-in resource file. This resource file is an XML file. All client applications using Client Resolver must be implemented as ECOM plug-ins and must have capabilities.

            An application must declare capabilities, that are the supported content types and media formats that use the SIP headers and SDP m-lines. The capabilities must be declared in the code of the plug-in, in the XML file, or in the opaque_data field of the resource file.

            The following is the DTD for the ECOM plug-in’s resource file:

            <!-- SIP_CLIENT --> +<!ELEMENT SIP_CLIENT (SIP_HEADERS, SDP_LINES?)> + +<!-- ALLOW_STARTING determines if a client can be started by the SIP stack. --> +<!ATTLIST SIP_CLIENT ALLOW_STARTING (YES|NO) #REQUIRED> + +<!-- SIP_HEADERS --> +<!ELEMENT SIP_HEADERS (ACCEPT+, ALLOW_EVENTS*, ACCEPT_CONTACT*)> + +<!-- ACCEPT: Accept-header as specified in RFC 3261. + Indicates Content-Types supported by the client. + Note that support for application/sdp must be announced as well, + especially when the application aims to indicate capabilities based + on SDP. Otherwise the SDP-based rules will not be taken into account. + An empty value means that the application is willing + to receive SIP requests without content. +--> +<!ELEMENT ACCEPT EMPTY> +<!ATTLIST ACCEPT value CDATA #REQUIRED> + +<!-- ALLOW_EVENTS: Allow-Events-header as specified in RFC 3265 + Indicates events supported by the client. + Compared to the event-package part of a Event-header + in an incoming SIP request if present. +--> +<!ELEMENT ALLOW_EVENTS EMPTY> +<!ATTLIST ALLOW_EVENTS value CDATA #REQUIRED> + +<!-- ACCEPT_CONTACT: Accept-Contact-header as specified in RFC 3841 + Indicates caller preferences supported by the client. + All the parameters must match to a Accept-Contact header + in an incoming SIP request if present. +--> +<!ELEMENT ACCEPT_CONTACT EMPTY> +<!ATTLIST ACCEPT_CONTACT value CDATA #REQUIRED> + +<!-- SDP_LINES --> +<!ELEMENT SDP_LINES (LINE+)> + +<!-- SDP Lines + Can be used to indicate supported media by the client. + If defined the application must announce the capability of + receiving content of type application/sdp. + Only M-line is supported currently as follows: + - supported values of media field + - port is rendered useless, + but is mandatory in M-Line's BNF (should be set to zero) + - supported values of proto field + - name of the application in fmt field if the + value of media field is 'application' + BNF for the value of the M-Line: + media space port ["/" integer] space proto 1*(space fmt) + media = 1*(alpha-numeric) + port = 1*(DIGIT) + proto = 1*(alpha-numeric) + fmt = 1*(alpha-numeric) + alpha-numeric = ALPHA | DIGIT + ALPHA = "a"|"b"|"c"|"d"|"e"|"f"|"g"|"h"|"I"|"j"|"k"| + "l"|"m"|"n"|"o "|"p"|"q"|"r"|"s"|"t"|"u"|"v"| + "w"|"x"|"y"|"z"|"A"|"B"|"C "|"D"|"E"|"F"|"G"| + "H"|"I"|"J"|"K"|"L"|"M"|"N"|"O"|"P"|" Q"|"R"| + "S"|"T"|"U"|"V"|"W"|"X"|"Y"|"Z" + DIGIT = "0"|"1"|"2"|"3"|"4"|"5"|"6"|"7"|"8"|"9" +--> +<!ELEMENT LINE EMPTY> +<!ATTLIST LINE name CDATA #REQUIRED> +<!ATTLIST LINE value CDATA #REQUIRED> +

            The resource (.rss) file contains the XML file and the following information:

            • dll_uid and implementation_uid: These UIDs are supplied on request to Symbian Signed.

              Note: These UIDs can be the same.

            • interface_uid: This must have the value 0x102010DD.

            • default_data: The application UID (without 0x).

            • opaque_data: The application capabilities in XML format. This field is empty if application capabilities are defined in the implementation.

            Resolving the target client using CSIPResolvedClient

            The following illustration shows how the SIP Client Resolver subsystem resolves the target client implementation and requests the resolved client to connect to the SIP implementation. In this plan, the default resolution logic is applied.

            + Call flow of resolving a target client implementation using + CSIPResolvedClient +

            The following list describes how the target client is resolved using CSIPResolvedClient.

            1. The user receives a SIP request and the target client is defined using CSIPResolvedClient.

            2. The user requests the SIP Client Resolver API implementation for a channel UI to connect to the user.

            3. The user requests the target client to connect to SIP with the resolved UID if there is no connection with the resolved channel UID.

            4. The SIP Client Resolver API implementation starts the target client.

            See also

            Example of a SIP client resolver plug-in

            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5C4922C8-3AE3-424A-A2E7-5C6DA323FFA6.dita --- a/Symbian3/SDK/Source/GUID-5C4922C8-3AE3-424A-A2E7-5C6DA323FFA6.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-5C4922C8-3AE3-424A-A2E7-5C6DA323FFA6.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,153 +1,153 @@ - - - - - -Alarm -Server Overview -

            Alarm Server is a system server, which starts during device start-up. It -is responsible for maintaining a queue of all system-wide alarms.

            -

            It allows clients to query the status of alarms, set alarms, remove alarms -and perform other utility functions. The Alarm client API allows other components -to interact with the Alarm Server. The Alarm Server sends notification of -alarm expiry to the Alert Server, which then notifies the Alarm UI to display -dialogs and play sound.

            -

            The typical clients of Alarm Server include Clock and Calendar applications.

            -
            Purpose

            The Alarm Server manages the alarms in -the system and provides the following functionality:

              -

            • adding, updating and -deleting alarms.

              • -

            • getting and setting -client-specific data associated with the alarm.

              • -

            • performing alarm category-based -operations such as retrieval and deletion. Retrieving alarm information includes -alarm count, unique identifiers based on alarm states.

              • -

            • getting and setting -Alarm Server’s global sound state and play intervals.

              • -

            • notifying the client -when alarm settings change and when the alarm expires.

              • -
            -
            Key concepts and terms
            - -
            Duration
            -

            It is the time period, in seconds, for which the alarm sound is played.

            -             - -
            Offset
            -

            It is the time (in minutes) duration of alarm sound played after the -alarm expiry.

            -             - -
            Alarm play interval
            -

            Alarm play interval consists of duration and an offset. At each offset, -the Alarm Server makes a request to the Alarm Alert Server to display the -alarm dialog and play the alarm sound.

            -             - -
            Universal Time Coordinated (UTC)
            -

            It is the international time standard. It is the current term for what -was commonly referred as Greenwich Meridian Time (GMT) . Zero hours UTC is -midnight in Greenwich England, which lies on the zero longitudinal meridian. -Universal time is based on a 24-hour clock. Therefore, afternoon hours such -as 4 PM are expressed as 16:00 UTC.

            -             - -
            Daylight Saving Time (DST)
            -

            Daylight Saving Time or Summer Time, is a way of utilizing more daylight -by advancing the local time by one hour during the summer.

            -             - -
            Session alarms
            -

            The alarms that are removed from the alarm queue when their session -owners disconnect are referred as Session Alarms.

            -             - -
            Non-Session alarms
            -

            The alarms that continue to persist in the alarm queue, even after -their session owners which added these alarms disconnect, are referred as -Non-Session alarms. These alarms are also referred to as Orphaned Session -alarms.

            -             - -
            Wake-Up alarms
            -

            An alarm that wakes-up the device if the device is switched OFF when -the alarm occurs, is referred to as Wake-Up alarm.

            -             -
            -
            Architecture

            Alarm Server is implemented using -the Symbian platform IPC client-server architecture. It has an interface to -the Alarm Alert server, which is delivered as part of the Application Framework -(UIKON component). Alarm Alert Server is responsible for displaying the alarm -dialog when an alarm expires. The Alarm Server implements the Alarm Alert -server’s client side DLL to send and receive notifications to and from the -Alarm UI. Alarm Alert Server is a part of the UIKON server (Eiksrv.exe). -The Alarm Server itself implements the client-side APIs since it is the only -client for the Alarm Alert server. The following diagram illustrates the Alarm -Server architecture:

            - Alarm Server Architecture - -

            Alarm Client and Alarm Shared

            They are the static -interface DLLs. Alarm client is the client side of the Alarm Server, which -allows other components to interact with the Alarm Server.

            The Alarm -Shared facilitates a common format shared across server and its clients for -providing definition for an alarm. It consists of shared objects such as alarm -class, IPC messages, repeat definitions, alarm states.

            Alarm Server

            Alarm -Server manages all alarms on the device and enables client UI applications -to use the services provided by the Alarm Server. It relies on the Alarm UI -to notify, which includes displaying and playing sounds.

            It uses a -resource file to configure the sound intervals required for the alarm to repeat. -The compiled resource file resides in the private directory of the Alarm Server. -The resource file is used only for initial configuration.

            Alarm Server -configurations are stored in AlarmServer.ini file and Backup_Registration.xml file -performs a passive backup of this .ini file to the PC-side -at runtime. For secure backup of this .ini file, backuprestorenotification.lib is -used. For more information on the resource file and backup, refer to the Alarm Sound Play Control.

            It -listens to the following events:

              -

            • System state changes -- Using System State -Manager (SSM), Alarm Server listens to the system state changes (normal -and shutdown states) to synchronize the backup of the alarm server queue to -the AlarmServer.ini backup file.

              • -

            • Environment change - -Using Environment Change -Notifier (bafl.dll), Alarm Server listens to the changes -in the environment, such as system time/date change, workdays change or UTC -offset change.

              • -

            UIKON Server

            UIKON server is responsible for starting -the Alarm Server at the device boot-up.

            It is also responsible for -playing sounds, flashing lights and displaying the message. Through the UIKON -server, alarms can be cleared, snoozed or silenced. Alarm server implements -and uses the client side interface. Alarm UI implements the server side of -the UIKON server.

            -
            APIs

            The Alarm Server provides the following client -API:

            - - - -API -Description - - - - -

            RASCliSession

            -

            Client interface to Alarm session on Symbian Platform.

            -             - - -
            -
            Typical uses

            The following are the typical use -cases of Alarm Server:

              -

            • Using Alarm Server to -add, update and delete alarms, set alarm status and so on.

              • -

            • Playing an alarm continuously.

              • -

            • Activating an alarm -on specified days.

              • -
            + + + + + +Alarm +Server Overview +

            Alarm Server is a system server, which starts during device start-up. It +is responsible for maintaining a queue of all system-wide alarms.

            +

            It allows clients to query the status of alarms, set alarms, remove alarms +and perform other utility functions. The Alarm client API allows other components +to interact with the Alarm Server. The Alarm Server sends notification of +alarm expiry to the Alert Server, which then notifies the Alarm UI to display +dialogs and play sound.

            +

            The typical clients of Alarm Server include Clock and Calendar applications.

            +
            Purpose

            The Alarm Server manages the alarms in +the system and provides the following functionality:

              +

            • adding, updating and +deleting alarms.

              • +

            • getting and setting +client-specific data associated with the alarm.

              • +

            • performing alarm category-based +operations such as retrieval and deletion. Retrieving alarm information includes +alarm count, unique identifiers based on alarm states.

              • +

            • getting and setting +Alarm Server’s global sound state and play intervals.

              • +

            • notifying the client +when alarm settings change and when the alarm expires.

              • +
            +
            Key concepts and terms
            + +
            Duration
            +

            It is the time period, in seconds, for which the alarm sound is played.

            +             + +
            Offset
            +

            It is the time (in minutes) duration of alarm sound played after the +alarm expiry.

            +             + +
            Alarm play interval
            +

            Alarm play interval consists of duration and an offset. At each offset, +the Alarm Server makes a request to the Alarm Alert Server to display the +alarm dialog and play the alarm sound.

            +             + +
            Universal Time Coordinated (UTC)
            +

            It is the international time standard. It is the current term for what +was commonly referred as Greenwich Meridian Time (GMT) . Zero hours UTC is +midnight in Greenwich England, which lies on the zero longitudinal meridian. +Universal time is based on a 24-hour clock. Therefore, afternoon hours such +as 4 PM are expressed as 16:00 UTC.

            +             + +
            Daylight Saving Time (DST)
            +

            Daylight Saving Time or Summer Time, is a way of utilizing more daylight +by advancing the local time by one hour during the summer.

            +             + +
            Session alarms
            +

            The alarms that are removed from the alarm queue when their session +owners disconnect are referred as Session Alarms.

            +             + +
            Non-Session alarms
            +

            The alarms that continue to persist in the alarm queue, even after +their session owners which added these alarms disconnect, are referred as +Non-Session alarms. These alarms are also referred to as Orphaned Session +alarms.

            +             + +
            Wake-Up alarms
            +

            An alarm that wakes-up the device if the device is switched OFF when +the alarm occurs, is referred to as Wake-Up alarm.

            +             +
            +
            Architecture

            Alarm Server is implemented using +the Symbian platform IPC client-server architecture. It has an interface to +the Alarm Alert server, which is delivered as part of the Application Framework +(UIKON component). Alarm Alert Server is responsible for displaying the alarm +dialog when an alarm expires. The Alarm Server implements the Alarm Alert +server’s client side DLL to send and receive notifications to and from the +Alarm UI. Alarm Alert Server is a part of the UIKON server (Eiksrv.exe). +The Alarm Server itself implements the client-side APIs since it is the only +client for the Alarm Alert server. The following diagram illustrates the Alarm +Server architecture:

            + Alarm Server Architecture + +

            Alarm Client and Alarm Shared

            They are the static +interface DLLs. Alarm client is the client side of the Alarm Server, which +allows other components to interact with the Alarm Server.

            The Alarm +Shared facilitates a common format shared across server and its clients for +providing definition for an alarm. It consists of shared objects such as alarm +class, IPC messages, repeat definitions, alarm states.

            Alarm Server

            Alarm +Server manages all alarms on the device and enables client UI applications +to use the services provided by the Alarm Server. It relies on the Alarm UI +to notify, which includes displaying and playing sounds.

            It uses a +resource file to configure the sound intervals required for the alarm to repeat. +The compiled resource file resides in the private directory of the Alarm Server. +The resource file is used only for initial configuration.

            Alarm Server +configurations are stored in AlarmServer.ini file and Backup_Registration.xml file +performs a passive backup of this .ini file to the PC-side +at runtime. For secure backup of this .ini file, backuprestorenotification.lib is +used. For more information on the resource file and backup, refer to the Alarm Sound Play Control.

            It +listens to the following events:

              +

            • System state changes +- Using System State +Manager (SSM), Alarm Server listens to the system state changes (normal +and shutdown states) to synchronize the backup of the alarm server queue to +the AlarmServer.ini backup file.

              • +

            • Environment change - +Using Environment Change +Notifier (bafl.dll), Alarm Server listens to the changes +in the environment, such as system time/date change, workdays change or UTC +offset change.

              • +

            UIKON Server

            UIKON server is responsible for starting +the Alarm Server at the device boot-up.

            It is also responsible for +playing sounds, flashing lights and displaying the message. Through the UIKON +server, alarms can be cleared, snoozed or silenced. Alarm server implements +and uses the client side interface. Alarm UI implements the server side of +the UIKON server.

            +
            APIs

            The Alarm Server provides the following client +API:

            + + + +API +Description + + + + +

            RASCliSession

            +

            Client interface to Alarm session on Symbian Platform.

            +             + + +
            +
            Typical uses

            The following are the typical use +cases of Alarm Server:

              +

            • Using Alarm Server to +add, update and delete alarms, set alarm status and so on.

              • +

            • Playing an alarm continuously.

              • +

            • Activating an alarm +on specified days.

              • +
             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5C52B6B9-546C-5152-A968-B91CB3D885A0_d0e336267_href.jpg Binary file Symbian3/SDK/Source/GUID-5C52B6B9-546C-5152-A968-B91CB3D885A0_d0e336267_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5C52B6B9-546C-5152-A968-B91CB3D885A0_d0e342464_href.jpg Binary file Symbian3/SDK/Source/GUID-5C52B6B9-546C-5152-A968-B91CB3D885A0_d0e342464_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5C5A695C-A0BB-53C3-A20B-7C7F4DD718DF_d0e266965_href.png Binary file Symbian3/SDK/Source/GUID-5C5A695C-A0BB-53C3-A20B-7C7F4DD718DF_d0e266965_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5C5A695C-A0BB-53C3-A20B-7C7F4DD718DF_d0e270673_href.png Binary file Symbian3/SDK/Source/GUID-5C5A695C-A0BB-53C3-A20B-7C7F4DD718DF_d0e270673_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5C7F92F7-F3BC-4B00-A093-682AA6A26FFE-master.png Binary file Symbian3/SDK/Source/GUID-5C7F92F7-F3BC-4B00-A093-682AA6A26FFE-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5C7F92F7-F3BC-4B00-A093-682AA6A26FFE_d0e64131_href.png Binary file Symbian3/SDK/Source/GUID-5C7F92F7-F3BC-4B00-A093-682AA6A26FFE_d0e64131_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5C7F92F7-F3BC-4B00-A093-682AA6A26FFE_d0e69363_href.png Binary file Symbian3/SDK/Source/GUID-5C7F92F7-F3BC-4B00-A093-682AA6A26FFE_d0e69363_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5D408616-8A7A-4882-A64F-4BF6EC3FD6AA-master.png Binary file Symbian3/SDK/Source/GUID-5D408616-8A7A-4882-A64F-4BF6EC3FD6AA-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5D408616-8A7A-4882-A64F-4BF6EC3FD6AA_d0e67451_href.png Binary file Symbian3/SDK/Source/GUID-5D408616-8A7A-4882-A64F-4BF6EC3FD6AA_d0e67451_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5D712F4A-E956-543D-BCC0-91107C6E4717.dita --- a/Symbian3/SDK/Source/GUID-5D712F4A-E956-543D-BCC0-91107C6E4717.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-5D712F4A-E956-543D-BCC0-91107C6E4717.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,12 +1,12 @@ - - - - - -Notification of changes to the comms databaseThis topic describes the mechanism that allows the CommsDat API to notify tools and applications of changes to the Comms Database.

            All elements that you can read and write have the class MMetaDatabase as a base class. This base class contains the functions that allow the CommsDat API to notify tools and applicaions of changes to the database.

            Tables, records, links and fields are all elements. The classes that represent tables, records, links and fields have MMetaDatabase in their class hierearchy. You can use the CommsDat::MMetaDatabase::RequestNotification() function to register for notification of changes to the Comms Database. You can use the CommsDat::MMetaDatabase::CancelNotification() function to cancel a request for notification.

            \ No newline at end of file + + + + + +Notification of changes to the comms databaseThis topic describes the mechanism that allows the CommsDat API to notify tools and applications of changes to the Comms Database.

            All elements that you can read and write have the class MMetaDatabase as a base class. This base class contains the functions that allow the CommsDat API to notify tools and applicaions of changes to the database.

            Tables, records, links and fields are all elements. The classes that represent tables, records, links and fields have MMetaDatabase in their class hierearchy. You can use the CommsDat::MMetaDatabase::RequestNotification() function to register for notification of changes to the Comms Database. You can use the CommsDat::MMetaDatabase::CancelNotification() function to cancel a request for notification.

            \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5D831531-2430-4C61-B8C4-BEE9850387C2_d0e38281_href.png Binary file Symbian3/SDK/Source/GUID-5D831531-2430-4C61-B8C4-BEE9850387C2_d0e38281_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5D831531-2430-4C61-B8C4-BEE9850387C2_d0e43848_href.png Binary file Symbian3/SDK/Source/GUID-5D831531-2430-4C61-B8C4-BEE9850387C2_d0e43848_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5DB0F7C7-6132-552B-BA42-B47D267D1143_d0e19011_href.png Binary file Symbian3/SDK/Source/GUID-5DB0F7C7-6132-552B-BA42-B47D267D1143_d0e19011_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5DB0F7C7-6132-552B-BA42-B47D267D1143_d0e49355_href.png Binary file Symbian3/SDK/Source/GUID-5DB0F7C7-6132-552B-BA42-B47D267D1143_d0e49355_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5DB0F7C7-6132-552B-BA42-B47D267D1143_d0e54913_href.png Binary file Symbian3/SDK/Source/GUID-5DB0F7C7-6132-552B-BA42-B47D267D1143_d0e54913_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5E380880-9DBB-51D7-8942-829C6FD788C2_d0e281245_href.png Binary file Symbian3/SDK/Source/GUID-5E380880-9DBB-51D7-8942-829C6FD788C2_d0e281245_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5E380880-9DBB-51D7-8942-829C6FD788C2_d0e284931_href.png Binary file Symbian3/SDK/Source/GUID-5E380880-9DBB-51D7-8942-829C6FD788C2_d0e284931_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5E7FB4BD-DF3B-4F97-8394-5E1A6FF8D11B_d0e3219_href.png Binary file Symbian3/SDK/Source/GUID-5E7FB4BD-DF3B-4F97-8394-5E1A6FF8D11B_d0e3219_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5E7FB4BD-DF3B-4F97-8394-5E1A6FF8D11B_d0e4494_href.png Binary file Symbian3/SDK/Source/GUID-5E7FB4BD-DF3B-4F97-8394-5E1A6FF8D11B_d0e4494_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5E8AA6B6-38EB-5347-BA30-F9FF4BF7C107.dita --- a/Symbian3/SDK/Source/GUID-5E8AA6B6-38EB-5347-BA30-F9FF4BF7C107.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-5E8AA6B6-38EB-5347-BA30-F9FF4BF7C107.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,189 +1,189 @@ - - - - - -Index -

            Messaging Server maintains an index entry in memory. A copy of the index -entry of all message types is stored in the SQL database, so that it can be -restored in the event of a system reset or Messaging Server failure.

            -

            Some fields only apply to particular types of entry (such as messages or -services); other fields can be interpreted differently for different entry -types.

            -
            Operating with -the SQL database

            The SQL database is used to store each TMsvEntry (index -entry) as a row of an SQL table in the SQL database. It caches entries, and -maintains the most recently accessed entries in the RAM. Entries are cached -in the RAM, and are loaded only when required. The RAM usage is controlled -by emptying the oldest entry in the cache when it is full. For more information -on caching, see Caching. -The following illustration shows the architecture of the Message Server with -the SQL database.

            - Message Server architecture with the SQL database - - - Write operations like updating, creating and deleting entries -require disk operation to retrieve TMsvEntry from database, -because the entry cache is always in synchronisation with the corresponding -entry in the database.

            Advantages

            The following are -the advantages of using the SQL database to store index entries:

              -

            • Reduces the amount of -RAM used by messaging, as the message the index file is not used.

              • -

            • Enables more messages -to be stored on the device, as the number of messages stored is not restricted -to the amount of RAM available to store the message index file.

              • -

            • Enables controlled usage -of RAM, as index entries are loaded on a need basis.

              • -

            • Eliminates the possibility -of the message index file getting damaged and messages stored on the device -getting deleted.

              • -

            • Provides advanced search -and sort capabilities for searching messages.

              • -

            • Accesses and manages -message entries on one or more drives at the same time.

              • -
            -
            Index fields

            The -following information is stored for each index entry. Some fields only apply -to particular types of entry, such as, messages or services; other fields -can be interpreted differently for different entry types.

            - - - -

            Attachment flag

            -

            Indicates that the message has an attachment

            -             - -

            BIO

            -

            BIO message type

            -             - -

            Complete flag

            -

            Indicates that the message is complete (for example download has -completed.

            -             - -

            Connected flag

            -

            For a service: indicates whether it is currently connected to a -remote server

            -             - -

            Deleted flag

            -

            Indicates that the entry has been deleted. The entry is not removed -until any PC synchronisation tools have been informed of the deletion.

            -             - -

            Description

            -

            A text string, usually giving the subject of the message

            -             - -

            Details

            -

            A text string, as follows:

            Message: For received messages, -this is the sender; for outgoing messages, it is the recipient

            Attachment: -The name of the attachment

            Folder: The name of the folder

            Service: -The name of the service

            -             - -

            Error

            -

            A system-wide or MTM-specific error code

            -             - -

            Flag

            -

            Use

            -             - -

            Failed flag

            -

            For an outgoing message: indicates that sending failed

            -             - -

            Identifier

            -

            An integer that uniquely identifies the entry in the Index

            -             - -

            In preparation

            -

            Entry deleted if server restarts

            -             - -

            MTM

            -

            A unique identifier specifying the MTM associated with the entry

            -             - -

            MTM Data

            -

            Three integer fields for MTM-specific use

            -             - -

            Multiple Recipients flag

            -

            Indicates the message has multiple recipients that require separate -transmissions (for example, a fax going to two people)

            -             - -

            New flag

            -

            Indicates a new message in a folder

            -             - -

            Owner flag

            -

            Indicates that the entry owns other entries (that it is a parent)

            -             - -

            Parent

            -

            An integer giving the identifier of the entry’s parent

            -             - -

            Priority

            -

            An integer giving the message priority

            -             - -

            Read flag

            -

            Indicates that a message has been read

            -             - -

            Read Only flag

            -

            Indicates that the entry is read-only

            -             - -

            Related folder

            -

            The identifier of a target folder for copying or moving entries

            -             - -

            Sending state

            -

            Describes the state the message is in, for example "Sending", "Failed" -and "Sent"

            -             - -

            Service

            -

            The identifier of the service by which the message is to be sent -or from which it was received

            -             - -

            Size

            -

            An integer giving the size of the message

            -             - -

            Standard Folder flag

            -

            Identifies standard folders so that they can be properly sorted -and stops them being changed/deleted

            -             - -

            Time

            -

            The time when the message was last edited, sent, or received. Includes -date.

            -             - -

            Type

            -

            A unique identifier giving the type (service, folder, message, and -attachment) of the entry

            -             - -

            Visibility flag

            -

            Indicates the intended visibility of the entry to users of message -client applications

            -             - - -
            + + + + + +Index +

            Messaging Server maintains an index entry in memory. A copy of the index +entry of all message types is stored in the SQL database, so that it can be +restored in the event of a system reset or Messaging Server failure.

            +

            Some fields only apply to particular types of entry (such as messages or +services); other fields can be interpreted differently for different entry +types.

            +
            Operating with +the SQL database

            The SQL database is used to store each TMsvEntry (index +entry) as a row of an SQL table in the SQL database. It caches entries, and +maintains the most recently accessed entries in the RAM. Entries are cached +in the RAM, and are loaded only when required. The RAM usage is controlled +by emptying the oldest entry in the cache when it is full. For more information +on caching, see Caching. +The following illustration shows the architecture of the Message Server with +the SQL database.

            + Message Server architecture with the SQL database + + + Write operations like updating, creating and deleting entries +require disk operation to retrieve TMsvEntry from database, +because the entry cache is always in synchronisation with the corresponding +entry in the database.

            Advantages

            The following are +the advantages of using the SQL database to store index entries:

              +

            • Reduces the amount of +RAM used by messaging, as the message the index file is not used.

              • +

            • Enables more messages +to be stored on the device, as the number of messages stored is not restricted +to the amount of RAM available to store the message index file.

              • +

            • Enables controlled usage +of RAM, as index entries are loaded on a need basis.

              • +

            • Eliminates the possibility +of the message index file getting damaged and messages stored on the device +getting deleted.

              • +

            • Provides advanced search +and sort capabilities for searching messages.

              • +

            • Accesses and manages +message entries on one or more drives at the same time.

              • +
            +
            Index fields

            The +following information is stored for each index entry. Some fields only apply +to particular types of entry, such as, messages or services; other fields +can be interpreted differently for different entry types.

            + + + +

            Attachment flag

            +

            Indicates that the message has an attachment

            +             + +

            BIO

            +

            BIO message type

            +             + +

            Complete flag

            +

            Indicates that the message is complete (for example download has +completed.

            +             + +

            Connected flag

            +

            For a service: indicates whether it is currently connected to a +remote server

            +             + +

            Deleted flag

            +

            Indicates that the entry has been deleted. The entry is not removed +until any PC synchronisation tools have been informed of the deletion.

            +             + +

            Description

            +

            A text string, usually giving the subject of the message

            +             + +

            Details

            +

            A text string, as follows:

            Message: For received messages, +this is the sender; for outgoing messages, it is the recipient

            Attachment: +The name of the attachment

            Folder: The name of the folder

            Service: +The name of the service

            +             + +

            Error

            +

            A system-wide or MTM-specific error code

            +             + +

            Flag

            +

            Use

            +             + +

            Failed flag

            +

            For an outgoing message: indicates that sending failed

            +             + +

            Identifier

            +

            An integer that uniquely identifies the entry in the Index

            +             + +

            In preparation

            +

            Entry deleted if server restarts

            +             + +

            MTM

            +

            A unique identifier specifying the MTM associated with the entry

            +             + +

            MTM Data

            +

            Three integer fields for MTM-specific use

            +             + +

            Multiple Recipients flag

            +

            Indicates the message has multiple recipients that require separate +transmissions (for example, a fax going to two people)

            +             + +

            New flag

            +

            Indicates a new message in a folder

            +             + +

            Owner flag

            +

            Indicates that the entry owns other entries (that it is a parent)

            +             + +

            Parent

            +

            An integer giving the identifier of the entry’s parent

            +             + +

            Priority

            +

            An integer giving the message priority

            +             + +

            Read flag

            +

            Indicates that a message has been read

            +             + +

            Read Only flag

            +

            Indicates that the entry is read-only

            +             + +

            Related folder

            +

            The identifier of a target folder for copying or moving entries

            +             + +

            Sending state

            +

            Describes the state the message is in, for example "Sending", "Failed" +and "Sent"

            +             + +

            Service

            +

            The identifier of the service by which the message is to be sent +or from which it was received

            +             + +

            Size

            +

            An integer giving the size of the message

            +             + +

            Standard Folder flag

            +

            Identifies standard folders so that they can be properly sorted +and stops them being changed/deleted

            +             + +

            Time

            +

            The time when the message was last edited, sent, or received. Includes +date.

            +             + +

            Type

            +

            A unique identifier giving the type (service, folder, message, and +attachment) of the entry

            +             + +

            Visibility flag

            +

            Indicates the intended visibility of the entry to users of message +client applications

            +             + + +
             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5E8C5D5C-8B84-4126-A8A8-F61F7DA0AD32_d0e65812_href.png Binary file Symbian3/SDK/Source/GUID-5E8C5D5C-8B84-4126-A8A8-F61F7DA0AD32_d0e65812_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5F4510C9-5B16-593A-A225-37606800915B.dita --- a/Symbian3/SDK/Source/GUID-5F4510C9-5B16-593A-A225-37606800915B.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-5F4510C9-5B16-593A-A225-37606800915B.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,32 +1,32 @@ - - - - - -Controlling Video Playback

            This tutorial describes how to control video playback.

            Purpose

            The purpose of this tutorial is to show you how to use the video player to control video playback.

            Required Background

            The Video Client Overview introduces the video client utilities.

            Introduction

            The video player utility is used to open, play, and obtain information from sampled video data. This functionality is implemented by the CVideoPlayerUtility class. The video data can be supplied either in a file, a descriptor or a URL.

            The sequence diagram below explains the different functionalities of the Video Player Utility:

            - Video Player sequence diagram -
            Using Video Player

            The following tasks will be covered in this tutorial:

            • Play Video Clips

            • Get Current Frame

            Playing Video Clips

            The high level steps to play video clips are shown here:

            1. After configuring the properties, the CVideoPlayerUtility::Play() function is called for the video clip to be played.

            2. The play can be paused for a small duration using CVideoPlayerUtility::PauseL() and later resumed by calling CVideoPlayerUtility::Play() function once again.

            3. To halt the video play CVideoPlayerUtility::Stop() is called.

            4. In order to unload all related controllers and return, use CVideoPlayerUtility::Close().

            These high level steps are shown in the following example code:

            void CPlayVideo::Play() //Starts playback of the video clip - { - iVideoUtility->Play(); - } - -void CPlayVideo::PauseL() //Call to this function will maintain the current position - //playback can be resumed by calling Play function again - { - TRAPD(err,iVideoUtility->PauseL()); - } - -TInt CPlayVideo::Stop() //Stops playing - { - TInt err = iVideoUtility->Stop(); - return err; - }

            Note: You must call the CVideoPlayerUtility::Prepare() function, before calling any of the functions used in the above given code.

            Getting the Current Frame

            The high level steps to get the current frame are shown here:

            1. To get the video frame currently being played, use the CVideoPlayerUtility::GetFrameL() function.

              void CPlayVideo::GetFrameL(TDisplayMode aDisplayMode) //Returns the current frame - { - iVideoUtility->GetFrameL(aDisplayMode); + + + + + +Controlling Video Playback

              This tutorial describes how to control video playback.

              Purpose

              The purpose of this tutorial is to show you how to use the video player to control video playback.

              Required Background

              The Video Client Overview introduces the video client utilities.

              Introduction

              The video player utility is used to open, play, and obtain information from sampled video data. This functionality is implemented by the CVideoPlayerUtility class. The video data can be supplied either in a file, a descriptor or a URL.

              The sequence diagram below explains the different functionalities of the Video Player Utility:

              + Video Player sequence diagram +
              Using Video Player

              The following tasks will be covered in this tutorial:

              • Play Video Clips

              • Get Current Frame

              Playing Video Clips

              The high level steps to play video clips are shown here:

              1. After configuring the properties, the CVideoPlayerUtility::Play() function is called for the video clip to be played.

              2. The play can be paused for a small duration using CVideoPlayerUtility::PauseL() and later resumed by calling CVideoPlayerUtility::Play() function once again.

              3. To halt the video play CVideoPlayerUtility::Stop() is called.

              4. In order to unload all related controllers and return, use CVideoPlayerUtility::Close().

              These high level steps are shown in the following example code:

              void CPlayVideo::Play() //Starts playback of the video clip + { + iVideoUtility->Play(); + } + +void CPlayVideo::PauseL() //Call to this function will maintain the current position + //playback can be resumed by calling Play function again + { + TRAPD(err,iVideoUtility->PauseL()); + } + +TInt CPlayVideo::Stop() //Stops playing + { + TInt err = iVideoUtility->Stop(); + return err; + }

              Note: You must call the CVideoPlayerUtility::Prepare() function, before calling any of the functions used in the above given code.

              Getting the Current Frame

              The high level steps to get the current frame are shown here:

              1. To get the video frame currently being played, use the CVideoPlayerUtility::GetFrameL() function.

                void CPlayVideo::GetFrameL(TDisplayMode aDisplayMode) //Returns the current frame + { + iVideoUtility->GetFrameL(aDisplayMode); }

              2. The current frame is sent to the client asynchronously via the MVideoPlayerUtilityObserver::MvpuoFrameReady() callback function.

              See Also

              Creating and Preparing a Video Player

              Configuring the Video Player

              Enabling/Disabling Audio or Video Playback Separately

              Scaling Automatically

              Fast Forwarding and Rewinding

              Stepping Frames

              Controlling the Video Controller Plugin

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5F72210C-1636-584D-9D89-987D25136975-master.png Binary file Symbian3/SDK/Source/GUID-5F72210C-1636-584D-9D89-987D25136975-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5F72210C-1636-584D-9D89-987D25136975_d0e382613_href.png Binary file Symbian3/SDK/Source/GUID-5F72210C-1636-584D-9D89-987D25136975_d0e382613_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5FE10ECA-1FAB-4E4F-A1D9-67D379EE8CB3_d0e290304_href.png Binary file Symbian3/SDK/Source/GUID-5FE10ECA-1FAB-4E4F-A1D9-67D379EE8CB3_d0e290304_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-5FE10ECA-1FAB-4E4F-A1D9-67D379EE8CB3_d0e293561_href.png Binary file Symbian3/SDK/Source/GUID-5FE10ECA-1FAB-4E4F-A1D9-67D379EE8CB3_d0e293561_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6006AAB0-B319-546F-8D79-E2D4887A1E72.dita --- a/Symbian3/SDK/Source/GUID-6006AAB0-B319-546F-8D79-E2D4887A1E72.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-6006AAB0-B319-546F-8D79-E2D4887A1E72.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,35 +1,35 @@ - - - - - -Singly -linked listsA singly linked list is one where each element points forwards -to the next element. -

              Unlike a doubly linked list, elements do not point back to the previous -element. The list has an anchor point which points forwards to the first element -and also has a pointer to the last element.

              -

              Anchor points are always referred to as headers.

              -

              A singly linked list is useful for maintaining a non-circular queue of -items; for example, a stack.

              - -Singly linked list - - -

              Singly linked lists involve the creation and use of the classes:

              -
                -

              • TSglQueLink

                • -

              • TSglQue<class -T>

                • -

              • TSglQueIter<class -T

                • -
              -

              In practice, these classes are almost always used as components of other -classes.

              + + + + + +Singly +linked listsA singly linked list is one where each element points forwards +to the next element. +

              Unlike a doubly linked list, elements do not point back to the previous +element. The list has an anchor point which points forwards to the first element +and also has a pointer to the last element.

              +

              Anchor points are always referred to as headers.

              +

              A singly linked list is useful for maintaining a non-circular queue of +items; for example, a stack.

              + +Singly linked list + + +

              Singly linked lists involve the creation and use of the classes:

              +
                +

              • TSglQueLink

                • +

              • TSglQue<class +T>

                • +

              • TSglQueIter<class +T

                • +
              +

              In practice, these classes are almost always used as components of other +classes.

               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-600DCD27-ADC0-40D7-B061-1D44238363BA_d0e128297_href.png Binary file Symbian3/SDK/Source/GUID-600DCD27-ADC0-40D7-B061-1D44238363BA_d0e128297_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-600DCD27-ADC0-40D7-B061-1D44238363BA_d0e134835_href.png Binary file Symbian3/SDK/Source/GUID-600DCD27-ADC0-40D7-B061-1D44238363BA_d0e134835_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6067DF61-D32F-4029-ADCD-9E69CA564212.dita --- a/Symbian3/SDK/Source/GUID-6067DF61-D32F-4029-ADCD-9E69CA564212.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,46 +0,0 @@ - - - - - -Key -presses -

              A key press is a press and release of a key (down and up).

              -

              Typically, the primary action of the key is performed when the key is pressed -down, already before the key is released (there may be exceptions to this -rule; see Typical functions -of the standard keys for an example).

              -

              Some functions depend on the length of the key press:

              -
                -

              • In a short press, the key is held down for less than 0.6 seconds (please -note that this time-out value may depend on the product implementation). If -the key is held down longer, the result is a long key press.

                • -

              • If the pressed key (in the given context) has functions for both a -short and long press, the short key press action is performed first at the -moment when the key is pressed down. If the key press is long, then the long -key press action is performed. In the case of the Home / Menu key and the -Edit key, the interaction is different, causing the action on the key release -event.

                • -

              • Certain keys, possibly in certain contexts only, may perform key repeat. -Key repeat starts after the long key press time-out when the key is continuously -being held down, and the associated function is performed according to the -key repeat frequency. For example, in scrolling within lists and text editors, -these frequencies are by default 6 times/second for vertical and 10 times/second -for horizontal scrolling (the repeat frequency may be product or application -specific).

                • -

              • Long key press actions and key repeat actions are not defined at the -same time; only one can occur in the given context.

                • -

              • The primary key press action should not be conflicting with the long -key press action or key repeat action.

                • -
              - With certain input hardware (for example, Roller), long -key presses and key repeat may not be possible. The long key press actions -and key repeat actions should be designed so that this does not cause harm: -the long key press must never be the only way to perform a function -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-60B4CDBE-B863-52EA-9125-632A1FF1A059_d0e396128_href.png Binary file Symbian3/SDK/Source/GUID-60B4CDBE-B863-52EA-9125-632A1FF1A059_d0e396128_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-60B4CDBE-B863-52EA-9125-632A1FF1A059_d0e396290_href.png Binary file Symbian3/SDK/Source/GUID-60B4CDBE-B863-52EA-9125-632A1FF1A059_d0e396290_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-60B9404B-5102-4FBB-A32F-55F2ACFD1481.dita --- a/Symbian3/SDK/Source/GUID-60B9404B-5102-4FBB-A32F-55F2ACFD1481.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-60B9404B-5102-4FBB-A32F-55F2ACFD1481.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,83 +1,83 @@ - - - - - -GStreamer -OverviewGStreamer is a development framework for creating applications -like media players, streaming media broadcasters and video editors. -

              GStreamer is designed to make it easier to write applications easily that -handle audio, video, or both. Pluggable components can be mixed and matched -into arbitrary pipelines, which consist of a chain of processing elements.

              -
              Purpose

              GStreamer is an open -source multimedia framework that allows you to write any streaming multimedia -application, not just audio or video. GStreamer can handle any data flow.

              GStreamer -core provides the following features:

                -

              • Plug-in handling

                • -

              • Media type negotiation

                • -

              • Clocking and data flow

                • -
              GStreamer also provides APIs to write applications using various plug-ins -such as source plug-in, transform plug-in and sink plug-in. The framework -uses these plug-ins to perform various roles such as encoding, decoding and -media processing.

              -GStreamer plug-ins - -

              -
              Description

              Some -GStreamer concepts are as follows:

                -

              • Element

                An element is an object that performs some action -on a multimedia stream. Examples of such actions are reading a file, decoding -or encoding data and capturing data from a hardware device.

                • -

              • Bin

                A bin is a subclass of element. A bin acts as a container -for other elements, so multiple elements combine into one logical unit.

                • -

              • Pipeline

                A pipeline is a set of data processing elements -connected in series, so the output from one element is the input for the next -element.

                In GStreamer the pipeline is a specialized bin subclass that -provides execution of all contained elements. Normally, applications create -one pipeline that will manage all the elements contained within it.

                • -

              Note: Elements can be added to and removed from pipelines -based on the use-case being handled. For example a use-case such as playing -an MP3 file using GStreamer.

              An element can provide a number -of pads, which can be either source or sink pads. A pad is a plug or port -on an element to link with other elements. The pads are responsible for data -flow between the elements. Source pads supply data, and sink pads consume -data. Basically, pads are used to negotiate compatibility and allow data flow -between elements.

              An element can be in one of four different states -during the application request:

                -

              • Null

                • -

              • Ready

                • -

              • Pause

                • -

              • Play

                • -
              In the Null and Ready states, the element is not processing -any data. The processing of data happens only in the Play state. The Pause state -is used to fill all connected elements in the data pipeline so the Play state -change happens quickly.

              GStreamer also provides higher level utilities -and components to detect automatically the media type of an application, and -to create the best possible pipeline for a use-case. This process is called -auto plugging.

              -
              GStreamer applications

              GStreamer -is used in many types of applications including:

                -

              1. Media playback and streaming

                2. -

              2. Media recording

                3. -

              3. Media transcoding

                4. -

              4. Video editing

                5. -

              For example the diagram below shows how a Media Player uses GStreamer:

              -Media playback using GStreamer - -

              Sound device is a framework -to perform hardware accelerated audio functionality. Audio Policy manages -the requests to access the audio hardware. Digital Signal Processing converts -the digital audio signal to the analog audio signal.

              -
              See also
                -

              • GStreamer documentation -published on Forum Nokia.

                • -

              • Multimedia Framework -Component

                • -
              + + + + + +GStreamer +OverviewGStreamer is a development framework for creating applications +like media players, streaming media broadcasters and video editors. +

              GStreamer is designed to make it easier to write applications easily that +handle audio, video, or both. Pluggable components can be mixed and matched +into arbitrary pipelines, which consist of a chain of processing elements.

              +
              Purpose

              GStreamer is an open +source multimedia framework that allows you to write any streaming multimedia +application, not just audio or video. GStreamer can handle any data flow.

              GStreamer +core provides the following features:

                +

              • Plug-in handling

                • +

              • Media type negotiation

                • +

              • Clocking and data flow

                • +
              GStreamer also provides APIs to write applications using various plug-ins +such as source plug-in, transform plug-in and sink plug-in. The framework +uses these plug-ins to perform various roles such as encoding, decoding and +media processing.

              +GStreamer plug-ins + +

              +
              Description

              Some +GStreamer concepts are as follows:

                +

              • Element

                An element is an object that performs some action +on a multimedia stream. Examples of such actions are reading a file, decoding +or encoding data and capturing data from a hardware device.

                • +

              • Bin

                A bin is a subclass of element. A bin acts as a container +for other elements, so multiple elements combine into one logical unit.

                • +

              • Pipeline

                A pipeline is a set of data processing elements +connected in series, so the output from one element is the input for the next +element.

                In GStreamer the pipeline is a specialized bin subclass that +provides execution of all contained elements. Normally, applications create +one pipeline that will manage all the elements contained within it.

                • +

              Note: Elements can be added to and removed from pipelines +based on the use-case being handled. For example a use-case such as playing +an MP3 file using GStreamer.

              An element can provide a number +of pads, which can be either source or sink pads. A pad is a plug or port +on an element to link with other elements. The pads are responsible for data +flow between the elements. Source pads supply data, and sink pads consume +data. Basically, pads are used to negotiate compatibility and allow data flow +between elements.

              An element can be in one of four different states +during the application request:

                +

              • Null

                • +

              • Ready

                • +

              • Pause

                • +

              • Play

                • +
              In the Null and Ready states, the element is not processing +any data. The processing of data happens only in the Play state. The Pause state +is used to fill all connected elements in the data pipeline so the Play state +change happens quickly.

              GStreamer also provides higher level utilities +and components to detect automatically the media type of an application, and +to create the best possible pipeline for a use-case. This process is called +auto plugging.

              +
              GStreamer applications

              GStreamer +is used in many types of applications including:

                +

              1. Media playback and streaming

                2. +

              2. Media recording

                3. +

              3. Media transcoding

                4. +

              4. Video editing

                5. +

              For example the diagram below shows how a Media Player uses GStreamer:

              +Media playback using GStreamer + +

              Sound device is a framework +to perform hardware accelerated audio functionality. Audio Policy manages +the requests to access the audio hardware. Digital Signal Processing converts +the digital audio signal to the analog audio signal.

              +
              See also
                +

              • GStreamer documentation +published on Forum Nokia.

                • +

              • Multimedia Framework +Component

                • +
               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-60B979FB-43BD-480E-8E17-1D3DA2002CB1.dita --- a/Symbian3/SDK/Source/GUID-60B979FB-43BD-480E-8E17-1D3DA2002CB1.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-60B979FB-43BD-480E-8E17-1D3DA2002CB1.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,142 +1,142 @@ - - - - - -Slider -pop-up -

              The Slider pop-up component can be used for situations where a value is -changed with a slider, for example when changing zoom or volume level. The -common Slider pop-up component has a set of elements from which to select -and modify the slider in question, for example, value ranges, whether to have -current value as text included, or additional icons related to the slider.

              -

              For application specific slider pop-up the application may define ways -to open the pop-up. For common pop-up such as Volume Control, ways to open -the pop-up are defined. The Slider pop-up has default time-out after which -it disappears, but for good reason this time-out can be overridden by the -application.

              -

              Instead of using the pop-up, the application may define the slider to be -always visible (fixed in the layout). If slider is fixed in the layout, the -pop-up is not shown.

              -

              The orientation of the slider pop-up can be either horizontal or vertical. -The orientation and location are always the same across applications, unless -application uses the slider as fixed in the layout. Value growth direction -in Slider is always either up or right depending on the Slider orientation -in the UI.

              -Default touch -events for the Slider pop-up - - - -

              User action

               -

              State change

               -

              Feedback

               -               - - - -

              Touch down (on slider)

               -

              Slider thumb is moved to the nearest slider step position on the -slider. Value is changed accordingly.

              If touch down event is performed -in the middle of two slider step positions, the slider thumb is moved towards -the greater (larger) value.

               -

              Tactile: No touch down effect. Sensitive slider effect and audio -feedback is provided when the thumb moves.

               -               - -

              Touch down (on slider thumb)

               -

              Slider thumb is activated and can be moved.

               -

              Tactile: Sensitive slider effect is provided with touch down.

               -               - -

              Touch release

               -

              No effect

               -

              Tactile: Sensitive slider effect is provided with the touch release -(on slider thumb).

               -               - -

              Touch down and hold (on slider)

               -

              Moves the thumb step by step to the place where touched down.

               -

              Tactile: Hold slider effect is given with long touch on the slider. -Effect is bound to the steps. If there are more than 15 steps, then smooth -slider effect is given instead.

               -               - -

              Touch down and hold (on slider thumb)

               -

              Inactive

               -

              Tactile: No effect

               -               - -

              Touch down and move

               -

              Slider thumb is moved along with the touch event. It moves step -by step via its possible positions. Value is changing accordingly.

              If -touch release in the middle of two slider step positions, the slider thumb -is moved towards the greater (larger) value.

              The slider control -area is the entire main pane area.

               -

              Tactile: Smooth slider effect is provide when dragging from the -thumb.

              Smooth feedback can be increasing and decreasing when there -is a meaning to use this kind of feature, for example, in volume and zoom -slider.

               -               - -

              Touch down and cancel (slider thumb)

               -

              Slider thumb is moved to the nearest slider step position where -it was when the touch left the slider control area.

               -

              Tactile: No feedback is provide with touch release after drag outside.

               -               - - -
              -

              -Default touch -events for the Minus / Plus indicators. - - - -

              User action

               -

              State change

               -

              Feedback

               -               - - - -

              Touch down

               -

              Slider thumb moves either up or down. Direction depends on which -indicator has been touched.

               -

              Tactile: Sensitive button effect and audio feedback is provided -with the touch down event.

               -               - -

              Touch down and hold (keep touch down)

               -

              This action performs a “key repeat”, similar to many single touch -down and release on the indicator.

               -

              Tactile: Sensitive button effect provided with steps.

               -               - -

              Touch release

               -

              Slider thumb stops in its position

               -

              Tactile: Sensitive button effect given with touch release event.

               -               - -

              Touch down and move outside and release the control area

               -

              Slider’s thumb remains in the position, where it was, before moving -out of both pop-up and indicator area.

               -

              Tactile: No effect

               -               - - -
              -

              Using -slider pop-ups in C++ applications

              The API to use for the slider -pop-up is the Slider API.

              To use a slider pop-up in your application, -create an instance of the class CAknSlider.

              Use the method CAknSlider::SetValueL() to set the slider handle's position. -To set the range of acceptable values, use the method CAknSlider::SetRange(). To set the step size, use -the method CAknSlider::SetStepSize().

              To set the texts for the minimum and maximum values, use the -methods CAknSlider::SetMinimumTextL() and CAknSlider::SetMaximumTextL().

              To enable drag events in the slider, use the method CAknSlider::EnableDrag()

              To use a custom graphic in your slider component, use the method CAknSlider::SetGraphics().

              + + + + + +Slider +pop-up +

              The Slider pop-up component can be used for situations where a value is +changed with a slider, for example when changing zoom or volume level. The +common Slider pop-up component has a set of elements from which to select +and modify the slider in question, for example, value ranges, whether to have +current value as text included, or additional icons related to the slider.

              +

              For application specific slider pop-up the application may define ways +to open the pop-up. For common pop-up such as Volume Control, ways to open +the pop-up are defined. The Slider pop-up has default time-out after which +it disappears, but for good reason this time-out can be overridden by the +application.

              +

              Instead of using the pop-up, the application may define the slider to be +always visible (fixed in the layout). If slider is fixed in the layout, the +pop-up is not shown.

              +

              The orientation of the slider pop-up can be either horizontal or vertical. +The orientation and location are always the same across applications, unless +application uses the slider as fixed in the layout. Value growth direction +in Slider is always either up or right depending on the Slider orientation +in the UI.

              +Default touch +events for the Slider pop-up + + + +

              User action

               +

              State change

               +

              Feedback

               +               + + + +

              Touch down (on slider)

               +

              Slider thumb is moved to the nearest slider step position on the +slider. Value is changed accordingly.

              If touch down event is performed +in the middle of two slider step positions, the slider thumb is moved towards +the greater (larger) value.

               +

              Tactile: No touch down effect. Sensitive slider effect and audio +feedback is provided when the thumb moves.

               +               + +

              Touch down (on slider thumb)

               +

              Slider thumb is activated and can be moved.

               +

              Tactile: Sensitive slider effect is provided with touch down.

               +               + +

              Touch release

               +

              No effect

               +

              Tactile: Sensitive slider effect is provided with the touch release +(on slider thumb).

               +               + +

              Touch down and hold (on slider)

               +

              Moves the thumb step by step to the place where touched down.

               +

              Tactile: Hold slider effect is given with long touch on the slider. +Effect is bound to the steps. If there are more than 15 steps, then smooth +slider effect is given instead.

               +               + +

              Touch down and hold (on slider thumb)

               +

              Inactive

               +

              Tactile: No effect

               +               + +

              Touch down and move

               +

              Slider thumb is moved along with the touch event. It moves step +by step via its possible positions. Value is changing accordingly.

              If +touch release in the middle of two slider step positions, the slider thumb +is moved towards the greater (larger) value.

              The slider control +area is the entire main pane area.

               +

              Tactile: Smooth slider effect is provide when dragging from the +thumb.

              Smooth feedback can be increasing and decreasing when there +is a meaning to use this kind of feature, for example, in volume and zoom +slider.

               +               + +

              Touch down and cancel (slider thumb)

               +

              Slider thumb is moved to the nearest slider step position where +it was when the touch left the slider control area.

               +

              Tactile: No feedback is provide with touch release after drag outside.

               +               + + +
              +

              +Default touch +events for the Minus / Plus indicators. + + + +

              User action

               +

              State change

               +

              Feedback

               +               + + + +

              Touch down

               +

              Slider thumb moves either up or down. Direction depends on which +indicator has been touched.

               +

              Tactile: Sensitive button effect and audio feedback is provided +with the touch down event.

               +               + +

              Touch down and hold (keep touch down)

               +

              This action performs a “key repeat”, similar to many single touch +down and release on the indicator.

               +

              Tactile: Sensitive button effect provided with steps.

               +               + +

              Touch release

               +

              Slider thumb stops in its position

               +

              Tactile: Sensitive button effect given with touch release event.

               +               + +

              Touch down and move outside and release the control area

               +

              Slider’s thumb remains in the position, where it was, before moving +out of both pop-up and indicator area.

               +

              Tactile: No effect

               +               + + +
              +

              Using +slider pop-ups in applications

              The API to use for the +slider pop-up is the Slider API.

              To use a slider pop-up in your application, +create an instance of the class CAknSlider.

              Use the method CAknSlider::SetValueL() to set the slider handle's position. +To set the range of acceptable values, use the method CAknSlider::SetRange(). To set the step size, use +the method CAknSlider::SetStepSize().

              To set the texts for the minimum and maximum values, use the +methods CAknSlider::SetMinimumTextL() and CAknSlider::SetMaximumTextL().

              To enable drag events in the slider, use the method CAknSlider::EnableDrag()

              To use a custom graphic in your slider component, use the method CAknSlider::SetGraphics().

               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-60DBA025-8FA0-5DF2-90D0-744A016998EE.dita --- a/Symbian3/SDK/Source/GUID-60DBA025-8FA0-5DF2-90D0-744A016998EE.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-60DBA025-8FA0-5DF2-90D0-744A016998EE.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,351 +1,351 @@ - - - - - -Panoramic -Stitching Guide -

              This document introduces you to the panoramic stitching functionality.

              -
              Purpose

              Panoramic -stitching involves combining a collection of images into a single image.

              -
              Panoramic stitching overview

              The panorama image -is created by stitching a collection of several separate image into one large -image. The panoramic stitching process is done by,

                -

              • image registration

                • -

              • cylindrical projection -of images

                • -

              • image blending.

                • -

              The panoramic stitch can be done eihter interactively by using camera -viewfinder, for tracking the camera movements or by stitching pre-captured -images together.

              Introduction -about the panoramic stitching

              The CImagePanorama stitches -a set of images into a single panorama image. The input to CImagePanorama is -a collection of high resolution images together with some guidance on the -relative positioning between the images expressed by CPanoramaTransform instances.

              For -the panorama creation, the most common use is rendering a full size panorama -image to the device file system.

              The high level steps to use CImagePanorama are -shown below:

                -

              • To construct CImagePanorama, -use CImagePanorama::NewL() which loads the image panorama -plugin.

                • -

              • To initialise CImagePanorama, -use CImagePanorama::InitialiseL().

                • -

              • To correct the lens -parameter use TPanoramaLens. You need to correct the lens -for panorama stitching quality. The lens parameters are camera specific.

                • -

              • To add images to CImagePanorama, -use CImagePanorama::AddFileL(),CImagePanorama::AddBufferL() or CImagePanorama::AddImageL(), providing a hint on relative positioning or translation of the images through CPanoramaTransform. -This transform only needs to be approximate.

                • -

              • To make the stitched -image available call CImagePanorama::RenderL().

                • -

              • The CImagePanorama instance -can then be deleted.

                • -

              Introduction -about the CVFTracker

              CVFTracker is used to -track viewfinder images to aid in capturing a panorama. The usage of CVFTracker are -demonstrated as follows:

                -

              • The CVFTracker output -is used for providing feedback and guidance to you, on how to move the camera -while capturing a panorama.

                • -

              • The CVFTracker is -used as an aid for the stitching process in the CImagePanorama. -The input to the CVFTracker is a rapid flow of raw images -from the viewfinder of the camera. The output is the movement of the camera.

                • -

              The high level steps to use the CVFTracker are -shown below:

                -

              • To create CVFTracker, -use the CVFTracker::NewL(). The CVFTracker::NewL() is -used to load the CVFTracker plugin.

                • -

              • To initialise CVFTracker, -use CVFTracker::InitialiseL().

                • -

              • To reset CVFTracker, -use CVFTracker::Reset().

                • -

              • To perform the image -registration, use CVFTracker::RegisterImageL().

                • -

              • To destroy the CVFTracker, -use CVFTracker::~CVFTracker().

                • -

              Camera -requirements

              The camera requirements for the CImagePanorama and CVFTracker are -as follows,

                -

              • The camera must provide -low resolution images (in the order of 160 by 120 up to 320 by 240 resolution) -as the raw format at a high frame rate to the CVFTracker and -high resolution captured images to the CImagePanorama.

                • -

              • For the CVFTracker, -it is better to have good frame rate than to have high resolution input images.

                • -

              • The use of large CVFTracker images -can cause a lower frame rate on slow devices, and do not give accurate tracking -for the view finder.

                • -

              • The optimal size of -images is a tradeoff between the panorama quality and the time for rendering -the panorama.

                • -
              -
              How to use Panoramic Stitching

              This section contains -some code snippets to show, how Panoramic stitching is accessed in several -situations.

              Basic -stitching

              The basic stitching is demonstrated by a simple example -of stitching four JPEG images into a single JPEG image providing an approximate -translation between each image:

              - - TSize imageSize(1200, 1000); - - TDirection direction = EPanoramaDirectionRight; - - //Lens parameters or internal camera characteristics should be available for the - //specific camera module in use. Here we use default values. - TPanoramaLens lens; - - //Create transform. A transform is an approximate offset between each image. - CPanoramaTransform* panTrans = CPanoramaTransform::NewL(); - CleanupStack::PushL(panTrans); - - //Create panorama object.This stitches the individual images together. - CImagePanorama* panImage = CImagePanorama::NewL(); - CleanupStack::PushL(panImage); - - //Create panorama engine and set the lens and size - panImage->InitializeL(imageSize, lens, direction); - - //Each file added is provided with an approximate translation. - //In this case there are 4 images. - panTrans->SetTranslationL(TPoint(0, 0), imageSize); - panImage->AddFileL(KTestFileName1, *panTrans); - - panTrans->SetTranslationL(TPoint(900, -30), imageSize); - panImage->AddFileL(KTestFileName2, *panTrans); - - panTrans->SetTranslationL(TPoint(900, 60), imageSize); - panImage->AddFileL(KTestFileName3, *panTrans); - - panTrans->SetTranslationL(TPoint(400, -30), imageSize); - panImage->AddFileL(KTestFileName4, *panTrans); - - //The image size can be obtained before rendering (if required) - TSize size; - panImage->CurrentImageSizeL(size); - - //view the output image - panImage->RenderL(KTestBSOutputFileName); - - CleanupStack::PopAndDestroy(2); //panTrans, panImage - -

              The main steps for using CImagePanorama are -as follows,

                -

              1. create CImagePanorama

                2. -

              2. some approximate transform -information for each image pair

                3. -

              3. add each images to CImagePanorama

                4. -

              4. render the output (for -example to the file)

                5. -

              5. delete the objects used.

                6. -

              Note: The following points must be noted by you:

                -

              • The lens parameters -are not resolution dependant. It is enough to calibrate once for each camera -model and no need to recalibrate for each resolution. For best accuracy, use -the highest resolution possible when calibrating with a calibration tool.

                The -approximate translations in x co-ordinate and y co-ordinate ( as dx, dy) must -be compliant with the value of direction.

                • -

              A -camera application example

              The CImagePanorama is -used in a camera application. The example is more complicated than the previous -example. In this example CVFTracker provides the approximate -transform between the captured images.

              Viewfinder -image tracking

              The CImagePanorama generates -panorama images. The application starts the process and then use the camera -for capturing the images. The CVFTracker will give an indication -when to capture the high resolution images, which will later be stitched into -a panorama image.

              The CVFTracker plays an important -role for getting the camera movement. The high level steps to use the CVFTracker in -the CImagePanorama for a camera application, are shown -below:

                -

              1. To create the CVFTracker object -and load the CVFTracker plugin, use CVFTracker::NewL().

                2. -

              2. To create CImagePanorama object -and load the CImagePanorama plugin, use CImagePanorama::NewL().

                3. -

              3. To create the CPanoramaTransform object -and set or get the values, use the CPanoramaTransform::NewL().

                4. -

              4. To create and set the CVFTracker, CImagePanorama, -and CPanoramaTransform functions for the Image Processor -Adaptation Plug-in objects, use CVFTracker::InitialiseL() and CImagePanorama::InitialiseL() respectively.

                5. -

              5. To get a translation -value from a viewfinder image, register an image by using CVFTracker::RegisterImageL(). -This will return translation information as a CPanoramaTransform object.

                6. -

              6. Check the right time -to capture the next image by using CVFTracker::IsTimeToCapture().

                7. -

              7. Reset the CVFTracker for -the next image, using CVFTracker::Reset().

                In order -to capture many images to be stitched into a single panorama image, repeat -the steps 5, 6 and 7.

                8. -
              - -

              Panorama -stitching

              The CVFTracker helps to decide when -to capture each of the full resolution images using the camera. The images -can then be passed to CImagePanorama and the stitching is done. The high level -steps to do panorama stitching are listed below:

                -

              1. Capture the next image -using the camera, then add the image to the CImagePanorama by -using CImagePanorama::AddImageL() or CImagePanorama::AddFileL, -passing in the CPanoramaTransform object obtained from -the CVFTracker.

                2. -

              2. When all images have -been captured you can render the stitched image to file, image buffer, CFbsBitmap -or image frame using CImagePanorama::RenderL().

                3. -
              - -

              User Interface

              Provide a good user interface (UI) application -for the CImagePanorama is crucial. An example of UI design -is described below, which gives you a robust and easy application for generating -panorama images.

              How -to shoot a panorama

              The steps to be followed for shooting a panorama -images:

                -

              1. You need to press the -start button of the camera and need to sweep the camera towards the wanted -scene.

                Note: You must try not to move the mobile phone, but -only rotate it. You see in the below diagram the camera is sweep in a clockwise -direction from left-to-right. The rotation is made around the imagined axis -through mobile (axis of rotation in the image). A panorama image covers approximately -a 100 degree field of view.

                - -
                2. -

              2. Application Start

                When -you launch the application the UI appears as shown in the below diagram.

                - -

                Here the screen area shows the viewfinder image. When you sweep -the mobile, several images are captured and then the images are stitched to -create a panorama image.

                3. -

              3. Capture a panorama -image during tracking

                When you choose to capture a panorama image -the UI changes, which is shown in the below diagram.

                - -

                In the above diagram you see three different boxes named 1, 2 and -3 which represent the position of the camera. The blue box representation -changes according to the rotation of the mobile phone.

                The boxes shown -in the above diagram is for illustrative purpose, so that it can be down scaled -for viewfinder image size. The total panorama coverage area box is estimated -by the number of images for capturing and the overlapping area size.

                The -code snippets below shows the CVFTracker tracking.

                - - _LIT(KFileOutput, "c:\\ICLExample\\viewfinder%d.mbm"); - _LIT(KFileCapturedImage, "c:\\ICLExample\\pancapture%d.jpg"); - TInt i = 0; - - TSize imageSize(1200,1000); - CFbsBitmap* bmp = new (ELeave) CFbsBitmap; - CleanupStack::PushL(bmp); - - // get 1st viewfinder image from camera into bmp (detail excluded) - TSize bmpSize = bmp->SizeInPixels(); - - CPanoramaTransform* panTrans = CPanoramaTransform::NewL();//create panorama transoform - CleanupStack::PushL(panTrans); - - CVFTracker* vfTracker = CVFTracker::NewL(); //create VFTracker and load the plugin - CleanupStack::PushL(vfTracker); - - vfTracker->InitializeL(bmpSize); //Create VFTracker and set size - - CImagePanorama* panImage = CImagePanorama::NewL(); //create CImagePanorama object - CleanupStack::PushL(panImage); - - TDirection direction = EPanoramaDirectionRight; //assign direction - - // Lens parameters or internal camera characteristics should be available for the - // specific camera module in use. Here we use default values. - TPanoramaLens lens; - panImage->InitializeL(imageSize, lens, direction); //initialise size, lens, direction and create panorama engine - - // get the first captured image from the camera as a starting point - its name is given in capturedFileName - TFileName capturedFileName; - capturedFileName.Format(KFileCapturedImage(),i); - panImage->AddFileL(capturedFileName, *panTrans); //add the captured image - - do - { - // give the next camera viewfinder image to the tracker (details ommitted) - vfTracker->RegisterImageL(*bmp, *panTrans); // register viewfinder image - - // check if we have a good overlap with the previous image - if(vfTracker->IsTimeToCapture(direction, KPanoramaDefaultOverlap)) - { - // capture the next image from the camera (details ommitted) - capturedFileName.Format(KFileCapturedImage(),i); - - panImage->AddFileL(capturedFileName, *panTrans); //add the captured image - vfTracker->Reset(); //reset the VFTracker object - } - if ( err != KErrNone ) // some termination condition usually a signal from user - { - // no more viewfinder images - break; - } - } - while (1); - panImage->RenderL(KTestVFTOutputFileName); // render the stitched image - CleanupStack::PopAndDestroy(4,bmp); //panTrans, vfTracker, panImage, bmp -

                The CVFTracker is passed each viewfinder -images which it checks and determines whether it is right time to capture -the next image. In return it provides translation information CPanoramaTransform::GetTranslation() which -indicates the shift of the current viewfinder image.

                The extracted -information is used to draw the blue rectangle on the screen. If it is time -to capture, then it triggers the capturing function and restarts the CVFTracker again -for next image.

                Note: The box representation is used in the -UI, to help you to take better panorama images. In addition a vibration effect -can be used to provide additional feedback on when to capture an image. For -example, when you sweep the mobile phone, it is in tracking mode so it vibrates. -When the mobile phone is ready to capture, the vibration stops to let you -know that it must be static for capturing an accurate second image. Then when -it vibrates again, you must rotate the mobile and until it stop.

                4. -

              4. User interface updating -details

                The UI design detail is shown in step by step process. -They are as follows:

                  -

                • The total panorama coverage -area is divided into four different image areas:

                  - -
                  • -

                • When you choose to capture -a panorama image the following steps are performed. The first image is captured -at position 0. The UI looks as follows:

                  - -
                  • -

                • When you rotate the -mobile phone clockwise, the blue box moves to the right using the translation -information from CPanoramaTransform. At the same time the -vibrator is set on to give direct feedback for the tracking process. When -the blue box and the grey box (which represent the position to capture the -next image) coincide, the blue box turns into a filled blue box and the vibrator -stops. You then known that the next image is captured. At this moment the -camera must be steady.

                  After second image is captured the blue box -is moving again and vibrator is set-on. The UI looks as follows:

                  - -

                  Again, you rotate the mobile clockwise until the two boxes coincide -and vibrator stops; third image then captured. After this, the UI looks as -follows:

                  - -

                  You rotate the mobile phone until the boxes coincide and the fourth -(last) image is captured.

                  Note: If the mobile phone rotation -deviates from chosen (clockwise) direction or translates up and down, the -blue box indicates this, and you must correct the mobile phone for the wrong -movement.

                  At this point the stitched image can be saved or you can -reset the camera, to create another panorama image:

                  - -
                  • -
                5. -

              Camera -calibration

              In order to produce good panorama images, the internal -characteristics of the camera is calibrated by the TPanoramaLens(). -The lens parameter such as the distance, the focal length, the principal point, -the skew, the width and the height are called the intrinsic parameters.

              The -camera module supplier should be able to provide this information or there -are a number of tools to get the camera parameters. A free tool that can be -used is the calibration functions in OpenCV. Typically these tools need an input of images -of a special reference pattern, for example a checker board like grid, photographed -from many directions. From that the tools automatically generate all the desired -lens parameters.

              + + + + + +Panoramic +Stitching Guide +

              This document introduces you to the panoramic stitching functionality.

              +
              Purpose

              Panoramic +stitching involves combining a collection of images into a single image.

              +
              Panoramic stitching overview

              The panorama image +is created by stitching a collection of several separate image into one large +image. The panoramic stitching process is done by,

                +

              • image registration

                • +

              • cylindrical projection +of images

                • +

              • image blending.

                • +

              The panoramic stitch can be done eihter interactively by using camera +viewfinder, for tracking the camera movements or by stitching pre-captured +images together.

              Introduction +about the panoramic stitching

              The CImagePanorama stitches +a set of images into a single panorama image. The input to CImagePanorama is +a collection of high resolution images together with some guidance on the +relative positioning between the images expressed by CPanoramaTransform instances.

              For +the panorama creation, the most common use is rendering a full size panorama +image to the device file system.

              The high level steps to use CImagePanorama are +shown below:

                +

              • To construct CImagePanorama, +use CImagePanorama::NewL() which loads the image panorama +plugin.

                • +

              • To initialise CImagePanorama, +use CImagePanorama::InitialiseL().

                • +

              • To correct the lens +parameter use TPanoramaLens. You need to correct the lens +for panorama stitching quality. The lens parameters are camera specific.

                • +

              • To add images to CImagePanorama, +use CImagePanorama::AddFileL(),CImagePanorama::AddBufferL() or CImagePanorama::AddImageL(), providing a hint on relative positioning or translation of the images through CPanoramaTransform. +This transform only needs to be approximate.

                • +

              • To make the stitched +image available call CImagePanorama::RenderL().

                • +

              • The CImagePanorama instance +can then be deleted.

                • +

              Introduction +about the CVFTracker

              CVFTracker is used to +track viewfinder images to aid in capturing a panorama. The usage of CVFTracker are +demonstrated as follows:

                +

              • The CVFTracker output +is used for providing feedback and guidance to you, on how to move the camera +while capturing a panorama.

                • +

              • The CVFTracker is +used as an aid for the stitching process in the CImagePanorama. +The input to the CVFTracker is a rapid flow of raw images +from the viewfinder of the camera. The output is the movement of the camera.

                • +

              The high level steps to use the CVFTracker are +shown below:

                +

              • To create CVFTracker, +use the CVFTracker::NewL(). The CVFTracker::NewL() is +used to load the CVFTracker plugin.

                • +

              • To initialise CVFTracker, +use CVFTracker::InitialiseL().

                • +

              • To reset CVFTracker, +use CVFTracker::Reset().

                • +

              • To perform the image +registration, use CVFTracker::RegisterImageL().

                • +

              • To destroy the CVFTracker, +use CVFTracker::~CVFTracker().

                • +

              Camera +requirements

              The camera requirements for the CImagePanorama and CVFTracker are +as follows,

                +

              • The camera must provide +low resolution images (in the order of 160 by 120 up to 320 by 240 resolution) +as the raw format at a high frame rate to the CVFTracker and +high resolution captured images to the CImagePanorama.

                • +

              • For the CVFTracker, +it is better to have good frame rate than to have high resolution input images.

                • +

              • The use of large CVFTracker images +can cause a lower frame rate on slow devices, and do not give accurate tracking +for the view finder.

                • +

              • The optimal size of +images is a tradeoff between the panorama quality and the time for rendering +the panorama.

                • +
              +
              How to use Panoramic Stitching

              This section contains +some code snippets to show, how Panoramic stitching is accessed in several +situations.

              Basic +stitching

              The basic stitching is demonstrated by a simple example +of stitching four JPEG images into a single JPEG image providing an approximate +translation between each image:

              + + TSize imageSize(1200, 1000); + + TDirection direction = EPanoramaDirectionRight; + + //Lens parameters or internal camera characteristics should be available for the + //specific camera module in use. Here we use default values. + TPanoramaLens lens; + + //Create transform. A transform is an approximate offset between each image. + CPanoramaTransform* panTrans = CPanoramaTransform::NewL(); + CleanupStack::PushL(panTrans); + + //Create panorama object.This stitches the individual images together. + CImagePanorama* panImage = CImagePanorama::NewL(); + CleanupStack::PushL(panImage); + + //Create panorama engine and set the lens and size + panImage->InitializeL(imageSize, lens, direction); + + //Each file added is provided with an approximate translation. + //In this case there are 4 images. + panTrans->SetTranslationL(TPoint(0, 0), imageSize); + panImage->AddFileL(KTestFileName1, *panTrans); + + panTrans->SetTranslationL(TPoint(900, -30), imageSize); + panImage->AddFileL(KTestFileName2, *panTrans); + + panTrans->SetTranslationL(TPoint(900, 60), imageSize); + panImage->AddFileL(KTestFileName3, *panTrans); + + panTrans->SetTranslationL(TPoint(400, -30), imageSize); + panImage->AddFileL(KTestFileName4, *panTrans); + + //The image size can be obtained before rendering (if required) + TSize size; + panImage->CurrentImageSizeL(size); + + //view the output image + panImage->RenderL(KTestBSOutputFileName); + + CleanupStack::PopAndDestroy(2); //panTrans, panImage + +

              The main steps for using CImagePanorama are +as follows,

                +

              1. create CImagePanorama

                2. +

              2. some approximate transform +information for each image pair

                3. +

              3. add each images to CImagePanorama

                4. +

              4. render the output (for +example to the file)

                5. +

              5. delete the objects used.

                6. +

              Note: The following points must be noted by you:

                +

              • The lens parameters +are not resolution dependant. It is enough to calibrate once for each camera +model and no need to recalibrate for each resolution. For best accuracy, use +the highest resolution possible when calibrating with a calibration tool.

                The +approximate translations in x co-ordinate and y co-ordinate ( as dx, dy) must +be compliant with the value of direction.

                • +

              A +camera application example

              The CImagePanorama is +used in a camera application. The example is more complicated than the previous +example. In this example CVFTracker provides the approximate +transform between the captured images.

              Viewfinder +image tracking

              The CImagePanorama generates +panorama images. The application starts the process and then use the camera +for capturing the images. The CVFTracker will give an indication +when to capture the high resolution images, which will later be stitched into +a panorama image.

              The CVFTracker plays an important +role for getting the camera movement. The high level steps to use the CVFTracker in +the CImagePanorama for a camera application, are shown +below:

                +

              1. To create the CVFTracker object +and load the CVFTracker plugin, use CVFTracker::NewL().

                2. +

              2. To create CImagePanorama object +and load the CImagePanorama plugin, use CImagePanorama::NewL().

                3. +

              3. To create the CPanoramaTransform object +and set or get the values, use the CPanoramaTransform::NewL().

                4. +

              4. To create and set the CVFTracker, CImagePanorama, +and CPanoramaTransform functions for the Image Processor +Adaptation Plug-in objects, use CVFTracker::InitialiseL() and CImagePanorama::InitialiseL() respectively.

                5. +

              5. To get a translation +value from a viewfinder image, register an image by using CVFTracker::RegisterImageL(). +This will return translation information as a CPanoramaTransform object.

                6. +

              6. Check the right time +to capture the next image by using CVFTracker::IsTimeToCapture().

                7. +

              7. Reset the CVFTracker for +the next image, using CVFTracker::Reset().

                In order +to capture many images to be stitched into a single panorama image, repeat +the steps 5, 6 and 7.

                8. +
              + +

              Panorama +stitching

              The CVFTracker helps to decide when +to capture each of the full resolution images using the camera. The images +can then be passed to CImagePanorama and the stitching is done. The high level +steps to do panorama stitching are listed below:

                +

              1. Capture the next image +using the camera, then add the image to the CImagePanorama by +using CImagePanorama::AddImageL() or CImagePanorama::AddFileL, +passing in the CPanoramaTransform object obtained from +the CVFTracker.

                2. +

              2. When all images have +been captured you can render the stitched image to file, image buffer, CFbsBitmap +or image frame using CImagePanorama::RenderL().

                3. +
              + +

              User Interface

              Provide a good user interface (UI) application +for the CImagePanorama is crucial. An example of UI design +is described below, which gives you a robust and easy application for generating +panorama images.

              How +to shoot a panorama

              The steps to be followed for shooting a panorama +images:

                +

              1. You need to press the +start button of the camera and need to sweep the camera towards the wanted +scene.

                Note: You must try not to move the mobile phone, but +only rotate it. You see in the below diagram the camera is sweep in a clockwise +direction from left-to-right. The rotation is made around the imagined axis +through mobile (axis of rotation in the image). A panorama image covers approximately +a 100 degree field of view.

                + +
                2. +

              2. Application Start

                When +you launch the application the UI appears as shown in the below diagram.

                + +

                Here the screen area shows the viewfinder image. When you sweep +the mobile, several images are captured and then the images are stitched to +create a panorama image.

                3. +

              3. Capture a panorama +image during tracking

                When you choose to capture a panorama image +the UI changes, which is shown in the below diagram.

                + +

                In the above diagram you see three different boxes named 1, 2 and +3 which represent the position of the camera. The blue box representation +changes according to the rotation of the mobile phone.

                The boxes shown +in the above diagram is for illustrative purpose, so that it can be down scaled +for viewfinder image size. The total panorama coverage area box is estimated +by the number of images for capturing and the overlapping area size.

                The +code snippets below shows the CVFTracker tracking.

                + + _LIT(KFileOutput, "c:\\ICLExample\\viewfinder%d.mbm"); + _LIT(KFileCapturedImage, "c:\\ICLExample\\pancapture%d.jpg"); + TInt i = 0; + + TSize imageSize(1200,1000); + CFbsBitmap* bmp = new (ELeave) CFbsBitmap; + CleanupStack::PushL(bmp); + + // get 1st viewfinder image from camera into bmp (detail excluded) + TSize bmpSize = bmp->SizeInPixels(); + + CPanoramaTransform* panTrans = CPanoramaTransform::NewL();//create panorama transoform + CleanupStack::PushL(panTrans); + + CVFTracker* vfTracker = CVFTracker::NewL(); //create VFTracker and load the plugin + CleanupStack::PushL(vfTracker); + + vfTracker->InitializeL(bmpSize); //Create VFTracker and set size + + CImagePanorama* panImage = CImagePanorama::NewL(); //create CImagePanorama object + CleanupStack::PushL(panImage); + + TDirection direction = EPanoramaDirectionRight; //assign direction + + // Lens parameters or internal camera characteristics should be available for the + // specific camera module in use. Here we use default values. + TPanoramaLens lens; + panImage->InitializeL(imageSize, lens, direction); //initialise size, lens, direction and create panorama engine + + // get the first captured image from the camera as a starting point - its name is given in capturedFileName + TFileName capturedFileName; + capturedFileName.Format(KFileCapturedImage(),i); + panImage->AddFileL(capturedFileName, *panTrans); //add the captured image + + do + { + // give the next camera viewfinder image to the tracker (details ommitted) + vfTracker->RegisterImageL(*bmp, *panTrans); // register viewfinder image + + // check if we have a good overlap with the previous image + if(vfTracker->IsTimeToCapture(direction, KPanoramaDefaultOverlap)) + { + // capture the next image from the camera (details ommitted) + capturedFileName.Format(KFileCapturedImage(),i); + + panImage->AddFileL(capturedFileName, *panTrans); //add the captured image + vfTracker->Reset(); //reset the VFTracker object + } + if ( err != KErrNone ) // some termination condition usually a signal from user + { + // no more viewfinder images + break; + } + } + while (1); + panImage->RenderL(KTestVFTOutputFileName); // render the stitched image + CleanupStack::PopAndDestroy(4,bmp); //panTrans, vfTracker, panImage, bmp +

                The CVFTracker is passed each viewfinder +images which it checks and determines whether it is right time to capture +the next image. In return it provides translation information CPanoramaTransform::GetTranslation() which +indicates the shift of the current viewfinder image.

                The extracted +information is used to draw the blue rectangle on the screen. If it is time +to capture, then it triggers the capturing function and restarts the CVFTracker again +for next image.

                Note: The box representation is used in the +UI, to help you to take better panorama images. In addition a vibration effect +can be used to provide additional feedback on when to capture an image. For +example, when you sweep the mobile phone, it is in tracking mode so it vibrates. +When the mobile phone is ready to capture, the vibration stops to let you +know that it must be static for capturing an accurate second image. Then when +it vibrates again, you must rotate the mobile and until it stop.

                4. +

              4. User interface updating +details

                The UI design detail is shown in step by step process. +They are as follows:

                  +

                • The total panorama coverage +area is divided into four different image areas:

                  + +
                  • +

                • When you choose to capture +a panorama image the following steps are performed. The first image is captured +at position 0. The UI looks as follows:

                  + +
                  • +

                • When you rotate the +mobile phone clockwise, the blue box moves to the right using the translation +information from CPanoramaTransform. At the same time the +vibrator is set on to give direct feedback for the tracking process. When +the blue box and the grey box (which represent the position to capture the +next image) coincide, the blue box turns into a filled blue box and the vibrator +stops. You then known that the next image is captured. At this moment the +camera must be steady.

                  After second image is captured the blue box +is moving again and vibrator is set-on. The UI looks as follows:

                  + +

                  Again, you rotate the mobile clockwise until the two boxes coincide +and vibrator stops; third image then captured. After this, the UI looks as +follows:

                  + +

                  You rotate the mobile phone until the boxes coincide and the fourth +(last) image is captured.

                  Note: If the mobile phone rotation +deviates from chosen (clockwise) direction or translates up and down, the +blue box indicates this, and you must correct the mobile phone for the wrong +movement.

                  At this point the stitched image can be saved or you can +reset the camera, to create another panorama image:

                  + +
                  • +
                5. +

              Camera +calibration

              In order to produce good panorama images, the internal +characteristics of the camera is calibrated by the TPanoramaLens(). +The lens parameter such as the distance, the focal length, the principal point, +the skew, the width and the height are called the intrinsic parameters.

              The +camera module supplier should be able to provide this information or there +are a number of tools to get the camera parameters. A free tool that can be +used is the calibration functions in OpenCV. Typically these tools need an input of images +of a special reference pattern, for example a checker board like grid, photographed +from many directions. From that the tools automatically generate all the desired +lens parameters.

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-60EE22AA-402D-4FC2-9AD1-B3AEF822E8DC.dita --- a/Symbian3/SDK/Source/GUID-60EE22AA-402D-4FC2-9AD1-B3AEF822E8DC.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-60EE22AA-402D-4FC2-9AD1-B3AEF822E8DC.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,98 +1,98 @@ - - - - - -Receiving -Channel Data based on ConditionsConditional listening enables you to receive sensor data feeds -based on a specific condition. For example, you can choose to receive sensor -feeds that are only movement specific. -

              Before listening -for channel data, you must open -the sensor channel.

               - -Create channel condition -items using CSensrvChannelCondition constructor. These -conditions can be used to filter the sensor data feeds. -//Comparison values needed for condition -... -TInt firstNumber=45; -HBufC8 *firstBufNumber=NULL; -InetProtTextUtils::ConvertIntToDescriptorL(firstNumber,firstBufNumber); -CleanupStack::PushL(firstBufNumber); - -TInt secondNumber=150; -HBufC8 *secondBufNumber=NULL; -InetProtTextUtils::ConvertIntToDescriptorL(secondNumber,secondBufNumber); -CleanupStack::PushL(secondBufNumber); - -//Creates a SingleLimit Condition with a GreaterThan operator -CSensrvChannelCondition *firstCondition = CSensrvChannelCondition::NewL(ESensrvSingleLimitCondition,ESensrvOperatorGreaterThan,1,*firstBufNumber); - -//Creates a SingleLimit Condition with a LessThan operator -CSensrvChannelCondition *secondCondition = CSensrvChannelCondition::NewL(ESensrvSingleLimitCondition,ESensrvOperatorLessThan,2,*secondBufNumber); - -Create a channel -condition set using CSensrvChannelConditionSet constructor. -Add the condition items to the condition set using the CSensrvChannelConditionSet::AddConditionL() function. -//Creates a ConditionSet with ConditionType OR - CSensrvChannelConditionSet *ConditionSet=CSensrvChannelConditionSet::NewLC(ESensrvAndConditionSet); - - //Add channel1 and channel2 to conditonset - ConditionSet->AddChannelConditionL(firstCondition); - ConditionSet->AddChannelConditionL(secondCondition); - -Add the condition -set to the required channel using the CSensrvChannel::AddConditionL() function. -CSensrvChannel* channel; -channel->AddConditionL(*ConditionSet); - - -Create a condition -listener implementation for the MSensrvChannelConditionListener interface, -which listens for sensor data feeds based on CSensrvChannelConditionSet. -class ConditionListener:public MSensrvChannelConditionListener - { - public: - void ConditionMet(CSensrvChannel &aChannel, CSensrvChannelConditionSet &aChannelConditionSet, TDesC8 &avalue) - { - ... - //Implementation - } - void ConditionError(CSensrvChannel &aChannel, TSensrvErrorSeverity aError) - { - ... - //Implementation - } - void GetChannelConditionListenerInterfaceL(TUid aInterfaceUid, TAny *&aInterface) - { - ... - //Implementation - } - }; - -Start conditional -listening by passing an instance of the condition listener implementation, -using the CSensrvChannel::StartConditionListeningL() function. -//Instance of the condition listener implementation -ConditionListener conditionListener; -... -channel->StartConditionListeningL(conditionListener,1,1); -... - -Once you get the -required sensor data feeds from the sensor channel based on the conditions -set, you can stop conditional listening using the CSensrvChannel::StopConditionListening() function. -channel->StopConditionListening(); - - - -

              End the session -with the sensor channel using the CSensrvChannel::CloseChannel() function.

               + + + + + +Receiving +Channel Data based on ConditionsConditional listening enables you to receive sensor data feeds +based on a specific condition. For example, you can choose to receive sensor +feeds that are only movement specific. +

              Before listening +for channel data, you must open +the sensor channel.

               + +Create channel condition +items using CSensrvChannelCondition constructor. These +conditions can be used to filter the sensor data feeds. +//Comparison values needed for condition +... +TInt firstNumber=45; +HBufC8 *firstBufNumber=NULL; +InetProtTextUtils::ConvertIntToDescriptorL(firstNumber,firstBufNumber); +CleanupStack::PushL(firstBufNumber); + +TInt secondNumber=150; +HBufC8 *secondBufNumber=NULL; +InetProtTextUtils::ConvertIntToDescriptorL(secondNumber,secondBufNumber); +CleanupStack::PushL(secondBufNumber); + +//Creates a SingleLimit Condition with a GreaterThan operator +CSensrvChannelCondition *firstCondition = CSensrvChannelCondition::NewL(ESensrvSingleLimitCondition,ESensrvOperatorGreaterThan,1,*firstBufNumber); + +//Creates a SingleLimit Condition with a LessThan operator +CSensrvChannelCondition *secondCondition = CSensrvChannelCondition::NewL(ESensrvSingleLimitCondition,ESensrvOperatorLessThan,2,*secondBufNumber); + +Create a channel +condition set using CSensrvChannelConditionSet constructor. +Add the condition items to the condition set using the CSensrvChannelConditionSet::AddConditionL() function. +//Creates a ConditionSet with ConditionType OR + CSensrvChannelConditionSet *ConditionSet=CSensrvChannelConditionSet::NewLC(ESensrvAndConditionSet); + + //Add channel1 and channel2 to conditonset + ConditionSet->AddChannelConditionL(firstCondition); + ConditionSet->AddChannelConditionL(secondCondition); + +Add the condition +set to the required channel using the CSensrvChannel::AddConditionL() function. +CSensrvChannel* channel; +channel->AddConditionL(*ConditionSet); + + +Create a condition +listener implementation for the MSensrvChannelConditionListener interface, +which listens for sensor data feeds based on CSensrvChannelConditionSet. +class ConditionListener:public MSensrvChannelConditionListener + { + public: + void ConditionMet(CSensrvChannel &aChannel, CSensrvChannelConditionSet &aChannelConditionSet, TDesC8 &avalue) + { + ... + //Implementation + } + void ConditionError(CSensrvChannel &aChannel, TSensrvErrorSeverity aError) + { + ... + //Implementation + } + void GetChannelConditionListenerInterfaceL(TUid aInterfaceUid, TAny *&aInterface) + { + ... + //Implementation + } + }; + +Start conditional +listening by passing an instance of the condition listener implementation, +using the CSensrvChannel::StartConditionListeningL() function. +//Instance of the condition listener implementation +ConditionListener conditionListener; +... +channel->StartConditionListeningL(conditionListener,1,1); +... + +Once you get the +required sensor data feeds from the sensor channel based on the conditions +set, you can stop conditional listening using the CSensrvChannel::StopConditionListening() function. +channel->StopConditionListening(); + + + +

              End the session +with the sensor channel using the CSensrvChannel::CloseChannel() function.

                             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-61056CE2-97BF-5D32-8AC5-E625FBC7D0EC.dita --- a/Symbian3/SDK/Source/GUID-61056CE2-97BF-5D32-8AC5-E625FBC7D0EC.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-61056CE2-97BF-5D32-8AC5-E625FBC7D0EC.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,80 +1,80 @@ - - - - - -Modifying -DOM TreeThis topic explains how to create or modify a DOM tree by adding -nodes and changing their contents. -

              Before you start, you must:

                -

              • understand the concept -of Document Object Model -(DOM)

                • -

              • understand the structure -and classes of the XML -DOM Engine component

                • -
               -

              The following diagram shows a sequence of calls that -create a DOM tree from an empty document. There are many functions in the -DOM Engine API that add nodes to a tree: refer to the reference documentation -of the TXmlEngElement class for a comprehensive -list.

              - Creating a DOM tree - -               - - -Create an instance of RXmlEngDocument. -RXmlEngDocument myDoc; - - -Set the root node with the RXmlEngDocument::CreateDocumentElementL() function. -_LIT8( KRootName, "playlist" ); -TXmlEngElement root = myDoc->CreateDocumentElementL( KRootName ); - - -Add child nodes and attributes by calling the TXmlEngElement::AddNewElementL() and TXmlEngElement::AddNewAttributeL() functions. -_LIT8( KChildName, "song" ); -_LIT8( KAttrName, "filename" ); - -for( TInt i=1;i<6;i++ ) - { - TXmlEngElement tempElement = root.AddNewElementL( KChildName ); - TBuf8<12> value( _L8( "music0" ) ); - value.AppendNum( i ); - value.Append( _L8( ".mp3" ) ); - tempElement.AddNewAttributeL( KAttrName, value ); - } - - -Swap the first two song elements by calling the TXmlEngElement::MoveAfterSibling() function. -TXmlEngNode swap = root.FirstChild(); -swap.MoveAfterSibling( swap.NextSibling() ); - - -If you want to save the DOM tree into a file, call the XmlEnginePushL() method -first. -You must call the XmlEnginePushL() method -before parsing or saving an XML file, and the XmlEnginePopAndClose() method -after these operations. - - -

              The result is a DOM tree corresponding to the following XML structure:

              - <playlist> - <song filename = "music02.mp3"/> - <song filename = "music01.mp3"/> - <song filename = "music03.mp3"/> - <song filename = "music04.mp3"/> - <song filename = "music05.mp3"/> - </playlist> -               -               -Parsing XML -DOM + + + + + +Modifying +DOM TreeThis topic explains how to create or modify a DOM tree by adding +nodes and changing their contents. +

              Before you start, you must:

                +

              • understand the concept +of Document Object Model +(DOM)

                • +

              • understand the structure +and classes of the XML +DOM Engine component

                • +
               +

              The following diagram shows a sequence of calls that +create a DOM tree from an empty document. There are many functions in the +DOM Engine API that add nodes to a tree: refer to the reference documentation +of the TXmlEngElement class for a comprehensive +list.

              + Creating a DOM tree + +               + + +Create an instance of RXmlEngDocument. +RXmlEngDocument myDoc; + + +Set the root node with the RXmlEngDocument::CreateDocumentElementL() function. +_LIT8( KRootName, "playlist" ); +TXmlEngElement root = myDoc->CreateDocumentElementL( KRootName ); + + +Add child nodes and attributes by calling the TXmlEngElement::AddNewElementL() and TXmlEngElement::AddNewAttributeL() functions. +_LIT8( KChildName, "song" ); +_LIT8( KAttrName, "filename" ); + +for( TInt i=1;i<6;i++ ) + { + TXmlEngElement tempElement = root.AddNewElementL( KChildName ); + TBuf8<12> value( _L8( "music0" ) ); + value.AppendNum( i ); + value.Append( _L8( ".mp3" ) ); + tempElement.AddNewAttributeL( KAttrName, value ); + } + + +Swap the first two song elements by calling the TXmlEngElement::MoveAfterSibling() function. +TXmlEngNode swap = root.FirstChild(); +swap.MoveAfterSibling( swap.NextSibling() ); + + +If you want to save the DOM tree into a file, call the XmlEnginePushL() method +first. +You must call the XmlEnginePushL() method +before parsing or saving an XML file, and the XmlEnginePopAndClose() method +after these operations. + + +

              The result is a DOM tree corresponding to the following XML structure:

              + <playlist> + <song filename = "music02.mp3"/> + <song filename = "music01.mp3"/> + <song filename = "music03.mp3"/> + <song filename = "music04.mp3"/> + <song filename = "music05.mp3"/> + </playlist> +               +               +Parsing XML +DOM               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6146A5BB-1AC1-48D4-9EB8-7FA4EC35BFF2.dita --- a/Symbian3/SDK/Source/GUID-6146A5BB-1AC1-48D4-9EB8-7FA4EC35BFF2.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,165 +0,0 @@ - - - - - -Typical -full QWERTY keyboard functions -

              The default short key press events of a QWERTY keyboard are listed in the -following table:

              -Default short -key press event on full QWERTY keyboard - - - -Key -Action - - - - -

              Character keys

               -

              Adds a character.

               -               - -

              Backspace

               -

              Moves the cursor one step back, clearing any character or selected -text in that position.

               -               - -

              Enter

               -

              Adds a carriage return where possible (a new line). Elsewhere the -default behavior is similar with the Selection key.

               -               - -

              Space

               -

              Adds a space.

               -               - -

              Chr

               -

              Opens the special characters table.

               -               - -

              Shift

               -

              Activates the Shift character mode for the character that is pressed -after Shift. For example, consecutive presses of Shift and the character -a' produce a capital A' character.

               -               - -

              Scroll keys

               -

              Moves the cursor or focus to the pressed direction.

               -               - -

              Fn key (optional key)

               -

              Activates Fn-mode character input for the next following key press.Two -presses activate Fn mode (locked) until single press deactivates the mode.

               -               - - -
              -

              The default long key press events of a full QWERTY keyboard are listed -in the following table:

              -Default long -key press events on full QWERTY keyboard - - - -Key -Action - - - - -

              Character keys

               -

              Adds a character with key repeat.

               -               - -

              Backspace

               -

              Moves the cursor back, clearing the previous character with key -repeat.

               -               - -

              Enter

               -

              Adds a carriage return where possible (a new line) with key repeat.

               -               - -

              Space

               -

              Adds a space with key repeat.

               -               - -

              Chr

               -

              Accented characters can be entered by holding down the Chr key and -pressing a character key consecutively.

               -               - -

              Scroll keys

               -

              Moves the cursor or focus to the pressed direction with key repeat.

               -               - - -
              -

              The key combinations for full QWERTY keyboard are listed in the following -table:

              -Key combinations -on full QWERTY keyboard - - - -Key -Action - - - - -

              Shift + a character key

               -

              Enters the Shift character of that particular character key. Can -be used either as two consecutive short presses or simultaneous presses.

               -               - -

              Shift + scroll keys

               -

              Selects text from the present cursor position to the direction of -the selected scroll key. Simultaneous pressing is required.

               -               - -

              Chr + a character key

               -

              Accented characters can be entered by holding down the Chr key and -then pressing a character key repeatedly.

               -               - -

              "Dead" keys

               -

              Some keys in certain localized keyboards that produce a visible -outcome in editing only after another key is pressed right afterwards. For -example, accents over characters.

               -               - -

              Ctrl + x'

               -

              Cuts the text in editors (for example, text that was -selected with Shift + a scroll key).

               -               - -

              Ctrl + c'

               -

              Copies the text in editors (for example, text that was selected -with Shift + a scroll key).

               -               - -

              Ctrl + v'

               -

              Pastes text in editors (for example, text that was selected with -Shift + a scroll key).

               -               - -

              Fn + a character key

               -

              Activates Fn-mode for that key press.

               -               - -

              Fn + space

               -

              Opens editing menu.

               -               - - -
               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6163197B-7983-5FB7-9B92-02E490A900FB.dita --- a/Symbian3/SDK/Source/GUID-6163197B-7983-5FB7-9B92-02E490A900FB.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-6163197B-7983-5FB7-9B92-02E490A900FB.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,45 +1,45 @@ - - - - - -How to -construct a headerThis document describes how to create a header for a doubly linked -list. -

              In order to construct a header, two important pieces of information are -needed:

              -
                -

              • the type of object -which forms the elements.

                • -

              • the offset of -the link object from the start of the element.

                • -
              -

              To create a header for a doubly linked list of CMyClass elements, -defined as:

              -class CMyClass : public CBase - { - ... - TDblQueLink iDlink; - ... - }; -

              construct a TDblQue as follows:

              -TDblQue<CMyClass> queHeader(_FOFF(CMyClass,iDlink)); -

              The TDblQue class takes a class template parameter which -defines the type of object which is to form an element of the list. In this -example, objects of type CMyClass form the elements of the -list.

              -

              The _FOFF macro (i.e. the "field offset" macro) calculates -the offset of the component link object within the element. In this example, -the required value is the offset of the iDlink data member -from the start of CMyClass.

              - - -<image href="GUID-29E7942D-A00D-5771-9782-59260965C687_d0e217648_href.png" placement="inline"/> -</fig> +<?xml version="1.0" encoding="utf-8"?> +<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> +<!-- This component and the accompanying materials are made available under the terms of the License +"Eclipse Public License v1.0" which accompanies this distribution, +and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> +<!-- Initial Contributors: + Nokia Corporation - initial contribution. +Contributors: +--> +<!DOCTYPE concept + PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> +<concept id="GUID-6163197B-7983-5FB7-9B92-02E490A900FB" xml:lang="en"><title>How to +construct a headerThis document describes how to create a header for a doubly linked +list. +

              In order to construct a header, two important pieces of information are +needed:

              +
                +

              • the type of object +which forms the elements.

                • +

              • the offset of +the link object from the start of the element.

                • +
              +

              To create a header for a doubly linked list of CMyClass elements, +defined as:

              +class CMyClass : public CBase + { + ... + TDblQueLink iDlink; + ... + }; +

              construct a TDblQue as follows:

              +TDblQue<CMyClass> queHeader(_FOFF(CMyClass,iDlink)); +

              The TDblQue class takes a class template parameter which +defines the type of object which is to form an element of the list. In this +example, objects of type CMyClass form the elements of the +list.

              +

              The _FOFF macro (i.e. the "field offset" macro) calculates +the offset of the component link object within the element. In this example, +the required value is the offset of the iDlink data member +from the start of CMyClass.

              + + +<image href="GUID-29E7942D-A00D-5771-9782-59260965C687_d0e213911_href.png" placement="inline"/> +</fig> </conbody></concept> \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6167C2F2-BC5B-5B10-BD5D-7702BE4112F6.dita --- a/Symbian3/SDK/Source/GUID-6167C2F2-BC5B-5B10-BD5D-7702BE4112F6.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-6167C2F2-BC5B-5B10-BD5D-7702BE4112F6.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,60 +1,60 @@ -<?xml version="1.0" encoding="utf-8"?> -<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> -<!-- This component and the accompanying materials are made available under the terms of the License -"Eclipse Public License v1.0" which accompanies this distribution, -and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> -<!-- Initial Contributors: - Nokia Corporation - initial contribution. -Contributors: ---> -<!DOCTYPE concept - PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> -<concept id="GUID-6167C2F2-BC5B-5B10-BD5D-7702BE4112F6" xml:lang="en"><title>View -Server Tutorial -

              The UI Control Framework (CONE) provides CCoeAppUi that -provides an interface to the View Server, which enables seamless switching -between different views across various applications.

              - -
              Introduction

              The UI framework built on Cone/uikon -can make a choice to use the View Server.

              The view architecture allows -applications to make and receive requests to show a particular view of their -data. It allows applications to have integration between their user interfaces. -This particularly allows the user to navigate through the UI on the basis -of the task they are working on, rather than perceiving separate applications. -For example, an application provides a view of a given Contact, any other -application may display a contact using that view.

              Views are UI controls -that are derived from the MCoeView abstract view interface -and display application data. Typically views are top-level window-owning -controls. Each view is given a unique identifier of type TVwsViewId. TVwsViewId is -a combination of the UID of the application and the UID of the view within -the application. An application participating in the view switching must complete -the steps given in the procedure section.

              -
              Procedure
                -

              1. Create -an instance of CCoeAppUi

                2. -

              2. Implement -the observer functions to get notification on events, if required.

                3. -

              3. Derive -a class from the MCoeView class.

                4. -

              4. Add -the view to the control stack to receive key events.

                5. -

              5. Register -the view with the View Server.

                6. -

              6. Perform one or more -of the following tasks:

                  -

                1. Activate -a view through the client session.

                  If the view which has to -be activated is not registered with the server when an activation request -arrives, the view server starts the application associated with that view.

                  2. -

                2. Set -a view as a default view.

                  3. -

                3. Deregister -a view, if required.

                  4. -
                7. -
              -               -View Server -Overview -Control Stack - + + + + + +View +Server Tutorial +

              The UI Control Framework (CONE) provides CCoeAppUi that +provides an interface to the View Server, which enables seamless switching +between different views across various applications.

              + +
              Introduction

              The UI framework built on Cone/uikon +can make a choice to use the View Server.

              The view architecture allows +applications to make and receive requests to show a particular view of their +data. It allows applications to have integration between their user interfaces. +This particularly allows the user to navigate through the UI on the basis +of the task they are working on, rather than perceiving separate applications. +For example, an application provides a view of a given Contact, any other +application may display a contact using that view.

              Views are UI controls +that are derived from the MCoeView abstract view interface +and display application data. Typically views are top-level window-owning +controls. Each view is given a unique identifier of type TVwsViewId. TVwsViewId is +a combination of the UID of the application and the UID of the view within +the application. An application participating in the view switching must complete +the steps given in the procedure section.

              +
              Procedure
                +

              1. Create +an instance of CCoeAppUi

                2. +

              2. Implement +the observer functions to get notification on events, if required.

                3. +

              3. Derive +a class from the MCoeView class.

                4. +

              4. Add +the view to the control stack to receive key events.

                5. +

              5. Register +the view with the View Server.

                6. +

              6. Perform one or more +of the following tasks:

                  +

                1. Activate +a view through the client session.

                  If the view which has to +be activated is not registered with the server when an activation request +arrives, the view server starts the application associated with that view.

                  2. +

                2. Set +a view as a default view.

                  3. +

                3. Deregister +a view, if required.

                  4. +
                7. +
              +               +View Server +Overview +Control Stack +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-61B965D9-B85E-5F40-8D56-1C0FA77D2492-GENID-1-8-1-3-1-1-8-1.dita --- a/Symbian3/SDK/Source/GUID-61B965D9-B85E-5F40-8D56-1C0FA77D2492-GENID-1-8-1-3-1-1-8-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,15 +0,0 @@ - - - - - -Using UI Graphics -Utilities (EGUL) and Text Utilities (ETUL)This section explains the Symbian Text Utility components and the -miscellaneous user interface utility functions relating to fonts, colors and -drawing. \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-61B965D9-B85E-5F40-8D56-1C0FA77D2492-GENID-1-8-1-6-1-1-4-1-7-1.dita --- a/Symbian3/SDK/Source/GUID-61B965D9-B85E-5F40-8D56-1C0FA77D2492-GENID-1-8-1-6-1-1-4-1-7-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,15 +0,0 @@ - - - - - -Using UI Graphics -Utilities (EGUL) and Text Utilities (ETUL)This section explains the Symbian Text Utility components and the -miscellaneous user interface utility functions relating to fonts, colors and -drawing. \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-61B965D9-B85E-5F40-8D56-1C0FA77D2492.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-61B965D9-B85E-5F40-8D56-1C0FA77D2492.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,15 @@ + + + + + +Using UI Graphics +Utilities (EGUL) and Text Utilities (ETUL)This section explains the Symbian Text Utility components and the +miscellaneous user interface utility functions relating to fonts, colors and +drawing. \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-61BB12AA-7467-5633-8E4C-54D82AFF0F5E-master.jpg Binary file Symbian3/SDK/Source/GUID-61BB12AA-7467-5633-8E4C-54D82AFF0F5E-master.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-61BB12AA-7467-5633-8E4C-54D82AFF0F5E_d0e185528_href.jpg Binary file Symbian3/SDK/Source/GUID-61BB12AA-7467-5633-8E4C-54D82AFF0F5E_d0e185528_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-61C340D0-9058-45C2-9A90-4AB8E0612872_d0e41032_href.png Binary file Symbian3/SDK/Source/GUID-61C340D0-9058-45C2-9A90-4AB8E0612872_d0e41032_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-61C340D0-9058-45C2-9A90-4AB8E0612872_d0e46589_href.png Binary file Symbian3/SDK/Source/GUID-61C340D0-9058-45C2-9A90-4AB8E0612872_d0e46589_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6262B90B-3F91-517C-B2FA-749C84CE01DE_d0e107083_href.png Binary file Symbian3/SDK/Source/GUID-6262B90B-3F91-517C-B2FA-749C84CE01DE_d0e107083_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6262B90B-3F91-517C-B2FA-749C84CE01DE_d0e113621_href.png Binary file Symbian3/SDK/Source/GUID-6262B90B-3F91-517C-B2FA-749C84CE01DE_d0e113621_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-628A90FC-35F9-51D0-853E-9BECB3C91B59_d0e276648_href.png Binary file Symbian3/SDK/Source/GUID-628A90FC-35F9-51D0-853E-9BECB3C91B59_d0e276648_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-628A90FC-35F9-51D0-853E-9BECB3C91B59_d0e280334_href.png Binary file Symbian3/SDK/Source/GUID-628A90FC-35F9-51D0-853E-9BECB3C91B59_d0e280334_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6290D35A-7A41-5B9E-882A-E14F6D165ED7_d0e332712_href.png Binary file Symbian3/SDK/Source/GUID-6290D35A-7A41-5B9E-882A-E14F6D165ED7_d0e332712_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6290D35A-7A41-5B9E-882A-E14F6D165ED7_d0e338869_href.png Binary file Symbian3/SDK/Source/GUID-6290D35A-7A41-5B9E-882A-E14F6D165ED7_d0e338869_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-631E27DB-97A7-47E2-8FC1-856198435FFF_d0e4681_href.png Binary file Symbian3/SDK/Source/GUID-631E27DB-97A7-47E2-8FC1-856198435FFF_d0e4681_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-631E27DB-97A7-47E2-8FC1-856198435FFF_d0e5956_href.png Binary file Symbian3/SDK/Source/GUID-631E27DB-97A7-47E2-8FC1-856198435FFF_d0e5956_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-63AD2899-FDDC-4E3F-8876-C72EC7C194CE_d0e11012_href.png Binary file Symbian3/SDK/Source/GUID-63AD2899-FDDC-4E3F-8876-C72EC7C194CE_d0e11012_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-63AD2899-FDDC-4E3F-8876-C72EC7C194CE_d0e12287_href.png Binary file Symbian3/SDK/Source/GUID-63AD2899-FDDC-4E3F-8876-C72EC7C194CE_d0e12287_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-63BA04BD-2242-4365-95A1-717569207E92_d0e306657_href.png Binary file Symbian3/SDK/Source/GUID-63BA04BD-2242-4365-95A1-717569207E92_d0e306657_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-63BA04BD-2242-4365-95A1-717569207E92_d0e313051_href.png Binary file Symbian3/SDK/Source/GUID-63BA04BD-2242-4365-95A1-717569207E92_d0e313051_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-63BB9C30-9103-5900-9FD7-5B45FD78A5D7_d0e15172_href.png Binary file Symbian3/SDK/Source/GUID-63BB9C30-9103-5900-9FD7-5B45FD78A5D7_d0e15172_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-63BB9C30-9103-5900-9FD7-5B45FD78A5D7_d0e45518_href.png Binary file Symbian3/SDK/Source/GUID-63BB9C30-9103-5900-9FD7-5B45FD78A5D7_d0e45518_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-63BB9C30-9103-5900-9FD7-5B45FD78A5D7_d0e51074_href.png Binary file Symbian3/SDK/Source/GUID-63BB9C30-9103-5900-9FD7-5B45FD78A5D7_d0e51074_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-63C60154-2A50-5A39-A188-515A607F498B.dita --- a/Symbian3/SDK/Source/GUID-63C60154-2A50-5A39-A188-515A607F498B.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-63C60154-2A50-5A39-A188-515A607F498B.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,42 +1,42 @@ - - - - - -Array -of same length elements, flat bufferDescribes how elements are organised within the array buffer. -

              This can be either an RArray<class T> or a CArrayFixFlat<class T> object.

              -

              In both arrays, all elements:

              -
                -

              • have the same length.

                • -

              • are physically contiguous -within a flat array buffer. The length of an element is the size of the template -class.

                • -
              -

              A flat buffer always occupies a single cell allocated from the heap and -is always extended by the process of reallocation.

              -

              The following diagram illustrates how elements are organised within the -array buffer:

              - - - -

              This kind of array is suitable for a small number of elements or for a -moderately large but fixed maximum number of elements. It is not suitable -for large arrays with a high turnover of elements.

              -

              The RArray<class T> array has the simpler and -more efficient implementation but the length of an element is limited to 640 -bytes. This array can also be constructed on te program stack.

              -

              The CArrayFixFlat<class T> array is more general -and is allocated on the heap. This class is immediately derived from the abstract -templated base class CArrayFix<class T> which is -itself derived from the abstract non-template base class CArrayFixBase. -Its array buffer is implemented using a CBufFlat object.

              -
              See also

              Using -Dynamic Buffers .

              + + + + + +Array +of same length elements, flat bufferDescribes how elements are organised within the array buffer. +

              This can be either an RArray<class T> or a CArrayFixFlat<class T> object.

              +

              In both arrays, all elements:

              +
                +

              • have the same length.

                • +

              • are physically contiguous +within a flat array buffer. The length of an element is the size of the template +class.

                • +
              +

              A flat buffer always occupies a single cell allocated from the heap and +is always extended by the process of reallocation.

              +

              The following diagram illustrates how elements are organised within the +array buffer:

              + + + +

              This kind of array is suitable for a small number of elements or for a +moderately large but fixed maximum number of elements. It is not suitable +for large arrays with a high turnover of elements.

              +

              The RArray<class T> array has the simpler and +more efficient implementation but the length of an element is limited to 640 +bytes. This array can also be constructed on te program stack.

              +

              The CArrayFixFlat<class T> array is more general +and is allocated on the heap. This class is immediately derived from the abstract +templated base class CArrayFix<class T> which is +itself derived from the abstract non-template base class CArrayFixBase. +Its array buffer is implemented using a CBufFlat object.

              +
              See also

              Using +Dynamic Buffers .

               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-63CBD66E-9E92-51EB-8709-9DE6F2808DC8-GENID-1-8-1-18-1-1-4-1-7-1.dita --- a/Symbian3/SDK/Source/GUID-63CBD66E-9E92-51EB-8709-9DE6F2808DC8-GENID-1-8-1-18-1-1-4-1-7-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,29 +0,0 @@ - - - - - -S60 -Platform: Image Converter Example -

              This example demonstrates how to use the image conversion APIs available -in the S60 platform (Image Conversion Library, ICL). These APIs include important -classes, such as CBitmapRotator and CBitmapScaler to be used for rotating -and scaling images, respectively. CImageEncoder and CImageDecoder classes -are used to access image encoders and decoders available in the ICL. Images -can be opened, rotated, scaled, and saved in the same or a different format. -The UI of the updated application has been optimised for touch using, for -example, long taps and tactile feedback. The example project supports building -for both S60 5th Edition with touch UI and S60 3rd Edition with a traditional -keypad. Important classes: CAknLongTapDetector, MTouchFeedback, CBitmapRotator, -CBitmapScaler, CImageEncoder, CImageDecoder, CFbsBitmap, CAknQueryDialog. -For more details, click on this link : ImageConverter..zip file

              -

              The overview contains the following sections:

              -
              Download

              Click -on the following link to download the example: ICLExample.zip file

              Click: browse to view the example code.

              -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-63CBD66E-9E92-51EB-8709-9DE6F2808DC8-GENID-1-8-1-18-1-1-5-1-6-1-5-1-3-1.dita --- a/Symbian3/SDK/Source/GUID-63CBD66E-9E92-51EB-8709-9DE6F2808DC8-GENID-1-8-1-18-1-1-5-1-6-1-5-1-3-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,29 +0,0 @@ - - - - - -S60 -Platform: Image Converter Example -

              This example demonstrates how to use the image conversion APIs available -in the S60 platform (Image Conversion Library, ICL). These APIs include important -classes, such as CBitmapRotator and CBitmapScaler to be used for rotating -and scaling images, respectively. CImageEncoder and CImageDecoder classes -are used to access image encoders and decoders available in the ICL. Images -can be opened, rotated, scaled, and saved in the same or a different format. -The UI of the updated application has been optimised for touch using, for -example, long taps and tactile feedback. The example project supports building -for both S60 5th Edition with touch UI and S60 3rd Edition with a traditional -keypad. Important classes: CAknLongTapDetector, MTouchFeedback, CBitmapRotator, -CBitmapScaler, CImageEncoder, CImageDecoder, CFbsBitmap, CAknQueryDialog. -For more details, click on this link : ImageConverter..zip file

              -

              The overview contains the following sections:

              -
              Download

              Click -on the following link to download the example: ICLExample.zip file

              Click: browse to view the example code.

              -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6408C26A-2736-59A9-B785-6B119143619B.dita --- a/Symbian3/SDK/Source/GUID-6408C26A-2736-59A9-B785-6B119143619B.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-6408C26A-2736-59A9-B785-6B119143619B.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,76 +1,76 @@ - - - - - -How -to use a thread-death notifierDescribes the thread-death notifier and provides a code snippet -to show you how to use it. -

              To use a thread-death notifier, a thread which needs to know about the -death of other threads:

              -
                -

              • constructs an RUndertaker handle -and then calls its Create() member function to create the -associated Kernel side object. The RUndertaker handle is process-relative which -means that the handle is not closed if the requesting thread dies.

                • -

              • issues a notification -request to the thread-death notifier, passing a reference to a TRequestStatus object -and a reference to a TInt.

                • -
              -

              When any other thread dies, the requesting thread's request semaphore is -signalled to indicate that the notification request is complete. The TRequestStatus object -supplied by the requesting thread is set to KErrDied.

              -

              In addition, the Kernel opens a local thread-relative handle on the dying -thread. (thread-relative, here, means relative to the requesting thread) and -sets the TInt, supplied by the requesting thread, to the -resulting handle-number. The requesting thread can construct an RThread from -this handle-number. The following diagram helps visualise the situation.

              - - Thread-death notifier - - -

              The following code fragments demonstrate this:

              -{ -... -RUndertaker the_undertaker; -TRequestStatus the_status; -TInt the_dyingthread_handle_number; -... -the_undertaker.Create(); -the_undertaker.Logon(the_status,the_dyingthread_handle_number); -User::WaitForRequest(the_status); -... -...// prepare for a long wait -... -RThread r; -r.SetHandle(the_dyingthread_handle_number); -... -...// Now have an open thread-relative handle to the -...// dying thread so we can, for example, ... -if (r.ExitReason()==0x666) - { - ... - } -...// We have an open handle on the dying thread; the dying thread -...// remains in existence until we close it. -r.Close(); -... -} -

              In practical code, an RUndertaker is used by an active -object.

              -

              The RUndertaker handle also offers a LogonCancel() function. -Calling this function, causes the requesting thread's request semaphore to -be signalled and any wait to complete. The TRequestStatus is -set to KErrCancel.

              -

              This technique of using an RUndertaker is not guaranteed -to report the death of all threads. In particular, if a second thread dies -while a requesting thread is handling the request completion due to the death -of a first thread (but before it can make another notification request), the -death of this second thread will go unnoticed.

              + + + + + +How +to use a thread-death notifierDescribes the thread-death notifier and provides a code snippet +to show you how to use it. +

              To use a thread-death notifier, a thread which needs to know about the +death of other threads:

              +
                +

              • constructs an RUndertaker handle +and then calls its Create() member function to create the +associated Kernel side object. The RUndertaker handle is process-relative which +means that the handle is not closed if the requesting thread dies.

                • +

              • issues a notification +request to the thread-death notifier, passing a reference to a TRequestStatus object +and a reference to a TInt.

                • +
              +

              When any other thread dies, the requesting thread's request semaphore is +signalled to indicate that the notification request is complete. The TRequestStatus object +supplied by the requesting thread is set to KErrDied.

              +

              In addition, the Kernel opens a local thread-relative handle on the dying +thread. (thread-relative, here, means relative to the requesting thread) and +sets the TInt, supplied by the requesting thread, to the +resulting handle-number. The requesting thread can construct an RThread from +this handle-number. The following diagram helps visualise the situation.

              + + Thread-death notifier + + +

              The following code fragments demonstrate this:

              +{ +... +RUndertaker the_undertaker; +TRequestStatus the_status; +TInt the_dyingthread_handle_number; +... +the_undertaker.Create(); +the_undertaker.Logon(the_status,the_dyingthread_handle_number); +User::WaitForRequest(the_status); +... +...// prepare for a long wait +... +RThread r; +r.SetHandle(the_dyingthread_handle_number); +... +...// Now have an open thread-relative handle to the +...// dying thread so we can, for example, ... +if (r.ExitReason()==0x666) + { + ... + } +...// We have an open handle on the dying thread; the dying thread +...// remains in existence until we close it. +r.Close(); +... +} +

              In practical code, an RUndertaker is used by an active +object.

              +

              The RUndertaker handle also offers a LogonCancel() function. +Calling this function, causes the requesting thread's request semaphore to +be signalled and any wait to complete. The TRequestStatus is +set to KErrCancel.

              +

              This technique of using an RUndertaker is not guaranteed +to report the death of all threads. In particular, if a second thread dies +while a requesting thread is handling the request completion due to the death +of a first thread (but before it can make another notification request), the +death of this second thread will go unnoticed.

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-643AFF2D-3EDB-5FAB-9631-7B93FABC56B6_d0e184568_href.png Binary file Symbian3/SDK/Source/GUID-643AFF2D-3EDB-5FAB-9631-7B93FABC56B6_d0e184568_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-643AFF2D-3EDB-5FAB-9631-7B93FABC56B6_d0e191164_href.png Binary file Symbian3/SDK/Source/GUID-643AFF2D-3EDB-5FAB-9631-7B93FABC56B6_d0e191164_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-644810EC-7D5E-4569-834B-C207447B88A3.dita --- a/Symbian3/SDK/Source/GUID-644810EC-7D5E-4569-834B-C207447B88A3.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,60 +0,0 @@ - - - - - -Multitasking -

              The Symbian UI style allows multitasking; that is, working with more than -one application simultaneously. Mobile device users can leave an application -running when they start another application, swap between running applications, -and interact with them.

              -

              To open a new application without closing the one that is presently being -used, users can press the Home / Menu key to go to the Menu and -select application suites and applications.

              -

              The first application process remains running in the background while the -user interacts with the second application.

              -

              The number of simultaneously running (different) applications is limited -only by the available memory in the device. When a new application process -cannot be created because of limited memory, the system can automatically -shut down applications to increase the amount of free memory.

              -

              To swap active applications, users can:

              -
                -

              • Long-press the Home / Menu key to open the task swapping window.

                • -

              • Alternatively, select Options > Show -open applications to open the task swapping window.

                • -
              - -Visualized multitasking: task swapping window - - -

              The task swapping window displays the applications that are currently running -in the order of their most recent use. By default, the focus is on the first -item in the grid. The task swapping window is a pop-up with a heading (Open -applications). The names of the open applications are displayed -in an Information pop-up. The Information pop-up is launched with a 0.5 second -delay after the focus is moved onto each item, and it remains visible for -1.5 seconds (or until the focus is moved to another item). Menu and home screen -are always visible in the task swapping window. The configuration and visual -appearance of the task swapping window might depend on the product.

              -

              Users can use the task swapping window to close active applications. In -devices with a keypad, users move the focus onto the application to be closed, -and press the Clear (delete) key. In touch devices, -users tap and hold the item to open a pop-up menu where they can select the Exit option.

              -

              For implementation information on -using the application -and UI frameworks, see Window -server events.

              -               - -Application -framework concepts -Framework -requirements for GUI applications - -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-646C2A7A-B90C-5E82-B44F-EA24DDBB1EC5_d0e111639_href.png Binary file Symbian3/SDK/Source/GUID-646C2A7A-B90C-5E82-B44F-EA24DDBB1EC5_d0e111639_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-646C2A7A-B90C-5E82-B44F-EA24DDBB1EC5_d0e118177_href.png Binary file Symbian3/SDK/Source/GUID-646C2A7A-B90C-5E82-B44F-EA24DDBB1EC5_d0e118177_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-64AC6F53-A9A5-46FD-BCC6-4A9BD8D4DB5C.dita --- a/Symbian3/SDK/Source/GUID-64AC6F53-A9A5-46FD-BCC6-4A9BD8D4DB5C.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-64AC6F53-A9A5-46FD-BCC6-4A9BD8D4DB5C.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,123 +1,123 @@ - - - - - -Compensating -Sensor Data for Display OrientationYou can use the sensor data compensator APIs to correct the display -and device orientation data. -

              Before you begin -using the sensor data compensator APIs, you must do the following:

                -

              1. Open a Sensor Channel -for communication. For details, see Using -Sensor Channels APIs

                2. -

              2. Implement the data listener -interface. For details see, Receiving -Data from Sensors

                3. -

              3. Register as a listener -with any of the sensor types using an instance of CSensrvChannel.

                4. -

              4. Ensure that the data -received from the sensor channel is not already compensated using the CSensrvChannel::GetPropertyL() function, -as shown in the following example:

                // 'iChannel' contains an open channel -TSensrvProperty property; -TRAPD( err, iChannel->GetPropertyL( KSensrvPropIdChannelDataCompensation, KSensrvItemIndexNone, property ) ); -if ( err == KErrNone && property.PropertyType() == ESensrvIntProperty ) - { - // Channel data is compensated, check the compensation type - TInt compensationType; - property.GetValue( compensationType ); - // 'compensationType' contains now a value from TSensorCompensationType enumeration declared in sensordatacompensationtypes.h - } -else - { - // Channel data is not compensated - }

                For more information, see Retrieving -channel properties .

                5. -
               -

              The sensor -data compensator APIs allows you to compensate sensor data values, based on:

                -

              • Display Orientation, when the display is changed from portrait to landscape.

                • -

              • Device Orientation, when the keyboard is opened, resulting in the display -being set at an angle to the keyboard. For example, N97.

                • -
               - -Create an instance -of CSensorDataCompensator. -iCompensator = CSensorDataCompensator::NewL(TSensrvAccelerometerAxisData::KDataTypeId,ESensorCompensateDeviceAndUIOrientation); - -Use the CSensorDataCompensator::Compensate() function -to correct the sensor data received from the following channel types and related -classes: - - - - -Sensor Channel Type -Data Class - - - - -Accelerometer axis data -TSensrvAccelerometerAxisData - - -Magnetometer axis data -TSensrvMagnetometerAxisData - - -Accelerometer double-tap -TSensrvTappingData - - - -
               -               -               -Example

              The following example illustrates the usage -of sensor data compensator APIs to correct axis data received from accelerometer -sensor.

              #include <sensordatacompensator.h> // link against sensordatacompensator.lib - -void CMyClass::ConstructL() - - { - // iSensorChannel already instantiated and registered - if ( !AlreadyCompensated() ) - { - iCompensator = CSensorDataCompensator::NewL( - TSensrvAccelerometerAxisData::KDataTypeId, - ESensorCompensateDeviceAndUIOrientation ); - } - } - -CMyClass::~CMyClass() - - { - delete iCompensator; - } - -void CMyClass::DataReceived( CSensrvChannel& aChannel, - - TInt /*aCount*/, - TInt /*aDataLost*/ ) - { - - TPckgBuf <TSensrvAccelerometerAxisData> dataBuf; - iSensorChannel -> GetData( dataBuf ); - - if ( iCompensator ) - { - if ( iCompensator->Compensate( dataBuf ) == KErrNone ) - { - // Now use the compensated data. - } - }               -

              End the session -with the sensor channel using the CSensrvChannel::CloseChannel() function.

               + + + + + +Compensating +Sensor Data for Display OrientationYou can use the sensor data compensator APIs to correct the display +and device orientation data. +

              Before you begin +using the sensor data compensator APIs, you must do the following:

                +

              1. Open a Sensor Channel +for communication. For details, see Using +Sensor Channels APIs

                2. +

              2. Implement the data listener +interface. For details see, Receiving +Data from Sensors

                3. +

              3. Register as a listener +with any of the sensor types using an instance of CSensrvChannel.

                4. +

              4. Ensure that the data +received from the sensor channel is not already compensated using the CSensrvChannel::GetPropertyL() function, +as shown in the following example:

                // 'iChannel' contains an open channel +TSensrvProperty property; +TRAPD( err, iChannel->GetPropertyL( KSensrvPropIdChannelDataCompensation, KSensrvItemIndexNone, property ) ); +if ( err == KErrNone && property.PropertyType() == ESensrvIntProperty ) + { + // Channel data is compensated, check the compensation type + TInt compensationType; + property.GetValue( compensationType ); + // 'compensationType' contains now a value from TSensorCompensationType enumeration declared in sensordatacompensationtypes.h + } +else + { + // Channel data is not compensated + }

                For more information, see Retrieving +channel properties .

                5. +
               +

              The sensor +data compensator APIs allows you to compensate sensor data values, based on:

                +

              • Display Orientation, when the display is changed from portrait to landscape.

                • +

              • Device Orientation, when the keyboard is opened, resulting in the display +being set at an angle to the keyboard. For example, N97.

                • +
               + +Create an instance +of CSensorDataCompensator. +iCompensator = CSensorDataCompensator::NewL(TSensrvAccelerometerAxisData::KDataTypeId,ESensorCompensateDeviceAndUIOrientation); + +Use the CSensorDataCompensator::Compensate() function +to correct the sensor data received from the following channel types and related +classes: + + + + +Sensor Channel Type +Data Class + + + + +Accelerometer axis data +TSensrvAccelerometerAxisData + + +Magnetometer axis data +TSensrvMagnetometerAxisData + + +Accelerometer double-tap +TSensrvTappingData + + + +
               +               +               +Example

              The following example illustrates the usage +of sensor data compensator APIs to correct axis data received from accelerometer +sensor.

              #include <sensordatacompensator.h> // link against sensordatacompensator.lib + +void CMyClass::ConstructL() + + { + // iSensorChannel already instantiated and registered + if ( !AlreadyCompensated() ) + { + iCompensator = CSensorDataCompensator::NewL( + TSensrvAccelerometerAxisData::KDataTypeId, + ESensorCompensateDeviceAndUIOrientation ); + } + } + +CMyClass::~CMyClass() + + { + delete iCompensator; + } + +void CMyClass::DataReceived( CSensrvChannel& aChannel, + + TInt /*aCount*/, + TInt /*aDataLost*/ ) + { + + TPckgBuf <TSensrvAccelerometerAxisData> dataBuf; + iSensorChannel -> GetData( dataBuf ); + + if ( iCompensator ) + { + if ( iCompensator->Compensate( dataBuf ) == KErrNone ) + { + // Now use the compensated data. + } + }               +

              End the session +with the sensor channel using the CSensrvChannel::CloseChannel() function.

                             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-64BDD1DA-6B93-5F45-8CBD-7DBAF92CC4C7_d0e262462_href.png Binary file Symbian3/SDK/Source/GUID-64BDD1DA-6B93-5F45-8CBD-7DBAF92CC4C7_d0e262462_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-64BDD1DA-6B93-5F45-8CBD-7DBAF92CC4C7_d0e266170_href.png Binary file Symbian3/SDK/Source/GUID-64BDD1DA-6B93-5F45-8CBD-7DBAF92CC4C7_d0e266170_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-64D2B0E2-BB5D-4009-ACE5-7A3503016341.dita --- a/Symbian3/SDK/Source/GUID-64D2B0E2-BB5D-4009-ACE5-7A3503016341.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-64D2B0E2-BB5D-4009-ACE5-7A3503016341.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,254 +1,254 @@ - - - - - -Troubleshooting -TipsThis section addresses the basic differences in the way things -are done in Symbian Platform and in Linux. -
              Symbian -directory structure

              In Symbian platform, project source files -are arranged based on the directory pattern shown below.

              - - - -

              Directory

               -

              Description

               -               - -src -

              Contains all the source files of the project.

               -               - -inc -

              Contains all the header files of the project.

               -               - -group -

              Contains MMP files, and bld.inf.

              -               - - -

              The developer can choose whether to follow these tips.

              -
              EXPORT_C, -DEF file and ordinal numbers

              This applies only for the DLL -target type. If a DLL wants to export an API, the code definition should start -with the macro EXPORT_C.

              // Declaration -#ifdef SYMBIAN -#define GLOBAL(type) EXPORT_C type -#else -#define GLOBAL(type) type -#endif // SYMBIAN - // Definition - GLOBAL(void) - jpeg_CreateDecompress (j_decompress_ptr cinfo, int version, size_t structsize) - { - int i; - - /* Guard against version mismatches between library and caller. */ - cinfo->mem = NULL; /* so jpeg_destroy knows mem mgr not called */ - if (version != JPEG_LIB_VERSION) - ERREXIT2(cinfo, JERR_BAD_LIB_VERSION, JPEG_LIB_VERSION, version); - if (structsize != SIZEOF(struct jpeg_decompress_struct)) - ERREXIT2(cinfo, JERR_BAD_STRUCT_SIZE, - (int) SIZEOF(struct jpeg_decompress_struct), (int) structsize); - ... - }

              Whenever a DLL is built on Symbian platform, it creates -three files:

                -

              • <target>.dll is the actual DLL that gets loaded -at runtime

                • -

              • <target>.lib is the static library which contains -wrappers for each DLL exported function that, when run, will locate and execute -the real function’s code in the appropriate runtime-loaded DLL.

                • -

              • <target.def> gets created when the user executes -abld freeze. The .def file contains the list of exported -DLL functions along with their ordinal numbers. Symbian platform does not -store exported symbol names in DLL; instead, the exported functions are referenced -using only their ordinal numbers. Storing the ordinal numbers instead of names -reduces the size of the DLL.

                • -

              The following is a sample .def file created for libjpeg:

              EXPORTS -jcopy_block_row @ 1 NONAME -jcopy_sample_rows @ 2 NONAME -jdiv_round_up @ 3 NONAME -jinit_1pass_quantizer @ 4 NONAME -jinit_2pass_quantizer @ 5 NONAME -jinit_c_coef_controller @ 6 NONAME -jinit_c_main_controller @ 7 NONAME -jinit_c_master_control @ 8 NONAME -jinit_c_prep_controller @ 9 NONAME -jinit_color_converter @ 10 NONAME -

              The following example shows how to declare and define an exportable -function from a DLL and to make it callable from a Symbian C++ application: -

              In xxx.h

              #ifdef __cplusplus -extern "C" -#endif -IMPORT_C int Foo(); -

              In xxx.c

              extern "C" EXPORT_C int Foo() - { - return something; - } -
              -
              <codeph>dlsym()</codeph> or <codeph>g_module_symbol()</codeph> -

              Since DLL entry points are not exported by name, DLL symbol lookup -functions do not work on Symbian platform. For more information about alternatives -suggested on Symbian platform, see Dynamic -Link Libraries.

              The functions dlsym() from libdl and g_module_symbol() from GLib are examples of such functions. Look for usage of these functions -in the OSS port and change the code.

              ret = g_module_symbol (module, "jinit_c_prep_controller", &ptr); -

              needs to be changed to:

              ret = g_module_symbol (module, "9", &ptr);

              For -example, for dlsym() pass the function's ordinal number as -symbol parameter (refer the library's list of exports, the DEF file for the -function's ordinal number):

              dlsym(&handle, "foo") -

              needs to be changed to:

              dlsym (&handle, "3")
              -
              Problem with -a variable list of arguments in macros

              This section suggests a way -to overcome the problems faced when macros with a variable list of arguments -are used.

              #define DEBUG(a,...)

              The above statement -causes a compilation error. One of the solutions to solve this problem is -as follows:

              #define DEBUG _DEBUG -static inline void _DEBUG (const char *a, ...) -{ -}
              -
              Keep -changes to OSS to a minimum

              While porting the OSS code, keep the -changes to the OSS code as few as possible. The OSS code is already tested -and used by a bigger community, and is unlikely to have any compilation errors -or major logical errors. In many cases code changes that are necessary brings -potential logical flaws to the OSS port. Minimum changes to the OSS code while -porting also helps in merging to the new OSS.

              -
              Exporting -variables from a DLL

              Exporting data from a DLL is not allowed -in Symbian platform . The following pattern can be used:

                -

              1. Do not export global -variables. Within DLL, there is one global variable, for example:

                int globalVal;
                2. -

              2. Export one method -that returns a pointer to that variable.

                extern "C" EXPORT_C int* GlbData () - { - return &globalVal - } -
                3. -

              3. Define a macro for the -user of the DLL. See the example below. Within the DLL header (for example, xxx.h), -define the following:

                #ifdef __cplusplus -extern "C" -#endif -IMPORT_C int* GlbData (); -#define globalVal (*GlbData())
                4. -
              -
              Application -is not loaded

              The absence of the dependent libraries could -be one of the reasons for the application not to load in the mobile device. -On the target device, Symbian platform looks for libraries in c:\sys\bin or -in z:\sys\bin.

              Do make sure that all the libraries -are present in either of the above-mentioned libraries.

              -
              Capabilities -not known

              Capabilities are specified in the MMP file. The -primary information source is the P.I.P.S. API reference documentation. If -problems with capabilities remain, one known method to find the capability -is to analyze the [Debug Messages] window in CodeWarrior IDE (while debugging). -During development, CAPABILITY All –Tcb is acceptable, but -for release code it is good practice to give a valid capability in the MMP -file in order to have the application successfully signed. The following is -a sample of a capability error found in the [Debug Messages] window.

              *PlatSec* ERROR - Capability check failed - Process hellogst.exe[10015942]0001 was checked by Thread c32exe.exe[101f7989]0001::ESock_IP and was found to be missing the capabilities: NetworkServices.
              -
              Environment -variables

              At the moment, environment variables are not completely -supported in Symbian C++. Therefore be wary of using library functions like getenv() which -work on environment variables. Make sure the library initialization routine -calls setenv() with the proper value of the environment variable. -Also, be wary of functions like g_get_home_dir() which may -not work as they behave in Linux.

              if ((memenv = getenv("JPEGMEM")) != NULL) // will not work properly

              Suggested -change:

              void LibraryInit() -{ - setenv ("JPEGMEM ", "XXXXX", 1); -}
              -
              Assembly -code

              The syntax for inline assembly code is different in -Symbian platform. The following is a code snippet of assembly code syntax -in Symbian platform.

              EXPORT_C __NAKED__ TUint16 TTemplate::Register16(TUint anAddr) -/** - Read a 16-bit register - @returns register contents -*/ - { - asm("ldrh r0,[r0]"); - __JUMP(,lr); - }

              In common practice the assembly code has the extension .CIA in -Symbian platform, whereas in Linux the assembly code has the extension .S. -

              -
              Glossary -

              The following table lists terms used in Linux and their approximate -equivalents in Symbian platform:

              - - - -

              Linux

               -

              Symbian

               -               - -

              -D of Makefile

              -

              MACRO of theMMP file

              -               - -

              -I of Makefile

               -

              USERINCLUDE of the MMP file

              -               - -

              SO

               -

              DLL

               -               - -

              A

               -

              LIB

               -               - -

              Makefile

               -

              MMP file

               -               - -

              SOURCES of Makefile

              -

              SOURCE of the MMP file

              -               - -

              /usr/include/

               -

              \EPOC32\INCLUDE

               -               - -

              /usr/lib/

               -

              \epoc32\data\c\sys\bin on an emulator, \sys\bin on -a target device

               -               - - -

              The following table lists a few important things about the Symbian -platform:

              - - - -

              ABI_DIR

               -

              Platform, for example winscw or armv5

               -               - -

              BUILD_DIR

               -

              UDEB or UREL

               -               - -

              c: drive in emulator

              -

              \epoc32\data\c and \epoc32\winscw\c

               -               - -

              z: drive in emulator

               -

              Z:\epoc32\data\z

               -               - -

              bld.inf

               -

              Lists public header files and their location in \EPOC32\INCLUDE

               -               - - -
              + + + + + +Troubleshooting +TipsThis section addresses the basic differences in the way things +are done in Symbian Platform and in Linux. +
              Symbian +directory structure

              In Symbian platform, project source files +are arranged based on the directory pattern shown below.

              + + + +

              Directory

               +

              Description

               +               + +src +

              Contains all the source files of the project.

               +               + +inc +

              Contains all the header files of the project.

               +               + +group +

              Contains MMP files, and bld.inf.

              +               + + +

              The developer can choose whether to follow these tips.

              +
              EXPORT_C, +DEF file and ordinal numbers

              This applies only for the DLL +target type. If a DLL wants to export an API, the code definition should start +with the macro EXPORT_C.

              // Declaration +#ifdef SYMBIAN +#define GLOBAL(type) EXPORT_C type +#else +#define GLOBAL(type) type +#endif // SYMBIAN + // Definition + GLOBAL(void) + jpeg_CreateDecompress (j_decompress_ptr cinfo, int version, size_t structsize) + { + int i; + + /* Guard against version mismatches between library and caller. */ + cinfo->mem = NULL; /* so jpeg_destroy knows mem mgr not called */ + if (version != JPEG_LIB_VERSION) + ERREXIT2(cinfo, JERR_BAD_LIB_VERSION, JPEG_LIB_VERSION, version); + if (structsize != SIZEOF(struct jpeg_decompress_struct)) + ERREXIT2(cinfo, JERR_BAD_STRUCT_SIZE, + (int) SIZEOF(struct jpeg_decompress_struct), (int) structsize); + ... + }

              Whenever a DLL is built on Symbian platform, it creates +three files:

                +

              • <target>.dll is the actual DLL that gets loaded +at runtime

                • +

              • <target>.lib is the static library which contains +wrappers for each DLL exported function that, when run, will locate and execute +the real function’s code in the appropriate runtime-loaded DLL.

                • +

              • <target.def> gets created when the user executes +abld freeze. The .def file contains the list of exported +DLL functions along with their ordinal numbers. Symbian platform does not +store exported symbol names in DLL; instead, the exported functions are referenced +using only their ordinal numbers. Storing the ordinal numbers instead of names +reduces the size of the DLL.

                • +

              The following is a sample .def file created for libjpeg:

              EXPORTS +jcopy_block_row @ 1 NONAME +jcopy_sample_rows @ 2 NONAME +jdiv_round_up @ 3 NONAME +jinit_1pass_quantizer @ 4 NONAME +jinit_2pass_quantizer @ 5 NONAME +jinit_c_coef_controller @ 6 NONAME +jinit_c_main_controller @ 7 NONAME +jinit_c_master_control @ 8 NONAME +jinit_c_prep_controller @ 9 NONAME +jinit_color_converter @ 10 NONAME +

              The following example shows how to declare and define an exportable +function from a DLL and to make it callable from a Symbian C++ application: +

              In xxx.h

              #ifdef __cplusplus +extern "C" +#endif +IMPORT_C int Foo(); +

              In xxx.c

              extern "C" EXPORT_C int Foo() + { + return something; + } +
              +
              <codeph>dlsym()</codeph> or <codeph>g_module_symbol()</codeph> +

              Since DLL entry points are not exported by name, DLL symbol lookup +functions do not work on Symbian platform. For more information about alternatives +suggested on Symbian platform, see Dynamic +Link Libraries.

              The functions dlsym() from libdl and g_module_symbol() from GLib are examples of such functions. Look for usage of these functions +in the OSS port and change the code.

              ret = g_module_symbol (module, "jinit_c_prep_controller", &ptr); +

              needs to be changed to:

              ret = g_module_symbol (module, "9", &ptr);

              For +example, for dlsym() pass the function's ordinal number as +symbol parameter (refer the library's list of exports, the DEF file for the +function's ordinal number):

              dlsym(&handle, "foo") +

              needs to be changed to:

              dlsym (&handle, "3")
              +
              Problem with +a variable list of arguments in macros

              This section suggests a way +to overcome the problems faced when macros with a variable list of arguments +are used.

              #define DEBUG(a,...)

              The above statement +causes a compilation error. One of the solutions to solve this problem is +as follows:

              #define DEBUG _DEBUG +static inline void _DEBUG (const char *a, ...) +{ +}
              +
              Keep +changes to OSS to a minimum

              While porting the OSS code, keep the +changes to the OSS code as few as possible. The OSS code is already tested +and used by a bigger community, and is unlikely to have any compilation errors +or major logical errors. In many cases code changes that are necessary brings +potential logical flaws to the OSS port. Minimum changes to the OSS code while +porting also helps in merging to the new OSS.

              +
              Exporting +variables from a DLL

              Exporting data from a DLL is not allowed +in Symbian platform . The following pattern can be used:

                +

              1. Do not export global +variables. Within DLL, there is one global variable, for example:

                int globalVal;
                2. +

              2. Export one method +that returns a pointer to that variable.

                extern "C" EXPORT_C int* GlbData () + { + return &globalVal + } +
                3. +

              3. Define a macro for the +user of the DLL. See the example below. Within the DLL header (for example, xxx.h), +define the following:

                #ifdef __cplusplus +extern "C" +#endif +IMPORT_C int* GlbData (); +#define globalVal (*GlbData())
                4. +
              +
              Application +is not loaded

              The absence of the dependent libraries could +be one of the reasons for the application not to load in the mobile device. +On the target device, Symbian platform looks for libraries in c:\sys\bin or +in z:\sys\bin.

              Do make sure that all the libraries +are present in either of the above-mentioned libraries.

              +
              Capabilities +not known

              Capabilities are specified in the MMP file. The +primary information source is the P.I.P.S. API reference documentation. If +problems with capabilities remain, one known method to find the capability +is to analyze the [Debug Messages] window in CodeWarrior IDE (while debugging). +During development, CAPABILITY All –Tcb is acceptable, but +for release code it is good practice to give a valid capability in the MMP +file in order to have the application successfully signed. The following is +a sample of a capability error found in the [Debug Messages] window.

              *PlatSec* ERROR - Capability check failed - Process hellogst.exe[10015942]0001 was checked by Thread c32exe.exe[101f7989]0001::ESock_IP and was found to be missing the capabilities: NetworkServices.
              +
              Environment +variables

              At the moment, environment variables are not completely +supported in Symbian C++. Therefore be wary of using library functions like getenv() which +work on environment variables. Make sure the library initialization routine +calls setenv() with the proper value of the environment variable. +Also, be wary of functions like g_get_home_dir() which may +not work as they behave in Linux.

              if ((memenv = getenv("JPEGMEM")) != NULL) // will not work properly

              Suggested +change:

              void LibraryInit() +{ + setenv ("JPEGMEM ", "XXXXX", 1); +}
              +
              Assembly +code

              The syntax for inline assembly code is different in +Symbian platform. The following is a code snippet of assembly code syntax +in Symbian platform.

              EXPORT_C __NAKED__ TUint16 TTemplate::Register16(TUint anAddr) +/** + Read a 16-bit register + @returns register contents +*/ + { + asm("ldrh r0,[r0]"); + __JUMP(,lr); + }

              In common practice the assembly code has the extension .CIA in +Symbian platform, whereas in Linux the assembly code has the extension .S. +

              +
              Glossary +

              The following table lists terms used in Linux and their approximate +equivalents in Symbian platform:

              + + + +

              Linux

               +

              Symbian

               +               + +

              -D of Makefile

              +

              MACRO of theMMP file

              +               + +

              -I of Makefile

               +

              USERINCLUDE of the MMP file

              +               + +

              SO

               +

              DLL

               +               + +

              A

               +

              LIB

               +               + +

              Makefile

               +

              MMP file

               +               + +

              SOURCES of Makefile

              +

              SOURCE of the MMP file

              +               + +

              /usr/include/

               +

              \EPOC32\INCLUDE

               +               + +

              /usr/lib/

               +

              \epoc32\data\c\sys\bin on an emulator, \sys\bin on +a target device

               +               + + +

              The following table lists a few important things about the Symbian +platform:

              + + + +

              ABI_DIR

               +

              Platform, for example winscw or armv5

               +               + +

              BUILD_DIR

               +

              UDEB or UREL

               +               + +

              c: drive in emulator

              +

              \epoc32\data\c and \epoc32\winscw\c

               +               + +

              z: drive in emulator

               +

              Z:\epoc32\data\z

               +               + +

              bld.inf

               +

              Lists public header files and their location in \EPOC32\INCLUDE

               +               + + +
               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6501FAFF-6E21-5BC8-BA85-B1B4CE1AC6A7-GENID-1-8-1-3-1-1-8-1-6-1.dita --- a/Symbian3/SDK/Source/GUID-6501FAFF-6E21-5BC8-BA85-B1B4CE1AC6A7-GENID-1-8-1-3-1-1-8-1-6-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,88 +0,0 @@ - - - - - -Phone -number utility overview -
              Purpose

              The -Phone Number Utility is part of the Symbian Text Utility Component (etul.dll) -and it offers methods for parsing and validating phone numbers.

              Examples -of valid phone numbers:

                -

              • 1. +358501234567

                • -

              • 2. +358 (50) 123 4567

                • -

              Even though both of the above examples are valid phone numbers, only -the first one is accepted as a phone number by many systems. To convert the -second number to the first number, parsing methods of Phone Number Utility -can be used.

              -
              Architectural -Relationships

              The TulPhoneNumberUtils class -implements the static methods that make up the interface.

              Phone Number -Utility can be accessed through the TulPhoneNumberUtils class -that is defined in the header tulphonenumberutils.h. This -utility is linked to the etul.lib library.

              -
              Description

              Method -Information

              The enumerated type TPhoneNumberType is -used to specify the type of phone number for some of the methods below.

              - - - -Method name -Details - - - - -

              static TBool ParsePhoneNumber(TDes& aNumber, - TPhoneNumberType aType)

              -

              Removes irrelevant characters and white space from the supplied -phone number. Allowed characters are determined by phone number type, in other -words, the aType parameter. For example, parsing the number +358 -(40) 123 467 results in the number +35840123467.

              -               - -

              static TBool IsValidPhoneNumber(const TDesC& aNumber, - TPhoneNumberType aType)

              -

              Checks if the supplied phone number is a valid phone number of the -supplied type.

              -               - -

              TBool IsValidPhoneNumber(const TDesC& aNumber, const - TDesC& aValidChars)

              -

              Checks if the supplied phone number is a valid phone number. The -phone number is valid if it contains only characters specified by the parameter aValidChars.

              -               - -

              static void ParseInvalidChars(TDes& aNumber, const - TDesC& aInvalidChars)

              -

              Removes the specified invalid characters from the supplied phone -number string.

              -               - - -

              Example

              The following example shows how to use -the TulPhoneNumberUtils class parsing methods:

              TBuf<50> number = _L("+358 (40) 123 132"); -TBool validNumber = TulPhoneNumberUtils::ParsePhoneNumber(number, - TulPhoneNumberUtils::EPlainPhoneNumber ); -// validNumber == ETrue; -// number == "+35840123132" - -SendSMS(number) // etc.. - -// OR - -TBuf<50> number = _L("+358 (40) 123p132"); // note 'p' -TBool validNumber = TulPhoneNumberUtils::ParsePhoneNumber(number, - TulPhoneNumberUtils::EPlainPhoneNumber ); - -// validNumber == EFalse; -// number == "+358 (40) 123p132" // unchanged -

              For more information on individual methods, please see the -reference API for TulPhoneNumberUtils

              -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6501FAFF-6E21-5BC8-BA85-B1B4CE1AC6A7-GENID-1-8-1-6-1-1-4-1-7-1-6-1.dita --- a/Symbian3/SDK/Source/GUID-6501FAFF-6E21-5BC8-BA85-B1B4CE1AC6A7-GENID-1-8-1-6-1-1-4-1-7-1-6-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,88 +0,0 @@ - - - - - -Phone -number utility overview -
              Purpose

              The -Phone Number Utility is part of the Symbian Text Utility Component (etul.dll) -and it offers methods for parsing and validating phone numbers.

              Examples -of valid phone numbers:

                -

              • 1. +358501234567

                • -

              • 2. +358 (50) 123 4567

                • -

              Even though both of the above examples are valid phone numbers, only -the first one is accepted as a phone number by many systems. To convert the -second number to the first number, parsing methods of Phone Number Utility -can be used.

              -
              Architectural -Relationships

              The TulPhoneNumberUtils class -implements the static methods that make up the interface.

              Phone Number -Utility can be accessed through the TulPhoneNumberUtils class -that is defined in the header tulphonenumberutils.h. This -utility is linked to the etul.lib library.

              -
              Description

              Method -Information

              The enumerated type TPhoneNumberType is -used to specify the type of phone number for some of the methods below.

              - - - -Method name -Details - - - - -

              static TBool ParsePhoneNumber(TDes& aNumber, - TPhoneNumberType aType)

              -

              Removes irrelevant characters and white space from the supplied -phone number. Allowed characters are determined by phone number type, in other -words, the aType parameter. For example, parsing the number +358 -(40) 123 467 results in the number +35840123467.

              -               - -

              static TBool IsValidPhoneNumber(const TDesC& aNumber, - TPhoneNumberType aType)

              -

              Checks if the supplied phone number is a valid phone number of the -supplied type.

              -               - -

              TBool IsValidPhoneNumber(const TDesC& aNumber, const - TDesC& aValidChars)

              -

              Checks if the supplied phone number is a valid phone number. The -phone number is valid if it contains only characters specified by the parameter aValidChars.

              -               - -

              static void ParseInvalidChars(TDes& aNumber, const - TDesC& aInvalidChars)

              -

              Removes the specified invalid characters from the supplied phone -number string.

              -               - - -

              Example

              The following example shows how to use -the TulPhoneNumberUtils class parsing methods:

              TBuf<50> number = _L("+358 (40) 123 132"); -TBool validNumber = TulPhoneNumberUtils::ParsePhoneNumber(number, - TulPhoneNumberUtils::EPlainPhoneNumber ); -// validNumber == ETrue; -// number == "+35840123132" - -SendSMS(number) // etc.. - -// OR - -TBuf<50> number = _L("+358 (40) 123p132"); // note 'p' -TBool validNumber = TulPhoneNumberUtils::ParsePhoneNumber(number, - TulPhoneNumberUtils::EPlainPhoneNumber ); - -// validNumber == EFalse; -// number == "+358 (40) 123p132" // unchanged -

              For more information on individual methods, please see the -reference API for TulPhoneNumberUtils

              -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6501FAFF-6E21-5BC8-BA85-B1B4CE1AC6A7.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-6501FAFF-6E21-5BC8-BA85-B1B4CE1AC6A7.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,88 @@ + + + + + +Phone +number utility overview +
              Purpose

              The +Phone Number Utility is part of the Symbian Text Utility Component (etul.dll) +and it offers methods for parsing and validating phone numbers.

              Examples +of valid phone numbers:

                +

              • 1. +358501234567

                • +

              • 2. +358 (50) 123 4567

                • +

              Even though both of the above examples are valid phone numbers, only +the first one is accepted as a phone number by many systems. To convert the +second number to the first number, parsing methods of Phone Number Utility +can be used.

              +
              Architectural +Relationships

              The TulPhoneNumberUtils class +implements the static methods that make up the interface.

              Phone Number +Utility can be accessed through the TulPhoneNumberUtils class +that is defined in the header tulphonenumberutils.h. This +utility is linked to the etul.lib library.

              +
              Description

              Method +Information

              The enumerated type TPhoneNumberType is +used to specify the type of phone number for some of the methods below.

              + + + +Method name +Details + + + + +

              static TBool ParsePhoneNumber(TDes& aNumber, + TPhoneNumberType aType)

              +

              Removes irrelevant characters and white space from the supplied +phone number. Allowed characters are determined by phone number type, in other +words, the aType parameter. For example, parsing the number +358 +(40) 123 467 results in the number +35840123467.

              +               + +

              static TBool IsValidPhoneNumber(const TDesC& aNumber, + TPhoneNumberType aType)

              +

              Checks if the supplied phone number is a valid phone number of the +supplied type.

              +               + +

              TBool IsValidPhoneNumber(const TDesC& aNumber, const + TDesC& aValidChars)

              +

              Checks if the supplied phone number is a valid phone number. The +phone number is valid if it contains only characters specified by the parameter aValidChars.

              +               + +

              static void ParseInvalidChars(TDes& aNumber, const + TDesC& aInvalidChars)

              +

              Removes the specified invalid characters from the supplied phone +number string.

              +               + + +

              Example

              The following example shows how to use +the TulPhoneNumberUtils class parsing methods:

              TBuf<50> number = _L("+358 (40) 123 132"); +TBool validNumber = TulPhoneNumberUtils::ParsePhoneNumber(number, + TulPhoneNumberUtils::EPlainPhoneNumber ); +// validNumber == ETrue; +// number == "+35840123132" + +SendSMS(number) // etc.. + +// OR + +TBuf<50> number = _L("+358 (40) 123p132"); // note 'p' +TBool validNumber = TulPhoneNumberUtils::ParsePhoneNumber(number, + TulPhoneNumberUtils::EPlainPhoneNumber ); + +// validNumber == EFalse; +// number == "+358 (40) 123p132" // unchanged +

              For more information on individual methods, please see the +reference API for TulPhoneNumberUtils

              +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-651C2913-2AB9-5873-B296-5C4233967F21-GENID-1-8-1-3-1-1-7-1-5-1.dita --- a/Symbian3/SDK/Source/GUID-651C2913-2AB9-5873-B296-5C4233967F21-GENID-1-8-1-3-1-1-7-1-5-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,61 +0,0 @@ - - - - - -CONE -resource loader overview -
              Purpose

              The CONE Resource Loader utility is part -of the Symbian CONE component, and it offers methods for opening and closing -resource files. The actual reading of resources from an opened resource file -is done using various CCoeEnv provided -resource-reading methods.

              -
              Architectural Relationships

              This utility is implemented -as a single class, RCoeResourceLoader. -Access to the CCoeEnv instance -is required in order to use this utility.

              CONE Resource Loader can -be accessed through the RCoeResourceLoader class -that is defined in the header CoeUtils.h. The actual component -is linked to the cone.dll library.

              -
              Description

              Usage

              CONE Resource -Loader functionality can be accessed via public methods on an RCoeResourceLoader instance.

              To use, an instance of RCoeResourceLoader is -first created. Then calling either one of the open methods of RCoeResourceLoader opens -the resource file. After the resource file is no longer needed, it must be -closed.

              A single instance of RCoeResourceLoader can -only have a maximum of one resource file open at any time. If multiple simultaneously -open files are required, instantiate a separate RCoeResourceLoader for -each required file.

              Example

              The following example shows -how to use the RCoeResourceLoader class:

              #include <CoeUtils.h> - -// … Other code … - -// Get CCoeEnv instance -CEikonEnv* eikEnv = CEikonEnv::Static(); - -// Initialize loader -RCoeResourceLoader rLoader(eikEnv); - -// Open resource file -_LIT( KSampleResourceFileName, "Z:\\System\\Apps\\sample\\sample.rsc" ); -TFileName fileName(KSampleResourceFileName); -rLoader.OpenL(fileName); - -// Push resource loader to cleanup stack, so that it will always be properly -// closed when popped. -CleanupClosePushL(rLoader); - -// Read a resource -iSomeArray = eikEnv->ReadDesC16ArrayResourceL(R_SOME_RESOURCE); - -// Pop and destroy rLoader from stack. -// This also calls close on rLoader since CleanupClosePushL was used. -CleanupStack::PopAndDestroy(); // rLoader -

              For more information on individual methods, please see the -reference API for RCoeResourceLoader.

              -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-651C2913-2AB9-5873-B296-5C4233967F21-GENID-1-8-1-6-1-1-4-1-6-1-5-1.dita --- a/Symbian3/SDK/Source/GUID-651C2913-2AB9-5873-B296-5C4233967F21-GENID-1-8-1-6-1-1-4-1-6-1-5-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,61 +0,0 @@ - - - - - -CONE -resource loader overview -
              Purpose

              The CONE Resource Loader utility is part -of the Symbian CONE component, and it offers methods for opening and closing -resource files. The actual reading of resources from an opened resource file -is done using various CCoeEnv provided -resource-reading methods.

              -
              Architectural Relationships

              This utility is implemented -as a single class, RCoeResourceLoader. -Access to the CCoeEnv instance -is required in order to use this utility.

              CONE Resource Loader can -be accessed through the RCoeResourceLoader class -that is defined in the header CoeUtils.h. The actual component -is linked to the cone.dll library.

              -
              Description

              Usage

              CONE Resource -Loader functionality can be accessed via public methods on an RCoeResourceLoader instance.

              To use, an instance of RCoeResourceLoader is -first created. Then calling either one of the open methods of RCoeResourceLoader opens -the resource file. After the resource file is no longer needed, it must be -closed.

              A single instance of RCoeResourceLoader can -only have a maximum of one resource file open at any time. If multiple simultaneously -open files are required, instantiate a separate RCoeResourceLoader for -each required file.

              Example

              The following example shows -how to use the RCoeResourceLoader class:

              #include <CoeUtils.h> - -// … Other code … - -// Get CCoeEnv instance -CEikonEnv* eikEnv = CEikonEnv::Static(); - -// Initialize loader -RCoeResourceLoader rLoader(eikEnv); - -// Open resource file -_LIT( KSampleResourceFileName, "Z:\\System\\Apps\\sample\\sample.rsc" ); -TFileName fileName(KSampleResourceFileName); -rLoader.OpenL(fileName); - -// Push resource loader to cleanup stack, so that it will always be properly -// closed when popped. -CleanupClosePushL(rLoader); - -// Read a resource -iSomeArray = eikEnv->ReadDesC16ArrayResourceL(R_SOME_RESOURCE); - -// Pop and destroy rLoader from stack. -// This also calls close on rLoader since CleanupClosePushL was used. -CleanupStack::PopAndDestroy(); // rLoader -

              For more information on individual methods, please see the -reference API for RCoeResourceLoader.

              -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-651C2913-2AB9-5873-B296-5C4233967F21.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-651C2913-2AB9-5873-B296-5C4233967F21.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,61 @@ + + + + + +CONE +resource loader overview +
              Purpose

              The CONE Resource Loader utility is part +of the Symbian CONE component, and it offers methods for opening and closing +resource files. The actual reading of resources from an opened resource file +is done using various CCoeEnv provided +resource-reading methods.

              +
              Architectural Relationships

              This utility is implemented +as a single class, RCoeResourceLoader. +Access to the CCoeEnv instance +is required in order to use this utility.

              CONE Resource Loader can +be accessed through the RCoeResourceLoader class +that is defined in the header CoeUtils.h. The actual component +is linked to the cone.dll library.

              +
              Description

              Usage

              CONE Resource +Loader functionality can be accessed via public methods on an RCoeResourceLoader instance.

              To use, an instance of RCoeResourceLoader is +first created. Then calling either one of the open methods of RCoeResourceLoader opens +the resource file. After the resource file is no longer needed, it must be +closed.

              A single instance of RCoeResourceLoader can +only have a maximum of one resource file open at any time. If multiple simultaneously +open files are required, instantiate a separate RCoeResourceLoader for +each required file.

              Example

              The following example shows +how to use the RCoeResourceLoader class:

              #include <CoeUtils.h> + +// … Other code … + +// Get CCoeEnv instance +CEikonEnv* eikEnv = CEikonEnv::Static(); + +// Initialize loader +RCoeResourceLoader rLoader(eikEnv); + +// Open resource file +_LIT( KSampleResourceFileName, "Z:\\System\\Apps\\sample\\sample.rsc" ); +TFileName fileName(KSampleResourceFileName); +rLoader.OpenL(fileName); + +// Push resource loader to cleanup stack, so that it will always be properly +// closed when popped. +CleanupClosePushL(rLoader); + +// Read a resource +iSomeArray = eikEnv->ReadDesC16ArrayResourceL(R_SOME_RESOURCE); + +// Pop and destroy rLoader from stack. +// This also calls close on rLoader since CleanupClosePushL was used. +CleanupStack::PopAndDestroy(); // rLoader +

              For more information on individual methods, please see the +reference API for RCoeResourceLoader.

              +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-652DA0DD-AB1D-58A4-A6D2-27B5BAA506FF.dita --- a/Symbian3/SDK/Source/GUID-652DA0DD-AB1D-58A4-A6D2-27B5BAA506FF.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-652DA0DD-AB1D-58A4-A6D2-27B5BAA506FF.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,52 +1,52 @@ - - - - - -Flipping -and Rotating an External SurfaceThis topic provides an example of flipping and rotating a surface -in order to mirror the camera viewfinder during video telephony. -

              Variant: ScreenPlay. Target audience: Device -creators.

              -

              When users use the camera at the front of their phone during video telephony, -they expect their image to be mirrored like when they look in a mirror. The -camera viewfinder renders its content to a graphics surface which is displayed -in a window by setting it as the background surface. To mirror the viewfinder -content, first flip the surface and then rotate it by 180°.

              - - Mirroring - - -

              The following example code assumes that the surface already exists. Call TSurfaceConfiguration::SetFlip() to -flip the surface, then call TSurfaceConfiguration::SetOrientation() to -rotate the flipped surface by 180°. Finally bind the surface to the window. -If necessary, set attributes such as extent to the surface configuration.

              -TSurfaceConfiguration config; -RWindow iWindow; - -// Set the surface ID. -config.SetSurfaceId(iSurfaceId); - -// Get the window size and set the extent. -const TRect windowSize(iWindow->Size()); -config.SetExtent(windowSize); - -// Set the flipping -config.SetFlip(ETrue); - -// Rotate the flipped surface by 180° -config.SetOrientation(CFbsBitGc::EGraphicsOrientationRotated180); - -// Bind the surface to the window using the configuration -iWindow.SetBackgroundSurface(config, ETrue); -               -External -Surfaces Overview - + + + + + +Flipping +and Rotating an External SurfaceThis topic provides an example of flipping and rotating a surface +in order to mirror the camera viewfinder during video telephony. +

              Variant: ScreenPlay. Target audience: Device +creators.

              +

              When users use the camera at the front of their phone during video telephony, +they expect their image to be mirrored like when they look in a mirror. The +camera viewfinder renders its content to a graphics surface which is displayed +in a window by setting it as the background surface. To mirror the viewfinder +content, first flip the surface and then rotate it by 180°.

              + + Mirroring + + +

              The following example code assumes that the surface already exists. Call TSurfaceConfiguration::SetFlip() to +flip the surface, then call TSurfaceConfiguration::SetOrientation() to +rotate the flipped surface by 180°. Finally bind the surface to the window. +If necessary, set attributes such as extent to the surface configuration.

              +TSurfaceConfiguration config; +RWindow iWindow; + +// Set the surface ID. +config.SetSurfaceId(iSurfaceId); + +// Get the window size and set the extent. +const TRect windowSize(iWindow->Size()); +config.SetExtent(windowSize); + +// Set the flipping +config.SetFlip(ETrue); + +// Rotate the flipped surface by 180° +config.SetOrientation(CFbsBitGc::EGraphicsOrientationRotated180); + +// Bind the surface to the window using the configuration +iWindow.SetBackgroundSurface(config, ETrue); +               +External +Surfaces Overview +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-65365507-5773-4FE9-B63E-450CC2DD7570_d0e40462_href.png Binary file Symbian3/SDK/Source/GUID-65365507-5773-4FE9-B63E-450CC2DD7570_d0e40462_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-65365507-5773-4FE9-B63E-450CC2DD7570_d0e46022_href.png Binary file Symbian3/SDK/Source/GUID-65365507-5773-4FE9-B63E-450CC2DD7570_d0e46022_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-65365507-5773-4FE9-B63E-450CC2DD7570_d0e57538_href.png Binary file Symbian3/SDK/Source/GUID-65365507-5773-4FE9-B63E-450CC2DD7570_d0e57538_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-65365507-5773-4FE9-B63E-450CC2DD7570_d0e74290_href.png Binary file Symbian3/SDK/Source/GUID-65365507-5773-4FE9-B63E-450CC2DD7570_d0e74290_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-656E2E4F-D7C5-5FDC-B1E6-DFA5970BB3F0_d0e286968_href.jpg Binary file Symbian3/SDK/Source/GUID-656E2E4F-D7C5-5FDC-B1E6-DFA5970BB3F0_d0e286968_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-656E2E4F-D7C5-5FDC-B1E6-DFA5970BB3F0_d0e290601_href.jpg Binary file Symbian3/SDK/Source/GUID-656E2E4F-D7C5-5FDC-B1E6-DFA5970BB3F0_d0e290601_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-65885916-0242-5DDB-9D88-EB214096C4DF_d0e308626_href.png Binary file Symbian3/SDK/Source/GUID-65885916-0242-5DDB-9D88-EB214096C4DF_d0e308626_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-65885916-0242-5DDB-9D88-EB214096C4DF_d0e315020_href.png Binary file Symbian3/SDK/Source/GUID-65885916-0242-5DDB-9D88-EB214096C4DF_d0e315020_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-659E2A30-C2E0-4E5A-AA9F-50EBEC7E9579.dita --- a/Symbian3/SDK/Source/GUID-659E2A30-C2E0-4E5A-AA9F-50EBEC7E9579.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-659E2A30-C2E0-4E5A-AA9F-50EBEC7E9579.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,76 +1,77 @@ - - - - - -Windows -and panes -

              The display layouts are hierarchically organized. The layouts are built -using components called windows and panes.

              -Windows and panes - - - -Window / Pane -

              Description

               -               - - - -

              Screen

               -

              The screen is the topmost display component, corresponding to the -entire pixel area of the physical screen.

               -               - -

              Window

               -

              A window is a component that has no parent except the screen. Typically, -a window fills up the entire screen, but there are also smaller (temporary) -windows that take up only a part of the screen, leaving other parts of the -screen visible around themselves. Each application runs in a window of its -own. Applications can also use other temporary windows.

               -               - -

              Pane

               -

              A pane is a subcomponent of a window. A window may contain several -panes, and each pane may contain further sub-panes and so on. A bottom level -component that cannot have a sub-component can be called an element.

               -               - -

              Application window

               -

              An application window is a main window filling up the entire screen. -It is usually not used directly for display, but just as a parent for the -various panes. A typical application window is divided into the following -panes:

                -

              • Status pane

                • -

              • Main pane

                • -

              • Control pane

                • -
              See Main pane , Status pane and Control pane for more -detailed descriptions on each of these panes.

               -               - -

              Pop-up window

               -

              A pop-up window must not fill the entire screen; the pop-up window -has a frame, and typically the underlying application is partly visible around -the pop-up window. Pop-up windows are typically used in temporary states. -Back stepping should not usually lead to a pop-up window. Detailed information -on the various pop-up windows can be found in Pop-up -windows.

               -               - - -
              - -Panes - - -
              Using -windows and panes in C++ applications

              Windows and panes use the -Symbian application and UI frameworks. For implementation information, see Application and UI framework -implementation considerations.

              + + + + + +Windows +and panes +

              The display layouts are hierarchically organized. The layouts are built +using components called windows and panes.

              +Windows and panes + + + +Window / Pane +

              Description

               +               + + + +

              Screen

               +

              The screen is the topmost display component, corresponding to the +entire pixel area of the physical screen.

               +               + +

              Window

               +

              A window is a component that has no parent except the screen. Typically, +a window fills up the entire screen, but there are also smaller (temporary) +windows that take up only a part of the screen, leaving other parts of the +screen visible around themselves. Each application runs in a window of its +own. Applications can also use other temporary windows.

               +               + +

              Pane

               +

              A pane is a subcomponent of a window. A window may contain several +panes, and each pane may contain further sub-panes and so on. A bottom level +component that cannot have a sub-component can be called an element.

               +               + +

              Application window

               +

              An application window is a main window filling up the entire screen. +It is usually not used directly for display, but just as a parent for the +various panes. A typical application window is divided into the following +panes:

                +

              • Status pane

                • +

              • Main pane

                • +

              • Control pane

                • +
              See Main pane , Status pane and Control pane for more +detailed descriptions on each of these panes.

               +               + +

              Pop-up window

               +

              A pop-up window must not fill the entire screen; the pop-up window +has a frame, and typically the underlying application is partly visible around +the pop-up window. Pop-up windows are typically used in temporary states. +Back stepping should not usually lead to a pop-up window. Detailed information +on the various pop-up windows can be found in Pop-up +windows.

               +               + + +
              + +Panes + + +
              Using +windows and panes in applications

              Windows and panes +use the Symbian application and UI frameworks. For implementation information, +see Application and +UI framework implementation considerations.

               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-65A4BA91-579F-5B9B-ACC1-D3D9B1F233B7_d0e77550_href.png Binary file Symbian3/SDK/Source/GUID-65A4BA91-579F-5B9B-ACC1-D3D9B1F233B7_d0e77550_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-65A4BA91-579F-5B9B-ACC1-D3D9B1F233B7_d0e84262_href.png Binary file Symbian3/SDK/Source/GUID-65A4BA91-579F-5B9B-ACC1-D3D9B1F233B7_d0e84262_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-65E9C040-AAB6-5C1E-9724-8828DADFC741.dita --- a/Symbian3/SDK/Source/GUID-65E9C040-AAB6-5C1E-9724-8828DADFC741.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-65E9C040-AAB6-5C1E-9724-8828DADFC741.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,110 +1,110 @@ - - - - - -Location -Acquisition API OverviewApplications use the Location Acquisition API to obtain location -fixes from the LBS subsystem. -
              Purpose

              This document describes the Location Acquisition -API. Client applications use the API to obtain the location of the mobile -device and to discover the type and status of the available Positioning Modules.

              -
              Introduction

              The Location Acquisition API defines -the client application view of the LBS Location Server. The API is a standard -Symbian platform client/server implementation. Applications use the API to:

                -

              • Obtain the location -of the mobile device

                The Location Acquisition API is designed so that -client applications can always make the same API calls to obtain the device -location irrespective of the underlying positioning technologies used by the -Location Server.

                • -

              • Discover the type and -status of available positioning technologies

                The API allows applications -to discover the available Positioning Modules and to receive notification -of changes in their status. Applications can also make a choice of the specific -Positioning Module to use to get the device location.

                • -
              -
              Key concepts
              - -
              Location Server
              -

              The Symbian platform server used by client applications to get location -information. The Location Server can use multiple Positioning Modules to obtain -location information.

              -               - -
              Positioning Module
              -

              An ECom plug-in that handles requests for location information and -interfaces with positioning technology hardware.

              -               -
              -
              API summary

              Figure 1 illustrates the client interface -classes of the Location Acquisition API including the data classes that hold -basic location information. The classes shown are defined in the header file lbs.h. -See Location Acquisition -API reference for a full list of all the API header files.

              The -following is a brief description of some of the most important API classes:

                -

              • RPositionServer is -used by client applications to create a session with the Location Server. -This class is also used to get details of the positioning technology modules -available and their status. Opening a session with the Location Server may -generate a standard client/server error code which a client application must -check for.

                • -

              • RPositioner is -used by client applications to create a subsession with the Location Server. -A client application uses this class to request location information and set -the frequency of location information updates. In addition to standard client/server -error codes, calls to RPositioner may generate LBS specific -error codes (defined in LbsErrors.h) or error codes generated -by Positioning Modules.

                • -

              • TPositionInfo is -a simple data wrapper class. An empty object of this type is passed to RPositioner by -a client application when basic location information is required. The returned -object holds the identifier of the positioning technology module used to obtain -the position data. The position data is held in a TPosition object.

                See Position data and info classes for -an overview of the data classes that hold position data.

                • -

              • TPosition is -the class that holds basic position data: latitude, longitude and altitude -(and their accuracy) and the time at which the location fix was obtained. -See Position data for -more information about how co-ordinate values are represented in this class.

                • -
              - Figure 1. RPositionServer and RPositioner with basic -position data classes - -
              -
              Platform security capabilities

              Applications must -have the Location capability to use the Location Acquisition -API.

              -
              Typical uses

              Client applications use the API -in three ways:

                -

              1. To get location information.

                The -main purpose of the Location Acquisition API is to provide location information -to client applications.

                See How -to get location information for examples of how to get basic location -information using the API.

                2. -

              2. To get positioning technology -module information.

                The API provides functions to allow discovery -of the capabilities and quality of information provided by the set of positioning -technology modules.

                See Positioning -technology modules for a description of the positioning technology -module information which is accessible to client applications using the API.

                See How to use module information for -an example of how to obtain information about the available modules.

                3. -

              3. To receive notification -of positioning technology module status changes.

                An application may -wish to be informed when a module becomes available or unavailable. For example, -an application may want to know when GPS becomes available as this may increase -its capabilities and so change its behaviour. The API provides a way for client -applications to receive notification of module status changes.

                See Positioning technology module -status for a description of Positioning Module status and events.

                See How to get module status -change notifications for an example of how to get notification of module -status changes.

                4. -
              -               -Position -Data and Info Classes + + + + + +Location +Acquisition API OverviewApplications use the Location Acquisition API to obtain location +fixes from the LBS subsystem. +
              Purpose

              This document describes the Location Acquisition +API. Client applications use the API to obtain the location of the mobile +device and to discover the type and status of the available Positioning Modules.

              +
              Introduction

              The Location Acquisition API defines +the client application view of the LBS Location Server. The API is a standard +Symbian platform client/server implementation. Applications use the API to:

                +

              • Obtain the location +of the mobile device

                The Location Acquisition API is designed so that +client applications can always make the same API calls to obtain the device +location irrespective of the underlying positioning technologies used by the +Location Server.

                • +

              • Discover the type and +status of available positioning technologies

                The API allows applications +to discover the available Positioning Modules and to receive notification +of changes in their status. Applications can also make a choice of the specific +Positioning Module to use to get the device location.

                • +
              +
              Key concepts
              + +
              Location Server
              +

              The Symbian platform server used by client applications to get location +information. The Location Server can use multiple Positioning Modules to obtain +location information.

              +               + +
              Positioning Module
              +

              An ECom plug-in that handles requests for location information and +interfaces with positioning technology hardware.

              +               +
              +
              API summary

              Figure 1 illustrates the client interface +classes of the Location Acquisition API including the data classes that hold +basic location information. The classes shown are defined in the header file lbs.h. +See Location Acquisition +API reference for a full list of all the API header files.

              The +following is a brief description of some of the most important API classes:

                +

              • RPositionServer is +used by client applications to create a session with the Location Server. +This class is also used to get details of the positioning technology modules +available and their status. Opening a session with the Location Server may +generate a standard client/server error code which a client application must +check for.

                • +

              • RPositioner is +used by client applications to create a subsession with the Location Server. +A client application uses this class to request location information and set +the frequency of location information updates. In addition to standard client/server +error codes, calls to RPositioner may generate LBS specific +error codes (defined in LbsErrors.h) or error codes generated +by Positioning Modules.

                • +

              • TPositionInfo is +a simple data wrapper class. An empty object of this type is passed to RPositioner by +a client application when basic location information is required. The returned +object holds the identifier of the positioning technology module used to obtain +the position data. The position data is held in a TPosition object.

                See Position data and info classes for +an overview of the data classes that hold position data.

                • +

              • TPosition is +the class that holds basic position data: latitude, longitude and altitude +(and their accuracy) and the time at which the location fix was obtained. +See Position data for +more information about how co-ordinate values are represented in this class.

                • +
              + Figure 1. RPositionServer and RPositioner with basic +position data classes + +
              +
              Platform security capabilities

              Applications must +have the Location capability to use the Location Acquisition +API.

              +
              Typical uses

              Client applications use the API +in three ways:

                +

              1. To get location information.

                The +main purpose of the Location Acquisition API is to provide location information +to client applications.

                See How +to get location information for examples of how to get basic location +information using the API.

                2. +

              2. To get positioning technology +module information.

                The API provides functions to allow discovery +of the capabilities and quality of information provided by the set of positioning +technology modules.

                See Positioning +technology modules for a description of the positioning technology +module information which is accessible to client applications using the API.

                See How to use module information for +an example of how to obtain information about the available modules.

                3. +

              3. To receive notification +of positioning technology module status changes.

                An application may +wish to be informed when a module becomes available or unavailable. For example, +an application may want to know when GPS becomes available as this may increase +its capabilities and so change its behaviour. The API provides a way for client +applications to receive notification of module status changes.

                See Positioning technology module +status for a description of Positioning Module status and events.

                See How to get module status +change notifications for an example of how to get notification of module +status changes.

                4. +
              +               +Position +Data and Info Classes               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-667E7F90-D6C2-55CE-AE60-6C938072FB9C.dita --- a/Symbian3/SDK/Source/GUID-667E7F90-D6C2-55CE-AE60-6C938072FB9C.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-667E7F90-D6C2-55CE-AE60-6C938072FB9C.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,89 +1,89 @@ - - - - - -Graphics -and Drawing OverviewThis topic provides an introduction to drawing graphics to the -screen. -

              Variant: Both (ScreenPlay and non-ScreenPlay). Target -audience: Application developers.

              -

              Applications can draw to any RDrawableWindow —such as -an RWindow —via a graphics device, of type CWsScreenDevice, -and a graphics context, of type CWindowGc. These classes -are derived from the GDI -component classes CGraphicsDevice and CGraphicsContext, -respectively. This means that general drawing functions can be used for drawing -to windows, as well as to other graphics devices. The Window Server itself -does not provide the facilities to draw graphics to a physical device. CWindowGc functions -are not passed to the Window Server directly. Rather, they are stored in a -buffer maintained by the Window Server Client API. This buffer is flushed -to the Window Server only rarely. By this means the context switching involved -in drawing is minimised, and system performance significantly enhanced.

              -

              CWsScreenDeviceminimized encapsulates the device-dependent -aspects of graphics operations. Graphics functions are not carried out directly -via a CWsScreenDevice, however, but via a graphics context -with which it is associated. The graphics context class, CWindowGc, -provides a rich set of drawing functions, including functions to draw lines, -arcs, polygons, text and bitmaps.

              -

              A graphics context contains a collection of configurable parameters concerned -with graphics, such as pen width, pen color, brush color. It is stored in -the server, thus reducing the amount of information that has to be sent with -each graphics call. The graphics call simply specifies the graphics context -it wishes to use, and a single graphics context can be shared between multiple -windows.

              -

              To draw to a graphics context it must be associated with a window. Typically -a graphics context is created when a session is constructed, and that graphics -context is shared between several windows in the application. When the window -needs to use the graphics context it calls CWindowGc::Activate(). -If necessary it can change the graphics context's settings. CWindowGc::Deactivate() should -be called first if the graphics context is currently active upon another window.

              -

              Several optimizations are used by the Window Server to obtain high-performance -graphics:

              -
                -

              • Each window is associated -with an RWsSession which is in turn associated with a client-side -buffer. Instead of implementing graphics operations by a direct client-server -call, which involves expensive context switching, all graphics operations -are stored as opcodes in the buffer, and the buffer is only flushed in certain -circumstances.

                • -

              • The CFbsBitmap class -allows a bitmap to be shared between all threads in the system, including -the client and the Window Server. This sharing is mediated by the Font -and Bitmap server. The CWsBitmap class eliminates -further context switches by taking ownership of the handle of the bitmap. -Applications can use this class to more efficiently open, blit-to-screen, -and close a series of bitmaps. Use functions that take a CWsBitmap in -preference to those that take a CFbsBitmap, because they -are faster.

                • -

              • A single graphics context -may be used for drawing to many windows—it is not necessary to have one per -window. The Activate() function associates a CWindowGc with -a particular window.

                • -

              • Provided drawing operations -to an RWindow are performed as redraw -drawing, the Window Server stores the sequence of drawing commands -that represent the window contents in redraw stores. Then when the Window -Server needs to repaint the window (because, for example, a dialog box popped -up over it and has now closed) it simply replays the sequence of stored commands, -rather than sending a redraw request to the client. This minimizes the number -of client-server transactions and means that windows are repainted as soon -as the Window Server detects that they are needed.

                This means that -all CWindowGc drawing should now be redraw drawing, which -means that it takes place between RWindow::BeginRedraw() and RWindow::EndRedraw() calls. -If you use the CCoeControl::DrawNow() and CCoeControl::DrawDeferred() methods, -the UI Control Framework (CONE) takes care of this for you. See Redraw -Drawing for more information.

                • -
              -               -Graphics -and Drawing -The UI Control -Framework (CONE) + + + + + +Graphics +and Drawing OverviewThis topic provides an introduction to drawing graphics to the +screen. +

              Variant: Both (ScreenPlay and non-ScreenPlay). Target +audience: Application developers.

              +

              Applications can draw to any RDrawableWindow —such as +an RWindow —via a graphics device, of type CWsScreenDevice, +and a graphics context, of type CWindowGc. These classes +are derived from the GDI +component classes CGraphicsDevice and CGraphicsContext, +respectively. This means that general drawing functions can be used for drawing +to windows, as well as to other graphics devices. The Window Server itself +does not provide the facilities to draw graphics to a physical device. CWindowGc functions +are not passed to the Window Server directly. Rather, they are stored in a +buffer maintained by the Window Server Client API. This buffer is flushed +to the Window Server only rarely. By this means the context switching involved +in drawing is minimised, and system performance significantly enhanced.

              +

              CWsScreenDeviceminimized encapsulates the device-dependent +aspects of graphics operations. Graphics functions are not carried out directly +via a CWsScreenDevice, however, but via a graphics context +with which it is associated. The graphics context class, CWindowGc, +provides a rich set of drawing functions, including functions to draw lines, +arcs, polygons, text and bitmaps.

              +

              A graphics context contains a collection of configurable parameters concerned +with graphics, such as pen width, pen color, brush color. It is stored in +the server, thus reducing the amount of information that has to be sent with +each graphics call. The graphics call simply specifies the graphics context +it wishes to use, and a single graphics context can be shared between multiple +windows.

              +

              To draw to a graphics context it must be associated with a window. Typically +a graphics context is created when a session is constructed, and that graphics +context is shared between several windows in the application. When the window +needs to use the graphics context it calls CWindowGc::Activate(). +If necessary it can change the graphics context's settings. CWindowGc::Deactivate() should +be called first if the graphics context is currently active upon another window.

              +

              Several optimizations are used by the Window Server to obtain high-performance +graphics:

              +
                +

              • Each window is associated +with an RWsSession which is in turn associated with a client-side +buffer. Instead of implementing graphics operations by a direct client-server +call, which involves expensive context switching, all graphics operations +are stored as opcodes in the buffer, and the buffer is only flushed in certain +circumstances.

                • +

              • The CFbsBitmap class +allows a bitmap to be shared between all threads in the system, including +the client and the Window Server. This sharing is mediated by the Font +and Bitmap server. The CWsBitmap class eliminates +further context switches by taking ownership of the handle of the bitmap. +Applications can use this class to more efficiently open, blit-to-screen, +and close a series of bitmaps. Use functions that take a CWsBitmap in +preference to those that take a CFbsBitmap, because they +are faster.

                • +

              • A single graphics context +may be used for drawing to many windows—it is not necessary to have one per +window. The Activate() function associates a CWindowGc with +a particular window.

                • +

              • Provided drawing operations +to an RWindow are performed as redraw +drawing, the Window Server stores the sequence of drawing commands +that represent the window contents in redraw stores. Then when the Window +Server needs to repaint the window (because, for example, a dialog box popped +up over it and has now closed) it simply replays the sequence of stored commands, +rather than sending a redraw request to the client. This minimizes the number +of client-server transactions and means that windows are repainted as soon +as the Window Server detects that they are needed.

                This means that +all CWindowGc drawing should now be redraw drawing, which +means that it takes place between RWindow::BeginRedraw() and RWindow::EndRedraw() calls. +If you use the CCoeControl::DrawNow() and CCoeControl::DrawDeferred() methods, +the UI Control Framework (CONE) takes care of this for you. See Redraw +Drawing for more information.

                • +
              +               +Graphics +and Drawing +The UI Control +Framework (CONE)               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-669190F8-3BE9-58FC-B689-00F06FDAD74D-master.png Binary file Symbian3/SDK/Source/GUID-669190F8-3BE9-58FC-B689-00F06FDAD74D-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-669190F8-3BE9-58FC-B689-00F06FDAD74D_d0e382307_href.png Binary file Symbian3/SDK/Source/GUID-669190F8-3BE9-58FC-B689-00F06FDAD74D_d0e382307_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-66BBA81D-2488-50B8-8822-43AAAA139DDE.dita --- a/Symbian3/SDK/Source/GUID-66BBA81D-2488-50B8-8822-43AAAA139DDE.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-66BBA81D-2488-50B8-8822-43AAAA139DDE.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,62 +1,62 @@ - - - - - -Overview -of random number generation -
              Overview

              The -purpose of the Random Number Generation API is the generation of cryptographically -strong random numbers.

              Several cryptographic applications rely upon -the randomness, unpredictability and irreproducibility of the random number -generator, such as:

                -

              • one-time pads

                • -

              • key generation

                • -

              • random nonces

                • -

              • Initialization Vectors -(IVs)

                • -

              • salts to be hashed with -passwords

                • -

              • unique parameters in -signing operations.

                • -

              The RNG uses the RANROT algorithm -seeded by random data available on the target hardware (for instance free -running counters available on ARM processors).

              In order to be fully compliant -with DSS (Digital Signature Standard), applications using the cryptography -library must supply a FIPS-186-2 CR -1 compliant random number generator. The library provides a mechanism for -using such a random number generator if required.

              -
              The Random -Number Generation API

              The diagram below shows the main classes -used in the RNG, which are implemented in random.dll. -For information on each class see the Cryptography API Reference material.

              - The inheritance hierarchy for the RRandomSession and -CSystemRandom classes - -

              How to use TRandom

              TRandom is a -cryptographically stong random number generator. Its declaration is:

              class TRandom - { -public: - IMPORT_C static void RandomL(TDes8& aDestination); - }; The function TRandom::Random() which -panics rather than leaves when it cannot obtain a random number, is deprecated -from v9.1 onwards.

              TRandom::RandomL() generates -random bytes by first connecting to the random number generation server (using RRandomSession). -If the attempt to connect fails, TRandom::RandomL() leaves.

              The -server fills aDestination with randomly generated bytes up -to its current length (not its maximum length). If this fails, TRandom::RandomL() leaves. -If aDestination is 1024 or more bytes long, multiple calls -are made to the server. Finally, TRandom closes the session.

              TRandom can -be used like this:

              HBufC8* rand = HBufC8::NewLC(5); -TPtr8 pRand=rand->Des(); -pRand.SetLength(5); -TRandom::RandomL(pRand); -... -CleanupStack::PopAndDestroy(rand);
              + + + + + +Overview +of random number generation +
              Overview

              The +purpose of the Random Number Generation API is the generation of cryptographically +strong random numbers.

              Several cryptographic applications rely upon +the randomness, unpredictability and irreproducibility of the random number +generator, such as:

                +

              • one-time pads

                • +

              • key generation

                • +

              • random nonces

                • +

              • Initialization Vectors +(IVs)

                • +

              • salts to be hashed with +passwords

                • +

              • unique parameters in +signing operations.

                • +

              The RNG uses the RANROT algorithm +seeded by random data available on the target hardware (for instance free +running counters available on ARM processors).

              In order to be fully compliant +with DSS (Digital Signature Standard), applications using the cryptography +library must supply a FIPS-186-2 CR +1 compliant random number generator. The library provides a mechanism for +using such a random number generator if required.

              +
              The Random +Number Generation API

              The diagram below shows the main classes +used in the RNG, which are implemented in random.dll. +For information on each class see the Cryptography API Reference material.

              + The inheritance hierarchy for the RRandomSession and +CSystemRandom classes + +

              How to use TRandom

              TRandom is a +cryptographically stong random number generator. Its declaration is:

              class TRandom + { +public: + IMPORT_C static void RandomL(TDes8& aDestination); + }; The function TRandom::Random() which +panics rather than leaves when it cannot obtain a random number, is deprecated +from v9.1 onwards.

              TRandom::RandomL() generates +random bytes by first connecting to the random number generation server (using RRandomSession). +If the attempt to connect fails, TRandom::RandomL() leaves.

              The +server fills aDestination with randomly generated bytes up +to its current length (not its maximum length). If this fails, TRandom::RandomL() leaves. +If aDestination is 1024 or more bytes long, multiple calls +are made to the server. Finally, TRandom closes the session.

              TRandom can +be used like this:

              HBufC8* rand = HBufC8::NewLC(5); +TPtr8 pRand=rand->Des(); +pRand.SetLength(5); +TRandom::RandomL(pRand); +... +CleanupStack::PopAndDestroy(rand);
              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-66E0B7F2-DEB4-5326-9DE0-5C0E253568AF_d0e351163_href.png Binary file Symbian3/SDK/Source/GUID-66E0B7F2-DEB4-5326-9DE0-5C0E253568AF_d0e351163_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-66E0B7F2-DEB4-5326-9DE0-5C0E253568AF_d0e357243_href.png Binary file Symbian3/SDK/Source/GUID-66E0B7F2-DEB4-5326-9DE0-5C0E253568AF_d0e357243_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-66EFFCF5-581A-4EE7-B784-8087A1081B6D.dita --- a/Symbian3/SDK/Source/GUID-66EFFCF5-581A-4EE7-B784-8087A1081B6D.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-66EFFCF5-581A-4EE7-B784-8087A1081B6D.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,40 +1,44 @@ - - - - - -Title -pane -

              The Title pane displays a context-dependent application -title or state name. Title pane in Home screen view can work with touch down -and release but by default, there is no functionality.

              - -Title pane - - -
                -

              • Typically, the title text is the descriptive name of the current main -pane view.

                • -

              • In an application idle state, the title text is typically the application -name.

                • -

              • In the idle state, the Title pane may contain -an operator logo (left-aligned in the area available) instead of the operator -name as text.

                • -
              -
              Using -the title pane in C++ applications

              The API to use for the title -pane component is the Title pane API. For observing title pane touch events, -use the Title Pane Touch Observer API.

              To use a title pane -in your application, create an instance of the class CAknTitlePane.

              Use the method SetTextL() in the class CAknTitlePane to set the title pane text and display it. To set the text to scroll -if it does not fit the title pane text area, set the flag aScroll to ETrue. -To set the text to the default (name of the application), use the method SetTextToDefault().

              Use the method SetPicture() to display a picture in the title pane. -To set the icon from a file, use the method SetPictureFromFileL(). Alternatively, to set a small -icon to be displayed together with text, use the method SetSmallPicture().

              To set the title pane contents -from a resource file, use the method SetFromResourceL().

              + + + + + +Title +pane +

              The Title pane displays a context-dependent application +title or state name. Title pane in Home screen view can work with touch down +and release but by default, there is no functionality.

              + +Title pane + + +
                +

              • Typically, the title text is the descriptive name of the current main +pane view.

                • +

              • In an application title pane, the title text is typically +the application name.

                • +

              • In the home screen, the Title pane may contain +an operator logo (left-aligned in the area available) instead of the operator +name as text.

                • +
              +
              Using +the title pane in applications

              The API to use for the title pane +component is the Title pane API. For observing title pane touch events, use +the Title Pane Touch Observer API.

              To use a title pane in your application, +create an instance of the CAknTitlePane class.

              Use +the CAknTitlePane::SetTextL() method to set the title pane +text and display it. To set the text to scroll if it does not fit the title +pane text area, set the flag aScroll to ETrue. +To set the text to the default (name of the application), use the CAknTitlePane::SetTextToDefault() method.

              Use +the CAknTitlePane::SetPicture() method to display a picture +in the title pane. To set the icon from a file, use the CAknTitlePane::SetPictureFromFileL() method. +Alternatively, to set a small icon to be displayed together with text, use +the CAknTitlePane::SetSmallPicture() method.

              To set +the title pane contents from a resource file, use the CAknTitlePane::SetFromResourceL() method.

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6740A668-33A2-52B1-9416-E9F21591D16C_d0e168995_href.jpg Binary file Symbian3/SDK/Source/GUID-6740A668-33A2-52B1-9416-E9F21591D16C_d0e168995_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6740A668-33A2-52B1-9416-E9F21591D16C_d0e175596_href.jpg Binary file Symbian3/SDK/Source/GUID-6740A668-33A2-52B1-9416-E9F21591D16C_d0e175596_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-679390E8-1DE6-55F0-9A0C-60D58956A1E3.dita --- a/Symbian3/SDK/Source/GUID-679390E8-1DE6-55F0-9A0C-60D58956A1E3.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,12 +0,0 @@ - - - - - -Hash (message digest) algorithms

              A cryptographic hash algorithm (also known as a message digest, a one-way function, or simply a hash) takes a variable-length input (the message) and produce a fixed length output known as the hash (or digest) of the input. It is often useful to think of the resulting output as a representation, or fingerprint, of the original input.

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-67D0F837-65EE-54FE-B8D6-E5226CB9D8C9-GENID-1-10-1-22-1-1-4-1-1-3-1.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-67D0F837-65EE-54FE-B8D6-E5226CB9D8C9-GENID-1-10-1-22-1-1-4-1-1-3-1.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,13 @@ + + + + + +Feature Management OverviewThis section gives an overview of feature management, what it does, how it works, how to use it and links to relevant links.
              Purpose

              A feature is a piece of functionality that is shipped with the device, but which can be disabled or enabled.

              Feature management is used to manage the enabling and disabling of these features and associated activities for example to provide a means of allowing the system to know if a feature is enabled or not.

              Architecture

              The feature management system consists of a server and two dll files.

              The feature management system has a standard client server architecture. The server is the feature management server and the dll files provide a series of APIs with which the client can communicate with the server.

              Description

              As described above, the functionality of feature management can be broken into two groups: the server and the dll files.

              The feature manager server: this comes as an executable called featmgrserver.exe.

              • This does all the feature management work that is keeping track of the status of each feature.

              The communication to the feature management server is carried out via the two dll files i.e. featdiscovery.dll and featmgr.dll.

              • Provide a means of telling the client when a change to the status of a feature has occurred.

              • Allows the client to specify which feature is to be enabled or disabled.

              • Allows the client to add or delete features.

              Components

              The following components make up the feature management collection.

              • Feature Discovery

                featdiscovery.dll

                Provides the APIs that provide only a subset of what can be provided by feature management.

                It provides the functionality for TFeatureSet and CFeatureDiscovery.

              • Feature Manager

                featmgr.dll

                Provides the APIs that allow the client to carry out the full functionality available with feature management.

                It provides the functionality for RFeatMgrClient, RFeatureControl, MFeatureObserver and CFeatureNotifier.

              • Feature Manager Server

                featmgrserver.exe

                Performs all the actual operations and maintains details about features.

              Feature Manager + Overview               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-67D0F837-65EE-54FE-B8D6-E5226CB9D8C9-GENID-1-10-1-22-1-1-4-1-1-4-1-4-1.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-67D0F837-65EE-54FE-B8D6-E5226CB9D8C9-GENID-1-10-1-22-1-1-4-1-1-4-1-4-1.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,13 @@ + + + + + +Feature Management OverviewThis section gives an overview of feature management, what it does, how it works, how to use it and links to relevant links.
              Purpose

              A feature is a piece of functionality that is shipped with the device, but which can be disabled or enabled.

              Feature management is used to manage the enabling and disabling of these features and associated activities for example to provide a means of allowing the system to know if a feature is enabled or not.

              Architecture

              The feature management system consists of a server and two dll files.

              The feature management system has a standard client server architecture. The server is the feature management server and the dll files provide a series of APIs with which the client can communicate with the server.

              Description

              As described above, the functionality of feature management can be broken into two groups: the server and the dll files.

              The feature manager server: this comes as an executable called featmgrserver.exe.

              • This does all the feature management work that is keeping track of the status of each feature.

              The communication to the feature management server is carried out via the two dll files i.e. featdiscovery.dll and featmgr.dll.

              • Provide a means of telling the client when a change to the status of a feature has occurred.

              • Allows the client to specify which feature is to be enabled or disabled.

              • Allows the client to add or delete features.

              Components

              The following components make up the feature management collection.

              • Feature Discovery

                featdiscovery.dll

                Provides the APIs that provide only a subset of what can be provided by feature management.

                It provides the functionality for TFeatureSet and CFeatureDiscovery.

              • Feature Manager

                featmgr.dll

                Provides the APIs that allow the client to carry out the full functionality available with feature management.

                It provides the functionality for RFeatMgrClient, RFeatureControl, MFeatureObserver and CFeatureNotifier.

              • Feature Manager Server

                featmgrserver.exe

                Performs all the actual operations and maintains details about features.

              Feature Manager + Overview               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-67D0F837-65EE-54FE-B8D6-E5226CB9D8C9-GENID-1-8-1-21-1-1-4-1-1-3-1.dita --- a/Symbian3/SDK/Source/GUID-67D0F837-65EE-54FE-B8D6-E5226CB9D8C9-GENID-1-8-1-21-1-1-4-1-1-3-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,13 +0,0 @@ - - - - - -Feature Management OverviewThis section gives an overview of feature management, what it does, how it works, how to use it and links to relevant links.
              Purpose

              A feature is a piece of functionality that is shipped with the device, but which can be disabled or enabled.

              Feature management is used to manage the enabling and disabling of these features and associated activities for example to provide a means of allowing the system to know if a feature is enabled or not.

              Architecture

              The feature management system consists of a server and two dll files.

              The feature management system has a standard client server architecture. The server is the feature management server and the dll files provide a series of APIs with which the client can communicate with the server.

              Description

              As described above, the functionality of feature management can be broken into two groups: the server and the dll files.

              The feature manager server: this comes as an executable called featmgrserver.exe.

              • This does all the feature management work that is keeping track of the status of each feature.

              The communication to the feature management server is carried out via the two dll files i.e. featdiscovery.dll and featmgr.dll.

              • Provide a means of telling the client when a change to the status of a feature has occurred.

              • Allows the client to specify which feature is to be enabled or disabled.

              • Allows the client to add or delete features.

              Components

              The following components make up the feature management collection.

              • Feature Discovery

                featdiscovery.dll

                Provides the APIs that provide only a subset of what can be provided by feature management.

                It provides the functionality for TFeatureSet and CFeatureDiscovery.

              • Feature Manager

                featmgr.dll

                Provides the APIs that allow the client to carry out the full functionality available with feature management.

                It provides the functionality for RFeatMgrClient, RFeatureControl, MFeatureObserver and CFeatureNotifier.

              • Feature Manager Server

                featmgrserver.exe

                Performs all the actual operations and maintains details about features.

              Feature Manager - Overview               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-67D0F837-65EE-54FE-B8D6-E5226CB9D8C9-GENID-1-8-1-21-1-1-4-1-1-4-1-4-1.dita --- a/Symbian3/SDK/Source/GUID-67D0F837-65EE-54FE-B8D6-E5226CB9D8C9-GENID-1-8-1-21-1-1-4-1-1-4-1-4-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,13 +0,0 @@ - - - - - -Feature Management OverviewThis section gives an overview of feature management, what it does, how it works, how to use it and links to relevant links.
              Purpose

              A feature is a piece of functionality that is shipped with the device, but which can be disabled or enabled.

              Feature management is used to manage the enabling and disabling of these features and associated activities for example to provide a means of allowing the system to know if a feature is enabled or not.

              Architecture

              The feature management system consists of a server and two dll files.

              The feature management system has a standard client server architecture. The server is the feature management server and the dll files provide a series of APIs with which the client can communicate with the server.

              Description

              As described above, the functionality of feature management can be broken into two groups: the server and the dll files.

              The feature manager server: this comes as an executable called featmgrserver.exe.

              • This does all the feature management work that is keeping track of the status of each feature.

              The communication to the feature management server is carried out via the two dll files i.e. featdiscovery.dll and featmgr.dll.

              • Provide a means of telling the client when a change to the status of a feature has occurred.

              • Allows the client to specify which feature is to be enabled or disabled.

              • Allows the client to add or delete features.

              Components

              The following components make up the feature management collection.

              • Feature Discovery

                featdiscovery.dll

                Provides the APIs that provide only a subset of what can be provided by feature management.

                It provides the functionality for TFeatureSet and CFeatureDiscovery.

              • Feature Manager

                featmgr.dll

                Provides the APIs that allow the client to carry out the full functionality available with feature management.

                It provides the functionality for RFeatMgrClient, RFeatureControl, MFeatureObserver and CFeatureNotifier.

              • Feature Manager Server

                featmgrserver.exe

                Performs all the actual operations and maintains details about features.

              Feature Manager - Overview               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6820BB9E-F0B9-4493-A4C3-686238527C9B-master.png Binary file Symbian3/SDK/Source/GUID-6820BB9E-F0B9-4493-A4C3-686238527C9B-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6820BB9E-F0B9-4493-A4C3-686238527C9B_d0e60647_href.png Binary file Symbian3/SDK/Source/GUID-6820BB9E-F0B9-4493-A4C3-686238527C9B_d0e60647_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-68417158-D625-56BF-BDD5-BE49A7651CED.dita --- a/Symbian3/SDK/Source/GUID-68417158-D625-56BF-BDD5-BE49A7651CED.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-68417158-D625-56BF-BDD5-BE49A7651CED.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,14 +1,14 @@ - - - - - -Audio Output Streaming Overview

              This document provides an overview of Audio Output Streaming.

              Purpose

              Audio Output Streaming is the interface to streaming sampled audio data to the low level audio controller part of the Multimedia Framework (MMF).

              Audio Output Streaming Library Details

              The DLL that provides the functionality and the library to which your code must link is identified below.

              DLL LIB Short Description

              mediaclientaudiostream.dll

              mediaclientaudiostream.lib

              These files are used for implementing Audio Output Streaming.

              Architectural Relationship

              How the Audio Output Streaming classes interact with other components of MMF is shown below:

              - Audio output streaming overview -
              Description

              Streamed audio data is sent and received incrementally. This means:

              • sound clips sent to the low level audio controller (audio play) can be sent as they arrive rather than waiting until the entire clip is received.

                The user of the API should maintain the data fragments in a queue before sending them to the server. If the user attempts to send data faster than the server can receive it, the excess data fragments are maintained in another client side queue (invisible to the user), whose elements are references to the buffers passed to it. The server notifies the client using a callback each time it has received a data fragment. This indicates to the client that the data fragment can be deleted.

              • sound clips that are being captured by the low level audio controller (audio record) can be read incrementally without having to wait until audio capture is complete.

                The low level audio controller maintains the received buffers where it can place the audio data that is being captured. The client uses a read function to read the received data into destination descriptors.

              The client is also notified (for audio play and record) when the stream is opened and available for use (opening takes place asynchronously), and when the stream is closed.

              This API can only be used to stream audio data, with the data being stored or sourced from a descriptor. Client applications must ensure that the data is in 16 bit PCM format as this is the only format supported. The API does not support mixing. A priority mechanism is used to control access to the sound device by more than one client.

              Key Audio Output Streaming Classes

              The functionality provided by Audio Output Streaming is contained within the CMdaAudioOutputStream class.

              Using Audio Output Streaming

              Clients can use Audio Output Streaming to:

              • Open, set audio properties, write to and close the audio stream.

              See Also

              Audio Output Streaming Tutorial

              \ No newline at end of file + + + + + +Audio Output Streaming Overview

              This document provides an overview of Audio Output Streaming.

              Purpose

              Audio Output Streaming is the interface to streaming sampled audio data to the low level audio controller part of the Multimedia Framework (MMF).

              Audio Output Streaming Library Details

              The DLL that provides the functionality and the library to which your code must link is identified below.

              DLL LIB Short Description

              mediaclientaudiostream.dll

              mediaclientaudiostream.lib

              These files are used for implementing Audio Output Streaming.

              Architectural Relationship

              How the Audio Output Streaming classes interact with other components of MMF is shown below:

              + Audio output streaming overview +
              Description

              Streamed audio data is sent and received incrementally. This means:

              • sound clips sent to the low level audio controller (audio play) can be sent as they arrive rather than waiting until the entire clip is received.

                The user of the API should maintain the data fragments in a queue before sending them to the server. If the user attempts to send data faster than the server can receive it, the excess data fragments are maintained in another client side queue (invisible to the user), whose elements are references to the buffers passed to it. The server notifies the client using a callback each time it has received a data fragment. This indicates to the client that the data fragment can be deleted.

              • sound clips that are being captured by the low level audio controller (audio record) can be read incrementally without having to wait until audio capture is complete.

                The low level audio controller maintains the received buffers where it can place the audio data that is being captured. The client uses a read function to read the received data into destination descriptors.

              The client is also notified (for audio play and record) when the stream is opened and available for use (opening takes place asynchronously), and when the stream is closed.

              This API can only be used to stream audio data, with the data being stored or sourced from a descriptor. Client applications must ensure that the data is in 16 bit PCM format as this is the only format supported. The API does not support mixing. A priority mechanism is used to control access to the sound device by more than one client.

              Key Audio Output Streaming Classes

              The functionality provided by Audio Output Streaming is contained within the CMdaAudioOutputStream class.

              Using Audio Output Streaming

              Clients can use Audio Output Streaming to:

              • Open, set audio properties, write to and close the audio stream.

              See Also

              Audio Output Streaming Tutorial

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-685C3F33-1530-4984-B125-E4EF8EBB2EE8.dita --- a/Symbian3/SDK/Source/GUID-685C3F33-1530-4984-B125-E4EF8EBB2EE8.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,34 +0,0 @@ - - - - - -Symbian -UI with rotation -

              Symbian UI can rotate between the portrait and landscape layout. This section -describes the guidelines for designing landscape-aware application user interfaces. -On the whole, the primary guideline in the Symbian platform is that no specific -UI design is necessary for landscape orientation and mode. Instead, applications -designed according to the guidelines described in this section should work -in both landscape orientation and with the default portrait orientation. This -section does, however, describe some exceptions to this rule.

              -

              The Symbian platform in landscape orientation follows the bottom softkey -style. In the bottom softkey style, the layout of the normal portrait UI is -merely stretched horizontally to fit the screen, leaving the softkeys below -the screen as in standard portrait orientation.

              - -Symbian UI rotated to landscape in the bottom softkey style - - -
              Using -portrait and landscape layouts in C++ applications

              Switching between -portrait and landscape layouts is handled in the application and UI frameworks -using layout change -events.

              -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-68A55CD5-EF01-5DE2-8119-EFA39589960F-GENID-1-8-1-3-1-1-9-1-4-1.dita --- a/Symbian3/SDK/Source/GUID-68A55CD5-EF01-5DE2-8119-EFA39589960F-GENID-1-8-1-3-1-1-9-1-4-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,13 +0,0 @@ - - - - - -How to Write -a FEP \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-68A55CD5-EF01-5DE2-8119-EFA39589960F-GENID-1-8-1-6-1-1-4-1-8-1-4-1.dita --- a/Symbian3/SDK/Source/GUID-68A55CD5-EF01-5DE2-8119-EFA39589960F-GENID-1-8-1-6-1-1-4-1-8-1-4-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,13 +0,0 @@ - - - - - -How to Write -a FEP \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-68A55CD5-EF01-5DE2-8119-EFA39589960F.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-68A55CD5-EF01-5DE2-8119-EFA39589960F.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,13 @@ + + + + + +How to Write +a FEP \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-68B999C2-0993-4804-9624-42C3D88BE5C7.dita --- a/Symbian3/SDK/Source/GUID-68B999C2-0993-4804-9624-42C3D88BE5C7.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-68B999C2-0993-4804-9624-42C3D88BE5C7.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,81 +1,81 @@ - - - - - -View -architecture -

              The following image illustrates the components of the view architecture -approach.

              -View architecture classes -

              Symbian platform applications that follow the view architecture require:

              -
                -

              • a UI -controller derived from CAknViewAppUi

                • -

              • a view -controller derived from CAknView

                • -

              • a view or -views derived from CCoeControl

                • -
              -

              The view architecture only allows one view to be active in each application. -If a new view is switched to within an application, the current view is immediately -deactivated, so this architectural approach is not appropriate in the -following cases:

              -
                -

              • Applications with any view that cannot cleanly handle unexpected -activation of another view in that application.

                • -

              • Applications that provide views that can be nested over other -applications, except where embedding is used.

                • -

              • Applications that provide controls that can be used inside -other applications (for example, using a Web control inside an e-mail viewer -to show an e‑mail with HTML content).

                • -
              -

              Typical responsibilities in this architecture are:

              -
                -

              • CAknViewAppUi-derived class acts as -a UI controller:

                - -
                  -

                • It creates one or more CAknView-derived -view controllers.

                  • -

                • It handles events that -are not handled by the view controllers.

                  • -

                • To switch between views, it activates and deactivates views.

                  -
                  • -

                • It handles menu commands passed -to it by the view controllers.

                  • -

                • It receives events such as layout and foreground notifications -from the run-time environment.

                  • -
                -                 -
                • -

              • CAknView-derived class acts as a view controller

                - -
                  -

                • It creates one of more CCoeControl-derived -views.

                  • -

                • It handles registering controls for key -event handling.

                  • -

                • It handles menu commands.

                  -
                  • -
                -                 -
                • -

              • CCoeControl-derived view:

                - -
                  -

                • Shows application data and state on the screen.

                  • -
                -                 -
                • -
              -

              For information on the CAknApplication and CAknDocument-derived -classes, see Framework -requirements for GUI applications.

              + + + + + +View +architecture +

              The following image illustrates the components of the view architecture +approach.

              +View architecture classes +

              Symbian platform applications that follow the view architecture require:

              +
                +

              • a UI +controller derived from CAknViewAppUi

                • +

              • a view +controller derived from CAknView

                • +

              • a view or +views derived from CCoeControl

                • +
              +

              The view architecture only allows one view to be active in each application. +If a new view is switched to within an application, the current view is immediately +deactivated, so this architectural approach is not appropriate in the +following cases:

              +
                +

              • Applications with any view that cannot cleanly handle unexpected +activation of another view in that application.

                • +

              • Applications that provide views that can be nested over other +applications, except where embedding is used.

                • +

              • Applications that provide controls that can be used inside +other applications (for example, using a Web control inside an e-mail viewer +to show an e‑mail with HTML content).

                • +
              +

              Typical responsibilities in this architecture are:

              +
                +

              • CAknViewAppUi-derived class acts as +a UI controller:

                + +
                  +

                • It creates one or more CAknView-derived +view controllers.

                  • +

                • It handles events that +are not handled by the view controllers.

                  • +

                • To switch between views, it activates and deactivates views.

                  +
                  • +

                • It handles menu commands passed +to it by the view controllers.

                  • +

                • It receives events such as layout and foreground notifications +from the run-time environment.

                  • +
                +                 +
                • +

              • CAknView-derived class acts as a view controller

                + +
                  +

                • It creates one of more CCoeControl-derived +views.

                  • +

                • It handles registering controls for key +event handling.

                  • +

                • It handles menu commands.

                  +
                  • +
                +                 +
                • +

              • CCoeControl-derived view:

                + +
                  +

                • Shows application data and state on the screen.

                  • +
                +                 +
                • +
              +

              For information on the CAknApplication and CAknDocument-derived +classes, see Framework +requirements for GUI applications.

               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-68BBBA98-BDF7-4562-8168-5E90C73ADCF8.dita --- a/Symbian3/SDK/Source/GUID-68BBBA98-BDF7-4562-8168-5E90C73ADCF8.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-68BBBA98-BDF7-4562-8168-5E90C73ADCF8.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,48 +1,48 @@ - - - - - -Device -security -

              The superior mobility and connectivity of mobile devices constitutes -their greatest threat, and allows intruders to try different attack methods -against the device. The figure below illustrates the most common methods of -attack against mobile devices.

              -Mobile device and common attack methods -

              Due to the nature of mobile devices, including the potential vulnerabilities -mentioned above, you should consider the following points when designing your -application:

              -
                -

              • If a mobile device is lost or stolen, confidential information -(for example, calendar and contacts) can be read even by those with little -expertise.

                • -

              • Users can access confidential information and files at any -time, including reverse engineering of software and algorithms.

                • -

              • Data can be transferred from and to the mobile device through -different methods, even accidentally.

                • -

              • Users may detach removable media or the battery at any time, -which can cause data loss or corruption.

                • -
              -

              When you handle confidential information in your application, remember -that with sufficient motivation and resources there are always ways to extract -information from a mobile device. As the level of software security improves -and attacks become less practical, interest in hardware attacks may in turn -increase.

              -

              In the continuously evolving digital world, every application should -have a certain level of robustness against a changing and hostile environment. -Applications should be prepared for data corruption and alteration, network -and storage blackouts, plug-ins and components that misbehave, malicious attackers, -and, perhaps most importantly, user errors.

              -

              The Symbian platform -security architecture is designed to protect mobile devices and their -contents.

              -

              For more details, see Device -security mechanisms.

              + + + + + +Device +security +

              The superior mobility and connectivity of mobile devices constitutes +their greatest threat, and allows intruders to try different attack methods +against the device. The figure below illustrates the most common methods of +attack against mobile devices.

              +Mobile device and common attack methods +

              Due to the nature of mobile devices, including the potential vulnerabilities +mentioned above, you should consider the following points when designing your +application:

              +
                +

              • If a mobile device is lost or stolen, confidential information +(for example, calendar and contacts) can be read even by those with little +expertise.

                • +

              • Users can access confidential information and files at any +time, including reverse engineering of software and algorithms.

                • +

              • Data can be transferred from and to the mobile device through +different methods, even accidentally.

                • +

              • Users may detach removable media or the battery at any time, +which can cause data loss or corruption.

                • +
              +

              When you handle confidential information in your application, remember +that with sufficient motivation and resources there are always ways to extract +information from a mobile device. As the level of software security improves +and attacks become less practical, interest in hardware attacks may in turn +increase.

              +

              In the continuously evolving digital world, every application should +have a certain level of robustness against a changing and hostile environment. +Applications should be prepared for data corruption and alteration, network +and storage blackouts, plug-ins and components that misbehave, malicious attackers, +and, perhaps most importantly, user errors.

              +

              The Symbian platform +security architecture is designed to protect mobile devices and their +contents.

              +

              For more details, see Device +security mechanisms.

               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-68E3609C-3429-5B1C-B8D9-C0EBBACEF357_d0e188429_href.png Binary file Symbian3/SDK/Source/GUID-68E3609C-3429-5B1C-B8D9-C0EBBACEF357_d0e188429_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-68E3609C-3429-5B1C-B8D9-C0EBBACEF357_d0e193491_href.png Binary file Symbian3/SDK/Source/GUID-68E3609C-3429-5B1C-B8D9-C0EBBACEF357_d0e193491_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6913F58F-FDA1-4708-B03E-16AF6C545E5B_d0e1315_href.jpg Binary file Symbian3/SDK/Source/GUID-6913F58F-FDA1-4708-B03E-16AF6C545E5B_d0e1315_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6913F58F-FDA1-4708-B03E-16AF6C545E5B_d0e1394_href.jpg Binary file Symbian3/SDK/Source/GUID-6913F58F-FDA1-4708-B03E-16AF6C545E5B_d0e1394_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-694C7416-927E-58F7-B010-CA55D2FFA88F_d0e189143_href.png Binary file Symbian3/SDK/Source/GUID-694C7416-927E-58F7-B010-CA55D2FFA88F_d0e189143_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-694C7416-927E-58F7-B010-CA55D2FFA88F_d0e194205_href.png Binary file Symbian3/SDK/Source/GUID-694C7416-927E-58F7-B010-CA55D2FFA88F_d0e194205_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6971B0A2-F79B-4E05-8AF3-BB1FC1932A22.dita --- a/Symbian3/SDK/Source/GUID-6971B0A2-F79B-4E05-8AF3-BB1FC1932A22.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-6971B0A2-F79B-4E05-8AF3-BB1FC1932A22.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,55 +1,55 @@ - - - - - -Capabilities -

              Capabilities allow the Symbian platform to control access by applications -to the functionalities provided by the platform APIs. Access to capabilities -is determined by the device configuration and how the application has been -signed. Capabilities can be divided into four categories:

              -
                -

              • user capabilities: LocalServices, NetworkServices, ReadUserData, WriteUserData, UserEnvironment and, Location

                -
                • -

              • system capabilities: PowerMgmt, ProtServ, ReadDeviceData, SurroundingsDD, SwEvent, TrustedUI, WriteDeviceData

                -
                • -

              • restricted capabilities: CommDD, DiskAdmin, MultimediaDD and NetworkControl

                -
                • -

              • device manufacturer capabilities: AllFiles, DRM and TCB

                -
                • -
              -

              Capabilities required by the application are defined in the mmp project -definition file during the build process, and cannot be changed during run -time. For information on the parameters you can use, see capability. -Carbide.c++ has a Capability Scanner tool which can be accessed through the Project -> Run Capability Scanner on Project MMP menu. The tool scans and checks -the project for required capabilities.

              -

              During the installation the Software -Installer application in the device checks whether the application -has been certified or signed. It then checks the capabilities requested by -the application. If the application has been certified, it checks that the -root certificate is allowed to grant the required capabilities. If no problems -are encountered, the installation can continue. For information on certifications -required by the capabilities, see Application -signing.

              -

              The user can grant the user capabilities to a self-signed application. -For example, the following dialog is shown to the user to grant the LocalServices capability:

              -Granting LocalServices capability during the installation -
              dll capabilities -

              A dll must have equal or greater set of capabilities -than the loading process, otherwise the process is not allowed to load the dll. -Once loaded, a dll runs at the capability level of the loading -process. A dll that has a higher capability set than the -loading process cannot leak capabilities to the process, but a process can -leak capabilities to the dll.

              -

              For more information, see DLL -capability model in a secure platform (TSS000454) in the Forum Nokia -Knowledge Base.

              -
              + + + + + +Capabilities +

              Capabilities allow the Symbian platform to control access by applications +to the functionalities provided by the platform APIs. Access to capabilities +is determined by the device configuration and how the application has been +signed. Capabilities can be divided into four categories:

              +
                +

              • user capabilities: LocalServices, NetworkServices, ReadUserData, WriteUserData, UserEnvironment and, Location

                +
                • +

              • system capabilities: PowerMgmt, ProtServ, ReadDeviceData, SurroundingsDD, SwEvent, TrustedUI, WriteDeviceData

                +
                • +

              • restricted capabilities: CommDD, DiskAdmin, MultimediaDD and NetworkControl

                +
                • +

              • device manufacturer capabilities: AllFiles, DRM and TCB

                +
                • +
              +

              Capabilities required by the application are defined in the mmp project +definition file during the build process, and cannot be changed during run +time. For information on the parameters you can use, see capability. +Carbide.c++ has a Capability Scanner tool which can be accessed through the Project +> Run Capability Scanner on Project MMP menu. The tool scans and checks +the project for required capabilities.

              +

              During the installation the Software +Installer application in the device checks whether the application +has been certified or signed. It then checks the capabilities requested by +the application. If the application has been certified, it checks that the +root certificate is allowed to grant the required capabilities. If no problems +are encountered, the installation can continue. For information on certifications +required by the capabilities, see Application +signing.

              +

              The user can grant the user capabilities to a self-signed application. +For example, the following dialog is shown to the user to grant the LocalServices capability:

              +Granting LocalServices capability during the installation +
              dll capabilities +

              A dll must have equal or greater set of capabilities +than the loading process, otherwise the process is not allowed to load the dll. +Once loaded, a dll runs at the capability level of the loading +process. A dll that has a higher capability set than the +loading process cannot leak capabilities to the process, but a process can +leak capabilities to the dll.

              +

              For more information, see DLL +capability model in a secure platform (TSS000454) in the Forum Nokia +Knowledge Base.

              +
               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-69831D75-D16D-54CF-A083-0EDB358F3390_d0e80140_href.png Binary file Symbian3/SDK/Source/GUID-69831D75-D16D-54CF-A083-0EDB358F3390_d0e80140_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-69831D75-D16D-54CF-A083-0EDB358F3390_d0e86852_href.png Binary file Symbian3/SDK/Source/GUID-69831D75-D16D-54CF-A083-0EDB358F3390_d0e86852_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-69847989-624F-5119-8AC0-3D95D72AF076_d0e76088_href.png Binary file Symbian3/SDK/Source/GUID-69847989-624F-5119-8AC0-3D95D72AF076_d0e76088_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-69847989-624F-5119-8AC0-3D95D72AF076_d0e82800_href.png Binary file Symbian3/SDK/Source/GUID-69847989-624F-5119-8AC0-3D95D72AF076_d0e82800_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6A482ACB-D39E-578B-B58B-44E4142A5897_d0e351818_href.png Binary file Symbian3/SDK/Source/GUID-6A482ACB-D39E-578B-B58B-44E4142A5897_d0e351818_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6A482ACB-D39E-578B-B58B-44E4142A5897_d0e357898_href.png Binary file Symbian3/SDK/Source/GUID-6A482ACB-D39E-578B-B58B-44E4142A5897_d0e357898_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6A5D0445-5D53-5293-A501-136203C80BEE_d0e202292_href.png Binary file Symbian3/SDK/Source/GUID-6A5D0445-5D53-5293-A501-136203C80BEE_d0e202292_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6A5D0445-5D53-5293-A501-136203C80BEE_d0e207300_href.png Binary file Symbian3/SDK/Source/GUID-6A5D0445-5D53-5293-A501-136203C80BEE_d0e207300_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6A7F8298-F3E9-513C-8C1F-D057AC62E5E3.dita --- a/Symbian3/SDK/Source/GUID-6A7F8298-F3E9-513C-8C1F-D057AC62E5E3.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-6A7F8298-F3E9-513C-8C1F-D057AC62E5E3.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,63 +1,373 @@ - - - - - -Advanced Settings for Focus, Drive Modes, and Bracket Modes This document provides a detailed description of various advanced settings of Ecam component.
              Introduction

              The advanced settings class, CCamera::CCameraAdvancedSettings, provides access to common camera hardware settings related to image acquisition for still images and video.

              Focus mode

              The high level steps to set the Camera focus mode are shown here:

              • Get the information about the supported focus modes on the camera using the TInt - CCamera::CCameraAdvancedSettings::SupportedFocusModes() method.

              • Set a specific focus mode on the camera using the CCamera::CCameraAdvancedSettings::SetFocusMode() method.

              • Get the current focus mode on the camera using the CCamera::CCameraAdvancedSettings::FocusMode() method.

                The enumerated type CCamera::CCameraAdvancedSettings::FocusMode() defines four supported focus modes:

                Enum Value

                Description

                EFocusModeUnknown

                Focus mode is unknown

                EStabilizationComplexityLow

                Focus mode is automatic

                EStabilizationComplexityMedium

                Focus is fixed

                EStabilizationComplexityHigh

                Focus is manually set

              The following example shows how to change the focus mode:

              // Assigns the focus mode to be set - CCamera::CCameraAdvancedSettings::TFocusMode focusMode = CCamera::CCameraAdvancedSettings::EFocusModeFixed; - - // Gets the supported modes - TInt suppFocusModes = settings->SupportedFocusModes();// Checks if the focus mode is supported before setting it - if (focusMode & suppFocusModes) - { - // Sets the focus mode if it is supported - settings->SetFocusMode(focusMode); - }

              Focus range

              Get the supported focus range using the enumerated type CCamera::CCameraAdvancedSettings::TFocusRange. This defines eight supported focus ranges:

              Enum Value

              Description

              EFocusRangeAuto

              Automatic

              EFocusRangeMacro

              Focus operates in close range

              EFocusRangeMacro

              Normal operation

              EFocusRangeMacro

              Extended (tele) operation

              EFocusRangePortrait

              Focus at larger areas at short to medium distance

              EFocusRangeSuperMacro

              Optimised macro operation, where depth of field is very shallow and observation area changes quickly

              EFocusRangeHyperfocal

              All objects at distances from half of the hyperfocal distance out to infinity will be in focus. This gives maximum depth of field.

              EFocusRangeInfinite

              Infinite range, when there is a near obstacle or better focus wanted for far away objects.

              The following example shows how to change the focus range:

              // Assigns the focus range to EFocusRangeHyperfocal and checks if it is supported - CCamera::CCameraAdvancedSettings::TFocusRange focusRange = CCamera::CCameraAdvancedSettings::EFocusRangeHyperfocal; - - // Gets the supported ranges - TInt suppRanges = settings->SupportedFocusRanges(); - - // Checks if the focus range is supported before setting it. - if (focusRange & suppRanges) - { - // Sets the focus range if it is supported - settings->SetFocusRange(focusRange); - }

              The result of SetFocusRange is notified to the client asynchronously through MCameraObserver2::HandleEvent() and with UID KUidECamEventCameraSettingFocusRange2.

              Autofocus types

              Get the supported autofocus types using the enumerated type CCamera::CCameraAdvancedSettings::TAutoFocusType. This defines three supported focus types:

              Enum

              Description

              EAutoFocusTypeOff

              Autofocus is switched off

              EAutoFocusTypeSingle

              Operates on a single shot, consumes less power

              EAutoFocusTypeContinuous

              Continuous autofocus, more precise but consumes more power. This is also known as AF Servo.

              The following example shows how to change the autofocus type:

              CCamera::CCameraAdvancedSettings::TAutoFocusType focusType = CCamera::CCameraAdvancedSettings::EAutoFocusTypeOff; - - // Gets the supported focus types - TInt suppFocusTypes = settings->SupportedAutoFocusTypes(); - - // Checks if the focus type is supported before setting it. - if (focusType & suppFocusTypes) - { - // Sets the focus type if it is supported - settings->SetAutoFocusType(focusType); - }

              The result of SetAutoFocusType is notified to the client asynchronously through MCameraObserver2::HandleEvent() and with uid KUidECamEventCameraSettingAutoFocusType2.

              Drive modes

              Get the supported drive modes for the camera using the enumerated type CCamera::CCameraAdvancedSettings::TDriveMode that determines how and in what succession images are captured. This defines eight supported drive modes for the camera with the following Enum Values:

              Enum Value

              Description

              EDriveModeAuto

              Automatic

              EDriveModeSingleShot

              Camera takes a single image or shot

              EDriveModeContinuous

              Camera continuously captures images as fast as it can until it is stopped or it exceeds the storage space.

              EDriveModeBracket

              Camera is in bracketing mode, producing individual frames.

              EDriveModeBracketMerge

              Camera is in bracketing mode, but producing a single image. Use CCamera::CCameraAdvancedSettings::SetBracketMerge method to work in this drive mode.

              EDriveModeTimed

              Camera captures a single shot after specified time period. Use CCamera::CCameraAdvancedSettings::SetTimerInterval method to work in this drive mode.

              EDriveModeTimeLapse

              Camera captures a set of images with an uniform interval between them. Use CCamera::CCameraAdvancedSettings::SetTimeLapse method to work in this drive mode.

              EDriveModeBurst

              Camera captures a set of images as fast as it can in batches or bursts. Use CCamera::CCameraAdvancedSettings::SetBurstImages method to set the number of burst images before capturing the image.

              Note: There are chances that the actual number of images captured may be less important due to memory or image size limitations.

              The following example shows how to change the drive mode:

              CCamera::CCameraAdvancedSettings::TDriveMode driveMode = CCamera::CCameraAdvancedSettings::EDriveModeSingleShot; - - // Gets the supported drive modes - TInt suppDriveModes = settings->SupportedDriveModes(); - - // Checks if the drive mode is supported before setting it. - if (driveMode & suppDriveModes) - { - // Sets the drive mode - settings->(driveMode); - }

              The result of SetDriveMode is notified to the client asynchronously through MCameraObserver2::HandleEvent() and with uid KUidECamEventCameraSettingDriveMode.

              Bracket modes

              Bracket mode is a type of drive mode, which is called using EDriveModeBracket method.

              Bracket mode involves the camera taking a sequence of pictures, while automatically varying a camera setting, such as exposure, over a range of values. The enumerated type CCamera::CCameraAdvancedSettings::TBracketMode defines three supported bracket modes for the camera. The setting that is varied is called the bracket parameter, and is represented by the CCamera::CCameraAdvancedSettings::TBracketParameter enumeration, while the scale of the change to the setting to make for each new picture is called the bracket step, and is represented by the CCamera::CCameraAdvancedSettings::TBracketStep enumeration. The possible bracket modes are:

              Enum Value

              Description

              EBracketModeOff

              Bracket mode is switched off. This is the default value.

              EBracketMode3Image

              Bracket mode on. Three consecutive pictures are taken in order, with the setting at under (-1), on (0), and over (+1).

              EBracketMode5Image

              Bracket mode on. Five consecutive pictures are taken in order, with the setting at under (-2), under (-1), on (0), over (+1), and over (+2).

              The following example shows how to change the bracket mode:

              CCamera::CCameraAdvancedSettings::TBracketMode bracketMode = CCamera::CCameraAdvancedSettings::EBracketMode3Image; - - // Gets the supported bracket modes - TInt suppBracketModes = settings->SupportedBracketModes(); - - // Checks if the bracket mode is supported before setting it. - if (bracketMode & suppBracketModes) - { - settings->SetBracketMode(bracketMode); - }

              Zoom Mode

              The high level steps to perform various operations in zoom mode are listed below:

              • Get the continuous zoom types supported by the camera using CCamera::CCameraAdvancedSettings::GetSupportedContinuousZoomTypeL method.

              • Start continuous zoom using CCamera::CCameraAdvancedSettings::StartContinuousZoomL() method with specified continuous zoom type and the zoom direction.

              • Notify the client about the extent of continuous zoom achieved using event KUidECamEvent2CameraSettingContinuousZoomPercentageCompletion. When continuous zoom reached its limit, notify the client using event KUidECamEventCameraSettingContinuousZoomReachedLimit.

              • Stop continuous zoom using CCamera::CCameraAdvancedSettings::StopContinuousZoom() method.

              Extending Pixel Aspect Ratio

              You can use the pixel aspect ratio to provide settings for PAL, NTSC and NTSC4:3. For this, you need to extend the enumeration of Enum TPixelAspectRatio as follows:

              Enum Value

              Description

              TPixelAspectRatio:: EEPixelAspect16:11

              PAL

              TPixelAspectRatio:: EEPixelAspect40:33

              NTSC

              TPixelAspectRatio:: EEPixelAspect10:11

              NTSC4:3

              Use CCamera::CCameraAdvancedSettings::PixelAspectRatio() method to get the current pixel aspect ratio.

              Use CCamera::CCameraAdvancedSettings::SetPixelAspectRatio() method to set the pixel aspect ratio. Notify MCameraObserver2 clients with KUidECamEventPixelAspectRatio event.

              Miscellaneous

              This section details the miscellaneous APIs used in CCameraAdvancedSettings class.

              • ISO rates : ISO indicates the sensitivity of the image sensor and is also a parameter that influences the exposure.

                • Get the set of camera supported ISO rates using theCCamera::CCameraAdvancedSettings::GetSupportedIsoRatesL() method. The Enum value TISORateType specifies the ISO type supported by the camera.

                • When camera device does not reveal the ISO supported rates, it has to be assumed that camera will work only on the permanently set value. If this value is not known, returns empty array and corresponding getter or setters for this feature should not be used in such a case.

                • Set the type of ISO rate and the exposure parameter or specific value using the CCamera::CCameraAdvancedSettings::SetISORateL() method.

                • Get the type of ISO rate, exposure parameter and the value set using the CCamera::CCameraAdvancedSettings::GetISORateL() method.

                • Get current ISO rate using CCamera::CCameraAdvancedSettings::IsoRate().

              • Get current aperture value using CCamera::CCameraAdvancedSettings::Aperture(). For example, the function returns 280 for the actual aperture of F2.8. If the value returned is Negative, indicates the error case (system wide error code) and positive represents the current aperture value.

              • Get the current shutter speed in microseconds using CCamera::CCameraAdvancedSettings::ShutterSpeed(). If the value returned is Negative, indicates the error case (system wide error code) and positive represents the current shutter speed.

              • Get all supported metering modes on this camera using CCamera::CCameraAdvancedSettings::SupportedMeteringModes().

              • Get all supported drive modes as bitfields of TDriveMode type using CCamera::CCameraAdvancedSettings::SupportedDriveModes().

              • Get the currently set flash mode using CCamera::TFlash - CCamera::CCameraAdvancedSettings::FlashMode().

              See also

              Overview for the advanced settings of Camera

              The Advanced Camera Settings tutorial

              \ No newline at end of file + + + + + +Advanced +Settings for Focus, Drive Modes, and Bracket Modes This document provides a detailed description of various advanced +settings of Ecam component. +
              Introduction

              The +advanced settings class, CCamera::CCameraAdvancedSettings, +provides access to common camera hardware settings related to image acquisition +for still images and video.

              Focus +mode

              The high level steps to set the Camera focus mode are shown +here:

                +

              • Get the information +about the supported focus modes on the camera using the CCamera::CCameraAdvancedSettings::SupportedFocusModes() +const method.

                • +

              • Set a specific focus +mode on the camera using the CCamera::CCameraAdvancedSettings::SetFocusMode(TFocusMode +aFocusMode) method.

                • +

              • Get the current focus +mode on the camera using the CCamera::CCameraAdvancedSettings::FocusMode() method.

                The +enumerated type CCamera::CCameraAdvancedSettings::TFocusMode defines +four supported focus modes:

                + + + +

                Enum Value

                +

                Description

                +                 + +

                EFocusModeUnknown

                +

                Focus mode is unknown

                +                 + +

                EStabilizationComplexityLow

                +

                Focus mode is automatic

                +                 + +

                EStabilizationComplexityMedium

                +

                Focus is fixed

                +                 + +

                EStabilizationComplexityHigh

                +

                Focus is manually set

                +                 + + +
                • +

              The following example shows how to change the focus mode:

              // Assigns the focus mode to be set + CCamera::CCameraAdvancedSettings::TFocusMode focusMode = CCamera::CCameraAdvancedSettings::EFocusModeFixed; + + // Gets the supported modes + TInt suppFocusModes = settings->SupportedFocusModes();// Checks if the focus mode is supported before setting it + if (focusMode & suppFocusModes) + { + // Sets the focus mode if it is supported + settings->SetFocusMode(focusMode); + }

              Focus +range

              Get the supported focus range using the enumerated type CCamera::CCameraAdvancedSettings:TFocusRange. +This defines eight supported focus ranges:

              + + + +

              Enum Value

              +

              Description

              +               + +

              EFocusRangeAuto

              +

              Automatic

              +               + +

              EFocusRangeMacro

              +

              Focus operates in close range

              +               + +

              EFocusRangeMacro

              +

              Normal operation

              +               + +

              EFocusRangeMacro

              +

              Extended (tele) operation

              +               + +

              EFocusRangePortrait

              +

              Focus at larger areas at short to medium distance

              +               + +

              EFocusRangeSuperMacro

              +

              Optimized macro operation, where depth of field is very shallow +and observation area changes quickly

              +               + +

              EFocusRangeHyperfocal

              +

              All objects at distances from half of the hyperfocal distance out +to infinity will be in focus. This gives maximum depth of field.

              +               + +

              EFocusRangeInfinite

              +

              Infinite range, when there is a near obstacle or better focus wanted +for far away objects.

              +               + + +

              The following example shows how to change the focus range:

              // Assigns the focus range to EFocusRangeHyperfocal and checks if it is supported + CCamera::CCameraAdvancedSettings::TFocusRange focusRange = CCamera::CCameraAdvancedSettings::EFocusRangeHyperfocal; + + // Gets the supported ranges + TInt suppRanges = settings->SupportedFocusRanges(); + + // Checks if the focus range is supported before setting it. + if (focusRange & suppRanges) + { + // Sets the focus range if it is supported + settings->SetFocusRange(focusRange); + }

              The result of SetFocusRange is notified +to the client asynchronously through MCameraObserver2::HandleEvent() and +with UID KUidECamEventCameraSettingFocusRange2.

              Autofocus

              Autofocus +support for camera applications is controlled through the CCameraAdvancedSettings class.

              +Implementation of autofocus + +

              Pressing the camera shutter key on the device halfway down generates +additional key events. The key events can be used to activate autofocus if +the camera hardware supports the functionality. Shutter release (image capture) +can be triggered by pressing the key all the way down. The key presses generate +separate key events. To capture other than autofocus key events from the shutter +key, you need the SwEvent capability.

              The +settings you can use in your application depend on the camera hardware on +the device. The Camera API allows you to query almost all features of the +device camera. For example, to get a list of supported advanced settings, +use the CCameraAdvancedSettings::GetSupportedSettingsL(RArray<TUid>& +aSettings) const method.

              Get the supported autofocus types +using the enumerated type CCamera::CCameraAdvancedSettings:TAutoFocusType. +This defines three supported focus types:

              + + + +

              Enum

              +

              Description

              +               + +

              EAutoFocusTypeOff

              +

              Autofocus is switched off.

               +               + +

              EAutoFocusTypeSingle

              +

              Operates on a single shot, consumes less power.

              +               + +

              EAutoFocusTypeContinuous

              +

              Continuous autofocus, more precise but consumes more power. This +is also known as AF Servo.

              +               + + +

              The following example shows how to change the autofocus type:

              CCamera::CCameraAdvancedSettings::TAutoFocusType focusType = CCamera::CCameraAdvancedSettings::EAutoFocusTypeOff; + + // Gets the supported focus types + TInt suppFocusTypes = settings->SupportedAutoFocusTypes(); + + // Checks if the focus type is supported before setting it. + if (focusType & suppFocusTypes) + { + // Sets the focus type if it is supported + settings->SetAutoFocusType(focusType); + }

              The result of CCamera::CCameraAdvancedSettings::SetAutoFocusType(TAutoFocusType +aAutoFocusType) is notified to the client asynchronously through MCameraObserver2::HandleEvent() and +with uid KUidECamEventCameraSettingAutoFocusType2.

              For +more information on how to easily use the device camera with zoom and autofocus, +see S60 Platform: Camera +Example. The Camera Wrapper provides a unified interface for various +Symbian camera APIs. The example application supports the use of both the +keypad and touch UI. The application can be self-signed, but it also provides +an option to use the dedicated camera key (Symbian signing required).

              Drive modes

              Get +the supported drive modes for the camera using the enumerated type CCamera::CCameraAdvancedSettings:TDriveMode that +determines how and in what succession images are captured. This defines eight +supported drive modes for the camera with the following Enum Values:

              + + + +

              Enum Value

              +

              Description

              +               + +

              EDriveModeAuto

              +

              Automatic

              +               + +

              EDriveModeSingleShot

              +

              Camera takes a single image or shot

              +               + +

              EDriveModeContinuous

              +

              Camera continuously captures images as fast as it can until it is +stopped or it exceeds the storage space.

              +               + +

              EDriveModeBracket

              +

              Camera is in bracketing mode, producing individual frames.

              +               + +

              EDriveModeBracketMerge

              +

              Camera is in bracketing mode, but producing a single image. Use CCamera::CCameraAdvancedSettings::SetBracketMerge(TInt +aStartIndex, TInt aFrames) method to work in this drive mode.

              +               + +

              EDriveModeTimed

              +

              Camera captures a single shot after specified time period. Use CCamera::CCameraAdvancedSettings::SetTimerInterval(TInt +aTimerInterval) method to work in this drive mode.

              +               + +

              EDriveModeTimeLapse

              +

              Camera captures a set of images with an uniform interval between +them. Use CCamera::CCameraAdvancedSettings::SetTimeLapse(const TTime& +aStart, const TTime& aEnd, const TTime& aInterval) method +to work in this drive mode.

              +               + +

              EDriveModeBurst

              +

              Camera captures a set of images as fast as it can in batches or +bursts. Use CCamera::CCameraAdvancedSettings::SetBurstImages(TInt +aImages) method to set the number of burst images before capturing +the image.

              Note: There are chances that the actual number +of images captured may be less important due to memory or image size limitations.

              +               + + +

              The following example shows how to change the drive mode:

              CCamera::CCameraAdvancedSettings::TDriveMode driveMode = CCamera::CCameraAdvancedSettings::EDriveModeSingleShot; + + // Gets the supported drive modes + TInt suppDriveModes = settings->SupportedDriveModes(); + + // Checks if the drive mode is supported before setting it. + if (driveMode & suppDriveModes) + { + // Sets the drive mode + settings->(driveMode); + }

              The result of CCamera::CCameraAdvancedSettings::SetDriveMode(TDriveMode +aDriveMode) is notified to the client asynchronously through MCameraObserver2::HandleEvent() and +with uid KUidECamEventCameraSettingDriveMode.

              Bracket +modes

              Bracket mode is a type of drive mode, which is called using CCamera::CCameraAdvancedSettings::EDriveModeBracket.

              Bracket mode involves the camera taking a sequence of pictures, +while automatically varying a camera setting, such as exposure, over a range +of values. The enumerated type CCamera::CCameraAdvancedSettings:TBracketMode defines +three supported bracket modes for the camera. The setting that is varied is +called the bracket parameter, and is represented by the CCamera::CCameraAdvancedSettings:TBracketParameter enumeration, +while the scale of the change to the setting to make for each new picture +is called the bracket step, and is represented by the CCamera::CCameraAdvancedSettings:TBracketStep enumeration. +The possible bracket modes are:

              + + + +

              Enum Value

              +

              Description

              +               + +

              EBracketModeOff

              +

              Bracket mode is switched off. This is the default value.

              +               + +

              EBracketMode3Image

              +

              Bracket mode on. Three consecutive pictures are taken in order, +with the setting at under (-1), on (0), and over (+1).

              +               + +

              EBracketMode5Image

              +

              Bracket mode on. Five consecutive pictures are taken in order, with +the setting at under (-2), under (-1), on (0), over (+1), and over (+2).

              +               + + +

              The following example shows how to change the bracket mode:

              CCamera::CCameraAdvancedSettings::TBracketMode bracketMode = CCamera::CCameraAdvancedSettings::EBracketMode3Image; + + // Gets the supported bracket modes + TInt suppBracketModes = settings->SupportedBracketModes(); + + // Checks if the bracket mode is supported before setting it. + if (bracketMode & suppBracketModes) + { + settings->SetBracketMode(bracketMode); + }

              Zoom Mode

              The high level steps to +perform various operations in zoom mode are listed below:

                +

              • Get the continuous zoom +types supported by the camera using CCamera::CCameraAdvancedSettings::GetSupportedContinuousZoomTypeL(TUint& +aSupportedContinuousZoomType) const method.

                • +

              • Start continuous zoom +using CCamera::CCameraAdvancedSettings::StartContinuousZoomL(CCamera::CCameraAdvancedSettings::TContinuousZoomParameters +aContinuousZoomParameters)() method with specified continuous zoom +type and the zoom direction.

                • +

              • Notify the client about +the extent of continuous zoom achieved using event KUidECamEvent2CameraSettingContinuousZoomPercentageCompletion. +When continuous zoom reached its limit, notify the client using event KUidECamEventCameraSettingContinuousZoomReachedLimit.

                • +

              • Stop continuous zoom +using CCamera::CCameraAdvancedSettings::StopContinuousZoom() method.

                • +

              Extending Pixel Aspect Ratio

              You can use the pixel +aspect ratio to provide settings for PAL, NTSC and NTSC4:3. For this, you +need to extend the enumeration of enum CCamera::CCameraAdvancedSettings:TPixelAspectRatio as +follows:

              + + + +

              Enum Value

              +

              Description

              +               + +

              TPixelAspectRatio::EEPixelAspect16:11

              +

              PAL

              +               + +

              TPixelAspectRatio::EEPixelAspect40:33

              +

              NTSC

              +               + +

              TPixelAspectRatio::EEPixelAspect10:11

              +

              NTSC4:3

              +               + + +

              Use CCamera::CCameraAdvancedSettings::PixelAspectRatio() method +to get the current pixel aspect ratio.

              Use CCamera::CCameraAdvancedSettings::SetPixelAspectRatio(TPixelAspectRatio +aPixelAspectRatio) method to set the pixel aspect ratio. Notify MCameraObserver2 clients +with KUidECamEventPixelAspectRatio event.

              +
              Miscellaneous

              This +section details the miscellaneous APIs used in CCameraAdvancedSettings class.

                +

              • ISO rates : +ISO indicates the sensitivity of the image sensor and is also a parameter +that influences the exposure.

                  +

                • Get the set of camera +supported ISO rates using theCCamera::CCameraAdvancedSettings::GetSupportedIsoRatesL(RArray<TInt>& +aSupportedIsoRates) const method. The enum value CCamera::CCameraAdvancedSettings:TISORateType specifies +the ISO type supported by the camera.

                  • +

                • When camera device does +not reveal the ISO supported rates, it has to be assumed that camera will +work only on the permanently set value. If this value is not known, returns +empty array and corresponding getter or setters for this feature should not +be used in such a case.

                  • +

                • Set the type of ISO +rate and the exposure parameter or specific value using the CCamera::CCameraAdvancedSettings::SetISORateL(TISORateType +aISORateType, TInt aParam) method.

                  • +

                • Get the type of ISO +rate, exposure parameter and the value set using the CCamera::CCameraAdvancedSettings::GetISORateL(TISORateType& +aISORateType, TInt& aParam, TInt& aISORate) const method.

                  • +

                • Get current ISO rate +using CCamera::CCameraAdvancedSettings::IsoRate() const.

                  • +
                • +

              • Get current aperture +value using CCamera::CCameraAdvancedSettings::Aperture() const. +For example, the function returns 280 for the actual aperture of F2.8. If +the value returned is negative, indicates the error case (system wide error +code) and positive represents the current aperture value.

                • +

              • Get the current shutter +speed in microseconds using CCamera::CCameraAdvancedSettings::ShutterSpeed() +const. If the value returned is negative, indicates the error case +(system wide error code) and positive represents the current shutter speed.

                • +

              • Get all supported metering +modes on this camera using CCamera::CCameraAdvancedSettings::SupportedMeteringModes() +const.

                • +

              • Get all supported drive +modes as bitfields of TDriveMode type using CCamera::CCameraAdvancedSettings::SupportedDriveModes() +const.

                • +

              • Get the currently set +flash mode using CCamera::CCameraAdvancedSettings::FlashMode().

                • +
              +
              See also

              Overview for the advanced +settings of Camera

              The Advanced +Camera Settings tutorials.

              The S60 +Platform: Camera Example.

              +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6A9991B8-CF03-5097-BE7D-FB486D26D41B_d0e289302_href.png Binary file Symbian3/SDK/Source/GUID-6A9991B8-CF03-5097-BE7D-FB486D26D41B_d0e289302_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6A9991B8-CF03-5097-BE7D-FB486D26D41B_d0e292985_href.png Binary file Symbian3/SDK/Source/GUID-6A9991B8-CF03-5097-BE7D-FB486D26D41B_d0e292985_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6ABEF478-F3DB-524E-A500-9431B42C6665.dita --- a/Symbian3/SDK/Source/GUID-6ABEF478-F3DB-524E-A500-9431B42C6665.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-6ABEF478-F3DB-524E-A500-9431B42C6665.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,92 +1,92 @@ - - - - - -Single -Call TutorialThis tutorial describes how to handle single call with the telephony -API for applications. -

              This state diagram -shows how to dial or answer one call at a time. It presumes there are no other -calls being made.

              - Single Call State Diagram - -

              The boxes are states. The enumeration value in each box is the status -of the voice line. Voice -line status describes the states and their meaning. You can also find -the status of individual calls. The line state and the call state are the -same in a single call.

              The arrows show events that trigger a change -of state. In these events, a word in bold indicates a CTelephony method -that you can call.

              - - -Check the Voice -line status - - -if the line is Idle(CTelephony::EStatusIdle) no calls -are in progress - - -if the line is on hold(CTelephony::EStatusHold) then -there is another call in progress, but it is on hold and you can still dial -or answer a second call - - -if a call is active, you must wait until it completes before you can -dial or receive a call. To detect when this occurs, see Notification -Request Tutorial - - - - - Dial a call -While no calls are in progress, the line status is CTelephony::EStatusIdle. -To dial a call, use CTelephony::DialNewCall(). -If successful and the remotes party answers the call then the line status -is CTelephony::EStatusConnected. - - - Answer a call -When no calls are in progress, the line status is CTelephony::EStatusIdle. -When a remote party calls your phone, the voice line status will change -to CTelephony::EStatusRinging. -When the status is CTelephony::EStatusRinging, use CTelephony::AnswerIncomingCall() to -answer the call. The status changes to CTelephony::EStatusConnected and -the phone user can talk to the remote party. - - - Terminate a -call - - - Detect remote -party call termination - - - Hold a Call - - - Resume a call - - - Send DTMF tones - - -

              When you successfully dial or answer a call, you will be given -a - CTelephony::TCallId the identifies the call. -

              A remote party might try to ring your phone. The voice line state will -change to CTelephony::EStatusRinging. You can ignore this -call. You can still terminate, hold, resume and send DTMF. -

               -               -Simultaneous - Call Tutorial + + + + + +Single +Call TutorialThis tutorial describes how to handle single call with the telephony +API for applications. +

              This state diagram +shows how to dial or answer one call at a time. It presumes there are no other +calls being made.

              + Single Call State Diagram + +

              The boxes are states. The enumeration value in each box is the status +of the voice line. Voice +line status describes the states and their meaning. You can also find +the status of individual calls. The line state and the call state are the +same in a single call.

              The arrows show events that trigger a change +of state. In these events, a word in bold indicates a CTelephony method +that you can call.

              + + +Check the Voice +line status + + +if the line is Idle(CTelephony::EStatusIdle) no calls +are in progress + + +if the line is on hold(CTelephony::EStatusHold) then +there is another call in progress, but it is on hold and you can still dial +or answer a second call + + +if a call is active, you must wait until it completes before you can +dial or receive a call. To detect when this occurs, see Notification +Request Tutorial + + + + + Dial a call +While no calls are in progress, the line status is CTelephony::EStatusIdle. +To dial a call, use CTelephony::DialNewCall(). +If successful and the remotes party answers the call then the line status +is CTelephony::EStatusConnected. + + + Answer a call +When no calls are in progress, the line status is CTelephony::EStatusIdle. +When a remote party calls your phone, the voice line status will change +to CTelephony::EStatusRinging. +When the status is CTelephony::EStatusRinging, use CTelephony::AnswerIncomingCall() to +answer the call. The status changes to CTelephony::EStatusConnected and +the phone user can talk to the remote party. + + + Terminate a +call + + + Detect remote +party call termination + + + Hold a Call + + + Resume a call + + + Send DTMF tones + + +

              When you successfully dial or answer a call, you will be given +a + CTelephony::TCallId the identifies the call. +

              A remote party might try to ring your phone. The voice line state will +change to CTelephony::EStatusRinging. You can ignore this +call. You can still terminate, hold, resume and send DTMF. +

               +               +Simultaneous + Call Tutorial               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6B50C0B9-C3CB-4524-909D-7FD096A3F894.dita --- a/Symbian3/SDK/Source/GUID-6B50C0B9-C3CB-4524-909D-7FD096A3F894.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,78 +0,0 @@ - - - - - -Menu -list -

              Menu lists are used to select one item from a list and do nothing else; -the Options command is not available when a menu list is being browsed (the -Options menu itself is a menu list).

              -

              If a high-priority event, such as an incoming call, occurs when a menu -list is open, the list is cancelled and the new event takes control. These -lists are often displayed inside a pop-up window.

              -

              The default keypad functions in a menu list are the following:

              -Default key events -in a menu list - - - -Key -Action - - - - -

              Arrow up / down

               -

              Moves the focus in the list.

               -               - -

              Arrow left / right

               -

              Ignored (unless there is a submenu; see Submenus).

               -               - -

              Selection key

               -

              Selects the item, does the associated function.

               -               - -

              Left softkey (Select)

               -

              Selects the item, does the associated function.

               -               - -

              Right softkey (Cancel)

               -

              Dismisses the menu; returns to the state preceding the opening of -the menu.

               -               - -

              Call creation key, Edit key

               -

              Ignored.

               -               - -

              Numeric keypad

               -

              Ignored.

               -               - -

              Clear key

               -

              Ignored.

               -               - -

              Other keys

               -

              Dismiss the menu and do the default action of the key.

               -               - - -
              - -Options menu - - -
              Using -menu lists in C++ applications

              The API to use for menu lists is -the Lists API. For implementation information, see Using the Lists API.

              -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6B8BA8A8-AD56-55BA-9659-15091E988FB7.dita --- a/Symbian3/SDK/Source/GUID-6B8BA8A8-AD56-55BA-9659-15091E988FB7.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-6B8BA8A8-AD56-55BA-9659-15091E988FB7.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,43 +1,38 @@ - - - - - -S60 -Platform: HTTP Client ExampleThis example shows how to use HTTP APIs. -
              Description

              This -updated C++ application demonstrates simple HTTP GET and POST transactions -using the HTTP Client API. Basic HTTP authentication is also supported. The -updated v2.2 example uses application-level roaming (introduced in S60 3rd -Edition, Feature Pack 2 onwards). The updated example has been tested to support -S60 5th Edition and touch UI. Important classes: RHTTPSession, RHTTPTransaction, -RHTTPHeaders, MHTTPDataSupplier, MHTTPAuthenticationCallback, MHTTPTransactionCallback. -For more details, click on this link : Http Client Example

              -
              Download

              Click -on the following link to download the example: Httpclientexample.zip

              Click: browse to view the example code.

              -
              Building -and configuring

              To build the example:

                -

              • You can build the example -from your IDE or the command line.

                If you use an IDE, import the bld.inf file -of the example into your IDE, and use the build command of the IDE.

                If -you use the command line, open a command prompt, and set the current directory -to the source code directory of the example. You can then build the example -with the SBSv1 build tools with the following commands:

                bldmake -bldfiles

                abld build

                How to use bldmake and How to use abld describe -how to use the SBSv1 build tools.

                • -

              • For the emulator, the -example builds an executable called httpexampleclient.exe in -the epoc32\release\winscw\<udeb or urel>\ folder.

                • -
              -               -Simple Client -Session guide -HTTP Overview - + + + + + +HTTP +Client ExampleThis example shows how to use HTTP APIs. +
              Description

              This +updated C++ application demonstrates simple HTTP GET and POST transactions +using the HTTP Client API. Basic HTTP authentication is also supported.

              +
              Download

              Click +on the following link to download the example: Httpclientexample.zip

              Click: browse to view the example code.

              +
              Building and +configuring

              To build the example:

                +

              • You can build the example +from your IDE or the command line.

                If you use an IDE, import the bld.inf file +of the example into your IDE, and use the build command of the IDE.

                If +you use the command line, open a command prompt, and set the current directory +to the source code directory of the example. You can then build the example +with the SBSv1 build tools with the following commands:

                bldmake +bldfiles

                abld build

                How to use bldmake and How to use abld describe +how to use the SBSv1 build tools.

                • +

              • For the emulator, the +example builds an executable called httpexampleclient.exe in +the epoc32\release\winscw\<udeb or urel>\ folder.

                • +
              +               +Simple Client +Session guide +HTTP Overview +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6B97D07F-DF2A-5CF1-84A9-84DBE7CB2115.dita --- a/Symbian3/SDK/Source/GUID-6B97D07F-DF2A-5CF1-84A9-84DBE7CB2115.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-6B97D07F-DF2A-5CF1-84A9-84DBE7CB2115.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,62 +1,62 @@ - - - - - -System -Model Relationship -

              The Messaging subsystem resides between Messaging applications and the -lower level subsystems that Messaging subsystem uses for storage and transmission -of messages.

              -

              See the latest version of the public System Model from the Symbian foundation.

              - - System model relationship - - -
              - -
              Message Viewers
              -

              Application for viewing a message.

              -               - -
              Message Centre
              -

              Application that displays list views of messages to the user, allowing -the user to perform operations such as copying messages, sending messages, -creating new messages and so on.

              -               - -
              Message Editors
              -

              Application for creating or editing a message.

              -               - -
              SendAs Clients
              -

              Messaging clients, such as Client MTM, client applications that implement -SendAs.

              -               - -
              EStore
              -

              Symbian platform component that provides stream based storage. It provides -the framework classes for the Message Store files.

              -               - -
              File system
              -

              A set of conventions used to access a drive, and the software that -implements those conventions. Local, ROM and installable file systems are -supported.

              -               - -
              SQL
              -

              A component that provides an SQL database service. Messaging subsystem -stores each TMsvEntry (index entry) of the index file as -a row of an SQL table in the SQL database. For more information on how Messaging -subsystem has implemented SQL, see Operating -with the SQL database.

              -               -
              + + + + + +System +Model Relationship +

              The Messaging subsystem resides between Messaging applications and the +lower level subsystems that Messaging subsystem uses for storage and transmission +of messages.

              +

              See the latest version of the public System Model from the Symbian foundation.

              + + System model relationship + + +
              + +
              Message Viewers
              +

              Application for viewing a message.

              +               + +
              Message Centre
              +

              Application that displays list views of messages to the user, allowing +the user to perform operations such as copying messages, sending messages, +creating new messages and so on.

              +               + +
              Message Editors
              +

              Application for creating or editing a message.

              +               + +
              SendAs Clients
              +

              Messaging clients, such as Client MTM, client applications that implement +SendAs.

              +               + +
              EStore
              +

              Symbian platform component that provides stream based storage. It provides +the framework classes for the Message Store files.

              +               + +
              File system
              +

              A set of conventions used to access a drive, and the software that +implements those conventions. Local, ROM and installable file systems are +supported.

              +               + +
              SQL
              +

              A component that provides an SQL database service. Messaging subsystem +stores each TMsvEntry (index entry) of the index file as +a row of an SQL table in the SQL database. For more information on how Messaging +subsystem has implemented SQL, see Operating +with the SQL database.

              +               +
               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6B9E5B8D-E2F7-5972-ABFB-49F7F466EBBD_d0e332788_href.png Binary file Symbian3/SDK/Source/GUID-6B9E5B8D-E2F7-5972-ABFB-49F7F466EBBD_d0e332788_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6B9E5B8D-E2F7-5972-ABFB-49F7F466EBBD_d0e338945_href.png Binary file Symbian3/SDK/Source/GUID-6B9E5B8D-E2F7-5972-ABFB-49F7F466EBBD_d0e338945_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6BA9989F-6D45-5D77-BC79-DE4B5DD35A6C_d0e244875_href.png Binary file Symbian3/SDK/Source/GUID-6BA9989F-6D45-5D77-BC79-DE4B5DD35A6C_d0e244875_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6BA9989F-6D45-5D77-BC79-DE4B5DD35A6C_d0e248612_href.png Binary file Symbian3/SDK/Source/GUID-6BA9989F-6D45-5D77-BC79-DE4B5DD35A6C_d0e248612_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6BD861E5-7F33-513D-8B35-CFA47E3E82F3.dita --- a/Symbian3/SDK/Source/GUID-6BD861E5-7F33-513D-8B35-CFA47E3E82F3.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-6BD861E5-7F33-513D-8B35-CFA47E3E82F3.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,47 +1,47 @@ - - - - - -ArchitectureThis section describes the architectural relationships of the telephony -API for applications. -

              The telephony API for applications provides access to the basic telephony -functionality for applications. The telephony API for applications is a subset -of the multimode telephony API that provides a rich set of telephony applications -to the handset manufacturers.

              -
              Overview

              The API is implemented as static linked -library etel3rdparty.dll. The library must be linked -in the client applications to access the telephony functions. The client applications -access the functions with the CTelephony class.

              - Telephony API for Applications - Block Diagram - - -
              -
              Description

              The CTelephony class -provides a limited set of telephony functions to client applications. The CTelephony is built on top of the core, multimode -and packet data telephony APIs. The CTelephony class -provides client applications with the functions to :

                -

              • dial a call

                • -

              • answer a call

                • -

              • get the capabilities -of the line, the call and the network

                • -

              • get information about -the basic and supplementary services of the network

                • -

              The CTelephony class translates -the client API request into the internal commands and forwards them to the -telephony server. The telephony server forwards the command requests to the -telephony server plug-in (TSY). The TSY is developed and customised by the -handset manufacturers. The telephony functions available to client applications -depend on the functions implemented in the TSY.

              -
              Platform security

              The DLL for the telephony API -for applications, etel3rdparty.dll is protected with the ALL --TCB capability. According to the Symbian Platform -security model the client applications must have the minimum capability -of ALL -TCB to use the DLL.

              + + + + + +ArchitectureThis section describes the architectural relationships of the telephony +API for applications. +

              The telephony API for applications provides access to the basic telephony +functionality for applications. The telephony API for applications is a subset +of the multimode telephony API that provides a rich set of telephony applications +to the handset manufacturers.

              +
              Overview

              The API is implemented as static linked +library etel3rdparty.dll. The library must be linked +in the client applications to access the telephony functions. The client applications +access the functions with the CTelephony class.

              + Telephony API for Applications - Block Diagram + + +
              +
              Description

              The CTelephony class +provides a limited set of telephony functions to client applications. The CTelephony is built on top of the core, multimode +and packet data telephony APIs. The CTelephony class +provides client applications with the functions to :

                +

              • dial a call

                • +

              • answer a call

                • +

              • get the capabilities +of the line, the call and the network

                • +

              • get information about +the basic and supplementary services of the network

                • +

              The CTelephony class translates +the client API request into the internal commands and forwards them to the +telephony server. The telephony server forwards the command requests to the +telephony server plug-in (TSY). The TSY is developed and customised by the +handset manufacturers. The telephony functions available to client applications +depend on the functions implemented in the TSY.

              +
              Platform security

              The DLL for the telephony API +for applications, etel3rdparty.dll is protected with the ALL +-TCB capability. According to the Symbian Platform +security model the client applications must have the minimum capability +of ALL -TCB to use the DLL.

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6C069F43-207C-5C6A-B9F6-3865BE8E70E8.dita --- a/Symbian3/SDK/Source/GUID-6C069F43-207C-5C6A-B9F6-3865BE8E70E8.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-6C069F43-207C-5C6A-B9F6-3865BE8E70E8.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,134 +1,134 @@ - - - - - -Variant -configuration file syntax -
              Purpose

              A variant configuration file (.var) -defines settings that are specific to a variant. It is used to modify certain -aspects of an existing build platform.

              -
              Syntax

              KEYWORD [OPERATION] -[VALUE]

              A summary of keywords, operations and values -is given below:

              Keyword

              Possible keywords are as follows:

              - - - -

              VARIANT

              -

              Indicates that VALUE is the name of the variant -configuration.

              -               - -

              VIRTUAL

              -

              Indicates that the variant is meant only for grouping variants and -not to be used as a build configuration.

              -               - -

              EXTENDS

              -

              Indicates that the variant extends an existing variant configuration.

              -               - -

              VARIANT_HRH

              -

              Specifies the pre-included header (.hrh) file -that defines feature macros.

              -               - -

              BUILD_INCLUDE

              -

              Specifies the location of the files to be included when building -the binary.

              -               - -

              ROM_INCLUDE

              -

              Specifies the location of the files to be included when building -the ROM image containing the variant binary.

              -               - - -

              Note: If VARIANT_HRH keyword is not present, then /epoc32/include/variant/name.hrh is -used.

              operation

              The possible operations are set, append and prepend. -These operations provide the flexibility of extending the existing include -paths within the .var file. The operations are applicable -only to the BUILD_INCLUDE and ROM_INCLUDE keywords.

              Example

              # default.var -VARIANT default -BUILD_INCLUDE set /epoc32/include -BUILD_INCLUDE append /epoc32/include/variant -ROM_INCLUDE set /epoc32/rom/include # phone.var -VARIANT phone -EXTENDS default -BUILD_INCLUDE append /epoc32/include/variant/phone -ROM_INCLUDE prepend /epoc32/rom/phone

              For the variant phone the -include lists will be:

              BUILD (/epoc32/include, /epoc32/include/variant, /epoc32/include/variant/phone) -ROM (/epoc32/rom/phone, /epoc32/rom/include)

              value

              Value -can be a variant name, a file name or a directory name. for example, myphone -or /epoc32/tools/variant/name.var.

                -

              • Use '/' as the path separator between files and directories.

                • -

              • Begin all paths with '/' implying that they are relative to EPOCROOT.

                • -

              Example

              An example of a variant:

              VARIANT name -VIRTUAL -EXTENDS parent -VARIANT_HRH /epoc32/include/variant/something.hrh -BUILD_INCLUDE set directoryA -BUILD_INCLUDE append directoryB -BUILD_INCLUDE prepend directoryC -ROM_INCLUDE set directoryD -ROM_INCLUDE append directoryE -ROM_INCLUDE prepend directoryF - -

              Notes

                -

              • All .var files -must exist in /epoc32/tools / variant.

                • -

              • A default variant configuration -file (default.var) must exist in /epoc32/tools/variant/.

                • -

              • The name of the variant -configuration file (.var) must be same as the variant name. For example, if -the variant name is myvar, then the variant configuration file must -be named as myvar.var.

                • -

              • Each variant must have -a default <variant_name>.hrh file at /epoc32/include/variant/. -If you want to use any other .hrh file under EPOCROOT, -use the VARIANT_HRH keyword to specify its name along with -the relative path.

                • -

              • A default variant cannot -be VIRTUAL.

                • -
              -
              Example

              An example of a variant:

              VARIANT name -VIRTUAL -EXTENDS parent -VARIANT_HRH /epoc32/include/variant/something.hrh -BUILD_INCLUDE set directoryA -BUILD_INCLUDE append directoryB -BUILD_INCLUDE prepend directoryC -ROM_INCLUDE set directoryD -ROM_INCLUDE append directoryE -ROM_INCLUDE prepend directoryF - -
              -
              Notes
                -

              • All .var files -must exist in /epoc32/tools / variant.

                • -

              • A default variant configuration -file (default.var) must exist in /epoc32/tools/variant/.

                • -

              • The name of the variant -configuration file (.var) must be same as the variant name. For example, if -the variant name is myvar, then the variant configuration file must -be named as myvar.var.

                • -

              • Each variant must have -a default <variant_name>.hrh file at /epoc32/include/variant/. -If you want to use any other .hrh file under EPOCROOT, -use the VARIANT_HRH keyword to specify its name along with -the relative path.

                • -

              • A default variant cannot -be VIRTUAL.

                • -
              -               -How to build -feature based variants -How to build -ROMs with variants + + + + + +Variant +configuration file syntax +
              Purpose

              A variant configuration file (.var) +defines settings that are specific to a variant. It is used to modify certain +aspects of an existing build platform.

              +
              Syntax

              KEYWORD [OPERATION] +[VALUE]

              A summary of keywords, operations and values +is given below:

              Keyword

              Possible keywords are as follows:

              + + + +

              VARIANT

              +

              Indicates that VALUE is the name of the variant +configuration.

              +               + +

              VIRTUAL

              +

              Indicates that the variant is meant only for grouping variants and +not to be used as a build configuration.

              +               + +

              EXTENDS

              +

              Indicates that the variant extends an existing variant configuration.

              +               + +

              VARIANT_HRH

              +

              Specifies the pre-included header (.hrh) file +that defines feature macros.

              +               + +

              BUILD_INCLUDE

              +

              Specifies the location of the files to be included when building +the binary.

              +               + +

              ROM_INCLUDE

              +

              Specifies the location of the files to be included when building +the ROM image containing the variant binary.

              +               + + +

              Note: If VARIANT_HRH keyword is not present, then /epoc32/include/variant/name.hrh is +used.

              operation

              The possible operations are set, append and prepend. +These operations provide the flexibility of extending the existing include +paths within the .var file. The operations are applicable +only to the BUILD_INCLUDE and ROM_INCLUDE keywords.

              Example

              # default.var +VARIANT default +BUILD_INCLUDE set /epoc32/include +BUILD_INCLUDE append /epoc32/include/variant +ROM_INCLUDE set /epoc32/rom/include # phone.var +VARIANT phone +EXTENDS default +BUILD_INCLUDE append /epoc32/include/variant/phone +ROM_INCLUDE prepend /epoc32/rom/phone

              For the variant phone the +include lists will be:

              BUILD (/epoc32/include, /epoc32/include/variant, /epoc32/include/variant/phone) +ROM (/epoc32/rom/phone, /epoc32/rom/include)

              value

              Value +can be a variant name, a file name or a directory name. for example, myphone +or /epoc32/tools/variant/name.var.

                +

              • Use '/' as the path separator between files and directories.

                • +

              • Begin all paths with '/' implying that they are relative to EPOCROOT.

                • +

              Example

              An example of a variant:

              VARIANT name +VIRTUAL +EXTENDS parent +VARIANT_HRH /epoc32/include/variant/something.hrh +BUILD_INCLUDE set directoryA +BUILD_INCLUDE append directoryB +BUILD_INCLUDE prepend directoryC +ROM_INCLUDE set directoryD +ROM_INCLUDE append directoryE +ROM_INCLUDE prepend directoryF + +

              Notes

                +

              • All .var files +must exist in /epoc32/tools / variant.

                • +

              • A default variant configuration +file (default.var) must exist in /epoc32/tools/variant/.

                • +

              • The name of the variant +configuration file (.var) must be same as the variant name. For example, if +the variant name is myvar, then the variant configuration file must +be named as myvar.var.

                • +

              • Each variant must have +a default <variant_name>.hrh file at /epoc32/include/variant/. +If you want to use any other .hrh file under EPOCROOT, +use the VARIANT_HRH keyword to specify its name along with +the relative path.

                • +

              • A default variant cannot +be VIRTUAL.

                • +
              +
              Example

              An example of a variant:

              VARIANT name +VIRTUAL +EXTENDS parent +VARIANT_HRH /epoc32/include/variant/something.hrh +BUILD_INCLUDE set directoryA +BUILD_INCLUDE append directoryB +BUILD_INCLUDE prepend directoryC +ROM_INCLUDE set directoryD +ROM_INCLUDE append directoryE +ROM_INCLUDE prepend directoryF + +
              +
              Notes
                +

              • All .var files +must exist in /epoc32/tools / variant.

                • +

              • A default variant configuration +file (default.var) must exist in /epoc32/tools/variant/.

                • +

              • The name of the variant +configuration file (.var) must be same as the variant name. For example, if +the variant name is myvar, then the variant configuration file must +be named as myvar.var.

                • +

              • Each variant must have +a default <variant_name>.hrh file at /epoc32/include/variant/. +If you want to use any other .hrh file under EPOCROOT, +use the VARIANT_HRH keyword to specify its name along with +the relative path.

                • +

              • A default variant cannot +be VIRTUAL.

                • +
              +               +How to build +feature based variants +How to build +ROMs with variants               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6C16417B-5B37-5310-B59A-750D971AA6D4-GENID-1-8-1-3-1-1-7-1.dita --- a/Symbian3/SDK/Source/GUID-6C16417B-5B37-5310-B59A-750D971AA6D4-GENID-1-8-1-3-1-1-7-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,12 +0,0 @@ - - - - - -The UI Control Framework (CONE)

              Purpose

              Let's get the important stuff out of the way first: CONE is an abbreviation of CON trol E nvironment. It is the internal Symbian component name for the UI Control Framework.

              CONE provides:

              • a framework for creating user interface controls,

              • a framework for applications to handle user interface events,

              • and an environment in which to access Window Server functionality.

              Contents

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6C16417B-5B37-5310-B59A-750D971AA6D4-GENID-1-8-1-6-1-1-4-1-6-1.dita --- a/Symbian3/SDK/Source/GUID-6C16417B-5B37-5310-B59A-750D971AA6D4-GENID-1-8-1-6-1-1-4-1-6-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,12 +0,0 @@ - - - - - -The UI Control Framework (CONE)

              Purpose

              Let's get the important stuff out of the way first: CONE is an abbreviation of CON trol E nvironment. It is the internal Symbian component name for the UI Control Framework.

              CONE provides:

              • a framework for creating user interface controls,

              • a framework for applications to handle user interface events,

              • and an environment in which to access Window Server functionality.

              Contents

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6C16417B-5B37-5310-B59A-750D971AA6D4.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-6C16417B-5B37-5310-B59A-750D971AA6D4.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,12 @@ + + + + + +The UI Control Framework (CONE)

              Purpose

              Let's get the important stuff out of the way first: CONE is an abbreviation of CON trol E nvironment. It is the internal Symbian component name for the UI Control Framework.

              CONE provides:

              • a framework for creating user interface controls,

              • a framework for applications to handle user interface events,

              • and an environment in which to access Window Server functionality.

              Contents

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6C8507F7-FE70-5654-91B5-53E356CFF67C.dita --- a/Symbian3/SDK/Source/GUID-6C8507F7-FE70-5654-91B5-53E356CFF67C.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,21 +0,0 @@ - - - - - -Controlling Pre-Image Capture This document explains how to configure the camera before using it for still image capture.
              Purpose

              The PreImageCaptureControl API allows the client to retrieve the following information:

              • Direct snapshot support

              • Embedded still capture setting support

              • Direct saving support

              • Image format and pixel aspect ratio supported for a given resolution

              • Maximum memory size setting support

              • Maximum memory size currently used in camera

              This new API creates a new set of camera configuration with improved speed. The new camera configuration is created, when there is an on-going still image capture based on previous configuration.

              Introduction

              This classes provide the necessary framework to control the image operations and settings prior to image capture. An observer class is associated with this class so that client may be notified of various relevant activities. This API provides replacement for few image capture related methods in class Ccamera.

              Required Background

              This is an extension API associated with Ccamera class. To create an object of the extension API facade class, a client application would need to provide a valid Ccamera reference as a parameter for the factory method.

              Clients use New2L or NewDuplicate2L method to create camera object. So, clients that uses NewL or NewDuplicateL will not be able to create instance of this extension. This prepares the clients to receive unrecognized enum or ids that can be included in future.

              Using PreImageCaptureControl

              Licensee should provide concrete implementation for MCameraPreImageCaptureControl class. Configuring the camera before using it for still image capture includes the following steps:

              1. Use CcameraPreImageCaptureControl::NewL() factory method to create a class pointer.

                This maps the exported call to an internal object of class CCameraPreImageCaptureControl that provides the functionality.

              2. Get this pointer using a call to Ccamera::CustomInterface() with UID value KECamMCameraPreImageCaptureControlUid.

              3. Use pointer to the MCameraPreImageCaptureControl derived class to initialize CCameraPreImageCaptureControl::iImpl during the second phase construction of the class CCamera::CCameraPreImageCaptureControl.

              4. Use MpreImageCaptureControlObserver that contains call-back to provide instance of image capture class object after successfully preparing the image parameters.

              5. Check if camera can provide capture event notification to the client using CCamera::CCameraPreImageCaptureControl::GetCaptureEventSupportInfoL method. If capture event notification is supported, ECam implementation will use KUidECamEventImageCaptureEvent event to notify the clients that the image has been exposed to the camera sensor.

              6. Clients can decide whether to play a capture sound.

              7. Client retrieves the information about direct snapshot support, embedded still capture setting support and direct saving support from the camera, and filled the desired TPrepareImageParameters to issue PrepareImageCapture call.

              8. Implementation sets up and allocates memory for image capture operation. It creates a new CCameraImageCapture object using the prepare image parameters passed by the client.

              9. The callback MPreImageCaptureControlObserver::PrepareImageComplete passes the ownership of the CCameraImageCapture object to the client.

              Note:

              • Client should provide implementation of MpreImageCaptureControlObserver class.

              • Licensees should provide a concrete implementation of McameraPreImageCaptureControl interface class.

              The following example code snippets illustrates the use of PreImageCaptureControl classes.

              CCamera* camera; -Use MCameraObserver2* observer2; -Use camera = CCamera::New2L(*observer2, 0); - -CCamera::CCameraPreImageCaptureControl* preImgCapture = CCamera::CCameraPreImageCaptureControl::NewL(*camera, MPreImageCaptureControlObserver* preImageCaptureControlObserver)); - -CCamera::CCameraPreImageCaptureControl::TPrepareImageParameters prepareImageParameters; -MCaptureImageObserver* captureImageObserver ; -preImgCapture->PrepareImageCapture(prepareImageParameters, *captureImageObserver);

              Setting Maximum Memory Size

              To set maximum memory size for a JPEG still image do the following:

              • Check if memory size is set to maximum using CCamera::CCameraPreImageCaptureControl::GetImageMaxMemorySizeSettingSupportInfoL method.

              • Get the maximum memory size in KB using CCamera::CCameraPreImageCaptureControl::GetImageMaxMemorySizeL method.

              • Use CCamera::CCameraPreImageCaptureControl::TPrepareImageParameters:: - iImageMaxMemorySize method to get the maximum memory size in kilo bytes. If client has no specific preference or if this setting is not supported, it will be KECamNoSpecificMaxMemorySize. The maximum memory size will take preference over JPEG quality if it is not sufficient to achieve the desired quality.

              Providing image file saving support

              To save the still images do the following steps:

              • Get the settings supported for embedded still captures using CCamera::CCameraPreImageCaptureControl::GetSupportedEmbeddedStillCaptureSettingsL method.

              • Get the information about the direct saving state supported by the camera using CCamera::CCameraPreImageCaptureControl::GetSupportedDirectSavingTypeL method. If supported, still images are saved in files instead of providing it to clients through MCameraImageBuffer callback.

              • Get the direct saving type currently used using CCamera::CCameraPreImageCaptureControl::GetDirectSavingTypeL method. Enum value TDirectSavingType will represent the direct saving type used by the camera.

              • Set the required type of direct saving option specified by its state using CCamera::CCameraPreImageCaptureControl::SetDirectSavingTypeL method.

              Note: Before capturing still images by direct saving option, clients need to provide the filename.

              See also

              Controlling Still-image Capture

              Controlling Captured Image

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6CDDDD1E-BDB9-5C61-8EFD-8B3369F5A12D.dita --- a/Symbian3/SDK/Source/GUID-6CDDDD1E-BDB9-5C61-8EFD-8B3369F5A12D.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-6CDDDD1E-BDB9-5C61-8EFD-8B3369F5A12D.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,212 +1,212 @@ - - - - - -P.I.P.S. -Overview -

              P.I.P.S. supplies a new framework of POSIX 'C' APIs to be used by Symbian -developers with RTOS, Linux or Microsoft Windows® knowledge. The new APIs -are packaged into industry standard libraries - libc, libm, libpthread and libdl - and will help reduce development costs.

              -
              Purpose

              The -Symbian platform already provides a library called 'ESTLIB', -which includes a subset of Standard C APIs. This was created to allow the -Java virtual machine to run on the Symbian platform rather than to allow applications -written in C to be ported to the Symbian platform. Furthermore, the functionality -provided by ESTLIB is not fully compliant with the Standard -C and POSIX standards. Symbian intends to deprecate ESTLIB once -P.I.P.S. is mature.

              The P.I.P.S. libraries are included in ROM on -certain smartphones based on Symbian OS v9.3 onwards. For smartphones based -on earlier versions of Symbian platform, a freely downloadable SIS file is -available from the Symbian Developer Network (specifically http://developer.symbian.org/wiki/index.php/Open_C_and_Open_C%2B%2B_Quick_Start) -and can be installed on any Symbian OS v9.x smartphones.

              -
              Required background

              The -differences between the Symbian platform and other operating systems

              The -Symbian platform is an operating system designed for mobile devices and comes -in the form of many libraries that contain hundreds of classes and thousands -of member functions.

              The Symbian platform has been specifically designed -to provide efficient memory and power management.

              P.I.P.S. has been -introduced to the Symbian platform to make it more attractive to third party -Symbian developers with C/C++ experience and to allow them to port their applications -to the Symbian platform with greater ease.

              The P.I.P.S. initiative -aims to reduce the development cost of porting software to run on the Symbian -platform. It achieves this by providing a POSIX-like API layer above the Symbian -platform. Given the structure of the Symbian platform, however, it is not -possible to provide a fully compliant API and some functionality, such as, fork() and exec() are -not supported. This guide details such non-compliance and recommended alternatives.

              Specific -differences between the Symbian platform and Unix-like systems are described -in the relevant sections of this guide.

              What P.I.P.S. is not

              The -P.I.P.S. environment is not a UNIX® application environment. You will -not be able to run a UNIX application on the Symbian platform 'as is'. At -a minimum, you will need to create a .mmp file and a bld.inf file -for the application and rebuild the application's source code for the Symbian -platform. For further information, see The -Symbian build process section.

              If the application does not -work at the first attempt, you may have to modify the application code to -replace missing APIs or port the required APIs to extend the P.I.P.S. environment. -To find out more about porting C libraries to the Symbian platform, see the P.I.P.S. Porting Tutorials sections.

              The -P.I.P.S. environment is not 100% POSIX compliant and it is not officially -certified as POSIX compatible. However, the implementation is as compliant -as the underlying Symbian platform allows it to be. For example, P.I.P.S. -does not provide the APIs fork() and exec(), -but it does provide popen(), mkfifo() and -so on, which can be used to implement well known alternative patterns. For -further information, see the Process -Creation section.

              -
              Architecture

              P.I.P.S. -provides an API layer above the native Symbian platform APIs that is more -closely aligned with industry standard APIs.

              The core P.I.P.S. libraries -are:

                -

              • libc: -Standard C and POSIX APIs - includes support for files, sockets, pipes, message -queues, shared memory APIs and environment variables

                • -

              • libm: -Standard C maths support APIs

                • -

              • libpthread: -Standard POSIX threading APIs

                • -

              • libdl: -Standard C dynamic loading and symbol lookup APIs (only ordinal lookup is -supported on pre-Symbian OS v9.3 releases).

                • -

              The first three libraries listed above are seeded from FreeBSD.

              The diagram below shows the high -level architecture of the P.I.P.S. environment.

              - P.I.P.S. environment architecture - -

              This diagram shows how P.I.P.S. fits in with the Symbian platform, -and also how C/C++ applications, additional C shared libraries and hybrid -applications developed by third party Symbian developers using P.I.P.S. fit -in.

              P.I.P.S. environment is based on industry-standard APIs. These -standards include

                -

              • Standard C (stdC) -and

                • -

              • POSIX.

                • -

              The P.I.P.S. environment is a mandatory part of Symbian OS v9.5 onward.

              For -devices already in the market, a SIS file is freely downloadable from the -Forum Nokia site (specifically http://www.forum.nokia.com/Technology_Topics/Development_Platforms/Open_C_and_C++/) -and can be installed on any v9.x phone.

              Components

              P.I.P.S. -is based on an industry-standard API and system behaviour.  The relevant -industry standards are Open Group standards and include Standard C (stdC), -POSIX, GNU C library (glibc) and Standard C++ (stdC++).

              The -diagram below shows how the Standard C libraries and exported applications -fit into the native platform.

              - The subsystem components - -

              The System Call Adaptation Layer (SCAL) is not directly accessed -by the developer wishing to export to the Symbian platform, but through calls -in the P.I.P.S. libraries.

              Traditionally, in Unix-like systems, system -calls are implemented in the kernel, separate from the C libraries. On the -Symbian platform, the 'System Call Adaptation Layer' runs in the context of -the user side but is considered 'kernel-like' code. APIs that belong to this -layer are tagged as @internalComponent and may only be extended -by Symbian.

              Note that P.I.P.S. is not a Linux application environment -- you cannot simply run an application that you've compiled for your Linux -desktop. At a minimum, you will have to rebuild your application from source.

              For -more information, see the Build -Process section.

              Glue -code (CRT0)

              Executables built for the Symbian platform enter via E32Main(), -whereas Standard C applications expect to be started from main(). -It is therefore necessary to have 'glue code' (formerly known as CRT0) between -these two functions. The glue code is also responsible for allocating any -system resources, obtaining system and environment data, and initialising -the SCAL infrastructure prior to calling the main() function -of the application. There are two versions of the glue code library - libcrt0.lib (for -use by applications that enter via char main()) and libwcrt0.lib (for -use by applications that enter via wide char main()).

              To -include the glue code library you should explicity link to libcrt0.lib and libwcrt0.lib statically, -however, if you are using the STDEXE or STDDLL target -types, glue code will be added automatically.

              P.I.P.S. -Core libraries

              Currently, the C libraries include the libc, libm, -and libpthread (seeded from FreeBSD) and libdl libraries. The -APIs provided by these libraries are defined to be compliant, via compatibility -features, with the POSIX standard. They are not officially certified as POSIX -compatible but they conform to it mostly.

              The P.I.P.S. libraries include -the following APIs:

                -

              • stdio, -including print(), scanf(), and so on

                • -

              • stdlib, -including environment variable support, and so on

                • -

              • string manipulation -and character APIs

                • -

              • locale and system services

                • -

              • searching, sort and -pattern matching

                • -

              • IPC mechanisms, including -shared memory, pipes, FIFOs and message queues

                • -

              • process creation, including popen(), posix_spawn() and system()

                • -

              • networking and socket -APIs

                • -

              • mathematical and arithmetic -APIs

                • -

              • dynamic loading and -symbol lookup

                • -

              • thread creation and -synchronisation mechanisms.

                • -

              Due to fundamental differences between Linux and the Symbian platform -kernel architecture, there is no support for fork() and exec(). -For more information, see the Process -Creation section.

              The original seed directory structure (FreeBSD) is preserved -as fully as possible to allow for future catch-ups to be performed more easily. -The table below shows the original seed directory structure in FreeBSD.

              - - - -

              Module

              -

              Description

              -               - -

              core\libc

              -

              Contains Standard C and POSIX APIs as defined by the Standard C -and POSIX standards

              -               - -

              core\libm

              -

              Contains the Standard C Math API as defined by -Standard C

              -               - -

              core\libpthread

              -

              Contains POSIX threading APIs as defined the POSIX standards

              -               - -

              core\libdl

              -

              Contains APIs for dynamic loading and symbol lookup by name.

              -               - - -

              Although P.I.P.S. provides a wide range of APIs, some of the functionality -required in order to complete a porting task might be missing - this could -be some APIs from an existing library or an entire library.

              Several -options are available to the user:

                -

              • Port the missing APIs -using the P.I.P.S. libraries

                • -

              • Implement the missing -APIs on top of the Symbian platform native C++ APIs

                • -

              • Use a workaround - for -example, use popen() instead of fork().

                • -

              Note: The following are the limitations associated with porting -a UNIX® application:

                -

              • Limited stack-space: The -default stack size per thread on Unix-like operating systems ranges from 64 -kB to 1 MB. The Symbian platform, however, defines a default stack size of -8 kB per thread. P.I.P.S. Pthreads use this by default. You can use the pthread_attr_setstacksize() function -to modify this before calling pthread_create().

                • -

              • Limited threads -per process: Assuming that all threads use the default stack size (8 kB), -Symbian specifies a limit of 128 threads per process. The limit changes depending -on the stack size you use for individual threads. For example, if you create -your threads with a stack size of 16 kB, the OS only supports 64 threads per -process.

                • -
              -               -P.I.P.S. -Concepts -P.I.P.S. -Porting Tutorials -P.I.P.S. -Examples + + + + + +P.I.P.S. +Overview +

              P.I.P.S. supplies a new framework of POSIX 'C' APIs to be used by Symbian +developers with RTOS, Linux or Microsoft Windows® knowledge. The new APIs +are packaged into industry standard libraries - libc, libm, libpthread and libdl - and will help reduce development costs.

              +
              Purpose

              The +Symbian platform already provides a library called 'ESTLIB', +which includes a subset of Standard C APIs. This was created to allow the +Java virtual machine to run on the Symbian platform rather than to allow applications +written in C to be ported to the Symbian platform. Furthermore, the functionality +provided by ESTLIB is not fully compliant with the Standard +C and POSIX standards. Symbian intends to deprecate ESTLIB once +P.I.P.S. is mature.

              The P.I.P.S. libraries are included in ROM on +certain smartphones based on Symbian OS v9.3 onwards. For smartphones based +on earlier versions of Symbian platform, a freely downloadable SIS file is +available from the Symbian Developer Network (specifically http://developer.symbian.org/wiki/index.php/Open_C_and_Open_C%2B%2B_Quick_Start) +and can be installed on any Symbian OS v9.x smartphones.

              +
              Required background

              The +differences between the Symbian platform and other operating systems

              The +Symbian platform is an operating system designed for mobile devices and comes +in the form of many libraries that contain hundreds of classes and thousands +of member functions.

              The Symbian platform has been specifically designed +to provide efficient memory and power management.

              P.I.P.S. has been +introduced to the Symbian platform to make it more attractive to third party +Symbian developers with C/C++ experience and to allow them to port their applications +to the Symbian platform with greater ease.

              The P.I.P.S. initiative +aims to reduce the development cost of porting software to run on the Symbian +platform. It achieves this by providing a POSIX-like API layer above the Symbian +platform. Given the structure of the Symbian platform, however, it is not +possible to provide a fully compliant API and some functionality, such as, fork() and exec() are +not supported. This guide details such non-compliance and recommended alternatives.

              Specific +differences between the Symbian platform and Unix-like systems are described +in the relevant sections of this guide.

              What P.I.P.S. is not

              The +P.I.P.S. environment is not a UNIX® application environment. You will +not be able to run a UNIX application on the Symbian platform 'as is'. At +a minimum, you will need to create a .mmp file and a bld.inf file +for the application and rebuild the application's source code for the Symbian +platform. For further information, see The +Symbian build process section.

              If the application does not +work at the first attempt, you may have to modify the application code to +replace missing APIs or port the required APIs to extend the P.I.P.S. environment. +To find out more about porting C libraries to the Symbian platform, see the P.I.P.S. Porting Tutorials sections.

              The +P.I.P.S. environment is not 100% POSIX compliant and it is not officially +certified as POSIX compatible. However, the implementation is as compliant +as the underlying Symbian platform allows it to be. For example, P.I.P.S. +does not provide the APIs fork() and exec(), +but it does provide popen(), mkfifo() and +so on, which can be used to implement well known alternative patterns. For +further information, see the Process +Creation section.

              +
              Architecture

              P.I.P.S. +provides an API layer above the native Symbian platform APIs that is more +closely aligned with industry standard APIs.

              The core P.I.P.S. libraries +are:

                +

              • libc: +Standard C and POSIX APIs - includes support for files, sockets, pipes, message +queues, shared memory APIs and environment variables

                • +

              • libm: +Standard C maths support APIs

                • +

              • libpthread: +Standard POSIX threading APIs

                • +

              • libdl: +Standard C dynamic loading and symbol lookup APIs (only ordinal lookup is +supported on pre-Symbian OS v9.3 releases).

                • +

              The first three libraries listed above are seeded from FreeBSD.

              The diagram below shows the high +level architecture of the P.I.P.S. environment.

              + P.I.P.S. environment architecture + +

              This diagram shows how P.I.P.S. fits in with the Symbian platform, +and also how C/C++ applications, additional C shared libraries and hybrid +applications developed by third party Symbian developers using P.I.P.S. fit +in.

              P.I.P.S. environment is based on industry-standard APIs. These +standards include

                +

              • Standard C (stdC) +and

                • +

              • POSIX.

                • +

              The P.I.P.S. environment is a mandatory part of Symbian OS v9.5 onward.

              For +devices already in the market, a SIS file is freely downloadable from the +Forum Nokia site (specifically http://www.forum.nokia.com/Technology_Topics/Development_Platforms/Open_C_and_C++/) +and can be installed on any v9.x phone.

              Components

              P.I.P.S. +is based on an industry-standard API and system behaviour.  The relevant +industry standards are Open Group standards and include Standard C (stdC), +POSIX, GNU C library (glibc) and Standard C++ (stdC++).

              The +diagram below shows how the Standard C libraries and exported applications +fit into the native platform.

              + The subsystem components + +

              The System Call Adaptation Layer (SCAL) is not directly accessed +by the developer wishing to export to the Symbian platform, but through calls +in the P.I.P.S. libraries.

              Traditionally, in Unix-like systems, system +calls are implemented in the kernel, separate from the C libraries. On the +Symbian platform, the 'System Call Adaptation Layer' runs in the context of +the user side but is considered 'kernel-like' code. APIs that belong to this +layer are tagged as @internalComponent and may only be extended +by Symbian.

              Note that P.I.P.S. is not a Linux application environment +- you cannot simply run an application that you've compiled for your Linux +desktop. At a minimum, you will have to rebuild your application from source.

              For +more information, see the Build +Process section.

              Glue +code (CRT0)

              Executables built for the Symbian platform enter via E32Main(), +whereas Standard C applications expect to be started from main(). +It is therefore necessary to have 'glue code' (formerly known as CRT0) between +these two functions. The glue code is also responsible for allocating any +system resources, obtaining system and environment data, and initialising +the SCAL infrastructure prior to calling the main() function +of the application. There are two versions of the glue code library - libcrt0.lib (for +use by applications that enter via char main()) and libwcrt0.lib (for +use by applications that enter via wide char main()).

              To +include the glue code library you should explicity link to libcrt0.lib and libwcrt0.lib statically, +however, if you are using the STDEXE or STDDLL target +types, glue code will be added automatically.

              P.I.P.S. +Core libraries

              Currently, the C libraries include the libc, libm, +and libpthread (seeded from FreeBSD) and libdl libraries. The +APIs provided by these libraries are defined to be compliant, via compatibility +features, with the POSIX standard. They are not officially certified as POSIX +compatible but they conform to it mostly.

              The P.I.P.S. libraries include +the following APIs:

                +

              • stdio, +including print(), scanf(), and so on

                • +

              • stdlib, +including environment variable support, and so on

                • +

              • string manipulation +and character APIs

                • +

              • locale and system services

                • +

              • searching, sort and +pattern matching

                • +

              • IPC mechanisms, including +shared memory, pipes, FIFOs and message queues

                • +

              • process creation, including popen(), posix_spawn() and system()

                • +

              • networking and socket +APIs

                • +

              • mathematical and arithmetic +APIs

                • +

              • dynamic loading and +symbol lookup

                • +

              • thread creation and +synchronisation mechanisms.

                • +

              Due to fundamental differences between Linux and the Symbian platform +kernel architecture, there is no support for fork() and exec(). +For more information, see the Process +Creation section.

              The original seed directory structure (FreeBSD) is preserved +as fully as possible to allow for future catch-ups to be performed more easily. +The table below shows the original seed directory structure in FreeBSD.

              + + + +

              Module

              +

              Description

              +               + +

              core\libc

              +

              Contains Standard C and POSIX APIs as defined by the Standard C +and POSIX standards

              +               + +

              core\libm

              +

              Contains the Standard C Math API as defined by +Standard C

              +               + +

              core\libpthread

              +

              Contains POSIX threading APIs as defined the POSIX standards

              +               + +

              core\libdl

              +

              Contains APIs for dynamic loading and symbol lookup by name.

              +               + + +

              Although P.I.P.S. provides a wide range of APIs, some of the functionality +required in order to complete a porting task might be missing - this could +be some APIs from an existing library or an entire library.

              Several +options are available to the user:

                +

              • Port the missing APIs +using the P.I.P.S. libraries

                • +

              • Implement the missing +APIs on top of the Symbian platform native C++ APIs

                • +

              • Use a workaround - for +example, use popen() instead of fork().

                • +

              Note: The following are the limitations associated with porting +a UNIX® application:

                +

              • Limited stack-space: The +default stack size per thread on Unix-like operating systems ranges from 64 +kB to 1 MB. The Symbian platform, however, defines a default stack size of +8 kB per thread. P.I.P.S. Pthreads use this by default. You can use the pthread_attr_setstacksize() function +to modify this before calling pthread_create().

                • +

              • Limited threads +per process: Assuming that all threads use the default stack size (8 kB), +Symbian specifies a limit of 128 threads per process. The limit changes depending +on the stack size you use for individual threads. For example, if you create +your threads with a stack size of 16 kB, the OS only supports 64 threads per +process.

                • +
              +               +P.I.P.S. +Concepts +P.I.P.S. +Porting Tutorials +P.I.P.S. +Examples               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6CE1C2E0-8F57-57D3-9041-929FE30ECEB9_d0e78396_href.png Binary file Symbian3/SDK/Source/GUID-6CE1C2E0-8F57-57D3-9041-929FE30ECEB9_d0e78396_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6CE1C2E0-8F57-57D3-9041-929FE30ECEB9_d0e85108_href.png Binary file Symbian3/SDK/Source/GUID-6CE1C2E0-8F57-57D3-9041-929FE30ECEB9_d0e85108_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6CEAFE12-EB30-5231-94F4-2D097E79BFE0-GENID-1-8-1-3-1-1-9-1-4-1-4-1.dita --- a/Symbian3/SDK/Source/GUID-6CEAFE12-EB30-5231-94F4-2D097E79BFE0-GENID-1-8-1-3-1-1-9-1-4-1-4-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,141 +0,0 @@ - - - - - -Implementing -the FEP APIThis topic describes various implementations of FEP. -
              Post-platform -security – the ECom plugin interface

              In the secure platform, FEPs -must be implemented as ECom plug-ins. ECom provides a secure environment for -loading FEPs that cannot be achieved using standard, non-ECom polymorphic -DLLs. The main tasks that are specific to implementing a FEP as an ECom plug-in -are described in this section. Note that the differences between pre- and -post-platform security FEPs are imposed by the change from old-style, standard -polymorphic DLLs to ECom plugins. The C++ APIs involved in FEP creation, which -are defined in fepbase.h, are unchanged.

              -
              Define a class -that implements the CCoeFepPlugIn interface

              This class must implement -the NewFepL() and SynchronouslyExecuteSettingsDialogL() functions -that were, pre-platform security, the first and second exports from the DLL. -Note that these functions have been redefined and no longer take the const TDesC& -aFullFileNameOfDll argument: the ECom plugin implementation is identified -by a UID rather than a filename. This means that the implementation of SynchronouslyExecuteSettingsDialogL() is -now responsible for locating the resource file needed to execute the settings -dialog itself.

              class CCoeFepPlugIn : public CBase - { -public: - inline static CCoeFepPlugIn* NewL(TUid aFepUid); - virtual ~CCoeFepPlugIn(); -public: - virtual CCoeFep* NewFepL(CCoeEnv& aConeEnvironment, const CCoeFepParameters& aFepParameters) = 0; - virtual void SynchronouslyExecuteSettingsDialogL(CCoeEnv& aConeEnvironment) = 0; - }; -
              -
              Provide the -factory code required to instantiate the derived class

              FEPs must -provide the standard factory code required by every ECom plugin. For more -information, see “Using ECom” in the Symbian Developer Library. For example, -(the following code is taken from TFEP1PlugIn.cpp):

              const TInt KTstFepPlugInImplementationValue = 0x102024D0; -const TImplementationProxy ImplementationTable[] = - { - IMPLEMENTATION_PROXY_ENTRY(KTstFepPlugInImplementationValue, CTstFepPlugIn::NewL ) - }; -EXPORT_C const TImplementationProxy* ImplementationGroupProxy(TInt& aTableCount) - { - aTableCount = sizeof(ImplementationTable) / sizeof(TImplementationProxy); - return ImplementationTable; - } -CTstFepPlugIn* CTstFepPlugIn::NewL() - { // static - return new(ELeave) CTstFepPlugIn; - } -
              -
              Create an ECom -resource file

              Each FEP must have an ECom resource file. Its interface -UID must be 0x1020233f, or CONE will not be able to find the FEP. For example,

              #include <RegistryInfo.rh> - -RESOURCE REGISTRY_INFO theInfo - { - dll_uid = 0x102024D0; // UID3 of the DLL - interfaces = - { - INTERFACE_INFO - { - interface_uid = 0x1020233F; // Same for every FEP - implementations = - { - IMPLEMENTATION_INFO - { - implementation_uid = 0x102024D0; - version_no = 1; - display_name = "FEPNAME"; - default_data = ""; - opaque_data = ""; - } - }; - } - }; - }
              -
              The CCoeFep -class

              The parts of CCoeFep relevant to classes -deriving from it are shown below:

              class CCoeFep : public CBase, protected MFepAttributeStorer, public MCoeForegroundObserver, public MCoeFocusObserver -{ -public: - enum TEventResponse - { - EEventWasNotConsumed, - EEventWasConsumed - }; - class MDeferredFunctionCall - { - public: - virtual void ExecuteFunctionL()=0; - }; - class MModifiedCharacter - { - public: - virtual TUint CharacterCode() const=0; - virtual TUint ModifierMask() const=0; - virtual TUint ModifierValues() const=0; - }; -public: - IMPORT_C virtual ~CCoeFep(); - virtual void CancelTransaction()=0; -protected: - IMPORT_C CCoeFep(CCoeEnv& aConeEnvironment); - IMPORT_C void BaseConstructL(const CCoeFepParameters& aFepParameters); - IMPORT_C void ReadAllAttributesL(); - IMPORT_C void MakeDeferredFunctionCall(MDeferredFunctionCall& aDeferredFunctionCall); - IMPORT_C void SimulateKeyEventsL(const TArray<TUint>& aArrayOfCharacters); - IMPORT_C void SimulateKeyEventsL(const TArray<MModifiedCharacter>& aArrayOfModifiedCharacters); - IMPORT_C void WriteAttributeDataAndBroadcastL(TUid aAttributeUid); - IMPORT_C void WriteAttributeDataAndBroadcastL(const TArray<TUid>& aAttributeUids); - IMPORT_C TBool IsOn() const; -private: - virtual void IsOnHasChangedState()=0; - virtual void OfferKeyEventL(TEventResponse& aEventResponse, const TKeyEvent& aKeyEvent, TEventCode aEventCode)=0; - virtual void OfferPointerEventL(TEventResponse& aEventResponse, const TPointerEvent& aPointerEvent, const CCoeControl* aWindowOwningControl)=0; - virtual void OfferPointerBufferReadyEventL(TEventResponse& aEventResponse, const CCoeControl* aWindowOwningControl)=0; - }; -

              Note that CCoeFep inherits, but does not -override, some pure virtual functions from its base classes MFepAttributeStorer, MCoeForegroundObserver and MCoeFocusObserver. These therefore need to be overridden in addition -to CCoeFep ’s own pure virtual member functions. The details -of the member functions of CCoeFep and its base classes -are explained in various sections of this document.

              -
              The CCoeControl -class

              The CCoeControl class (defined in epoc32\include\COECNTRL.H) -provides many useful features for implementing a FEP, such as functions for -handling window server events. In fact, for FEPs wishing to intercept key -events, writing a class that derives from CCoeControl is -a necessity because of the need to use the control stack (see Intercepting key events, below). Thus although deriving from CCoeControl is -not explicitly demanded by the FEP architecture, it is assumed throughout -this document that the object of the CCoeFep derived -class owns an object of a CCoeControl derived class.

              -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6CEAFE12-EB30-5231-94F4-2D097E79BFE0-GENID-1-8-1-6-1-1-4-1-8-1-4-1-4-1.dita --- a/Symbian3/SDK/Source/GUID-6CEAFE12-EB30-5231-94F4-2D097E79BFE0-GENID-1-8-1-6-1-1-4-1-8-1-4-1-4-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,141 +0,0 @@ - - - - - -Implementing -the FEP APIThis topic describes various implementations of FEP. -
              Post-platform -security – the ECom plugin interface

              In the secure platform, FEPs -must be implemented as ECom plug-ins. ECom provides a secure environment for -loading FEPs that cannot be achieved using standard, non-ECom polymorphic -DLLs. The main tasks that are specific to implementing a FEP as an ECom plug-in -are described in this section. Note that the differences between pre- and -post-platform security FEPs are imposed by the change from old-style, standard -polymorphic DLLs to ECom plugins. The C++ APIs involved in FEP creation, which -are defined in fepbase.h, are unchanged.

              -
              Define a class -that implements the CCoeFepPlugIn interface

              This class must implement -the NewFepL() and SynchronouslyExecuteSettingsDialogL() functions -that were, pre-platform security, the first and second exports from the DLL. -Note that these functions have been redefined and no longer take the const TDesC& -aFullFileNameOfDll argument: the ECom plugin implementation is identified -by a UID rather than a filename. This means that the implementation of SynchronouslyExecuteSettingsDialogL() is -now responsible for locating the resource file needed to execute the settings -dialog itself.

              class CCoeFepPlugIn : public CBase - { -public: - inline static CCoeFepPlugIn* NewL(TUid aFepUid); - virtual ~CCoeFepPlugIn(); -public: - virtual CCoeFep* NewFepL(CCoeEnv& aConeEnvironment, const CCoeFepParameters& aFepParameters) = 0; - virtual void SynchronouslyExecuteSettingsDialogL(CCoeEnv& aConeEnvironment) = 0; - }; -
              -
              Provide the -factory code required to instantiate the derived class

              FEPs must -provide the standard factory code required by every ECom plugin. For more -information, see “Using ECom” in the Symbian Developer Library. For example, -(the following code is taken from TFEP1PlugIn.cpp):

              const TInt KTstFepPlugInImplementationValue = 0x102024D0; -const TImplementationProxy ImplementationTable[] = - { - IMPLEMENTATION_PROXY_ENTRY(KTstFepPlugInImplementationValue, CTstFepPlugIn::NewL ) - }; -EXPORT_C const TImplementationProxy* ImplementationGroupProxy(TInt& aTableCount) - { - aTableCount = sizeof(ImplementationTable) / sizeof(TImplementationProxy); - return ImplementationTable; - } -CTstFepPlugIn* CTstFepPlugIn::NewL() - { // static - return new(ELeave) CTstFepPlugIn; - } -
              -
              Create an ECom -resource file

              Each FEP must have an ECom resource file. Its interface -UID must be 0x1020233f, or CONE will not be able to find the FEP. For example,

              #include <RegistryInfo.rh> - -RESOURCE REGISTRY_INFO theInfo - { - dll_uid = 0x102024D0; // UID3 of the DLL - interfaces = - { - INTERFACE_INFO - { - interface_uid = 0x1020233F; // Same for every FEP - implementations = - { - IMPLEMENTATION_INFO - { - implementation_uid = 0x102024D0; - version_no = 1; - display_name = "FEPNAME"; - default_data = ""; - opaque_data = ""; - } - }; - } - }; - }
              -
              The CCoeFep -class

              The parts of CCoeFep relevant to classes -deriving from it are shown below:

              class CCoeFep : public CBase, protected MFepAttributeStorer, public MCoeForegroundObserver, public MCoeFocusObserver -{ -public: - enum TEventResponse - { - EEventWasNotConsumed, - EEventWasConsumed - }; - class MDeferredFunctionCall - { - public: - virtual void ExecuteFunctionL()=0; - }; - class MModifiedCharacter - { - public: - virtual TUint CharacterCode() const=0; - virtual TUint ModifierMask() const=0; - virtual TUint ModifierValues() const=0; - }; -public: - IMPORT_C virtual ~CCoeFep(); - virtual void CancelTransaction()=0; -protected: - IMPORT_C CCoeFep(CCoeEnv& aConeEnvironment); - IMPORT_C void BaseConstructL(const CCoeFepParameters& aFepParameters); - IMPORT_C void ReadAllAttributesL(); - IMPORT_C void MakeDeferredFunctionCall(MDeferredFunctionCall& aDeferredFunctionCall); - IMPORT_C void SimulateKeyEventsL(const TArray<TUint>& aArrayOfCharacters); - IMPORT_C void SimulateKeyEventsL(const TArray<MModifiedCharacter>& aArrayOfModifiedCharacters); - IMPORT_C void WriteAttributeDataAndBroadcastL(TUid aAttributeUid); - IMPORT_C void WriteAttributeDataAndBroadcastL(const TArray<TUid>& aAttributeUids); - IMPORT_C TBool IsOn() const; -private: - virtual void IsOnHasChangedState()=0; - virtual void OfferKeyEventL(TEventResponse& aEventResponse, const TKeyEvent& aKeyEvent, TEventCode aEventCode)=0; - virtual void OfferPointerEventL(TEventResponse& aEventResponse, const TPointerEvent& aPointerEvent, const CCoeControl* aWindowOwningControl)=0; - virtual void OfferPointerBufferReadyEventL(TEventResponse& aEventResponse, const CCoeControl* aWindowOwningControl)=0; - }; -

              Note that CCoeFep inherits, but does not -override, some pure virtual functions from its base classes MFepAttributeStorer, MCoeForegroundObserver and MCoeFocusObserver. These therefore need to be overridden in addition -to CCoeFep ’s own pure virtual member functions. The details -of the member functions of CCoeFep and its base classes -are explained in various sections of this document.

              -
              The CCoeControl -class

              The CCoeControl class (defined in epoc32\include\COECNTRL.H) -provides many useful features for implementing a FEP, such as functions for -handling window server events. In fact, for FEPs wishing to intercept key -events, writing a class that derives from CCoeControl is -a necessity because of the need to use the control stack (see Intercepting key events, below). Thus although deriving from CCoeControl is -not explicitly demanded by the FEP architecture, it is assumed throughout -this document that the object of the CCoeFep derived -class owns an object of a CCoeControl derived class.

              -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6CEAFE12-EB30-5231-94F4-2D097E79BFE0.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-6CEAFE12-EB30-5231-94F4-2D097E79BFE0.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,141 @@ + + + + + +Implementing +the FEP APIThis topic describes various implementations of FEP. +
              Post-platform +security – the ECom plugin interface

              In the secure platform, FEPs +must be implemented as ECom plug-ins. ECom provides a secure environment for +loading FEPs that cannot be achieved using standard, non-ECom polymorphic +DLLs. The main tasks that are specific to implementing a FEP as an ECom plug-in +are described in this section. Note that the differences between pre- and +post-platform security FEPs are imposed by the change from old-style, standard +polymorphic DLLs to ECom plugins. The C++ APIs involved in FEP creation, which +are defined in fepbase.h, are unchanged.

              +
              Define a class +that implements the CCoeFepPlugIn interface

              This class must implement +the NewFepL() and SynchronouslyExecuteSettingsDialogL() functions +that were, pre-platform security, the first and second exports from the DLL. +Note that these functions have been redefined and no longer take the const TDesC& +aFullFileNameOfDll argument: the ECom plugin implementation is identified +by a UID rather than a filename. This means that the implementation of SynchronouslyExecuteSettingsDialogL() is +now responsible for locating the resource file needed to execute the settings +dialog itself.

              class CCoeFepPlugIn : public CBase + { +public: + inline static CCoeFepPlugIn* NewL(TUid aFepUid); + virtual ~CCoeFepPlugIn(); +public: + virtual CCoeFep* NewFepL(CCoeEnv& aConeEnvironment, const CCoeFepParameters& aFepParameters) = 0; + virtual void SynchronouslyExecuteSettingsDialogL(CCoeEnv& aConeEnvironment) = 0; + }; +
              +
              Provide the +factory code required to instantiate the derived class

              FEPs must +provide the standard factory code required by every ECom plugin. For more +information, see “Using ECom” in the Symbian Developer Library. For example, +(the following code is taken from TFEP1PlugIn.cpp):

              const TInt KTstFepPlugInImplementationValue = 0x102024D0; +const TImplementationProxy ImplementationTable[] = + { + IMPLEMENTATION_PROXY_ENTRY(KTstFepPlugInImplementationValue, CTstFepPlugIn::NewL ) + }; +EXPORT_C const TImplementationProxy* ImplementationGroupProxy(TInt& aTableCount) + { + aTableCount = sizeof(ImplementationTable) / sizeof(TImplementationProxy); + return ImplementationTable; + } +CTstFepPlugIn* CTstFepPlugIn::NewL() + { // static + return new(ELeave) CTstFepPlugIn; + } +
              +
              Create an ECom +resource file

              Each FEP must have an ECom resource file. Its interface +UID must be 0x1020233f, or CONE will not be able to find the FEP. For example,

              #include <RegistryInfo.rh> + +RESOURCE REGISTRY_INFO theInfo + { + dll_uid = 0x102024D0; // UID3 of the DLL + interfaces = + { + INTERFACE_INFO + { + interface_uid = 0x1020233F; // Same for every FEP + implementations = + { + IMPLEMENTATION_INFO + { + implementation_uid = 0x102024D0; + version_no = 1; + display_name = "FEPNAME"; + default_data = ""; + opaque_data = ""; + } + }; + } + }; + }
              +
              The CCoeFep +class

              The parts of CCoeFep relevant to classes +deriving from it are shown below:

              class CCoeFep : public CBase, protected MFepAttributeStorer, public MCoeForegroundObserver, public MCoeFocusObserver +{ +public: + enum TEventResponse + { + EEventWasNotConsumed, + EEventWasConsumed + }; + class MDeferredFunctionCall + { + public: + virtual void ExecuteFunctionL()=0; + }; + class MModifiedCharacter + { + public: + virtual TUint CharacterCode() const=0; + virtual TUint ModifierMask() const=0; + virtual TUint ModifierValues() const=0; + }; +public: + IMPORT_C virtual ~CCoeFep(); + virtual void CancelTransaction()=0; +protected: + IMPORT_C CCoeFep(CCoeEnv& aConeEnvironment); + IMPORT_C void BaseConstructL(const CCoeFepParameters& aFepParameters); + IMPORT_C void ReadAllAttributesL(); + IMPORT_C void MakeDeferredFunctionCall(MDeferredFunctionCall& aDeferredFunctionCall); + IMPORT_C void SimulateKeyEventsL(const TArray<TUint>& aArrayOfCharacters); + IMPORT_C void SimulateKeyEventsL(const TArray<MModifiedCharacter>& aArrayOfModifiedCharacters); + IMPORT_C void WriteAttributeDataAndBroadcastL(TUid aAttributeUid); + IMPORT_C void WriteAttributeDataAndBroadcastL(const TArray<TUid>& aAttributeUids); + IMPORT_C TBool IsOn() const; +private: + virtual void IsOnHasChangedState()=0; + virtual void OfferKeyEventL(TEventResponse& aEventResponse, const TKeyEvent& aKeyEvent, TEventCode aEventCode)=0; + virtual void OfferPointerEventL(TEventResponse& aEventResponse, const TPointerEvent& aPointerEvent, const CCoeControl* aWindowOwningControl)=0; + virtual void OfferPointerBufferReadyEventL(TEventResponse& aEventResponse, const CCoeControl* aWindowOwningControl)=0; + }; +

              Note that CCoeFep inherits, but does not +override, some pure virtual functions from its base classes MFepAttributeStorer, MCoeForegroundObserver and MCoeFocusObserver. These therefore need to be overridden in addition +to CCoeFep ’s own pure virtual member functions. The details +of the member functions of CCoeFep and its base classes +are explained in various sections of this document.

              +
              The CCoeControl +class

              The CCoeControl class (defined in epoc32\include\COECNTRL.H) +provides many useful features for implementing a FEP, such as functions for +handling window server events. In fact, for FEPs wishing to intercept key +events, writing a class that derives from CCoeControl is +a necessity because of the need to use the control stack (see Intercepting key events, below). Thus although deriving from CCoeControl is +not explicitly demanded by the FEP architecture, it is assumed throughout +this document that the object of the CCoeFep derived +class owns an object of a CCoeControl derived class.

              +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6CEE397C-78E3-40AE-8D39-3DC0980A932A_d0e3291_href.png Binary file Symbian3/SDK/Source/GUID-6CEE397C-78E3-40AE-8D39-3DC0980A932A_d0e3291_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6CEE397C-78E3-40AE-8D39-3DC0980A932A_d0e4566_href.png Binary file Symbian3/SDK/Source/GUID-6CEE397C-78E3-40AE-8D39-3DC0980A932A_d0e4566_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6DA5C169-5143-5DDD-B4A0-004D4571D9B8_d0e356629_href.png Binary file Symbian3/SDK/Source/GUID-6DA5C169-5143-5DDD-B4A0-004D4571D9B8_d0e356629_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6DA5C169-5143-5DDD-B4A0-004D4571D9B8_d0e362709_href.png Binary file Symbian3/SDK/Source/GUID-6DA5C169-5143-5DDD-B4A0-004D4571D9B8_d0e362709_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6DAF85AD-E412-5823-81C2-FC1755A90A84.dita --- a/Symbian3/SDK/Source/GUID-6DAF85AD-E412-5823-81C2-FC1755A90A84.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-6DAF85AD-E412-5823-81C2-FC1755A90A84.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,90 +1,90 @@ - - - - - -What -are elementsThis topic describes elements. All items that can be stored in -the Comms Database are elements. The topic also discusses the structure of -the unique numeric Id and the attributes that control access to elements. -

              An element is represented by the CMDBElement class. -The class is a base class for all items that can be stored in the Comms Database. -The class contains the data that is common to all items that can be stored -in the Comms database.

              -

              Elements contain three pieces of information:

              -
                -

              • a unique numeric Id -that defines the location of the element in the database. The Id defines the -meaning of the element in the database schema as a specific Table, Column, -Record or Field. A numeric Id also allows for fast access and retrieval of -an element.

                • -

              • a set of attributes -that controls access to the data.

                • -

              • a value that can be -a single numeric type, a Boolean type, a descriptor, or a composite of one -or more nested elements.

                • -
              -

              CMDBElement derives from MMetaDatabase. MMetaDatabase provides -the behaviour that allows an element to operate with the Comms Database. [See -accessing the database or words to that effect.]

              - - - -
              The Element -Id

              The iElementId data member of CMDBElement is -a 32 bit number that contains:

                -

              • the unique numeric Id -that shows the location of the element in the database. This numeric Id is -known as the Element Id.

                • -

              • the set of attributes -that controls access to the data. The bits define the access levels.

                • -

              Both pieces of information are encoded in the 32 bit number. The -32 bit number is a TMDBElementId type.

              The CMDBElement class provides member functions to -access and to change the information in the Element Id.

              -

              The unique -numeric Id

              The unique numeric Id has two parts: the Type Id and -the Record Id.

              The Type Id defines the type of element; the Record -Id identifies an instance of this type of element.

              The class CMDBElement provides the member functions CommsDat::CMDBElement::TypeId() and CommsDat::CMDBElement::RecordId() to -extract this information.

              Internally, the Type Id includes a 8 bit -number and a 7 bit number. The 8 bit number is the Table Id and the 7 bit -number is the Column Id. The Type Id and the Record Id are in defined locations -in the 32 bit number iElementId.

              - -

              The header file comsdat.h contains the constants -that define the location of these Ids in the 32 bit number:

              - - - -

              Table Id

              -

              KCDMaskShowRecordType

              -               - -

              Column Id

              -

              KCDMaskShowFieldType

              -               - -

              Type Id

              -

              KCDMaskShowType

              -               - -

              Record Id

              -

              KCDMaskShowRecordId

              -               - - -
              -

              The set of -attributes that controls access to the data

              The access levels of -an element are defined by the bits in the element. The TCDAttributeFlags enum -defines the access levels of an element. These bits are stored in the fourth -byte of the iElementId member of CMDBElement.

              - -

              KCDMaskShowAttributes in the header file comsdat.h defines -the location of these access control bits in the 32 bit number.

              + + + + + +What +are elementsThis topic describes elements. All items that can be stored in +the Comms Database are elements. The topic also discusses the structure of +the unique numeric Id and the attributes that control access to elements. +

              An element is represented by the CMDBElement class. +The class is a base class for all items that can be stored in the Comms Database. +The class contains the data that is common to all items that can be stored +in the Comms database.

              +

              Elements contain three pieces of information:

              +
                +

              • a unique numeric Id +that defines the location of the element in the database. The Id defines the +meaning of the element in the database schema as a specific Table, Column, +Record or Field. A numeric Id also allows for fast access and retrieval of +an element.

                • +

              • a set of attributes +that controls access to the data.

                • +

              • a value that can be +a single numeric type, a Boolean type, a descriptor, or a composite of one +or more nested elements.

                • +
              +

              CMDBElement derives from MMetaDatabase. MMetaDatabase provides +the behaviour that allows an element to operate with the Comms Database. [See +accessing the database or words to that effect.]

              + + + +
              The Element +Id

              The iElementId data member of CMDBElement is +a 32 bit number that contains:

                +

              • the unique numeric Id +that shows the location of the element in the database. This numeric Id is +known as the Element Id.

                • +

              • the set of attributes +that controls access to the data. The bits define the access levels.

                • +

              Both pieces of information are encoded in the 32 bit number. The +32 bit number is a TMDBElementId type.

              The CMDBElement class provides member functions to +access and to change the information in the Element Id.

              +

              The unique +numeric Id

              The unique numeric Id has two parts: the Type Id and +the Record Id.

              The Type Id defines the type of element; the Record +Id identifies an instance of this type of element.

              The class CMDBElement provides the member functions CommsDat::CMDBElement::TypeId() and CommsDat::CMDBElement::RecordId() to +extract this information.

              Internally, the Type Id includes a 8 bit +number and a 7 bit number. The 8 bit number is the Table Id and the 7 bit +number is the Column Id. The Type Id and the Record Id are in defined locations +in the 32 bit number iElementId.

              + +

              The header file comsdat.h contains the constants +that define the location of these Ids in the 32 bit number:

              + + + +

              Table Id

              +

              KCDMaskShowRecordType

              +               + +

              Column Id

              +

              KCDMaskShowFieldType

              +               + +

              Type Id

              +

              KCDMaskShowType

              +               + +

              Record Id

              +

              KCDMaskShowRecordId

              +               + + +
              +

              The set of +attributes that controls access to the data

              The access levels of +an element are defined by the bits in the element. The TCDAttributeFlags enum +defines the access levels of an element. These bits are stored in the fourth +byte of the iElementId member of CMDBElement.

              + +

              KCDMaskShowAttributes in the header file comsdat.h defines +the location of these access control bits in the 32 bit number.

               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6DF52DDC-B03C-5971-94C8-0E9BAAB949FD.dita --- a/Symbian3/SDK/Source/GUID-6DF52DDC-B03C-5971-94C8-0E9BAAB949FD.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-6DF52DDC-B03C-5971-94C8-0E9BAAB949FD.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,41 +1,41 @@ - - - - - -Drawing Text

              This topic provides examples that demonstrate how to draw a line of text and text in a colored box.

              Text

              The basic way to draw text is to call CGraphicsContext::DrawText() with a point specifying the bottom left position, as shown below:

              Before calling, you must use the graphics context to:

              1. Set the font to use

              2. Set the pen color for the text

              // In this example, we use one of the standard font styles -CFont* fontUsed = iEikonEnv->TitleFont(); -gc.UseFont(fontUsed); - -gc.SetPenColor(KRgbBlack); - -TPoint pos(50,50); -_LIT(KExampleText,"blacktext"); -gc.DrawText(KExampleText,pos);
              Text in a box

              To draw text in a box, you must specify:

              • a rectangle to draw the text in

              • an offset from the top of the rectangle to the text baseline: to center the text, add half the height of the rectangle to half the height of the font's ascent

              • the text alignment mode: in the example, left alignment is used

              • a margin: the left margin for left-aligned text, or the right margin for right-aligned text

              The following figure show how these fit together:

              In addition to the font and pen color, you can also set the brush for filling the box.

              ... -// Draw some text left justified in a box, -// Offset so text is just inside top of box - -TRect box(20,20,250,100); -TInt baseline = box.Height() /2 + fontUsed->FontMaxAscent()/2; - -TInt margin=10; // left margin is ten pixels - -gc.SetBrushStyle(CGraphicsContext::ESolidBrush); -gc.SetBrushColor(KRgbDarkGray); -gc.SetPenColor(KRgbWhite); - -_LIT(KExampleText,"Whitetextleftjustified"); -gc.DrawText(KExampleText, - box, - baseline, - CGraphicsContext::ELeft, - margin); - -...
              Drawing + + + + + +Drawing Text

              This topic provides examples that demonstrate how to draw a line of text and text in a colored box.

              Text

              The basic way to draw text is to call CGraphicsContext::DrawText() with a point specifying the bottom left position, as shown below:

              Before calling, you must use the graphics context to:

              1. Set the font to use

              2. Set the pen color for the text

              // In this example, we use one of the standard font styles +CFont* fontUsed = iEikonEnv->TitleFont(); +gc.UseFont(fontUsed); + +gc.SetPenColor(KRgbBlack); + +TPoint pos(50,50); +_LIT(KExampleText,"blacktext"); +gc.DrawText(KExampleText,pos);
              Text in a box

              To draw text in a box, you must specify:

              • a rectangle to draw the text in

              • an offset from the top of the rectangle to the text baseline: to center the text, add half the height of the rectangle to half the height of the font's ascent

              • the text alignment mode: in the example, left alignment is used

              • a margin: the left margin for left-aligned text, or the right margin for right-aligned text

              The following figure show how these fit together:

              In addition to the font and pen color, you can also set the brush for filling the box.

              ... +// Draw some text left justified in a box, +// Offset so text is just inside top of box + +TRect box(20,20,250,100); +TInt baseline = box.Height() /2 + fontUsed->FontMaxAscent()/2; + +TInt margin=10; // left margin is ten pixels + +gc.SetBrushStyle(CGraphicsContext::ESolidBrush); +gc.SetBrushColor(KRgbDarkGray); +gc.SetPenColor(KRgbWhite); + +_LIT(KExampleText,"Whitetextleftjustified"); +gc.DrawText(KExampleText, + box, + baseline, + CGraphicsContext::ELeft, + margin); + +...
              Drawing to a Graphics Context Tutorials Drawing and Graphics Contexts               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6E161670-EBC6-599B-8EB8-2E48C8EA57CC_d0e272089_href.jpg Binary file Symbian3/SDK/Source/GUID-6E161670-EBC6-599B-8EB8-2E48C8EA57CC_d0e272089_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6E161670-EBC6-599B-8EB8-2E48C8EA57CC_d0e275770_href.jpg Binary file Symbian3/SDK/Source/GUID-6E161670-EBC6-599B-8EB8-2E48C8EA57CC_d0e275770_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6E221034-9A01-53AB-8374-315C38CCA21E.dita --- a/Symbian3/SDK/Source/GUID-6E221034-9A01-53AB-8374-315C38CCA21E.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-6E221034-9A01-53AB-8374-315C38CCA21E.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,381 +1,381 @@ - - - - - -Examples -Showing the use of the SIP Profile API -

              The following sections describe how to use the SIP Profile API.

              -
                -

              • Creating a SIP profile

                • -

              • Modifying a SIP Profile

                • -

              • Enabling a SIP profile

                • -

              • Disabling a SIP profile

                • -

              • Destroying a SIP Profile

                • -

              • Retrieving a profile

                • -

              • Refreshing a SIP profile

                • -

              • Stopping SIP registration

                • -
              -
              Creating a -SIP profile

              CSIPManagedProfileRegistry manages -the SIP profiles and provides the functions to add, update, and remove profiles -at run time.

              The following steps describes how to create a SIP profile.

                -

              1. Create a default profile -that uses the CreateL() interface of CSIPManagedProfileRegistry(). CreateL() returns -an object of type CSIPManagedProfile.

                2. -

              2. Use SetParameter() of CSIPManagedProfile to -set the value for the profile parameters.

                3. -

              3. Use CSIPManagedProfileRegistry::SaveL() to -save the profile when the values are set.

                4. -

              4. When you call SaveL(), -wait until EProfileCreated event is reported in the observer. -When the event is received the profile is created.

                5. -
              - -

              The following code snippet shows how to create and save a profile.

              /*Client must create an instance of the CSIP class. The API used for this is, here TUid must be an application UID.*/ - -CSIP* CSIP::NewL(const TUid& aUid, MSIPObserver& aObserver); - -/* CSIPManagedProfileRegistry manages SIP profiles and provides functions for adding, updating, or removing profiles at run time. */ - -iManagedProfileRegistry= CSIPManagedProfileRegistry::NewL(aObserver); - -/* CreateL() of CSIPManagedProfileRegistry is used to create a profile with default values. This takes ProfileType as parameter so define a profile type.*/ - -/* Profilename */ - _LIT8( KProfileName, "ims" ); - - // Used to set and get the parameters of the profile - CSIPManagedProfile* aProfile = NULL; - - // Set the profile type , profile name. - TSIPProfileTypeInfo typeInfo; - typeInfo.iSIPProfileClass = TSIPProfileTypeInfo:: EIms; - typeInfo.iSIPProfileName = KProfileName; - - // Creates the profile of type IETF with default values - aProfile = iManagedProfileRegistry->CreateL( typeInfo ); - - // Set the values in the newly created profile. - TUint32 iapId(11); - aProfile->SetParameter(KSIPAccessPointId,iapId); - - _LIT8(aor,"sip:user@192.168.0.35"); - aProfile->SetParameter(KSIPUserAor,aor); - -// Save the profile - iManagedProfileRegistry->SaveL(*aProfile); - -// Wait for EProfileCreated event on the observer. -
              -
              Modifying a -SIP Profile

              The following steps describe how to modify a SIP profile.

                -

              1. The profile is modified -when you change the profile parameters and save the updated profile to the -permanent store.

                2. -

              2. When the updated profile -is saved to the permanent store the application gets the event notification EProfileUpdated.

                3. -

              3. Depending on the updated -parameters, the update leads to no actions, to registration or to re-registration. -The profile is re-registered if it is configured for auto-registration when -the profile is updated.

                4. -

              4. The profile must not -be used by another application while you update the profile. Use the CSIPManagedProfileRegistry::IsInUseL API -to check if the profile is currently in use.

                5. -
              -
              Enabling a -SIP profile

              The following steps describe how to enable a SIP profile.

                -

              1. A client of the SIP -Profile API must create a CSIPProfileRegistry object.

                Note: -The client must provide an instance of the class CSIP to -create an object of the type CSIPProfileRegistry.

                2. -

              2. The client must implement -the callback functions defined in the MSIPProfileRegistryObserver interface -to get notified when the status of the profile is changed.

                3. -

              3. Create an instance of CSIPProfile using -a retrieve function of the CSIPPProfileRegistry class.

                4. -

              4. The profile parameters -are read from the getter functions of the CSIPProfile.

                5. -

              5. The client can use the -profile when you enable it through CSIPProfileRegistry and -leaves on failure.

                6. -

              6. The user must check -the profile status after the EnableL function is called. -If the profile is not registered after this function is called, the user must -wait until it gets a notification through the MSIPProfileRegistryObserver callback -interface about the profile registration.

                7. -
              - -

              The following code snippet shows how to enable a SIP profile.

              -/*With the assumption that the profile was created and is saved to the persistent storage. */ -//Create an Instance of SIP client - -iSip = CSIP::NewL( aAppUid ); - -//use CSIPProfileRegistry to get the saved profile. - -iProfileRegistry = CSIPProfileRegistry::NewL(*iSip, *this); - -//Retrieve the profiles by the AOR - -_LIT8(KAor,"sip:user@10.192.192.43"); -TDesC8 aor(KAor); - -RPointerArray<CSIPProfile> profiles; - -/* Find and put the matching profiles by the given AOR into the pointer array. -Returns the set of profiles which has the provided AOR.*/ - -iProfileRegistry->ProfilesL(KAor,profiles); - -// Check the profile count. Get the required profile if the count is positive non-zero. -TInt profile_cnt = profiles.Count() ; -iProfile = profiles[0]; -iProfileRegistry->EnableL( *iProfile, *this ); - -//Application gets the event EProfileRegistered if the registration is successful. -
              -
              Disabling a -SIP profile

              The following steps describes how to disable a SIP -profile.

                -

              • A client of the SIP -Profile API must create a CSIPProfileRegistry object

                Note: -The client must provide an instance of the class CSIP to -create a CSIPProfileRegistry object.

                • -

              • The client must implement -the callback functions defined in the MSIPProfileRegistryObserver interface -to get notified with the events when the status of the profile is changed.

                • -

              • Use retrieve function -of the class CSIPPProfileRegistry to create an instance -of CSIPProfile.

                • -

              • The profile parameters -are read from the getter functions of the CSIPProfile.

                • -

              • Check the registration -status of the profile that uses the getter functions of CSIPProfile. -Disable the profile if it is registered.

                • -

              • An application gets -the notification event EProfileDeregistered if the de-registration -is successful, otherwise it leaves. The error is sent to the application through -the ProfileRegistryErrorOccurred callback function.

                • -

              The following code snippet shows how to disable a SIP profile.

              /*With the assumption that the profile was created and is saved to the persistent storage. -//Create an instance of SIP client -iSip = CSIP::NewL( aAppUid - -/*use CSIPProfileRegistry to get the saved profile.*/ -iProfileRegistry = CSIPProfileRegistry::NewL(*iSip, *this); - - /*Retrieve the profiles by the AOR*/ -_LIT8(KAor,"sip:user@10.192.192.43"); -TDesC8 aor(KAor); - -RPointerArray<CSIPProfile> profiles; - -// Find and put the matching profiles by the given AOR into the pointer array -// Returns the set of profiles which has the provided AOR. -iProfileRegistry->ProfilesL(KAor,profiles); - -/* Check the profile count. Get the required profile if the count is positive non-zero.*/ -TInt profile_cnt = profiles.Count() ; -iProfile = profiles[0]; - -// Registered is a bool type variable. Check the registration status of the iProfile. -// Registered holds TRUE if it is registered otherwise FALSE -iProfile->GetParameter( KSIPProfileRegistered, registered ); - -/* If the iProfile is registered ( the Registered variable must hold TRUE for iProfile )*/ -/* Disable API returns KErrNone if the profile was disabled successfully otherwise there is a system-wide error.*/ -CSIPProfileRegistry::Disable(*iProfile) -
              -
              Destroying -a SIP Profile

              When you destroy a SIP profile it is permanently -removed from the permanent storage and it cannot be used. The profile information -is removed from the sipprofiles.dat file in Epoc32\winscw\c\private\101F413C.

              The -following steps describe how to destroy a SIP profile.

                -

              1. When the profile is -destroyed the application gets the event EProfileDestroyed.

                2. -
                2. -

                • Registered: The removal -is two-step process, de-register the profile and remove the profile.

                  • -
                  -

                • De-registered : Removes -the profile from the permanent storage and the application is notified with -the event EProfileDestroyed.

                  • -
                3. -

              The following code snippet shows how to disable a profile.

              //Function leaves on failure. -CSIPManagedProfileRegistry::DestroyL(CSIPProfile& aSIPProfile); -
              -
              Retrieving -a profile

              Retrieving a default profile

              The following -code snippet shows how to retrieve the default profile.

              // Retrieving a default profile. -CSIPProfile* profile = iProfileRegistry->DefaultProfileL(); - -// When a client retrieves a profile, its ownership is transferred to that client, so it becomes responsible -// for deleting the instances when they are no longer needed. - -delete profile; -

              Retrieving profiles by type

              The following code -snippet shows how to retrieve profiles by type.

              // To retrieve more than one profile, the client must create -// an RPointerArray object to holding pointers to instances of CSIPProfile. - -RPointerArray<CSIPProfile> profiles; - -// The wanted type is defined using a variable of type TSIPProfileTypeInfo. - -TSIPProfileTypeInfo type; -type.iSIPProfileClass = TSIPProfileTypeInfo::EInternet; -type.iSIPProfileName = _L8("IETF"); - -// Profiles matching a given type are returned in the array. -iProfileRegistry->ProfilesL(type, profiles); -... -// When a client retrieves a profile, its ownership is transferred to that -// client, so it becomes responsible for deleting the instances when they are -// no longer needed. -profiles.ResetAndDestroy(); -

              Retrieving profiles by matching an AOR

              The -following code snippet shows how to retrieve profiles by matching an AOR.

              // To retrieve more than one profile, the client must create -// an RPointerArray object to hold pointers to instances of CSIPProfile. -RPointerArray<CSIPProfile> profiles; - -// Profiles matching a given AOR are returned in the array. -iProfileRegistry->ProfilesL(_L8( "sip:jane.doe@foo.com" ), profiles ); -... - -// When a client retrieves a profile, its ownership is transferred to that -// client, so it becomes responsible for deleting the instances when they are no longer needed. -profiles.ResetAndDestroy(); -
              -
              Getting the registration events

              The following code -snippet shows how to get the registration events for different scenarios.

              // A callback function, which must be implemented by the client, is called when the registration status -of a profile owned by the client is changed. - -void CMySIPClient:: ProfileRegistryEventOccurred(TUint32 aProfileId, -MSIPProfileRegistryObserver::TEvent aEvent) - { - iProfileId = aProfileId; - switch(aEvent) - { - case EProfileCreated: - { - iEventId = EAdded; - break; - } - case EProfileUpdated: - { - iEventId = EUpdated; - break; - } - case EProfileRegistered: - { - iEventId = CMySIPClient::ERegistered; - break; - } - case EProfileDeregistered: - { - iEventId = CMySIPClient::EDeregistered; - break; - } - case EProfileDestroyed: - { - iEventId = ERemoved; - break; - } - default: - break; - } -}
              -
              Refreshing -a SIP profile

              The SIP profile can use either WLAN or GPRS connections -to register to the SIP server. In case of WLAN, a registered SIP profile changes -its state to an unregistered state when the handset is out of WLAN coverage. -On re-entering the WLAN zone, the WLAN automatically scans to identify the -available access points and then the SIP profile is automatically registered -back with the server. This process is time consuming and is not efficient. -So, the client uses the RefreshEnableL() function to:

                -

              • Initiate the SIP registration -automatically.

                • -

              • Reduce the response -time for the SIP registration.

                • -

              • Improve the efficiency -of the application using the SIP stack during registration.

                • -

              The RefreshEnableL API refreshes the connection -on the used access point if it is not active. Refresh enabling a profile means -that the user has enabled the profile but is unregistered because of a connection -loss. For example, in a WLAN network, a connection refresh request to the -bearer monitor starts the WLAN scanning if it is stopped. When the Connection -Active notification is received, the stack automatically registers the profile -and gives a notification to the client with the event EProfileRegistered through -the MSIPProfileRegistryObserver.

              To refresh enable -a profile, do the following steps:

                -

              • Start the SIP Profile -server.

                • -

              • Fetch the profile that -must be refresh enabled from the SIP Profile Server.

                  -

                • If the profile is not -Enabled the RefreshEnable API leaves with KErrArgument error.

                  • -

                • If the profile is Enabled -and in a Registered state then the API leaves with KErrAlreadyExists error.

                  • -

                • If the profile is Enabled -and in an Unregistered state then the RefreshEnable API -refreshes the connection through CSIPConnection::RefreshConnection() API. -The profile receives notification about the active connection and it automatically -registers again and sends EProfileRegistered event to the -application.

                  • -
                • -

              • A REGISTER request sent -to the registrar server.

                • -

              • The registration status -of the profile is set to Registered.

                • -

              The following sequence diagram shows how to enable a profile to refresh.

              - -

              The following code describes how to refresh enable a profile.

              //Checks if the profile is already enabled and requests the Profile Agent to refresh it. -// If the profile is not enabled it leaves with KErrArgument. - -void RefreshEnableL(CSIPProfile& aSIPProfile, MSIPConnectionObserver& aObserver) -
              -
              Stopping SIP -registration

              In a setup, where there is no registrar, the SIP stack -tries to send REGISTER messages to the network for at least 3 minutes and -reserves the access point usage. During these 3 minutes the client cannot -use another WLAN access point without destroying the RConnection.

              The ForceDisable API -of the SIP stack stops all registration attempts and releases the access point. -The ForceDisable API in the profile agent module improves -the responsiveness of the applications using the SIP stack. It avoids situations -where an application is waiting for the SIP stack to complete a registration -procedure.

              To use the ForceDisable API the application -must have Network Control capability. If the application does not have Network -Control capability and invokes the ForceDisable API, then -it receives ErrPermissionDenied (-46) error. Sending a ForceDisable API -does not force the SIP stack to send any message to the network, instead it -destroys the SIP transaction for that profile and cleans all the resources -associated with that profile. The Profile Agent also notifies all the observers -with the event EProfileForciblyDisabled.

              The following -code describes how to forcibly disable a profile.

              // With the assumption that the profile is created and is saved to the persistent storage create an instance of the SIP client -iSip = CSIP::NewL( aAppUid ); - -// Use CSIPProfileRegistry to get the saved profile. -iProfileRegistry = CSIPProfileRegistry::NewL(*iSip, *this); - -// Retrieve the profiles by the AOR -_LIT8(KAor,"sip:user@10.192.192.43"); -TDesC8 aor(KAor); -RPointerArray<CSIPProfile> profiles; - -// Find and add the matching profiles by the given AOR into the pointer array -// Returns the set of profiles which has the provided AOR. -iProfileRegistry->ProfilesL(KAor,profiles); - -// Check the profile count. Get the required profile if the count is positive non-zero. -TInt profile_cnt = profiles.Count() ; -iProfile = profiles[0]; - -// If the iProfile is registered (the Registered variable must hold TRUE for iProfile) -// Disable API returns KErrNone if the profile is disabled successfully otherwise there is a system-wide error. -CSIPProfileRegistry::ForceDisable(*iProfile);
              + + + + + +Examples +Showing the use of the SIP Profile API +

              The following sections describe how to use the SIP Profile API.

              +
                +

              • Creating a SIP profile

                • +

              • Modifying a SIP Profile

                • +

              • Enabling a SIP profile

                • +

              • Disabling a SIP profile

                • +

              • Destroying a SIP Profile

                • +

              • Retrieving a profile

                • +

              • Refreshing a SIP profile

                • +

              • Stopping SIP registration

                • +
              +
              Creating a +SIP profile

              CSIPManagedProfileRegistry manages +the SIP profiles and provides the functions to add, update, and remove profiles +at run time.

              The following steps describes how to create a SIP profile.

                +

              1. Create a default profile +that uses the CreateL() interface of CSIPManagedProfileRegistry(). CreateL() returns +an object of type CSIPManagedProfile.

                2. +

              2. Use SetParameter() of CSIPManagedProfile to +set the value for the profile parameters.

                3. +

              3. Use CSIPManagedProfileRegistry::SaveL() to +save the profile when the values are set.

                4. +

              4. When you call SaveL(), +wait until EProfileCreated event is reported in the observer. +When the event is received the profile is created.

                5. +
              + +

              The following code snippet shows how to create and save a profile.

              /*Client must create an instance of the CSIP class. The API used for this is, here TUid must be an application UID.*/ + +CSIP* CSIP::NewL(const TUid& aUid, MSIPObserver& aObserver); + +/* CSIPManagedProfileRegistry manages SIP profiles and provides functions for adding, updating, or removing profiles at run time. */ + +iManagedProfileRegistry= CSIPManagedProfileRegistry::NewL(aObserver); + +/* CreateL() of CSIPManagedProfileRegistry is used to create a profile with default values. This takes ProfileType as parameter so define a profile type.*/ + +/* Profilename */ + _LIT8( KProfileName, "ims" ); + + // Used to set and get the parameters of the profile + CSIPManagedProfile* aProfile = NULL; + + // Set the profile type , profile name. + TSIPProfileTypeInfo typeInfo; + typeInfo.iSIPProfileClass = TSIPProfileTypeInfo:: EIms; + typeInfo.iSIPProfileName = KProfileName; + + // Creates the profile of type IETF with default values + aProfile = iManagedProfileRegistry->CreateL( typeInfo ); + + // Set the values in the newly created profile. + TUint32 iapId(11); + aProfile->SetParameter(KSIPAccessPointId,iapId); + + _LIT8(aor,"sip:user@192.168.0.35"); + aProfile->SetParameter(KSIPUserAor,aor); + +// Save the profile + iManagedProfileRegistry->SaveL(*aProfile); + +// Wait for EProfileCreated event on the observer. +
              +
              Modifying a +SIP Profile

              The following steps describe how to modify a SIP profile.

                +

              1. The profile is modified +when you change the profile parameters and save the updated profile to the +permanent store.

                2. +

              2. When the updated profile +is saved to the permanent store the application gets the event notification EProfileUpdated.

                3. +

              3. Depending on the updated +parameters, the update leads to no actions, to registration or to re-registration. +The profile is re-registered if it is configured for auto-registration when +the profile is updated.

                4. +

              4. The profile must not +be used by another application while you update the profile. Use the CSIPManagedProfileRegistry::IsInUseL API +to check if the profile is currently in use.

                5. +
              +
              Enabling a +SIP profile

              The following steps describe how to enable a SIP profile.

                +

              1. A client of the SIP +Profile API must create a CSIPProfileRegistry object.

                Note: +The client must provide an instance of the class CSIP to +create an object of the type CSIPProfileRegistry.

                2. +

              2. The client must implement +the callback functions defined in the MSIPProfileRegistryObserver interface +to get notified when the status of the profile is changed.

                3. +

              3. Create an instance of CSIPProfile using +a retrieve function of the CSIPPProfileRegistry class.

                4. +

              4. The profile parameters +are read from the getter functions of the CSIPProfile.

                5. +

              5. The client can use the +profile when you enable it through CSIPProfileRegistry and +leaves on failure.

                6. +

              6. The user must check +the profile status after the EnableL function is called. +If the profile is not registered after this function is called, the user must +wait until it gets a notification through the MSIPProfileRegistryObserver callback +interface about the profile registration.

                7. +
              + +

              The following code snippet shows how to enable a SIP profile.

              +/*With the assumption that the profile was created and is saved to the persistent storage. */ +//Create an Instance of SIP client + +iSip = CSIP::NewL( aAppUid ); + +//use CSIPProfileRegistry to get the saved profile. + +iProfileRegistry = CSIPProfileRegistry::NewL(*iSip, *this); + +//Retrieve the profiles by the AOR + +_LIT8(KAor,"sip:user@10.192.192.43"); +TDesC8 aor(KAor); + +RPointerArray<CSIPProfile> profiles; + +/* Find and put the matching profiles by the given AOR into the pointer array. +Returns the set of profiles which has the provided AOR.*/ + +iProfileRegistry->ProfilesL(KAor,profiles); + +// Check the profile count. Get the required profile if the count is positive non-zero. +TInt profile_cnt = profiles.Count() ; +iProfile = profiles[0]; +iProfileRegistry->EnableL( *iProfile, *this ); + +//Application gets the event EProfileRegistered if the registration is successful. +
              +
              Disabling a +SIP profile

              The following steps describes how to disable a SIP +profile.

                +

              • A client of the SIP +Profile API must create a CSIPProfileRegistry object

                Note: +The client must provide an instance of the class CSIP to +create a CSIPProfileRegistry object.

                • +

              • The client must implement +the callback functions defined in the MSIPProfileRegistryObserver interface +to get notified with the events when the status of the profile is changed.

                • +

              • Use retrieve function +of the class CSIPPProfileRegistry to create an instance +of CSIPProfile.

                • +

              • The profile parameters +are read from the getter functions of the CSIPProfile.

                • +

              • Check the registration +status of the profile that uses the getter functions of CSIPProfile. +Disable the profile if it is registered.

                • +

              • An application gets +the notification event EProfileDeregistered if the de-registration +is successful, otherwise it leaves. The error is sent to the application through +the ProfileRegistryErrorOccurred callback function.

                • +

              The following code snippet shows how to disable a SIP profile.

              /*With the assumption that the profile was created and is saved to the persistent storage. +//Create an instance of SIP client +iSip = CSIP::NewL( aAppUid + +/*use CSIPProfileRegistry to get the saved profile.*/ +iProfileRegistry = CSIPProfileRegistry::NewL(*iSip, *this); + + /*Retrieve the profiles by the AOR*/ +_LIT8(KAor,"sip:user@10.192.192.43"); +TDesC8 aor(KAor); + +RPointerArray<CSIPProfile> profiles; + +// Find and put the matching profiles by the given AOR into the pointer array +// Returns the set of profiles which has the provided AOR. +iProfileRegistry->ProfilesL(KAor,profiles); + +/* Check the profile count. Get the required profile if the count is positive non-zero.*/ +TInt profile_cnt = profiles.Count() ; +iProfile = profiles[0]; + +// Registered is a bool type variable. Check the registration status of the iProfile. +// Registered holds TRUE if it is registered otherwise FALSE +iProfile->GetParameter( KSIPProfileRegistered, registered ); + +/* If the iProfile is registered ( the Registered variable must hold TRUE for iProfile )*/ +/* Disable API returns KErrNone if the profile was disabled successfully otherwise there is a system-wide error.*/ +CSIPProfileRegistry::Disable(*iProfile) +
              +
              Destroying +a SIP Profile

              When you destroy a SIP profile it is permanently +removed from the permanent storage and it cannot be used. The profile information +is removed from the sipprofiles.dat file in Epoc32\winscw\c\private\101F413C.

              The +following steps describe how to destroy a SIP profile.

                +

              1. When the profile is +destroyed the application gets the event EProfileDestroyed.

                2. +
                2. +

                • Registered: The removal +is two-step process, de-register the profile and remove the profile.

                  • +
                  +

                • De-registered : Removes +the profile from the permanent storage and the application is notified with +the event EProfileDestroyed.

                  • +
                3. +

              The following code snippet shows how to disable a profile.

              //Function leaves on failure. +CSIPManagedProfileRegistry::DestroyL(CSIPProfile& aSIPProfile); +
              +
              Retrieving +a profile

              Retrieving a default profile

              The following +code snippet shows how to retrieve the default profile.

              // Retrieving a default profile. +CSIPProfile* profile = iProfileRegistry->DefaultProfileL(); + +// When a client retrieves a profile, its ownership is transferred to that client, so it becomes responsible +// for deleting the instances when they are no longer needed. + +delete profile; +

              Retrieving profiles by type

              The following code +snippet shows how to retrieve profiles by type.

              // To retrieve more than one profile, the client must create +// an RPointerArray object to holding pointers to instances of CSIPProfile. + +RPointerArray<CSIPProfile> profiles; + +// The wanted type is defined using a variable of type TSIPProfileTypeInfo. + +TSIPProfileTypeInfo type; +type.iSIPProfileClass = TSIPProfileTypeInfo::EInternet; +type.iSIPProfileName = _L8("IETF"); + +// Profiles matching a given type are returned in the array. +iProfileRegistry->ProfilesL(type, profiles); +... +// When a client retrieves a profile, its ownership is transferred to that +// client, so it becomes responsible for deleting the instances when they are +// no longer needed. +profiles.ResetAndDestroy(); +

              Retrieving profiles by matching an AOR

              The +following code snippet shows how to retrieve profiles by matching an AOR.

              // To retrieve more than one profile, the client must create +// an RPointerArray object to hold pointers to instances of CSIPProfile. +RPointerArray<CSIPProfile> profiles; + +// Profiles matching a given AOR are returned in the array. +iProfileRegistry->ProfilesL(_L8( "sip:jane.doe@foo.com" ), profiles ); +... + +// When a client retrieves a profile, its ownership is transferred to that +// client, so it becomes responsible for deleting the instances when they are no longer needed. +profiles.ResetAndDestroy(); +
              +
              Getting the registration events

              The following code +snippet shows how to get the registration events for different scenarios.

              // A callback function, which must be implemented by the client, is called when the registration status +of a profile owned by the client is changed. + +void CMySIPClient:: ProfileRegistryEventOccurred(TUint32 aProfileId, +MSIPProfileRegistryObserver::TEvent aEvent) + { + iProfileId = aProfileId; + switch(aEvent) + { + case EProfileCreated: + { + iEventId = EAdded; + break; + } + case EProfileUpdated: + { + iEventId = EUpdated; + break; + } + case EProfileRegistered: + { + iEventId = CMySIPClient::ERegistered; + break; + } + case EProfileDeregistered: + { + iEventId = CMySIPClient::EDeregistered; + break; + } + case EProfileDestroyed: + { + iEventId = ERemoved; + break; + } + default: + break; + } +}
              +
              Refreshing +a SIP profile

              The SIP profile can use either WLAN or GPRS connections +to register to the SIP server. In case of WLAN, a registered SIP profile changes +its state to an unregistered state when the handset is out of WLAN coverage. +On re-entering the WLAN zone, the WLAN automatically scans to identify the +available access points and then the SIP profile is automatically registered +back with the server. This process is time consuming and is not efficient. +So, the client uses the RefreshEnableL() function to:

                +

              • Initiate the SIP registration +automatically.

                • +

              • Reduce the response +time for the SIP registration.

                • +

              • Improve the efficiency +of the application using the SIP stack during registration.

                • +

              The RefreshEnableL API refreshes the connection +on the used access point if it is not active. Refresh enabling a profile means +that the user has enabled the profile but is unregistered because of a connection +loss. For example, in a WLAN network, a connection refresh request to the +bearer monitor starts the WLAN scanning if it is stopped. When the Connection +Active notification is received, the stack automatically registers the profile +and gives a notification to the client with the event EProfileRegistered through +the MSIPProfileRegistryObserver.

              To refresh enable +a profile, do the following steps:

                +

              • Start the SIP Profile +server.

                • +

              • Fetch the profile that +must be refresh enabled from the SIP Profile Server.

                  +

                • If the profile is not +Enabled the RefreshEnable API leaves with KErrArgument error.

                  • +

                • If the profile is Enabled +and in a Registered state then the API leaves with KErrAlreadyExists error.

                  • +

                • If the profile is Enabled +and in an Unregistered state then the RefreshEnable API +refreshes the connection through CSIPConnection::RefreshConnection() API. +The profile receives notification about the active connection and it automatically +registers again and sends EProfileRegistered event to the +application.

                  • +
                • +

              • A REGISTER request sent +to the registrar server.

                • +

              • The registration status +of the profile is set to Registered.

                • +

              The following sequence diagram shows how to enable a profile to refresh.

              + +

              The following code describes how to refresh enable a profile.

              //Checks if the profile is already enabled and requests the Profile Agent to refresh it. +// If the profile is not enabled it leaves with KErrArgument. + +void RefreshEnableL(CSIPProfile& aSIPProfile, MSIPConnectionObserver& aObserver) +
              +
              Stopping SIP +registration

              In a setup, where there is no registrar, the SIP stack +tries to send REGISTER messages to the network for at least 3 minutes and +reserves the access point usage. During these 3 minutes the client cannot +use another WLAN access point without destroying the RConnection.

              The ForceDisable API +of the SIP stack stops all registration attempts and releases the access point. +The ForceDisable API in the profile agent module improves +the responsiveness of the applications using the SIP stack. It avoids situations +where an application is waiting for the SIP stack to complete a registration +procedure.

              To use the ForceDisable API the application +must have Network Control capability. If the application does not have Network +Control capability and invokes the ForceDisable API, then +it receives ErrPermissionDenied (-46) error. Sending a ForceDisable API +does not force the SIP stack to send any message to the network, instead it +destroys the SIP transaction for that profile and cleans all the resources +associated with that profile. The Profile Agent also notifies all the observers +with the event EProfileForciblyDisabled.

              The following +code describes how to forcibly disable a profile.

              // With the assumption that the profile is created and is saved to the persistent storage create an instance of the SIP client +iSip = CSIP::NewL( aAppUid ); + +// Use CSIPProfileRegistry to get the saved profile. +iProfileRegistry = CSIPProfileRegistry::NewL(*iSip, *this); + +// Retrieve the profiles by the AOR +_LIT8(KAor,"sip:user@10.192.192.43"); +TDesC8 aor(KAor); +RPointerArray<CSIPProfile> profiles; + +// Find and add the matching profiles by the given AOR into the pointer array +// Returns the set of profiles which has the provided AOR. +iProfileRegistry->ProfilesL(KAor,profiles); + +// Check the profile count. Get the required profile if the count is positive non-zero. +TInt profile_cnt = profiles.Count() ; +iProfile = profiles[0]; + +// If the iProfile is registered (the Registered variable must hold TRUE for iProfile) +// Disable API returns KErrNone if the profile is disabled successfully otherwise there is a system-wide error. +CSIPProfileRegistry::ForceDisable(*iProfile);
              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6E2F23B0-4765-5E4E-9B15-9F1D0EC5C28B_d0e271965_href.jpg Binary file Symbian3/SDK/Source/GUID-6E2F23B0-4765-5E4E-9B15-9F1D0EC5C28B_d0e271965_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6E2F23B0-4765-5E4E-9B15-9F1D0EC5C28B_d0e275646_href.jpg Binary file Symbian3/SDK/Source/GUID-6E2F23B0-4765-5E4E-9B15-9F1D0EC5C28B_d0e275646_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6E3AF264-6149-51FA-BBA0-68E2DB679048_d0e107601_href.png Binary file Symbian3/SDK/Source/GUID-6E3AF264-6149-51FA-BBA0-68E2DB679048_d0e107601_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6E3AF264-6149-51FA-BBA0-68E2DB679048_d0e114139_href.png Binary file Symbian3/SDK/Source/GUID-6E3AF264-6149-51FA-BBA0-68E2DB679048_d0e114139_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6E4CAA18-635E-5476-8CE4-DCA69C05CC07.dita --- a/Symbian3/SDK/Source/GUID-6E4CAA18-635E-5476-8CE4-DCA69C05CC07.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-6E4CAA18-635E-5476-8CE4-DCA69C05CC07.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,50 +1,43 @@ - - - - - -HybridApp: -Demonstrating P.I.P.S. Hybrid Applications -

              This example shows how to develop P.I.P.S. hybrid applications. The example -uses both pure C and native Symbian C++ APIs.

              -
              Download

              Click on the following link to download -the example: HybridApp.zip

              Click: browse to view the example code.

              -
              Description

              This example displays the memory information -of all available drives of the system. As P.I.P.S. APIs cannot be used to -access these drives, native Symbian C++ APIs are used. The RFs::Drive() and RFs::Volume() APIs -are used to access the drives and get their memory information.

              It -displays the drive information by using the standard Input/Output functions -defined in P.I.P.S. libraries. The DescToChar() function -defined in the example converts the native Symbian descriptor strings to C -strings. As the drive name is stored in a descriptor, the example uses this -function to convert it to a C string.

              -
              Build

              The following statements are present in all -the .mmp files of the example:

              SYSTEMINCLUDE epoc32\include\stdapis -LIBRARY libc.lib -STATICLIBRARY libcrt0.lib

              Note: You require these statements -because of the following reasons:

                -

              • The epoc32\include\stdapis directory -contains header files such as, stdio.h, unistd.h and -so on that are required to build an Open Environment application.

                • -

              • The libc.lib file -contains the definitions of all functions that are defined in the header files -associated with this example.

                • -

              • The libcrt0.lib file -provides the E32Main() function, which is the entry point -for the main() function of the example.

                • -

              The Symbian -build process describes how to build this example.

              For -the emulator, the example builds an executable file called hybridapp.exe in -the epoc32\release\winscw\<udeb or urel>\ directory.

              -               -Hybrid Applications - -Build Process - + + + + + +HybridApp: Demonstrating P.I.P.S. Hybrid Applications +

              This example shows how to develop P.I.P.S. hybrid applications. +The example uses both pure C and native Symbian C++ APIs.

              +
              Download

              Click on the following link to download the example: HybridApp.zip

              Click: browse to view the example code.

              +
              Description

              This example displays the memory information of all available +drives of the system. As P.I.P.S. APIs cannot be used to access these +drives, native Symbian C++ APIs are used. The RFs::Drive() and RFs::Volume() APIs are used to access the drives +and get their memory information.

              It displays the drive information +by using the standard Input/Output functions defined in P.I.P.S. libraries. +The DescToChar() function defined in the example +converts the native Symbian descriptor strings to C strings. As the +drive name is stored in a descriptor, the example uses this function +to convert it to a C string.

              +
              Build

              The following statements are present in all the .mmp files of the example:

              SYSTEMINCLUDE epoc32\include\stdapis +LIBRARY libc.lib +STATICLIBRARY libcrt0.lib

              Note: You require +these statements because of the following reasons:

                +

              • The epoc32\include\stdapis directory contains header files +such as, stdio.h, unistd.h and so on that are required to build an Open Environment application.

                • +

              • The libc.lib file contains the definitions of all functions +that are defined in the header files associated with this example.

                • +

              • The libcrt0.lib file provides the E32Main() function, which is the entry point for the main() function of the example.

                • +

              The +Symbian build process describes how to build this example.

              For the emulator, the example builds an executable +file called hybridapp.exe in the epoc32\release\winscw\<udeb +or urel>\ directory.

              +               +Hybrid +Applications +Build +Process               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6E52C463-5489-591F-859D-68EAD5BA80FD.dita --- a/Symbian3/SDK/Source/GUID-6E52C463-5489-591F-859D-68EAD5BA80FD.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-6E52C463-5489-591F-859D-68EAD5BA80FD.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,14 +1,14 @@ - - - - - -Multimedia Framework Guide

              This document introduces the Multimedia Framework (MMF) audio and video client interfaces.

              Purpose

              Multimedia Framework (MMF) provides several client interfaces that encapsulate a lightweight plugin framework. These interfaces enable you to manipulate the audio and video features of the Symbian platform.

              Architectural Relationships

              The following diagram shows how the MMF client interfaces interact with the Multimedia Controller Framework and the Media Device Framework (MDF).

              - Multimedia Framework - client utilities -

              MMF Controller Framework

              The MMF Controller Framework provides support for multimedia plugins within the Symbian platform. The main type of plugin for the MMF Controller Framework is the controller plugin. Each controller plugin provides support for one or more multimedia formats, for example, MP3 or AVI.

              Note: In addition to controller plugins, the Multimedia framework can also be extended through format encoder/decoder, codec, and sink/source plugins. For more information about plugins, see How to write Multimedia Framework plugins.

              The player and recorder interfaces of both audio and video and also the audio converter interface use the controller plugins provided by the MMF Controller Framework. These plugins provide the functionality to convert, interpret, and play audio and video data. The resultant data from the plugins can then be directed to one or more sinks such as a file, or directly to a screen or lower level device driver.

              The video recorder interface can also interact with the Onboard Camera, through a video controller plugin, to capture video. For more information about capturing video, see Video Capture Tutorial.

              Note: Tone player and audio streaming are also provided as part of the MMF but do not interact with controller plugins. Input and output is already in a known data format and so does not require a plugin for encoding or decoding. As a result, they bypass the MMF Controller Framework.

              Media Device Framework

              Media Device Framework is the layer below the controller plugins and above the hardware. It provides a layer of abstraction for the audio and video hardware. The MDF consists of DevSound, for audio input and output, and DevVideo for video.

              For more information about DevSound, see DevSound Overview. For more information about DevVideo, see DevVideo Overview.

              DRM Support

              The Symbian platform provides support for playback of Digital Rights Management (DRM) protected audio and video content by making use of the Content Access Framework (CAF). For more information about the CAF, see Content Access Framework.

              Note: In order to access any DRM protected content using Symbian multimedia, the client process must have the DRM capability.

              Description

              The features made available by the MMF client interfaces are:

              • Audio playing, recording, and conversion - An interface consisting of three classes; CMdaAudioPlayerUtility, CMdaAudioRecorderUtility, and CMdaAudioConvertUtility. These classes provide methods to create, play, and manipulate audio data stored in files, descriptors, and URLs.

              • Audio streaming - An interface consisting of two classes; CMdaAudioInputStream and CMdaAudioOutputStream. These classes provide methods for recording and playing audio streams such as audio from a web address.

                Note: There are no explicit interfaces for video streaming. However, the Onboard Camera can be used to achieve video input streaming, and direct screen access can be used to achieve video output streaming. For more information about the Onboard Camera, see Onboard Camera Overview.

              • Tone playing - An interface consisting of a single class CMdaAudioToneUtility. This class provides methods for playing and configuring single and sequenced tones as well as DTMF (Dual Tone Multi-Frequency) strings.

              • Video playing and recording - An interface consisting of two classes CVideoPlayerUtility and CVideoRecorderUtility. These classes provide methods to create, play, and manipulate video clips with or without audio tracks stored in files, descriptors, and URLs.

              Observer Classes

              For each multimedia client interface, there is a corresponding mixin class that must be implemented by the client. For example, to use the audio player utility you must implement the observer mixin class MMdaAudioPlayerCallback.

              When instantiating any of the MMF interfaces, it is necessary to provide a reference to a class that implements the appropriate mixin class. This allows the MMF to notify the client of events that occur and also to notify the client of errors that may occur.

              Multimedia Framework Tutorials

              The following tutorials are provided:

              • How to use the audio convert utility

              • How to use the audio record utility

              • How to use the audio player utility

              • Audio Input Stream Tutorial

              • Audio Output Stream Tutorial

              • Video Client Tutorials

              See Also

              Audio Client Overview

              Audio Input Stream Overview

              Audio Output Stream Overview

              Video Client Overview

              \ No newline at end of file + + + + + +Multimedia Framework Guide

              This document introduces the Multimedia Framework (MMF) audio and video client interfaces.

              Purpose

              Multimedia Framework (MMF) provides several client interfaces that encapsulate a lightweight plugin framework. These interfaces enable you to manipulate the audio and video features of the Symbian platform.

              Architectural Relationships

              The following diagram shows how the MMF client interfaces interact with the Multimedia Controller Framework and the Media Device Framework (MDF).

              + Multimedia Framework - client utilities +

              MMF Controller Framework

              The MMF Controller Framework provides support for multimedia plugins within the Symbian platform. The main type of plugin for the MMF Controller Framework is the controller plugin. Each controller plugin provides support for one or more multimedia formats, for example, MP3 or AVI.

              Note: In addition to controller plugins, the Multimedia framework can also be extended through format encoder/decoder, codec, and sink/source plugins. For more information about plugins, see How to write Multimedia Framework plugins.

              The player and recorder interfaces of both audio and video and also the audio converter interface use the controller plugins provided by the MMF Controller Framework. These plugins provide the functionality to convert, interpret, and play audio and video data. The resultant data from the plugins can then be directed to one or more sinks such as a file, or directly to a screen or lower level device driver.

              The video recorder interface can also interact with the Onboard Camera, through a video controller plugin, to capture video. For more information about capturing video, see Video Capture Tutorial.

              Note: Tone player and audio streaming are also provided as part of the MMF but do not interact with controller plugins. Input and output is already in a known data format and so does not require a plugin for encoding or decoding. As a result, they bypass the MMF Controller Framework.

              Media Device Framework

              Media Device Framework is the layer below the controller plugins and above the hardware. It provides a layer of abstraction for the audio and video hardware. The MDF consists of DevSound, for audio input and output, and DevVideo for video.

              For more information about DevSound, see DevSound Overview. For more information about DevVideo, see DevVideo Overview.

              DRM Support

              The Symbian platform provides support for playback of Digital Rights Management (DRM) protected audio and video content by making use of the Content Access Framework (CAF). For more information about the CAF, see Content Access Framework.

              Note: In order to access any DRM protected content using Symbian multimedia, the client process must have the DRM capability.

              Description

              The features made available by the MMF client interfaces are:

              • Audio playing, recording, and conversion - An interface consisting of three classes; CMdaAudioPlayerUtility, CMdaAudioRecorderUtility, and CMdaAudioConvertUtility. These classes provide methods to create, play, and manipulate audio data stored in files, descriptors, and URLs.

              • Audio streaming - An interface consisting of two classes; CMdaAudioInputStream and CMdaAudioOutputStream. These classes provide methods for recording and playing audio streams such as audio from a web address.

                Note: There are no explicit interfaces for video streaming. However, the Onboard Camera can be used to achieve video input streaming, and direct screen access can be used to achieve video output streaming. For more information about the Onboard Camera, see Onboard Camera Overview.

              • Tone playing - An interface consisting of a single class CMdaAudioToneUtility. This class provides methods for playing and configuring single and sequenced tones as well as DTMF (Dual Tone Multi-Frequency) strings.

              • Video playing and recording - An interface consisting of two classes CVideoPlayerUtility and CVideoRecorderUtility. These classes provide methods to create, play, and manipulate video clips with or without audio tracks stored in files, descriptors, and URLs.

              Observer Classes

              For each multimedia client interface, there is a corresponding mixin class that must be implemented by the client. For example, to use the audio player utility you must implement the observer mixin class MMdaAudioPlayerCallback.

              When instantiating any of the MMF interfaces, it is necessary to provide a reference to a class that implements the appropriate mixin class. This allows the MMF to notify the client of events that occur and also to notify the client of errors that may occur.

              Multimedia Framework Tutorials

              The following tutorials are provided:

              • How to use the audio convert utility

              • How to use the audio record utility

              • How to use the audio player utility

              • Audio Input Stream Tutorial

              • Audio Output Stream Tutorial

              • Video Client Tutorials

              See Also

              Audio Client Overview

              Audio Input Stream Overview

              Audio Output Stream Overview

              Video Client Overview

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6EF9F8EA-AD61-4AEA-9457-FE645EED2E4D.dita --- a/Symbian3/SDK/Source/GUID-6EF9F8EA-AD61-4AEA-9457-FE645EED2E4D.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,21 +0,0 @@ - - - - - -Keypad -functions -

              This section describes the typical keypad functions. Some -application-specific functions may exist in addition to the typical keypad -functions.

              -
              Using -keypad functions in C++ applications

              For implementation information -on keypad functions, see Key -events.

              -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6F120C75-4D58-405C-8713-0626EE22E5DF.dita --- a/Symbian3/SDK/Source/GUID-6F120C75-4D58-405C-8713-0626EE22E5DF.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-6F120C75-4D58-405C-8713-0626EE22E5DF.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,39 +1,49 @@ - - - - - -Setting -the title pane touch observer -

              To set the title pane touch observer:

              -
                -

              1. Provide an observer -class that implements the MaknTitlePaneObserver interface.

                class MyTitlePaneObserver : public MAknTitlePaneObserver - { -public: - void HandleTitlePaneEventL( TInt aEventID ); - }; -
                2. -

              2. Get a pointer to the -title pane via the status pane pointer.

                iStatusPane = static_cast<CAknAppUi*>( CEikonEnv::Static()-> EikAppUi() )->StatusPane(); -if( !iStatusPane ) - { - User::Leave( KErrNotFound ); - } - -iTitlePane = ( CAknTitlePane* )iStatusPane->ControlL( TUid::Uid( EEikStatusPaneUidTitle ) ); -if( !iTitlePane ) - { - User::Leave( KErrNotFound ); - } -
                3. -

              3. Set the observer using -the SetTitlePaneObserver method.

                iTitlePane->SetTitlePaneObserver( this );
                4. -
              + + + + + +Setting +the title pane touch observer +

              To set the title pane touch observer:

              +
                +

              1. Provide an observer +class that implements the MaknTitlePaneObserver interface.

                class MyTitlePaneObserver : public MAknTitlePaneObserver + { +public: + void HandleTitlePaneEventL( TInt aEventID ); + }; + +{ + switch( TAknTitlePaneEvents ) + { + case EAknTitlePaneTapped: + ... + break; + + default + break; +}
                2. +

              2. Get a pointer to the +title pane via the status pane pointer.

                iStatusPane = static_cast<CAknAppUi*>( CEikonEnv::Static()-> EikAppUi() )->StatusPane(); +if( !iStatusPane ) + { + User::Leave( KErrNotFound ); + } + +iTitlePane = ( CAknTitlePane* )iStatusPane->ControlL( TUid::Uid( EEikStatusPaneUidTitle ) ); +if( !iTitlePane ) + { + User::Leave( KErrNotFound ); + } +
                3. +

              3. Set the observer using +the SetTitlePaneObserver method.

                iTitlePane->SetTitlePaneObserver( this );
                4. +
               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6F1ED7D0-5F41-4587-89AA-8DDE7AEC916F.dita --- a/Symbian3/SDK/Source/GUID-6F1ED7D0-5F41-4587-89AA-8DDE7AEC916F.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-6F1ED7D0-5F41-4587-89AA-8DDE7AEC916F.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,353 +1,373 @@ - - - - - - -What's -new in Symbian^3 -Symbian^3 introduces a lot of new features that enhance communication, -connectivity, multimedia, graphics, security and the overall usability of -Symbian devices. These features benefit operators, application developers -and device creators by making it easier to create feature-rich devices and -applications. - - - - - - -

              If you are moving from a older version of Symbian platform to Symbian^3, -see Porting applications -to Symbian^3.

              - - - - -Technology Domain -New Features - - - - -Data Communications -
                -

              • FreeWay or Three Plane Comms Architecture: The Symbian platform -now supports a new IP networking architecture. The new architecture significantly -improves data flow performance and makes it easier for third-party developers -to integrate new technologies, for example firewalls and hotspot authenticators. -It also implements automatic roaming between different access points, for -example WLAN and GPRS. For more information, see Goals -of the Comms Architecture.

                • -

              • One-Click Connectivity (OCC): The Symbian platform now provides -a new way of managing data connections on the Symbian platform. OCC builds -on the existing Application Level Roaming (ALR) solution. This feature makes -the user's interaction with "connecting" and "select access point" dialogs -significantly simple and easier.

                • -
               -               - -Device Connectivity -
                -

              • USB On-The-Go (OTG): The Symbian platform now supports the On-The-Go -(OTG) supplement to the USB 2.0 Specification, Revision 1.3. This enables -support for USB mass storage and audio devices on a Symbian device.

                • -

              • MTP Improvements: The Symbian MTP implementation now supports -Windows 7, MTP over Bluetooth, Ethernet RNDIS and also new content formats.

                • -

              • AVRCP (Audio/Video Remote Control Profile) v1.4 Support: A Symbian -device user can now see music track names and browse playlists directly from -the screen of a AVRCP v1.4 enabled Bluetooth headset or remote control.

                • -

              • Centralized AT-command Handling: The Symbian platform now enables -all AT commands to be handled using the same mechanism regardless of the connection -type. For more information, refer to the AT Extension Plug-in API.

                • -
               -               - -Device Management -
                -

              • Support for Open Mobile Alliance (OMA) Management Objects (MO): The -Symbian platform now supports OMA MO like Software Component Management Object -(SCOMO) v1.0, Device Capability Management Object (DCMO) v1.0 and Connectivity -Management Object (ConnMO). It also supports Nokia Standard Streaming MO. -Some enhancements have been made to Browser MO and Email MO.

                • -

              • Other Device Management Enhancements: The Symbian platform now -provides an improved device Lock with security and an enhanced firmware update -installation experience.

                • -
               -               - -Location -
                -

              • Landmark-based URL Parser: The Symbian platform now supports -a parser that converts between landmark objects and URLs. The parser supports -a URL format that is compliant with Ovi Maps. For more information, see CPosLandmarkParser.

                • -

              • New Management Object (MO) for A-GPS: The Symbian platform -now provides an enhancement to Secure User Plane Location (SUPL) now allows -the service provider to provide two access points for a SUPL server in the -MO. This improves the system stability because it acts as a fallback mechanism -in case one of the access points is unavailable.

                • -

              • Support for Application Processor Engine (APE) Centric Location -Architecture: Symbian devices can now use the new architecture based on -the APE that offers standardized session IDs on network privacy and classes -that use the SUPL. The architecture converges technology from OS, middleware -and application software layers.

                • -

              • Support for Location Based Services (LBS) SUPL Positioning Module -(PSY): The Symbian platform now enables the LBS SUPL PSY to allow GPS-enabled -devices to handle network-based SUPL location requests. This includes Cell -ID based positioning and assistance data exchange as part of SUPL v2.0.

                • -

              • Support for GPSCost5.0D and GPSCost4.0D GPS chipsets: The Symbian -platform now uses the APE-centric architecture to support GPSCost5.0D and -GPSCost4.0D chipsets. A new A-GPS Nokia Positioning Engine (NPE) integration -module replaces the OS LBS subsystem reference A-GPS version.

                • -

              • Support for LBS SUPL Radio Resource LCS Protocol (RRLP): The -Symbian platform now uses the APE-centric architecture to support NPE and -RRLP on GPS-enabled device.

                • -

              • SUPL 2.0 Trigger Support: The Symbian platform now provides -SUPL 2.0 trigger support that allows the requester to receive location updates -periodically, which is both network and device initiated.

                • -

              • Location-based Triggering Enhancements: The Symbian platform -now includes key enhancements that enable integration with an Context framework -to develop plug-ins and increase support for total and active triggers. An -enhanced, dedicated common gateway interface enables the client to provide -multiple CGIs to create a trigger, which is fired on successful matching with -at least one CGI.

                • -

              • Enhanced Location Acquisition API to support LocationKnownPositionArea.

                • -

              • Here and Now: The Symbian platform now includes Here and now -that offers easy-to-use Web services related to the user's current location. -Here and now allows the user to check the local weather and get other topical -information while on the move.

                • -
               -               - -Multimedia -
                -

              • Mobile TV DVB-H Receiver HAI: Mobile TV Receiver is a small -internal system but does so much more than traditional TV. It is broadcasted -in a multi-grounded environment with high speed by using low battery power -and low memory usage.

                • -

              • OpenMAX IL: OpenMAX IL is a low-level interface used in mobile -devices that allows the Multimedia Device Framework (MDF) to load, control, -connect and unload audio, video and imaging components..

                • -

              • Thin Adaptation of A3F DevSound: The A3F DevSound is one of -the key component in the Sound Device collection that provides access to the -hardware accelerator in audio technology. For more information, see A3F DevSound Component.

                • -

              • Image Processor library: The Image Processor is an independent -and high-level API and framework which is developed for mobile imaging. The -Image Processor has some pluggable advanced image editing libraries to perform -the Panoramic Stitching function and the Speed View function. For more information, -see Image Processor -Library.

                • -

              • Camera API Extensions: The Camera API is extended to support -the features such as background processing, continuous digital zooming, time -nudge image capturing and automatic aperture setting. For more information, -see Camera Library.

                • -

              • Camera Support for Video Encoding: The Camera supports mobile -device to capture video frames which are encoded in the H264 format. For more -information, see Using -the Encoded H264 Video Frames to Capture Video.

                • -

              • Video Playback from Non-user Interface Thread: Media Client -Video Display is a standalone library used by the Video Client library to -support video playback. For more information, see Media -Client Video Display Library.

                • -

              • Video Subtitle CRP: Displays artwork on a video window using -the Video Subtitle CRP component. The Subtitle Graphic library displays subtitles -artwork on the screen through its interaction with Client Process, Controller -Process and WServ Process. For more information, see Video -Subtitle CRP Component.

                • -

              • True Pause in Audio Playback: In the audio playback request -the true pause feature is implemented to stop the audio data at the physical -sound device without stopping the buffer traffic. For more information, see Pausing and Resuming -Audio Play.

                • -

              • Global Surface Updates: The Video Render component is extended -to support the global surface updates. For more information, see Global -Surface Updates.

                • -

              • Metadata Utility Library: The Metadata Utility library belongs -to the Metadata Utility Framework (MUF) component that provides fast metadata -access to audio, video and image media files.

                • -

              • UI Patterns or Thumbnails Enhancement: This is a Multimedia -specific pattern enhancement, which includes many UI (User Interface) features, -listed below:

                  -

                • Multiple customized Home Screens with 6 different widget enabled screens.

                  • -

                • Pinch zoom, kinetic scrolling and single-click features.

                  • -

                • Good screen view with a new UI theme, and renewed icons.

                  • -

                • Hardware acceleration with fast and responsive UI that creates new -transition effects.

                  • -

                • Multitasking with Teleport visual task swapper.

                  • -

                • Intelligent slide functionality for Hybrid touch and QWERTY slider -devices. Video Graphics Array (VGA) Touch supports for VGA QWERTY mono blocks.

                  • -

                • VGA Touch helps to control Music player.

                  • -
                • -

              • Mobile TV: Mobile TV uses DVB-H receiver to consume broadcast -digital mobile television. The Symbian platform provides fast and easy access -to all videos and TV media content. One key press opens videos and TV application -suite, and user scrolls and selects the desired video functionality. This -media experience is built with major components such as Videos and TV, video -player and Mobile TV. Videos and TV support high quality video up to 720 per -resolution at 12 Mbps and 30 frames per second.

                • -

              • Image Viewer Application: The Image Viewer application is used -when the client opens an image file for viewing. File Manager, Messaging, -Camcorder and Browser S60 components use the Image Viewer application. It -supports Extended ICL JPEG API, which enables a faster and less memory-consuming -way to rotate and zoom images.

                • -

              • FM Radio: The FM Radio application is used to listen FM radio -broadcast over the air. FM radio broadcast is a free service.

                • -

              • Video Sharing: Using the video sharing service, both call users -can start sharing their device live camera view or pre-recorded video clip -during a normal circuit switched (CS) voice call. The video sharing feature -allows the user to upgrade and downgrade their call with one-way video at -times of need. The video sharing application uses the Multimedia Comms Engine -API.

                • -
               -               - -Multimedia Applications -
                -

              • High-Definition Multimedia Interface (HDMI): The Symbian platform -now supports HDMI technology. HDMI is supported as an external accessory for -audio and video playback for a great television playback experience. It provides -improved data performance and is ideal for streaming high definition audio -and video. The 720p resolution is supported in still image and video viewing. -5+1 channel audio is also supported.

                • -

              • Home Music Widgets: The Symbian platform now provides music -information through Home Screen Music Widgets. The Home Music Widgets controls -from the Home Screen menu system enables to play and pause the playing track. -The Music Widget supports the Radio Player and includes the Music Suite Matrix -Menu. This menu is configured through XML and by default supports to launch -the functionality listed below:

                  -

                • The last played song

                  • -

                • The music collection view

                  • -

                • A music shop, or to open the FM radio

                  • -
                • -

              • Fusion Player Application: The Symbian platform now introduces -the Fusion Player, which replaces the existing Media Player and Video Center -applications. It enables access to both online video services and locally -stored videos. If DVB-H device is available, live TV viewing is also possible. -The main features supported by the Fusion player application are as follows:

                  -

                • To browse stored videos and to see metadata features of the video, -such as title, thumbnail DRM info, size or play-time.

                  • -

                • To check videos that are pre-installed with the device.

                  • -

                • To play stored video file in the device.

                  • -
                • -
               -               - -OS Base Services -
                -

              • Writable Data Paging (WDP): The Symbian platform now supports -WDP. This enables efficient use of memory and allows multiple applications -to run at the same time without physically adding more RAM to the hardware. -This leads to a more responsive system when switching between a number of -running applications.

                • -

              • Symmetric multiprocessor (SMP): The Symbian platform now supports -SMP for multi-core processors, such as the ARM Cortex A9. This allows device -integrators to prototype and prove ARM-based SMP platforms.

                • -

              • 64-bit file server: The Symbian platform now supports files -larger than 2 GB.

                • -
               -               - -Productivity -
                -

              • Enhanced Calendar UI Architecture: Calendar UI architecture -has changed to improve flexibility of calendar for regional, religious, custom-tailors -and xSP calendar service needs. Multiple storages are also supported. For -more information, see Calendar -Guide.

                • -

              • CalDAV Protocol: Calendar application now supports the CalDAV -Protocol, which is an open calendar synchronization standard contributed by -SUN Microsystems. This enables a user to access scheduling information on -remote servers.

                • -

              • Enhanced Contacts Application: The Contacts application in this -release includes the following changes:

                  -

                • Integration with social media.

                  • -

                • Support for Remote Contacts Lookup, for example, from post-installed -Mail for Exchange account.

                  • -

                • Virtual Phonebook API (supports getting access to the user’s own contact -card).

                  • -

                • Own contact card.

                  • -
                • -
               -               - -Runtimes -
                -

              • The Symbian platform now supports the Open Source based Java MIDP 2.1.

                • -

              • The Symbian platform now supports Browser Application v7.2 (with Web -Run Time 7.2) that includes the following features:

                  -

                • Browser Control

                  • -

                • Browser core features

                  • -

                • Browser Customization

                  • -

                • Browser plug-ins

                  • -

                • Browser with touch screen

                  • -

                • Content Download

                  • -

                • URI Schemes

                  • -

                • Display Resolution Optimizations

                  • -

                • Optical Finger Navigation (OFN)

                  • -

                • FlashLite 3.1

                  • -

                • Search Client Integration

                  • -

                • Expanding Language and Character Set Support

                  • -

                • Improved Security Prompting

                  • -

                • Updated Platform Service APIs

                  • -

                • Visual Task Swapper Support

                  • -

                • Performance Optimizations

                  • -

                • Multi-touch/pinch zooming

                  • -
                • -
               -               - -Security -The Symbian platform now provides an enhanced Security subsystem that -enables device creators to integrate hardware acceleration modules, which -improves the performance of cryptographic algorithms. This is particularly -valuable in intensive real-time use-cases, such as streaming audio or video -over a secure link, where bulk data needs to be encrypted and decrypted. - - -User Interface -
                -

              • ScreenPlay, also known as the New Graphics Architecture (NGA): This -new graphics architecture enables device creators to take advantage of improved -software performance, hardware acceleration and third party graphics engines. -It makes it possible to combine UI components, graphics and video to create -highly innovative UIs. For more information, see The -ScreenPlay Graphics Architecture.

                • -

              • Multi-Touch Support: The ScreenPlay version of the Window Server -has been extended to support multiple advanced pointers, with support for -proximity and pressure. The emulator now also supports multiple advanced pointers. -For more information, see Advanced -Pointers.

                • -

              • Enhanced Touch UI: The touch UI includes the following improvements:

                  -

                • Multi-page Home Screen enables the user to navigate between widgets -with a simple flick gesture

                  • -

                • Capacitive multi-touch events are supported.

                  • -

                • Tactile Feedback utilizes advanced haptics effects.

                  • -
                • -

              For more information about the new features in Graphics, see What's New in Graphics -in Symbian^3.

               -               - - -
               - - -New -C++ APIs in Symbian^3 -Porting -applications to Symbian^3 -Introduction -to Symbian^3 - - -               - + + + + + +What's new in Symbian^3Symbian^3 introduces a lot of new features that enhance +communication, connectivity, multimedia, graphics, security and the +overall usability of Symbian devices. These features benefit operators, +application developers and device creators by making it easier to +create feature-rich devices and applications. +

              If you are moving from a older version of Symbian platform to Symbian^3, +see Porting +applications to Symbian^3.

              + + + + +Technology Domain +New Features + + + + +Data Communications +
                +

              • FreeWay or Three Plane Comms Architecture: The Symbian +platform now supports a new IP networking architecture. The new architecture +significantly improves data flow performance and makes it easier for +third-party developers to integrate new technologies, for example +firewalls and hotspot authenticators. It also implements automatic +roaming between different access points, for example WLAN and GPRS. +For more information, see Goals of the Comms +Architecture.

                • +

              • One-Click Connectivity (OCC): The Symbian platform now +provides a new way of managing data connections on the Symbian platform. +OCC builds on the existing Application Level Roaming (ALR) solution. +This feature makes the user's interaction with "connecting" and "select +access point" dialogs significantly simple and easier. For more information, +see Extended +Connection Preferences.

                • +
               +               + +Device Connectivity +
                + + + +

              • MTP Device Services Extension Specification: The Symbian +MTP implementation now supports the MTP device services extension +to the Media Transfer Protocol (MTP). For more information, +see MTP Device Services Extension Specification.

                • +

              • AVRCP (Audio/Video Remote Control Profile) v1.4 Support: A Symbian device user can now see music track names and browse playlists +directly from the screen of a AVRCP v1.4 enabled Bluetooth headset +or remote control.

                • +

              • Centralized AT-command Handling: The Symbian platform +now enables all AT commands to be handled using the same mechanism +regardless of the connection type. For more information, refer to +the AT Extension Plug-in API.

                • +
               +               + +Device Management +
                +

              • Support for Open Mobile Alliance (OMA) Management Objects +(MO): The Symbian platform now supports OMA MO like Software Component +Management Object (SCOMO) v1.0, Device Capability Management Object +(DCMO) v1.0 and Connectivity Management Object (ConnMO). It also supports +Nokia Standard Streaming MO. Some enhancements have been made to Browser +MO and Email MO.

                • +

              • Other Device Management Enhancements: The Symbian platform +now provides an improved device Lock with security and an enhanced +firmware update installation experience.

                • +
               +               + +Location +
                +

              • Landmark-based URL Parser: The Symbian platform now +supports a parser that converts between landmark objects and URLs. +The parser supports a URL format that is compliant with Ovi Maps. +For more information, see CPosLandmarkParser.

                • +

              • New Management Object (MO) for A-GPS: The Symbian platform +now provides an enhancement to Secure User Plane Location (SUPL) now +allows the service provider to provide two access points for a SUPL +server in the MO. This improves the system stability because it acts +as a fallback mechanism in case one of the access points is unavailable.

                • +

              • Support for Application Processor Engine (APE) Centric Location +Architecture: Symbian devices can now use the new architecture +based on the APE that offers standardized session IDs on network privacy +and classes that use the SUPL. The architecture converges technology +from OS, middleware and application software layers.

                • +

              • Support for Location Based Services (LBS) SUPL Positioning +Module (PSY): The Symbian platform now enables the LBS SUPL PSY +to allow GPS-enabled devices to handle network-based SUPL location +requests. This includes Cell ID based positioning and assistance data +exchange as part of SUPL v2.0. .

                • +

              • Support for GPSCost5.0D and GPSCost4.0D GPS chipsets: The Symbian platform now uses the APE-centric architecture to support +GPSCost5.0D and GPSCost4.0D chipsets. A new A-GPS Nokia Positioning +Engine (NPE) integration module replaces the OS LBS subsystem reference +A-GPS version.

                • +

              • Support for LBS SUPL Radio Resource LCS Protocol (RRLP): The Symbian platform now uses the APE-centric architecture to support +NPE and RRLP on GPS-enabled device.

                • +

              • SUPL 2.0 Trigger Support: The Symbian platform now provides +SUPL 2.0 trigger support that allows the requester to receive location +updates periodically, which is both network and device initiated.

                • +

              • Location-based Triggering Enhancements: The Symbian +platform now includes key enhancements that enable integration with +an Context framework to develop plug-ins and increase support for +total and active triggers. An enhanced, dedicated common gateway interface +enables the client to provide multiple CGIs to create a trigger, which +is fired on successful matching with at least one CGI.

                • +

              • Enhanced Location Acquisition API to support LocationKnownPositionArea.

                • +

              • Here and Now: The Symbian platform now includes Here +and now that offers easy-to-use Web services related to the user's +current location. Here and now allows the user to check the local +weather and get other topical information while on the move.

                • +
               +               + +Multimedia +
                +

              • Mobile TV DVB-H Receiver HAI: Mobile TV Receiver is +a small internal system but does so much more than traditional TV. +It is broadcasted in a multi-grounded environment with high speed +by using low battery power and low memory usage. .

                • +

              • OpenMAX IL: OpenMAX IL is a low-level interface used +in mobile devices that allows the Multimedia Device Framework (MDF) +to load, control, connect and unload audio, video and imaging components. .

                • +

              • Thin Adaptation of A3F DevSound: The A3F DevSound is +one of the key component in the Sound Device collection that provides +access to the hardware accelerator in audio technology. For more information, +see A3F DevSound +Component.

                • +

              • Image Processor library: The Image Processor is an independent +and high-level API and framework which is developed for mobile imaging. +The Image Processor has some pluggable advanced image editing libraries +to perform the Panoramic Stitching function and the Speed View function. +For more information, see Image Processor Library.

                • +

              • Camera API Extensions: The Camera API is extended to +support the features such as background processing, continuous digital +zooming, time nudge image capturing and automatic aperture setting. +For more information, see Camera Library.

                • +

              • Camera Support for Video Encoding: The Camera supports +mobile device to capture video frames which are encoded in the H264 +format. For more information, see Using the Encoded +H264 Video Frames to Capture Video.

                • +

              • 3GP File Format Library: The 3GP Library component is +a Multimedia plug-in which supports for reading and writing 3GP, 3G2, +and MP4 files. The 3GP Library is also extended to support larger +3GP or MP4 files. .

                • +

              • Video Playback from Non-user Interface Thread: Media +Client Video Display is a standalone library used by the Video Client +library to support video playback. For more information, see Media Client Video +Display Library.

                • +

              • Video Subtitle CRP: Displays artwork on a video window +using the Video Subtitle CRP component. The Subtitle Graphic library +displays subtitles artwork on the screen through its interaction with +Client Process, Controller Process and WServ Process. For more information, +see Video Subtitle +CRP Component.

                • +

              • Dolby Digital Audio Support: The Symbian platform now +supports codecs that enable support for Dolby Digital Audio on Symbian +devices.

                • +

              • True Pause in Audio Playback: In the audio playback +request the true pause feature is implemented to stop the audio data +at the physical sound device without stopping the buffer traffic. +For more information, see Pausing and Resuming +Audio Play.

                • +

              • Global Surface Updates: The Video Render component is +extended to support the global surface updates. For more information, +see Global +Surface Updates.

                • +

              • Metadata Utility Library: The Metadata Utility library +belongs to the Metadata Utility Framework (MUF) component that provides +fast metadata access to audio, video and image media files. For more +information, see the Metadata Utility +Library section.

                • +

              • UI Patterns or Thumbnails Enhancement: This is a Multimedia +specific pattern enhancement, which includes many UI (User Interface) +features, listed below:

                  +

                • Multiple customized Home Screens with 6 different widget enabled +screens.

                  • +

                • Pinch zoom, kinetic scrolling and single-click features.

                  • +

                • Good screen view with a new UI theme, and renewed icons.

                  • +

                • Hardware acceleration with fast and responsive UI that creates +new transition effects.

                  • +

                • Multitasking with Teleport visual task swapper.

                  • +

                • Intelligent slide functionality for Hybrid touch and QWERTY +slider devices. Video Graphics Array (VGA) Touch supports for VGA +QWERTY mono blocks.

                  • +

                • VGA Touch helps to control Music player.

                  • +
                • +

              • Mobile TV: Mobile TV uses DVB-H receiver to consume +broadcast digital mobile television. The Symbian platform provides +fast and easy access to all videos and TV media content. One key press +opens videos and TV application suite, and user scrolls and selects +the desired video functionality. This media experience is built with +major components such as Videos and TV, video player and Mobile TV. +Videos and TV support high quality video up to 720 per resolution +at 12 Mbps and 30 frames per second.

                • +

              • Image Viewer Application: The Image Viewer application +is used when the client opens an image file for viewing. File Manager, +Messaging, Camcorder and Browser S60 components use the Image Viewer +application. It supports Extended ICL JPEG API, which enables a faster +and less memory-consuming way to rotate and zoom images.

                • +

              • FM Radio: The FM Radio application is used to listen +FM radio broadcast over the air. FM radio broadcast is a free service.

                • +

              • Video Sharing: Using the video sharing service, both +call users can start sharing their device live camera view or pre-recorded +video clip during a normal circuit switched (CS) voice call. The video +sharing feature allows the user to upgrade and downgrade their call +with one-way video at times of need. The video sharing application +uses the Multimedia Comms Engine API.

                • +
               +               + +Multimedia Applications +
                +

              • High-Definition Multimedia Interface (HDMI): The Symbian +platform now supports HDMI technology. HDMI is supported as an external +accessory for audio and video playback for a great television playback +experience. It provides improved data performance and is ideal for +streaming high definition audio and video. The 720p resolution is +supported in still image and video viewing. 5+1 channel audio is also +supported.

                • +

              • Home Music Widgets: The Symbian platform now provides +music information through Home Screen Music Widgets. The Home Music +Widgets controls from the Home Screen menu system enables to play +and pause the playing track. The Music Widget supports the Radio Player +and includes the Music Suite Matrix Menu. This menu is configured +through XML and by default supports to launch the functionality listed +below:

                  +

                • The last played song

                  • +

                • The music collection view

                  • +

                • A music shop, or to open the FM radio

                  • +
                • +

              • Fusion Player Application: The Symbian platform now +introduces the Fusion Player, which replaces the existing Media Player +and Video Center applications. It enables access to both online video +services and locally stored videos. If DVB-H device is available, +live TV viewing is also possible. The main features supported by the +Fusion player application are as follows:

                  +

                • To browse stored videos and to see metadata features of the +video, such as title, thumbnail DRM info, size or play-time.

                  • +

                • To check videos that are pre-installed with the device.

                  • +

                • To play stored video file in the device.

                  • +
                • +
               +               + +OS Base Services +
                +

              • Writable Data Paging (WDP): The Symbian platform now +supports WDP. This enables efficient use of memory and allows multiple +applications to run at the same time without physically adding more +RAM to the hardware. This leads to a more responsive system when switching +between a number of running applications. .

                • +

              • Symmetric multiprocessor (SMP): The Symbian platform +now supports SMP for multi-core processors, such as the ARM Cortex +A9. This allows device integrators to prototype and prove ARM-based +SMP platforms.

                • +

              • 64-bit file server: The Symbian platform now supports +files larger than 2 GB.

                • +
               +               + +Productivity +
                +

              • Nokia Messaging for Social Networks: Nokia Messaging +Social Networking service is a Nokia-hosted consumer service that +provides easy and affordable mobile access to popular social networking +communities.

                • +

              • Enhanced Calendar UI Architecture: Calendar UI architecture +has changed to improve flexibility of calendar for regional, religious, +custom-tailors and xSP calendar service needs. Multiple storages are +also supported. For more information, see Calendar Guide.

                • +

              • CalDAV Protocol: Calendar application now supports the +CalDAV Protocol, which is an open calendar synchronization standard +contributed by SUN Microsystems. This enables a user to access scheduling +information on remote servers.

                • +

              • Enhanced Contacts Application: The Contacts application +in this release includes the following changes:

                  +

                • Integration with social media.

                  • +

                • Support for Remote Contacts Lookup, for example, from post-installed +Mail for Exchange account.

                  • +

                • Virtual Phonebook API (supports getting access to the user’s +own contact card).

                  • +

                • Own contact card.

                  • +
                • +
               +               + +Runtimes +
                +

              • The Symbian platform now supports the Open Source based Java +MIDP 2.1.

                • +

              • The Symbian platform now supports Browser Application v7.2 +(with Web Run Time 7.2) that includes the following features:

                  +

                • Browser Control

                  • +

                • Browser core features

                  • +

                • Browser Customization

                  • +

                • Browser plug-ins

                  • +

                • Browser with touch screen

                  • +

                • Content Download

                  • +

                • URI Schemes

                  • +

                • Display Resolution Optimizations

                  • +

                • Optical Finger Navigation (OFN)

                  • +

                • FlashLite 3.1

                  • +

                • Search Client Integration

                  • +

                • Expanding Language and Character Set Support

                  • +

                • Improved Security Prompting

                  • +

                • Updated Platform Service APIs

                  • +

                • Visual Task Swapper Support

                  • +

                • Performance Optimizations

                  • +

                • Multi-touch/pinch zooming

                  • +
                • +
               +               + +Security +The Symbian platform now provides an enhanced Security subsystem +that enables device creators to integrate hardware acceleration modules, +which improves the performance of cryptographic algorithms. This is +particularly valuable in intensive real-time use-cases, such as streaming +audio or video over a secure link, where bulk data needs to be encrypted +and decrypted. + + +User Interface +
                +

              • ScreenPlay, also known as the New Graphics Architecture +(NGA): This new graphics architecture enables device creators +to take advantage of improved software performance, hardware acceleration +and third party graphics engines. It makes it possible to combine +UI components, graphics and video to create highly innovative UIs. +For more information, see The ScreenPlay Graphics +Architecture.

                • + + +

              • Multi-Touch Support: The ScreenPlay version of the Window +Server has been extended to support multiple advanced pointers, with +support for proximity and pressure. The emulator now also supports +multiple advanced pointers. For more information, see Advanced Pointers.

                • + +

              • Enhanced Touch UI: The touch UI includes the following +improvements:

                  +

                • Multi-page Home Screen enables the user to navigate between +widgets with a simple flick gesture

                  • +

                • Capacitive multi-touch events are supported.

                  • +

                • Tactile Feedback utilizes advanced haptics effects.

                  • +
                • +

              For more information about the new features in Graphics, see What's New in Graphics +in Symbian^3.

               +               + + +
               + +New +C++ APIs in Symbian^3 +Porting +applications to Symbian^3 +Introduction +to Symbian^3 + +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6FC62A2F-E27F-54A8-A97F-0F42426D1F63_d0e355771_href.png Binary file Symbian3/SDK/Source/GUID-6FC62A2F-E27F-54A8-A97F-0F42426D1F63_d0e355771_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6FC62A2F-E27F-54A8-A97F-0F42426D1F63_d0e361851_href.png Binary file Symbian3/SDK/Source/GUID-6FC62A2F-E27F-54A8-A97F-0F42426D1F63_d0e361851_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6FD4E7A4-D215-4CFB-BC7A-23065DE95C5C.dita --- a/Symbian3/SDK/Source/GUID-6FD4E7A4-D215-4CFB-BC7A-23065DE95C5C.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-6FD4E7A4-D215-4CFB-BC7A-23065DE95C5C.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,30 +1,30 @@ - - - - - -Add -a view to the control stack -

              To enable a view to receive key events, add a view to the control -stack using the following method. This method adds a control into the application -UI's control stack.

              Ensure that the view is constructed before adding -it to the control stack. IMPORT_C void AddToStackL( const MCoeView& aView, - CCoeControl *aControl, - TInt aPriority=ECoeStackPriorityDefault, - TInt aStackingFlags=ECoeStackFlagStandard );

              The -following code snippet shows adding a view to the control stack:

              /** -Add aControl to Cone's control stack with priority aPriority and behaviour aStackingFlags.\n -*/ -void CNewView::AddToStackL( CCoeControl* aControl, - TInt aPriority, - TInt aStackingFlags ) - { - iCCoeAppUi.AddToStackL( *this, aControl, aPriority, aStackingFlags); - }

              For more information on writing control stack, see How to write controls.

               + + + + + +Add +a view to the control stack +

              To enable a view to receive key events, add a view to the control +stack using the following method. This method adds a control into the application +UI's control stack.

              Ensure that the view is constructed before adding +it to the control stack. IMPORT_C void AddToStackL( const MCoeView& aView, + CCoeControl *aControl, + TInt aPriority=ECoeStackPriorityDefault, + TInt aStackingFlags=ECoeStackFlagStandard );

              The +following code snippet shows adding a view to the control stack:

              /** +Add aControl to Cone's control stack with priority aPriority and behaviour aStackingFlags.\n +*/ +void CNewView::AddToStackL( CCoeControl* aControl, + TInt aPriority, + TInt aStackingFlags ) + { + iCCoeAppUi.AddToStackL( *this, aControl, aPriority, aStackingFlags); + }

              For more information on writing control stack, see How to write controls.

                             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6FE79448-5052-46F9-A74E-A128CB367697_d0e52493_href.png Binary file Symbian3/SDK/Source/GUID-6FE79448-5052-46F9-A74E-A128CB367697_d0e52493_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6FE79448-5052-46F9-A74E-A128CB367697_d0e58588_href.png Binary file Symbian3/SDK/Source/GUID-6FE79448-5052-46F9-A74E-A128CB367697_d0e58588_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6FE79448-5052-46F9-A74E-A128CB367697_d0e67337_href.png Binary file Symbian3/SDK/Source/GUID-6FE79448-5052-46F9-A74E-A128CB367697_d0e67337_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6FE79448-5052-46F9-A74E-A128CB367697_d0e72538_href.png Binary file Symbian3/SDK/Source/GUID-6FE79448-5052-46F9-A74E-A128CB367697_d0e72538_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6FFEC753-4006-559C-B8E9-14940CFCD012_d0e176588_href.png Binary file Symbian3/SDK/Source/GUID-6FFEC753-4006-559C-B8E9-14940CFCD012_d0e176588_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-6FFEC753-4006-559C-B8E9-14940CFCD012_d0e183182_href.png Binary file Symbian3/SDK/Source/GUID-6FFEC753-4006-559C-B8E9-14940CFCD012_d0e183182_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-700CD2E2-DBB7-40BD-BC6D-9BC79C5A0BBF_d0e4528_href.png Binary file Symbian3/SDK/Source/GUID-700CD2E2-DBB7-40BD-BC6D-9BC79C5A0BBF_d0e4528_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-700CD2E2-DBB7-40BD-BC6D-9BC79C5A0BBF_d0e5803_href.png Binary file Symbian3/SDK/Source/GUID-700CD2E2-DBB7-40BD-BC6D-9BC79C5A0BBF_d0e5803_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-70483E81-311F-5247-9F39-3940F20C0EB1_d0e238861_href.png Binary file Symbian3/SDK/Source/GUID-70483E81-311F-5247-9F39-3940F20C0EB1_d0e238861_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-70483E81-311F-5247-9F39-3940F20C0EB1_d0e242598_href.png Binary file Symbian3/SDK/Source/GUID-70483E81-311F-5247-9F39-3940F20C0EB1_d0e242598_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-706263D6-AAE2-40E2-B0B4-D12E253F70A8_d0e70764_href.png Binary file Symbian3/SDK/Source/GUID-706263D6-AAE2-40E2-B0B4-D12E253F70A8_d0e70764_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-706263D6-AAE2-40E2-B0B4-D12E253F70A8_d0e75798_href.png Binary file Symbian3/SDK/Source/GUID-706263D6-AAE2-40E2-B0B4-D12E253F70A8_d0e75798_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7082D222-72B8-580F-B4FD-D2934F1B3800-GENID-1-8-1-18-1-1-4-1-12-1.dita --- a/Symbian3/SDK/Source/GUID-7082D222-72B8-580F-B4FD-D2934F1B3800-GENID-1-8-1-18-1-1-4-1-12-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,43 +0,0 @@ - - - - - -S60 -Platform: Audio Streaming Example This example helps the user in understanding the available audio -formats supported and how to do audio recording using Multimedia Framework. -
              Description

              This C++ example application demonstrates -the use of Audio Streaming API, which provides functionality for recording -audio stream into a buffer, and for playback of the audio buffer. Besides -playing, recording, and stopping the audio stream, the recorded audio stream -can be saved into a file, to be played again later. The package includes PCM -and AMR-NB encoded sample files. Audio Streaming API is part of the Symbian -Multimedia Framework (MMF). The updated example has been tested to support -S60 5th Edition and touch UI. Important classes: CMdaAudioInputStream, CMdaAudioOutputStream, -MMdaAudioInputStreamCallback, MMdaAudioOutputStreamCallback..

              For more -information, click on this link : Audio Streaming Example.

              -
              Download

              Click on the following link to download -the example: MMFRec.zip file

              Click: browse to view the example code.

              -
              Building and -configuring

              To build the example:

              You can build the example -from your IDE or the command line.

              If you use an IDE, import the bld.inf file -of the example into your IDE, and use the build command of the IDE.

              If -you use the command line, open a command prompt, and set the current directory -to the source code directory of the example. You can then build the example -with the SBSv1 build tools with the following commands:

              bldmake -bldfiles

              abld build

              How to use bldmake and How to use abld describe -how to use the SBSv1 build tools.

              For the emulator, the example builds -an executable called mmfrec.exe.exe in the epoc32\release\winscw\<udeb -or urel>\ folder.

              -
              Running the -example

              When running the example, the user is presented with various -menu options that are self explanatory.

              -
              See also:

              Audio -Client Overview

              -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7082D222-72B8-580F-B4FD-D2934F1B3800-GENID-1-8-1-18-1-1-5-1-7-1-6-1-4-1.dita --- a/Symbian3/SDK/Source/GUID-7082D222-72B8-580F-B4FD-D2934F1B3800-GENID-1-8-1-18-1-1-5-1-7-1-6-1-4-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,43 +0,0 @@ - - - - - -S60 -Platform: Audio Streaming Example This example helps the user in understanding the available audio -formats supported and how to do audio recording using Multimedia Framework. -
              Description

              This C++ example application demonstrates -the use of Audio Streaming API, which provides functionality for recording -audio stream into a buffer, and for playback of the audio buffer. Besides -playing, recording, and stopping the audio stream, the recorded audio stream -can be saved into a file, to be played again later. The package includes PCM -and AMR-NB encoded sample files. Audio Streaming API is part of the Symbian -Multimedia Framework (MMF). The updated example has been tested to support -S60 5th Edition and touch UI. Important classes: CMdaAudioInputStream, CMdaAudioOutputStream, -MMdaAudioInputStreamCallback, MMdaAudioOutputStreamCallback..

              For more -information, click on this link : Audio Streaming Example.

              -
              Download

              Click on the following link to download -the example: MMFRec.zip file

              Click: browse to view the example code.

              -
              Building and -configuring

              To build the example:

              You can build the example -from your IDE or the command line.

              If you use an IDE, import the bld.inf file -of the example into your IDE, and use the build command of the IDE.

              If -you use the command line, open a command prompt, and set the current directory -to the source code directory of the example. You can then build the example -with the SBSv1 build tools with the following commands:

              bldmake -bldfiles

              abld build

              How to use bldmake and How to use abld describe -how to use the SBSv1 build tools.

              For the emulator, the example builds -an executable called mmfrec.exe.exe in the epoc32\release\winscw\<udeb -or urel>\ folder.

              -
              Running the -example

              When running the example, the user is presented with various -menu options that are self explanatory.

              -
              See also:

              Audio -Client Overview

              -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-708FC2C8-19BB-5EFC-A8CD-B0E9E96A5409-master.png Binary file Symbian3/SDK/Source/GUID-708FC2C8-19BB-5EFC-A8CD-B0E9E96A5409-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-708FC2C8-19BB-5EFC-A8CD-B0E9E96A5409_d0e387120_href.png Binary file Symbian3/SDK/Source/GUID-708FC2C8-19BB-5EFC-A8CD-B0E9E96A5409_d0e387120_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-70E1117B-17F0-5CF4-A5D0-35D3BEBB0FEA.dita --- a/Symbian3/SDK/Source/GUID-70E1117B-17F0-5CF4-A5D0-35D3BEBB0FEA.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-70E1117B-17F0-5CF4-A5D0-35D3BEBB0FEA.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,60 +1,60 @@ - - - - - -Position -Area Data ClassesThis document describes the basic and extended position area data -classes that contain information about the accuracy of the position returned -to an application when it calls RPositioner::GetLastKnownPositionArea(). -

              LBS maintains a cache of previously calculated position fixes. If an application -calls RPositioner::GetLastKnownLocation(), LBS returns -the most recently calculated position. If an application calls RPositioner::GetLastKnownPositionArea(), -LBS returns the position fix that is the best match for the current location -of the mobile device. The current location of the mobile device is estimated -from data received from the network.

              -

              The Location Acquisition API defines a set of position area data classes -(figure 1). A client application passes an object of one of these classes -as a parameter when it calls RPositioner::GetLastKnownPositionArea(). -The position area data classes are defined in LbsAreaInfo.h.

              - - Figure 1. Position Area Data Classes. - - -

              A brief description of the classes follows. Follow the links to more detailed -reference documentation.

              -
                -

              • TPositionAreaInfoBase is -the base class of the position area data classes. Applications create an object -of one of the derived classes.

                • -

              • TPositionAreaInfo contains -basic information about the accuracy of a returned position. Its defines an -enumerated type TPositionAreaInfo::_TArea that defines -an estimate of how closely the current device position matches the returned -position. The position accuracy estimate can be from country level down to -street level, depending on how much information is available from the network.

                • -

              • TPositionAreaExtendedInfo extends TPositionAreaInfo to -provide details about how the accuracy estimate of the returned position was -calculated.

                An accuracy estimate can be obtained from the network -as some combination of the following:

                  -

                • Mobile Country Code

                  • -

                • Mobile Network Code

                  • -

                • Location Area Code

                  • -

                • Cell ID

                  • -

                LBS uses combinations of the above to derive the accuracy estimate -returned from TPositionAreaInfo::Area(). Your application -can find what types of data were used to calculate the accuracy estimate by -passing an object of class TPositionAreaExtendedInfo to RPositioner::GetLastKnownLocationArea() and -then using the methods shown in figure 1 to check for code and ID matches.

                • -
              -               - -How to Get -Location Information + + + + + +Position +Area Data ClassesThis document describes the basic and extended position area data +classes that contain information about the accuracy of the position returned +to an application when it calls RPositioner::GetLastKnownPositionArea(). +

              LBS maintains a cache of previously calculated position fixes. If an application +calls RPositioner::GetLastKnownLocation(), LBS returns +the most recently calculated position. If an application calls RPositioner::GetLastKnownPositionArea(), +LBS returns the position fix that is the best match for the current location +of the mobile device. The current location of the mobile device is estimated +from data received from the network.

              +

              The Location Acquisition API defines a set of position area data classes +(figure 1). A client application passes an object of one of these classes +as a parameter when it calls RPositioner::GetLastKnownPositionArea(). +The position area data classes are defined in LbsAreaInfo.h.

              + + Figure 1. Position Area Data Classes. + + +

              A brief description of the classes follows. Follow the links to more detailed +reference documentation.

              +
                +

              • TPositionAreaInfoBase is +the base class of the position area data classes. Applications create an object +of one of the derived classes.

                • +

              • TPositionAreaInfo contains +basic information about the accuracy of a returned position. Its defines an +enumerated type TPositionAreaInfo::_TArea that defines +an estimate of how closely the current device position matches the returned +position. The position accuracy estimate can be from country level down to +street level, depending on how much information is available from the network.

                • +

              • TPositionAreaExtendedInfo extends TPositionAreaInfo to +provide details about how the accuracy estimate of the returned position was +calculated.

                An accuracy estimate can be obtained from the network +as some combination of the following:

                  +

                • Mobile Country Code

                  • +

                • Mobile Network Code

                  • +

                • Location Area Code

                  • +

                • Cell ID

                  • +

                LBS uses combinations of the above to derive the accuracy estimate +returned from TPositionAreaInfo::Area(). Your application +can find what types of data were used to calculate the accuracy estimate by +passing an object of class TPositionAreaExtendedInfo to RPositioner::GetLastKnownLocationArea() and +then using the methods shown in figure 1 to check for code and ID matches.

                • +
              +               + +How to Get +Location Information               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-70E92884-004F-43B5-B740-B0C95E8E401C-master.png Binary file Symbian3/SDK/Source/GUID-70E92884-004F-43B5-B740-B0C95E8E401C-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-70E92884-004F-43B5-B740-B0C95E8E401C_d0e57062_href.png Binary file Symbian3/SDK/Source/GUID-70E92884-004F-43B5-B740-B0C95E8E401C_d0e57062_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-70E92884-004F-43B5-B740-B0C95E8E401C_d0e60390_href.png Binary file Symbian3/SDK/Source/GUID-70E92884-004F-43B5-B740-B0C95E8E401C_d0e60390_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-70E92884-004F-43B5-B740-B0C95E8E401C_d0e62839_href.png Binary file Symbian3/SDK/Source/GUID-70E92884-004F-43B5-B740-B0C95E8E401C_d0e62839_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-70E92884-004F-43B5-B740-B0C95E8E401C_d0e67952_href.png Binary file Symbian3/SDK/Source/GUID-70E92884-004F-43B5-B740-B0C95E8E401C_d0e67952_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-70E92884-004F-43B5-B740-B0C95E8E401C_d0e68178_href.png Binary file Symbian3/SDK/Source/GUID-70E92884-004F-43B5-B740-B0C95E8E401C_d0e68178_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-70E92884-004F-43B5-B740-B0C95E8E401C_d0e68784_href.png Binary file Symbian3/SDK/Source/GUID-70E92884-004F-43B5-B740-B0C95E8E401C_d0e68784_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-70E92884-004F-43B5-B740-B0C95E8E401C_d0e73929_href.png Binary file Symbian3/SDK/Source/GUID-70E92884-004F-43B5-B740-B0C95E8E401C_d0e73929_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-70FC2D13-493D-433F-9CFB-ACF9F512513F-master.png Binary file Symbian3/SDK/Source/GUID-70FC2D13-493D-433F-9CFB-ACF9F512513F-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-70FC2D13-493D-433F-9CFB-ACF9F512513F_d0e69973_href.png Binary file Symbian3/SDK/Source/GUID-70FC2D13-493D-433F-9CFB-ACF9F512513F_d0e69973_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-70FC2D13-493D-433F-9CFB-ACF9F512513F_d0e75057_href.png Binary file Symbian3/SDK/Source/GUID-70FC2D13-493D-433F-9CFB-ACF9F512513F_d0e75057_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-712DF59D-FAE1-592E-82A6-4E323676F5B8.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-712DF59D-FAE1-592E-82A6-4E323676F5B8.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,153 @@ + + + + + +Symmetric +ciphers -- guide +
                +

              • What are symmetric ciphers?

                • +

              • Block and stream ciphers

                • +

              • Types of symmetric algorithms supported

                • +

              • Base classes and their derived classes

                • +
              +
              What are symmetric +ciphers?

              Symmetric algorithms are much faster than asymmetric +algorithms so are used to encrypt and decrypt large amounts of data. In an +informal setting, symmetric ciphers can be thought of as a mapping of some +plaintext to ciphertext, via some well-known transformation function, dependent +on a single secret key. Symmetric algorithms have the property that if a message +is encrypted under a given key, it can only be decrypted using the same key:

              + The diagram above shows the encryption and decryption process using: +a symmetric algorithm; a plaintext message, M; a symmetric key, K; and the +ciphertext, K(M). + +

              So it provides secrecy and also some kind of authentication. If +Alice encrypts a secret using a key known only to her, then only she can access +the secrets.

              It can also be used for communication: if Alice shares +a key with Bob (and only Bob), then she can encrypt her messages with that +key and send it to Bob, and only Bob can decrypt them. In this case the key +is a 'shared secret' enabling private communications.

              There are two +basic types of symmetric ciphers: block +ciphers and stream ciphers.

              +
              Block and stream +ciphers
                +

              • Stream ciphers are +essentially functions that are initialized with a key, and output a stream +of pseudorandom bits, this 'keystream' is typically XOR-ed with the plaintext +to generate the ciphertext. So they encrypt a bit of plaintext at a time. +They map an n -bit stream of plaintext to a n -bit stream of +ciphertext.

                • +

              • Block ciphers encrypt +several bits at once in a fixed-size block. That is, they map m n -bit +blocks of plaintext to m n -bit blocks of ciphertext. The cipher +and its mode of operation define the block size: the plaintext is split up +into appropriately-sized blocks and each block is fed into the cipher.

                There +are two issues here that don't occur with stream ciphers:

                  +

                • padding: the +total size of the input has to be a multiple of the block size, so the plaintext +usually has to be padded to fit (see the class CPadding). +Optionally, instead of padding out a plaintext message to fit in a block, +block ciphers allow buffering of partial input blocks until the remainder +of the block is given as input. (see How +does buffering work within the symmetric cipher framework? and PKCS#7).

                  • +

                • combining blocks: +if you just encrypt each plaintext block with the cipher and then concatenate +the ciphertext blocks, then an attacker who knows something about the structure +can switch the order of the ciphertext blocks to alter the meaning of the +message. For example, if the plaintext includes instructions like 'pay £XXX +to account holder ABC, reference number YYY', then an attacker could replace +the encryption of XXX with some of the encryption of YYY. This leads to other +techniques for combining blocks, called modes, where, for example, the output +of the last block is fed into the input for the next one. So, the output is +not just a function of that plaintext block and key, but is a function of +that plaintext block, the key, and all preceding ciphertext blocks (see Symmetric +Modes).

                  • +
                • +

              Both stream ciphers and block ciphers are provided by the API with +a similar interface. Block ciphers usually need padding for non completed +blocks. The API allows the user to choose the padding to be added at the end +of the last encrypted block or to be checked and removed from the last decrypted +block.

              +
              Types of symmetric +algorithms supported

              The following symmetric algorithms are supported:

              + + + +Symmetric algorithm +Type +Specified in: + + + + +

              AES (Advanced Encryption Standard)

              +

              Block cipher

              +

              FIPS-197

              +               + +

              DES (Data Encryption Standard)

              +

              Block cipher

              +

              FIPS 46-3

              +               + +

              3DES (Triple Data Encryption Standard)

              +

              Block cipher

              +

              FIPS 46-3

              +               + +

              RC2-128

              +

              Block cipher

              +

              RFC +2268

              +               + +

              ARC4 ('alleged' RC4)

              +

              Stream cipher

              +

              the internet and a posting to sci.crypt in 1994.

              +               + + +
              +
              Base classes +and their derived classes

              The symmetric cipher API is used by Networking +(TLS/IPSec).

              CSymmetricCipher is the abstract +base class that allows a client to use the supported symmetric algorithms +listed above. It allows clients to encrypt and decrypt without having to know +anything about which encryption algorithm is currently in use.

              The +PKCS5 API (the TPKCS5KDF class, also see Password +Based Encryption) offers Key Derivation Support that allows the derivation +of deterministic arbitrary length byte streams from an input string. The output +byte stream is generated using multiple iterations of a SHA-1 message digest +(CSHA1) and is suitable for use as a cryptographic symmetric +key.

              The diagrams below show the main classes used in symmetric cipher +framework. Blue dotted arrows indicate that a class is contained or used by +another class. The arrows are labelled with the variable(s) through which +the pointed class is accessible. The colour of the boxes indicates the type +of Symbian class, i.e., M, C, R or T class. +For detailed information on each component see the Cryptography API Reference +material.

              CSymmetricCipher and derived classes

              +The inheritance diagram shows the <codeph>CSymmetricCipher</codeph> abstract +base class and its derived abstract classes <codeph>CBufferedTransformation</codeph> and <codeph>CStreamCipher</codeph> used +for block and stream ciphers respectively. Also shown are the following derived +classes: <codeph>CBufferedDecryptor</codeph>, <codeph>CBufferedEncryptor</codeph>, <codeph>CARC4</codeph>, +and <codeph>CNullCipher</codeph>. + +

              CBlockTransformation and derived classes

              +The inheritance diagram above shows the <xref href="GUID-CFDA5321-EE13-3203-8DED-71E69D4469BD.dita"><apiname>CBlockTransformation</apiname></xref> abstract +base class used for block ciphers. Also shown are the following derived classes: <xref href="GUID-436C3EBE-FC60-3760-A3BA-D8DF8FA5B8AF.dita"><apiname>CBlockChainingMode</apiname></xref>, <xref href="GUID-C65A1F55-A8D2-3393-8DC1-35656017E2B8.dita"><apiname>CModeCBCEncryptor</apiname></xref>, <xref href="GUID-7D5FBD2C-83A0-351A-96B3-C5C54FE525E6.dita"><apiname>CModeCBCDecryptor</apiname></xref>, <xref href="GUID-1C18ED2F-085F-3C3E-A93E-5FD37461E440.dita"><apiname>CDES</apiname></xref>, <xref href="GUID-E7401D77-AD0E-3B8F-A7CC-23ADA5151DB6.dita"><apiname>CDESEncryptor</apiname></xref>, <xref href="GUID-249270AC-907B-3E46-AFDB-131FDC6F612A.dita"><apiname>CDESDecryptor</apiname></xref>, <xref href="GUID-90A671B0-756E-3773-8429-6441D1594F4B.dita"><apiname>C3DES</apiname></xref>, <xref href="GUID-B931DBB9-4484-33FD-9E94-6F256ABD5C68.dita"><apiname>C3DESEncryptor</apiname></xref>, <xref href="GUID-C693C22D-04C5-3C9E-8605-0EA90F723AF3.dita"><apiname>C3DESDecryptor</apiname></xref>, <xref href="GUID-BEE18CDE-CFB6-3116-9FAE-046780D4D006.dita"><apiname>CRC2</apiname></xref>, <xref href="GUID-19F20C86-5722-3A35-B17D-3830D18CC7FC.dita"><apiname>CRC2Encryptor</apiname></xref>, <xref href="GUID-E6FD8DF9-258B-39BC-8C39-ABF7434A29B5.dita"><apiname>CRC2Decryptor</apiname></xref>, <xref href="GUID-B0AEE24A-91A6-335E-AD64-C9DDCC1F81A9.dita"><apiname>CRijndael</apiname></xref>, <xref href="GUID-AE1A9AC0-DB79-3C62-AA23-896812F25F14.dita"><apiname>CAESEncryptor</apiname></xref>, and <xref href="GUID-51666543-0256-3E0D-BF5F-8716753C5921.dita"><apiname>CAESDecryptor</apiname></xref>. + +

              CPadding and derived +classes

              +Above is an inheritance diagram showing the CPadding abstract base +class used with block ciphers. Also shown are the following derived classes: <xref href="GUID-B7090C61-ECC7-3E8A-8D19-75C9170B0135.dita"><apiname>CPaddingPKCS7</apiname></xref>, <xref href="GUID-3150ECC9-CF8E-3890-91CD-87F5EBCE550E.dita"><apiname>CPaddingPKCS1Encryption</apiname></xref>, <xref href="GUID-F845CB30-7ABE-3EB6-B1B9-C72581897D0C.dita"><apiname>CRSAPKCS1v15Encryptor</apiname></xref>, <xref href="GUID-57C40DCA-8340-38B5-9777-2863C8F88B59.dita"><apiname>CPaddingNone</apiname></xref>, <xref href="GUID-723F64D1-01C5-3A03-B987-0FB862EE8EDE.dita"><apiname>CPaddingPKCS1Signature</apiname></xref>, +and <xref href="GUID-CC2347BE-3272-3DDF-8BDD-B44F5C0026B3.dita"><apiname>CPaddingSSLv3</apiname></xref> + +
              +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-715E0EA4-8B3D-5DDF-B773-922E367B114F.dita --- a/Symbian3/SDK/Source/GUID-715E0EA4-8B3D-5DDF-B773-922E367B114F.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-715E0EA4-8B3D-5DDF-B773-922E367B114F.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,14 +1,14 @@ - - - - - -Audio Input Streaming Overview

              This document provides an overview of Audio Input Streaming.

              Purpose

              Audio Input Streaming is the interface to streaming sampled audio data from the low level audio controller part of the Multimedia Framework (MMF).

              Audio Input Streaming Library Details

              The DLL that provides the functionality and the library to which your code must link is identified below.

              DLL LIB Short Description

              mediaclientaudioinputstream.dll

              mediaclientaudioinputstream.lib

              These files are used for implementing Audio Input Streaming.

              Architectural Relationship

              How the Audio Input Streaming classes interact with other components of MMF is shown below:

              - Audio input streaming overview -
              Description

              Streamed audio data is sent and received incrementally. This means:

              • sound clips sent to the low level audio controller (audio play) can be sent as they arrive rather than waiting until the entire clip is received.

                The user of the API should maintain the data fragments in a queue before sending them to the server. If the user attempts to send data faster than the server can receive it, the excess data fragments are maintained in another client side queue (invisible to the user), whose elements are references to the buffers passed to it. The server notifies the client using a callback each time it has received a data fragment. This indicates to the client that the data fragment can be deleted.

              • sound clips that are being captured by the low level audio controller (audio record) can be read incrementally without having to wait until audio capture is complete.

                The low level audio controller maintains the received buffers where it can place the audio data that is being captured. The client uses a read function to read the received data into destination descriptors.

              The client is also notified (for audio play and record) when the stream is opened and available for use (opening takes place asynchronously), and when the stream is closed.

              This API can only be used to stream audio data, with the data being stored or sourced from a descriptor. Client applications must ensure that the data is in 16 bit PCM format as this is the only format supported. The API does not support mixing. A priority mechanism is used to control access to the sound device by more than one client.

              Key Audio Input Streaming Classes

              The functionality provided by Audio Input Streaming is contained within the CMdaAudioInputStream class.

              Using Audio Input Streaming

              Clients can use Audio Input Streaming to:

              • Open, set audio and mobile equipment properties, read from and close the audio stream.

              See Also

              Audio Input Streaming Tutorial

              \ No newline at end of file + + + + + +Audio Input Streaming Overview

              This document provides an overview of Audio Input Streaming.

              Purpose

              Audio Input Streaming is the interface to streaming sampled audio data from the low level audio controller part of the Multimedia Framework (MMF).

              Audio Input Streaming Library Details

              The DLL that provides the functionality and the library to which your code must link is identified below.

              DLL LIB Short Description

              mediaclientaudioinputstream.dll

              mediaclientaudioinputstream.lib

              These files are used for implementing Audio Input Streaming.

              Architectural Relationship

              How the Audio Input Streaming classes interact with other components of MMF is shown below:

              + Audio input streaming overview +
              Description

              Streamed audio data is sent and received incrementally. This means:

              • sound clips sent to the low level audio controller (audio play) can be sent as they arrive rather than waiting until the entire clip is received.

                The user of the API should maintain the data fragments in a queue before sending them to the server. If the user attempts to send data faster than the server can receive it, the excess data fragments are maintained in another client side queue (invisible to the user), whose elements are references to the buffers passed to it. The server notifies the client using a callback each time it has received a data fragment. This indicates to the client that the data fragment can be deleted.

              • sound clips that are being captured by the low level audio controller (audio record) can be read incrementally without having to wait until audio capture is complete.

                The low level audio controller maintains the received buffers where it can place the audio data that is being captured. The client uses a read function to read the received data into destination descriptors.

              The client is also notified (for audio play and record) when the stream is opened and available for use (opening takes place asynchronously), and when the stream is closed.

              This API can only be used to stream audio data, with the data being stored or sourced from a descriptor. Client applications must ensure that the data is in 16 bit PCM format as this is the only format supported. The API does not support mixing. A priority mechanism is used to control access to the sound device by more than one client.

              Key Audio Input Streaming Classes

              The functionality provided by Audio Input Streaming is contained within the CMdaAudioInputStream class.

              Using Audio Input Streaming

              Clients can use Audio Input Streaming to:

              • Open, set audio and mobile equipment properties, read from and close the audio stream.

              See Also

              Audio Input Streaming Tutorial

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-71B31715-3B6A-50F0-86C1-8F7F76985802_d0e169108_href.jpg Binary file Symbian3/SDK/Source/GUID-71B31715-3B6A-50F0-86C1-8F7F76985802_d0e169108_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-71B31715-3B6A-50F0-86C1-8F7F76985802_d0e175709_href.jpg Binary file Symbian3/SDK/Source/GUID-71B31715-3B6A-50F0-86C1-8F7F76985802_d0e175709_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-71DADA82-3ABC-52D2-8360-33FAEB2E5DE9.dita --- a/Symbian3/SDK/Source/GUID-71DADA82-3ABC-52D2-8360-33FAEB2E5DE9.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-71DADA82-3ABC-52D2-8360-33FAEB2E5DE9.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,14 +1,14 @@ - - - - - -The Font and Bitmap Server OverviewThe Font and Bitmap Server (FBServ) provides a memory efficient way of using bitmaps and fonts. It stores a single instance of each bitmap in either a shared heap or in eXecute In Place (XIP) ROM and provides clients with read and (when appropriate) write access.

              RAM-based fonts and bitmaps are reference counted and retained in RAM while they are being used. When they are no longer required they are automatically deleted.

              Key terms
              Bitmap

              A two-dimensional (2D) buffer (in memory) that contains the color values for individual pixels and is encapsulated by the CFbsBitmap class.

              Extended bitmap

              A bitmap that contains data compressed using proprietary formats.

              Raster image

              A data structure representing a rectangular grid of pixels. Scaling raster images usually leads to a loss of quality.

              Vector image

              The use of geometrical primitives such as points, lines, curves and polygons to represent an image. Vector images can be scaled without loss of quality.

              Rasterization

              The process of converting vector image drawing instructions into a raster image that can be displayed on the screen.

              Scan line

              A row of pixels in a raster image. This use of the term is derived from its original use in a raster scanning pattern, such as a video line on the cathode ray tube (CRT) display of a television.

              For font-related terms, see Font and Text Services Collection Overview.

              Architectural relationships

              The Font and Bitmap Server is tightly integrated with the BitGDI and Window Server components. It provides client-side classes for fonts, bitmaps and the typeface store.

              In use the Font and Bitmap Server is largely transparent. When a client of the Window Server opens a Window Server session, that session silently creates an RFbsSession and stores it in Thread Local Storage (TLS). Client-side font and bitmap classes such as CFbsFont and CFbsBitmap automatically find the session in TLS when they are constructed. (These are client-side objects that refer to objects in the server. Because they are heap-based classes, they have names beginning with C.)

              The Font and Bitmap Server contains the font store, which is a separate DLL provided by the Font Store (FntStore) component. Client-side access to the font store is through CFbsTypefaceStore.

              Description

              The Font and Bitmap Server is a singleton process that owns fonts and bitmaps. CFbsFont and CFbsBitmap objects are actually client-side handles to the font and bitmap objects, which are stored on a globally accessible heap while they are in use. Bitmap data is stored separately in a globally accessible disconnected chunk.

              When the reference count of clients using a font or bitmap that is resident in RAM falls to zero, the server can delete it and free the memory. XIP ROM based bitmaps are accessed in place, not copied into RAM.

              Open fonts, which are stored in font files as vector data, must be rasterized into the Font and Bitmap Server's shared heap. Rasterizers are plug-ins to the Font Store component. There is a performance overhead to rasterizing an open font and a memory overhead for storing it.

              API summary

              The Font and Bitmap Server presents a conventional client API through RFbsSession, which represents the handle to a server-side session. The classes CFbsFont and CFbsBitmap are client-side representations of font and bitmap classes.

              • The CFbsFont class represents fonts managed by the Font and Bitmap Server, both bitmap fonts and OpenType fonts.

              • The CFbsBitmap class represents bitmaps managed by the Font and Bitmap Server, both RAM and XIP ROM-based bitmaps. For RAM-based bitmaps, this class provides facilities for creating, loading, saving, and resizing bitmaps. RAM-based bitmaps are commonly loaded from a multi-bitmap file (.mbm) file or created as off-screen bitmaps, and then blitted to a window. For XIP ROM-based bitmaps, CFbsBitmap provides facilities for accessing the data.

              The Font and Bitmap Server is unusual in that the RFbsSession is stored in client-side thread local storage (TLS). The constructors for CFbsFont and CFbsBitmap find this session handle automatically: the client program does not have to pass it as a parameter. Therefore, to most client programs, the client/server nature of using fonts and bitmaps is hidden from the API.

              The RFbsSession is created for clients by the Window Server’s client-side API when a Window Server session, RWsSession, is constructed. A Window Server client is therefore also a client of the Font and Bitmap Server.

              When a client calls, for example, the CWindowGc::DrawBitmap() function, the handle number of the bitmap is passed to the Window Server through inter-process communication (IPC). Like all CWindowGc drawing commands, the handle number is stored in a client-side command buffer, which by default is flushed to the server side only when it is full. Once flushed to the server-side, the command buffer is processed by the Window Server rendering loop. Consider the scenario where an application calls CWindowGc::DrawBitmap() and then closes the bitmap before the client-side buffer is flushed. There needs to be some mechanism to prevent the bitmap’s reference count from reaching zero and hence being deleted before the Window Server can render it. For this reason, RFbsSession has a callback, which is invoked whenever a client closes a bitmap handle. The callback causes an immediate flush of the Window Server client-side command buffer. The Window Server then creates on the server side a duplicate CFbsBitmap for the bitmap. This increases the bitmap's reference count and therefore prevents it from being deleted before the Window Server attempts to render it. The same mechanism applies to font handles. This mechanism is transparent to clients of the Window Server.

              Font and Bitmap Server Collection Heap Locking in the Font and Bitmap - Server Font and Text Services Collection + + + + + +The Font and Bitmap Server OverviewThe Font and Bitmap Server (FBServ) provides a memory efficient way of using bitmaps and fonts. It stores a single instance of each bitmap in either a shared heap or in eXecute In Place (XIP) ROM and provides clients with read and (when appropriate) write access.

              RAM-based fonts and bitmaps are reference counted and retained in RAM while they are being used. When they are no longer required they are automatically deleted.

              Key terms
              Bitmap

              A two-dimensional (2D) buffer (in memory) that contains the color values for individual pixels and is encapsulated by the CFbsBitmap class.

              Extended bitmap

              A bitmap that contains data compressed using proprietary formats.

              Raster image

              A data structure representing a rectangular grid of pixels. Scaling raster images usually leads to a loss of quality.

              Vector image

              The use of geometrical primitives such as points, lines, curves and polygons to represent an image. Vector images can be scaled without loss of quality.

              Rasterization

              The process of converting vector image drawing instructions into a raster image that can be displayed on the screen.

              Scan line

              A row of pixels in a raster image. This use of the term is derived from its original use in a raster scanning pattern, such as a video line on the cathode ray tube (CRT) display of a television.

              For font-related terms, see Font and Text Services Collection Overview.

              Architectural relationships

              The Font and Bitmap Server is tightly integrated with the BitGDI and Window Server components. It provides client-side classes for fonts, bitmaps and the typeface store.

              In use the Font and Bitmap Server is largely transparent. When a client of the Window Server opens a Window Server session, that session silently creates an RFbsSession and stores it in Thread Local Storage (TLS). Client-side font and bitmap classes such as CFbsFont and CFbsBitmap automatically find the session in TLS when they are constructed. (These are client-side objects that refer to objects in the server. Because they are heap-based classes, they have names beginning with C.)

              The Font and Bitmap Server contains the font store, which is a separate DLL provided by the Font Store (FntStore) component. Client-side access to the font store is through CFbsTypefaceStore.

              Description

              The Font and Bitmap Server is a singleton process that owns fonts and bitmaps. CFbsFont and CFbsBitmap objects are actually client-side handles to the font and bitmap objects, which are stored on a globally accessible heap while they are in use. Bitmap data is stored separately in a globally accessible disconnected chunk.

              When the reference count of clients using a font or bitmap that is resident in RAM falls to zero, the server can delete it and free the memory. XIP ROM based bitmaps are accessed in place, not copied into RAM.

              Open fonts, which are stored in font files as vector data, must be rasterized into the Font and Bitmap Server's shared heap. Rasterizers are plug-ins to the Font Store component. There is a performance overhead to rasterizing an open font and a memory overhead for storing it.

              API summary

              The Font and Bitmap Server presents a conventional client API through RFbsSession, which represents the handle to a server-side session. The classes CFbsFont and CFbsBitmap are client-side representations of font and bitmap classes.

              • The CFbsFont class represents fonts managed by the Font and Bitmap Server, both bitmap fonts and OpenType fonts.

              • The CFbsBitmap class represents bitmaps managed by the Font and Bitmap Server, both RAM and XIP ROM-based bitmaps. For RAM-based bitmaps, this class provides facilities for creating, loading, saving, and resizing bitmaps. RAM-based bitmaps are commonly loaded from a multi-bitmap file (.mbm) file or created as off-screen bitmaps, and then blitted to a window. For XIP ROM-based bitmaps, CFbsBitmap provides facilities for accessing the data.

              The Font and Bitmap Server is unusual in that the RFbsSession is stored in client-side thread local storage (TLS). The constructors for CFbsFont and CFbsBitmap find this session handle automatically: the client program does not have to pass it as a parameter. Therefore, to most client programs, the client/server nature of using fonts and bitmaps is hidden from the API.

              The RFbsSession is created for clients by the Window Server’s client-side API when a Window Server session, RWsSession, is constructed. A Window Server client is therefore also a client of the Font and Bitmap Server.

              When a client calls, for example, the CWindowGc::DrawBitmap() function, the handle number of the bitmap is passed to the Window Server through inter-process communication (IPC). Like all CWindowGc drawing commands, the handle number is stored in a client-side command buffer, which by default is flushed to the server side only when it is full. Once flushed to the server-side, the command buffer is processed by the Window Server rendering loop. Consider the scenario where an application calls CWindowGc::DrawBitmap() and then closes the bitmap before the client-side buffer is flushed. There needs to be some mechanism to prevent the bitmap’s reference count from reaching zero and hence being deleted before the Window Server can render it. For this reason, RFbsSession has a callback, which is invoked whenever a client closes a bitmap handle. The callback causes an immediate flush of the Window Server client-side command buffer. The Window Server then creates on the server side a duplicate CFbsBitmap for the bitmap. This increases the bitmap's reference count and therefore prevents it from being deleted before the Window Server attempts to render it. The same mechanism applies to font handles. This mechanism is transparent to clients of the Window Server.

              Font and Bitmap Server Collection Heap Locking in the Font and Bitmap + Server Font and Text Services Collection Overview Font Store Component Overview               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-71E64F3E-40CB-560B-A482-CA92C7FD1AA2_d0e200807_href.png Binary file Symbian3/SDK/Source/GUID-71E64F3E-40CB-560B-A482-CA92C7FD1AA2_d0e200807_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-71E64F3E-40CB-560B-A482-CA92C7FD1AA2_d0e205815_href.png Binary file Symbian3/SDK/Source/GUID-71E64F3E-40CB-560B-A482-CA92C7FD1AA2_d0e205815_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-72262200-B940-4D0C-8FA0-6628E9894E8F-master.png Binary file Symbian3/SDK/Source/GUID-72262200-B940-4D0C-8FA0-6628E9894E8F-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-72262200-B940-4D0C-8FA0-6628E9894E8F_d0e40348_href.png Binary file Symbian3/SDK/Source/GUID-72262200-B940-4D0C-8FA0-6628E9894E8F_d0e40348_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-72262200-B940-4D0C-8FA0-6628E9894E8F_d0e45911_href.png Binary file Symbian3/SDK/Source/GUID-72262200-B940-4D0C-8FA0-6628E9894E8F_d0e45911_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-72262200-B940-4D0C-8FA0-6628E9894E8F_d0e66754_href.png Binary file Symbian3/SDK/Source/GUID-72262200-B940-4D0C-8FA0-6628E9894E8F_d0e66754_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-72262200-B940-4D0C-8FA0-6628E9894E8F_d0e72000_href.png Binary file Symbian3/SDK/Source/GUID-72262200-B940-4D0C-8FA0-6628E9894E8F_d0e72000_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-722FAAAD-AD14-4139-857E-83B639FDEB58_d0e65056_href.png Binary file Symbian3/SDK/Source/GUID-722FAAAD-AD14-4139-857E-83B639FDEB58_d0e65056_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-722FAAAD-AD14-4139-857E-83B639FDEB58_d0e70305_href.png Binary file Symbian3/SDK/Source/GUID-722FAAAD-AD14-4139-857E-83B639FDEB58_d0e70305_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7235E4E9-0046-4BE1-91CF-BD52CE4489DF.dita --- a/Symbian3/SDK/Source/GUID-7235E4E9-0046-4BE1-91CF-BD52CE4489DF.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-7235E4E9-0046-4BE1-91CF-BD52CE4489DF.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,27 +1,28 @@ - - - - - -Message -query -

              When there is need for a query that is longer than would fit one screen, -a message query can be used. A message query can contain a link text that -can be highlighted and opened.

              -

              By default the left softkey is OK, but with a link in the query the left -softkey opens the target view of the highlighted link text. The Selection -key also opens the link target view when the link is highlighted. Note that -there should be no more than three links in a single query.

              - -Message query - - -
              Using message queries -in C++ applications

              For implementation information, see Queries.

              + + + + + +Message +query +

              When there is need for a query that is longer than would fit one screen, +a message query can be used. A message query can contain a link text that +can be highlighted and opened.

              +

              By default the left softkey is OK, but with a link +in the query the left softkey opens the target view of the highlighted link +text. The Selection key also opens the link target view when the link is highlighted. +Note that there should be no more than three links in a single query.

              + +Message query + + +
              Using +message queries in applications

              For implementation information, +see Queries.

               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7250950C-5502-5ACE-864B-0EFD5C253053-GENID-1-8-1-3-1-1-7-1-10-1.dita --- a/Symbian3/SDK/Source/GUID-7250950C-5502-5ACE-864B-0EFD5C253053-GENID-1-8-1-3-1-1-7-1-10-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,76 +0,0 @@ - - - - - -How -to create a singleton -

              The CCoeStatic class allows singleton classes to be -created and stored by the environment (CCoeEnv) in Thread -Local Storage (TLS). This provides a means of creating writeable global static -data.

              -

              MySingleton.h

              - -class CMySingleton : public CCoeStatic - { -public: - static CMySingleton* SelfL() ; // Slightly slower - static CMySingleton* SelfL( CCoeEnv* aCoeEnv ) ; // Slightly faster - ... -private: - CMySingleton() ; - ~CMySingleton() ; - } ; - -

              MySingleton.cpp

              - -const TUid KUidMySingleton = {0x10204232} ; - -CMySingleton::CMySingleton() : CCoeStatic( KUidMySingleton, CCoeStatic::EThread /*or EApp*/ ) - { - } - -CMySingleton* CMySingleton::SelfL() - { - CMySingleton* self = static_cast<CMySingleton*>( CCoeStatic::Static( KUidMySingleton ) ) ; - if(!self) - { - self = new( ELeave ) CMySingleton() ; - } - return self ; - } - -CMySingleton* CMySingleton::SelfL( CCoeEnv* aCoeEnv ) - { - CMySingleton* self = static_cast<CMySingleton*>( aCoeEnv->FindStatic( KUidMySingleton ) ) ; - if( !self ) - { - self = new( ELeave ) CMySingleton() ; - } - return self ; - } - -

              A singleton must be given a UID. When it is instantiated for the first -time the base class constructor adds it to the list of singletons in the environment. -Any subsequent attempts to instantiate the same singleton will result in a -panic.

              -

              Singletons may be given a destruction priority and a scope.

              -

              The destruction priority determines when the singleton is destroyed -relative to any other singletons in the environment's list and relative to -the App Ui. The default priority, EDefaultDestructionPriority, -is 100. The higher the priority, the earlier the singleton will be destroyed. -A negative value indicates that the singleton should be destroyed after the -AppUi. The more negative the value, the later the destruction.

              -

              The scope may be EThread (the default) or EApp and -determines the visibility of the singleton.

              -

              Once a singleton has been created it may be accessed through the CCoeEnv API.

              -// Singleton access -IMPORT_C static CCoeStatic* Static( TUid aUid ) ; -IMPORT_C CCoeStatic* FindStatic( TUid aUid ) ; -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7250950C-5502-5ACE-864B-0EFD5C253053-GENID-1-8-1-6-1-1-4-1-6-1-10-1.dita --- a/Symbian3/SDK/Source/GUID-7250950C-5502-5ACE-864B-0EFD5C253053-GENID-1-8-1-6-1-1-4-1-6-1-10-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,76 +0,0 @@ - - - - - -How -to create a singleton -

              The CCoeStatic class allows singleton classes to be -created and stored by the environment (CCoeEnv) in Thread -Local Storage (TLS). This provides a means of creating writeable global static -data.

              -

              MySingleton.h

              - -class CMySingleton : public CCoeStatic - { -public: - static CMySingleton* SelfL() ; // Slightly slower - static CMySingleton* SelfL( CCoeEnv* aCoeEnv ) ; // Slightly faster - ... -private: - CMySingleton() ; - ~CMySingleton() ; - } ; - -

              MySingleton.cpp

              - -const TUid KUidMySingleton = {0x10204232} ; - -CMySingleton::CMySingleton() : CCoeStatic( KUidMySingleton, CCoeStatic::EThread /*or EApp*/ ) - { - } - -CMySingleton* CMySingleton::SelfL() - { - CMySingleton* self = static_cast<CMySingleton*>( CCoeStatic::Static( KUidMySingleton ) ) ; - if(!self) - { - self = new( ELeave ) CMySingleton() ; - } - return self ; - } - -CMySingleton* CMySingleton::SelfL( CCoeEnv* aCoeEnv ) - { - CMySingleton* self = static_cast<CMySingleton*>( aCoeEnv->FindStatic( KUidMySingleton ) ) ; - if( !self ) - { - self = new( ELeave ) CMySingleton() ; - } - return self ; - } - -

              A singleton must be given a UID. When it is instantiated for the first -time the base class constructor adds it to the list of singletons in the environment. -Any subsequent attempts to instantiate the same singleton will result in a -panic.

              -

              Singletons may be given a destruction priority and a scope.

              -

              The destruction priority determines when the singleton is destroyed -relative to any other singletons in the environment's list and relative to -the App Ui. The default priority, EDefaultDestructionPriority, -is 100. The higher the priority, the earlier the singleton will be destroyed. -A negative value indicates that the singleton should be destroyed after the -AppUi. The more negative the value, the later the destruction.

              -

              The scope may be EThread (the default) or EApp and -determines the visibility of the singleton.

              -

              Once a singleton has been created it may be accessed through the CCoeEnv API.

              -// Singleton access -IMPORT_C static CCoeStatic* Static( TUid aUid ) ; -IMPORT_C CCoeStatic* FindStatic( TUid aUid ) ; -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7250950C-5502-5ACE-864B-0EFD5C253053.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-7250950C-5502-5ACE-864B-0EFD5C253053.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,76 @@ + + + + + +How +to create a singleton +

              The CCoeStatic class allows singleton classes to be +created and stored by the environment (CCoeEnv) in Thread +Local Storage (TLS). This provides a means of creating writeable global static +data.

              +

              MySingleton.h

              + +class CMySingleton : public CCoeStatic + { +public: + static CMySingleton* SelfL() ; // Slightly slower + static CMySingleton* SelfL( CCoeEnv* aCoeEnv ) ; // Slightly faster + ... +private: + CMySingleton() ; + ~CMySingleton() ; + } ; + +

              MySingleton.cpp

              + +const TUid KUidMySingleton = {0x10204232} ; + +CMySingleton::CMySingleton() : CCoeStatic( KUidMySingleton, CCoeStatic::EThread /*or EApp*/ ) + { + } + +CMySingleton* CMySingleton::SelfL() + { + CMySingleton* self = static_cast<CMySingleton*>( CCoeStatic::Static( KUidMySingleton ) ) ; + if(!self) + { + self = new( ELeave ) CMySingleton() ; + } + return self ; + } + +CMySingleton* CMySingleton::SelfL( CCoeEnv* aCoeEnv ) + { + CMySingleton* self = static_cast<CMySingleton*>( aCoeEnv->FindStatic( KUidMySingleton ) ) ; + if( !self ) + { + self = new( ELeave ) CMySingleton() ; + } + return self ; + } + +

              A singleton must be given a UID. When it is instantiated for the first +time the base class constructor adds it to the list of singletons in the environment. +Any subsequent attempts to instantiate the same singleton will result in a +panic.

              +

              Singletons may be given a destruction priority and a scope.

              +

              The destruction priority determines when the singleton is destroyed +relative to any other singletons in the environment's list and relative to +the App Ui. The default priority, EDefaultDestructionPriority, +is 100. The higher the priority, the earlier the singleton will be destroyed. +A negative value indicates that the singleton should be destroyed after the +AppUi. The more negative the value, the later the destruction.

              +

              The scope may be EThread (the default) or EApp and +determines the visibility of the singleton.

              +

              Once a singleton has been created it may be accessed through the CCoeEnv API.

              +// Singleton access +IMPORT_C static CCoeStatic* Static( TUid aUid ) ; +IMPORT_C CCoeStatic* FindStatic( TUid aUid ) ; +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-72511204-FC90-54AA-9E2E-833318020318.dita --- a/Symbian3/SDK/Source/GUID-72511204-FC90-54AA-9E2E-833318020318.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-72511204-FC90-54AA-9E2E-833318020318.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,49 +1,53 @@ - - - - - -Reading -to a Buffer -

              This tutorial describes how to read the data from the table into a buffer.

              -
              Introduction

              This query allows you to retrieve -the data in a field. You can retrieve one entry or multiple entries in the -same column by executing the query in a loop.

              -
              Basic procedure

              The high level steps to read the -data into the buffer are shown here:

                -

              1. Configure the SQL statement.

                2. -

              2. Allocate memory and -copy data.

                3. -

              3. Deallocate memory.

                4. -
              -
              Detailed steps

              The steps to read data to a buffer -are as follows:

              Configure -the SQL statement

              Instantiate an RSqlStatement object -and declare the variables as required.

              RSqlStatement myStatement; -TInt err;

              Allocate -memory and copy data

              To retrieve all the entries, use a loop. -The steps to be performed within the loop are as described below:

                -

              1. Instantiate an object -of the RBuf class.

                while((err = myStatement.Next()) == KSqlAtRow) - { - RBuf myBuffer;
                2. -

              2. Allocate enough memory -to hold the column data using the CreateL() function as shown -below.

                err = myBuffer.CreateL(myStatement.ColumnSize(columnIndex));
                3. -

              3. Copy the data from the -table into the buffer using ColumnBinary() function.

                err = myStatement.ColumnBinary(myColumnIndex,myBuffer); - ... - // process data
                4. -

              Deallocate -memory

              Deallocate the memory assigned to the RBuf object.

              myBuffer.Close(); - }
              -
              See also

              Querying -a Database

              Deleting -Rows from a Table

              Reading to a buffer - This document

              Reading to Memory

              Reading to a Data Stream

              Writing to a Data Stream

              Performing Scalar Queries

              + + + + + +Reading +to a Buffer +

              This tutorial describes how to read the data from the table into a buffer.

              +
              Introduction

              This +query allows you to retrieve the data in a field. You can retrieve one entry +or multiple entries in the same column by executing the query in a loop.

              +
              Basic procedure

              The +high level steps to read the data into the buffer are shown here:

                +

              1. Configure the SQL statement.

                2. +

              2. Allocate memory and +copy data.

                3. +

              3. Deallocate memory.

                4. +
              +
              Detailed steps

              The +steps to read data to a buffer are as follows:

              Configure +the SQL statement

              Instantiate an RSqlStatement object +and declare the variables as required.

              RSqlStatement myStatement; +TInt err;

              Allocate +memory and copy data

              To retrieve all the entries, use a loop. +The steps to be performed within the loop are as described below:

                +

              1. Instantiate an object +of the RBuf class.

                while((err = myStatement.Next()) == KSqlAtRow) + { + RBuf myBuffer;
                2. +

              2. Allocate enough memory +to hold the column data using the CreateL() function as shown +below.

                err = myBuffer.CreateL(myStatement.ColumnSize(columnIndex));
                3. +

              3. Copy the data from the +table into the buffer using RSqlStatement::ColumnBinary(TInt,TDes8 +&)const function.

                err = myStatement.ColumnBinary(myColumnIndex,myBuffer); + ... + // process data
                4. +

              Deallocate +memory

              Deallocate the memory assigned to the RBuf object.

              myBuffer.Close(); + }
              +
              See also

              Querying a Database

              Deleting Rows from a Table

              Reading +to a buffer - This document

              Reading +to Memory

              Reading +to a Data Stream

              Writing +to a Data Stream

              Performing +Scalar Queries

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-727E6071-591B-539E-997C-BC0CC5B62A11_d0e135705_href.png Binary file Symbian3/SDK/Source/GUID-727E6071-591B-539E-997C-BC0CC5B62A11_d0e135705_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-727E6071-591B-539E-997C-BC0CC5B62A11_d0e142239_href.png Binary file Symbian3/SDK/Source/GUID-727E6071-591B-539E-997C-BC0CC5B62A11_d0e142239_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7287F1D4-023E-5C90-91E1-6D8DF78D8241.dita --- a/Symbian3/SDK/Source/GUID-7287F1D4-023E-5C90-91E1-6D8DF78D8241.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-7287F1D4-023E-5C90-91E1-6D8DF78D8241.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,67 +1,67 @@ - - - - - -Virtual -machine modelThe Kernel provides a 'virtual machine' environment to user processes -where each process accesses its data in the same virtual address range. -

              The Kernel provides a 'virtual machine' environment to user processes. -Each process accesses its data in the same virtual address range, called the -data section, which ranges from:

              -0x00400000 to 0x3FFFFFFF -

              but note that the static data always appears at:

              -0x00400000 -

              The code chunk for RAM loaded processes always appears at:

              -0x20000000 -

              This allows multiple processes to run, each executing the same code (from -the same code chunk) for each of the processes. For example, multiple word -documents open at the same time, each in a separate instance of the word application. -This reduces RAM usage.

              -

              In effect, each user process has the same kind of view. Code instructions -address data using the virtual address; the Memory Management Unit (MMU) is -responsible for the translation of the virtual address to the physical RAM -address.

              -

              Only one chunk can occupy a given virtual address range at a time, so a -context switch between different processes involves re-mapping the chunks. -The process chunks of the old process are re-mapped to their home addresses. -These are in the home section, which is the virtual address range from:

              -0x80000000 to 0xFFFFFFFF -

              ROM code is normally mapped into the address range:

              -0x50000000 to 0x5FFFFFFF -

              The process chunks of the new process are mapped from their home addresses -back to the data section. Chunks which are not accessible by the current user -process reside in the home section, and they have supervisor-mode-only access -permissions, so that only the kernel can access them.

              -

              The Kernel's data and stack/heap chunks also reside in the home section. -These are never visible to user processes. Code chunks for RAM-loaded libraries -reside at the top end of the home section and have user read-only access, -so that all user processes can execute code from a loaded library.

              -

              A context switch between processes therefore involves:

              -
                -

              • moving the old process -chunks to the home section, and changing their access permissions to supervisor-only

                • -

              • moving the new process -chunks to the data section and changing their access permissions back to user-accessible.

                • -
              -

              This is best seen graphically. In the first diagram shown below, user-process -1 is running and can 'see' all chunks in the clear boxes. Those boxes with -dark background represent chunks which are not visible to user-process 1.

              -

              When user-process 2 is running, the context switch re-maps the user-process -2 data to the data section and user process 1 data is re-mapped to the home -section as the second diagram shows.

              - -User process 1's view. - - - -User process 2's view. - - + + + + + +Virtual +machine modelThe Kernel provides a 'virtual machine' environment to user processes +where each process accesses its data in the same virtual address range. +

              The Kernel provides a 'virtual machine' environment to user processes. +Each process accesses its data in the same virtual address range, called the +data section, which ranges from:

              +0x00400000 to 0x3FFFFFFF +

              but note that the static data always appears at:

              +0x00400000 +

              The code chunk for RAM loaded processes always appears at:

              +0x20000000 +

              This allows multiple processes to run, each executing the same code (from +the same code chunk) for each of the processes. For example, multiple word +documents open at the same time, each in a separate instance of the word application. +This reduces RAM usage.

              +

              In effect, each user process has the same kind of view. Code instructions +address data using the virtual address; the Memory Management Unit (MMU) is +responsible for the translation of the virtual address to the physical RAM +address.

              +

              Only one chunk can occupy a given virtual address range at a time, so a +context switch between different processes involves re-mapping the chunks. +The process chunks of the old process are re-mapped to their home addresses. +These are in the home section, which is the virtual address range from:

              +0x80000000 to 0xFFFFFFFF +

              ROM code is normally mapped into the address range:

              +0x50000000 to 0x5FFFFFFF +

              The process chunks of the new process are mapped from their home addresses +back to the data section. Chunks which are not accessible by the current user +process reside in the home section, and they have supervisor-mode-only access +permissions, so that only the kernel can access them.

              +

              The Kernel's data and stack/heap chunks also reside in the home section. +These are never visible to user processes. Code chunks for RAM-loaded libraries +reside at the top end of the home section and have user read-only access, +so that all user processes can execute code from a loaded library.

              +

              A context switch between processes therefore involves:

              +
                +

              • moving the old process +chunks to the home section, and changing their access permissions to supervisor-only

                • +

              • moving the new process +chunks to the data section and changing their access permissions back to user-accessible.

                • +
              +

              This is best seen graphically. In the first diagram shown below, user-process +1 is running and can 'see' all chunks in the clear boxes. Those boxes with +dark background represent chunks which are not visible to user-process 1.

              +

              When user-process 2 is running, the context switch re-maps the user-process +2 data to the data section and user process 1 data is re-mapped to the home +section as the second diagram shows.

              + +User process 1's view. + + + +User process 2's view. + +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7293765E-2B1E-5F0D-B6A8-0E48729DC365_d0e188567_href.png Binary file Symbian3/SDK/Source/GUID-7293765E-2B1E-5F0D-B6A8-0E48729DC365_d0e188567_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7293765E-2B1E-5F0D-B6A8-0E48729DC365_d0e193629_href.png Binary file Symbian3/SDK/Source/GUID-7293765E-2B1E-5F0D-B6A8-0E48729DC365_d0e193629_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-72B7B5CC-2E04-53CE-8414-C362DFD40D52_d0e229035_href.png Binary file Symbian3/SDK/Source/GUID-72B7B5CC-2E04-53CE-8414-C362DFD40D52_d0e229035_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-72B7B5CC-2E04-53CE-8414-C362DFD40D52_d0e232772_href.png Binary file Symbian3/SDK/Source/GUID-72B7B5CC-2E04-53CE-8414-C362DFD40D52_d0e232772_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-72DE3EB1-1AF5-4157-8B99-A1C7143DAD2C.dita --- a/Symbian3/SDK/Source/GUID-72DE3EB1-1AF5-4157-8B99-A1C7143DAD2C.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,96 +0,0 @@ - - - - - -Navigation -using tabs -

              The Symbian user interface uses the tab metaphor that allows combining -several pages of related information into a single state when all of it would -not fit into a single screen or list. The user can switch the tabs using the -Arrow left and Arrow right keys as indicated in the Navi -pane.

              - -Navigation using tabs - - -

              In this example, state 1-3 uses two tabs to present its information. The -user moves between views 1-3a and 1-3b using the Arrow left and Arrow right -keys. Note that there is no Back function moving between the tab views; Back -from both of them leads to state 1.

              -

              Tab-controlled views apply the following rules:

              -
                -

              • A list view from which each of the tabbed views can be accessed should -precede the tabbed views one level higher.

                • -

              • Moving from one tab view to another has no effect on the function of -the Back softkey in these views: from all of them, the Back function leads -to the same place, the previous level in the application. In this respect, -tabbed views are interpreted as one state in the application.

                • -

              • When a state has tabbed views, one of them is the default view that -is opened when the user enters the state from the previous level.

                • -

              • When the user has proceeded from a tabbed view into a deeper hierarchy -level, the Back function returns to the same tabbed view where the user came -from (which is not necessarily the default view described in the previous -bullet).

                • -

              • The possibilities to go forward from tab views may differ from one -view to another (although typically they are similar). This means that one -tab view may have other functions available to the user than another tab view -in the same state.

                • -
              - - Touch interaction model for tabs - - -Default touch -events for tabs - - - - - - -

              User action

               -

              State change

               -

              Feedback

               -               - - - - -

              Touch down on a tab

               -

              No change

               -

              Highlight is shown.

              Tactile: Basic tab effect and audio feedback -are provided with touch down event.

               -               - -

              Touch down and hold on a tab

               -

              Inactive

               -

              Tactile: No effect

               -               - -

              Touch release on a tab

               -

              Corresponding view is changed.

              Activated tab moves to the -middle of the tab view (all the tabs move along) unless it is the first or -the last tab in the application.

               -

              Highlight disappears

              Tactile: Basic tab effect is provided -with touch release event.

               -               - -

              Touch down and move horizontally on tab area and release

               -

              Previous or next tab is opened

               -

              Tactile: Basic tab effect and audio feedback are provided with touch -down event.

               -               - - -
              -
              Using -tabs in C++ applications

              The API to use for tabs is the Tabs -API. For implementation information, see Using the Tabs API.

              -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-72F24867-8D67-5BD1-A8C4-93FC7A4290FC_d0e201561_href.png Binary file Symbian3/SDK/Source/GUID-72F24867-8D67-5BD1-A8C4-93FC7A4290FC_d0e201561_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-72F24867-8D67-5BD1-A8C4-93FC7A4290FC_d0e206569_href.png Binary file Symbian3/SDK/Source/GUID-72F24867-8D67-5BD1-A8C4-93FC7A4290FC_d0e206569_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-730E1E2B-BB8B-4C66-8A70-0FBCE7680B66.dita --- a/Symbian3/SDK/Source/GUID-730E1E2B-BB8B-4C66-8A70-0FBCE7680B66.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,15 +0,0 @@ - - - - - -Changes -and release information -

              The Generic button API is an SDK API and first released in S60 5th Edition.

              -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-73491C1D-6C74-5434-B2F3-4AF416AE37B7.dita --- a/Symbian3/SDK/Source/GUID-73491C1D-6C74-5434-B2F3-4AF416AE37B7.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-73491C1D-6C74-5434-B2F3-4AF416AE37B7.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,89 +1,89 @@ - - - - - -Overview -of hash algorithms -
                -

              • What is a cryptographic hash?

                • -

              • What is an HMAC?

                • -

              • The base class and its derived classes

                • -
              -
              What is a cryptographic -hash?

              A cryptographic hash algorithm (also known as a message digest, -a one-way function, or simply a hash) takes a variable-length input (the message) -and produce a fixed length output known as the hash (or digest) of the input. -It is often useful to think of the resulting output as a representation, or -fingerprint, of the original input.

              There are two properties that -are important to cryptographic hashes:

                -

              • it must be hard to find -collisions, i.e. it is highly unlikely that two distinct strings will hash -to the same output

                • -

              • it is extremely difficult -to determine the original input given only the output. Even very small changes -to the input will give rise to radical changes in the output.

                • -

              These properties make hash functions useful in cryptography and other -applications as they allow the representation of objects in a known fixed -size.

              The hash algorithms supported by the Symbian platform -are:

              - - - -Hash algorithms -Further information - - - - -

              MD4

              -

              RFC -1320

              -               - -

              MD5

              -

              RFC -1321

              -               - -

              SHA-1

              -

              FIPS -180-1 and RFC -3174

              -               - -

              HMAC

              -

              RFC -2104

              -               - - -

              There is also support for MD2 (see RFC 1319) and SHA, which is there for backward compatibility, -but it is not to be used in new code.

              -
              What is an -HMAC?

              Unlike the hashes mentioned above, HMAC (Hashed Message Authentication -Code) is a key-dependant hash. It allows a key to be specified at creation -of the HMAC. Only people with that key can verify the hash. HMACs are useful -when authentication but not secrecy of a message is required.

              The -sender appends to the message data an authentication tag (which is a function -of the data and the shared key). The recipient recomputes the authentication -tag on the received message using the shared key. The integrity of the message -is deemed valid only if the two authentication tags match.

              For further -details see RFC -2104.

              -
              The Hash API

              CMessageDigest is -the base class for all hash algorithms.

              The diagram below show the -main classes used in the hash framework. For information on each class see -the Cryptography API Reference material.

              - Inheritance diagram for the Hash API - -

              The hash API is used internally by the Security components: AppInst, -Certman (Certificate Management) and Cryptography. Networking/TLS uses a pseudo-random -function (PRF) based on HMAC. Both MD5 and SHA-1 are used in TLS.

              + + + + + +Overview +of hash algorithms +
                +

              • What is a cryptographic hash?

                • +

              • What is an HMAC?

                • +

              • The base class and its derived classes

                • +
              +
              What is a cryptographic +hash?

              A cryptographic hash algorithm (also known as a message digest, +a one-way function, or simply a hash) takes a variable-length input (the message) +and produce a fixed length output known as the hash (or digest) of the input. +It is often useful to think of the resulting output as a representation, or +fingerprint, of the original input.

              There are two properties that +are important to cryptographic hashes:

                +

              • it must be hard to find +collisions, i.e. it is highly unlikely that two distinct strings will hash +to the same output

                • +

              • it is extremely difficult +to determine the original input given only the output. Even very small changes +to the input will give rise to radical changes in the output.

                • +

              These properties make hash functions useful in cryptography and other +applications as they allow the representation of objects in a known fixed +size.

              The hash algorithms supported by the Symbian platform +are:

              + + + +Hash algorithms +Further information + + + + +

              MD4

              +

              RFC +1320

              +               + +

              MD5

              +

              RFC +1321

              +               + +

              SHA-1

              +

              FIPS +180-1 and RFC +3174

              +               + +

              HMAC

              +

              RFC +2104

              +               + + +

              There is also support for MD2 (see RFC 1319) and SHA, which is there for backward compatibility, +but it is not to be used in new code.

              +
              What is an +HMAC?

              Unlike the hashes mentioned above, HMAC (Hashed Message Authentication +Code) is a key-dependant hash. It allows a key to be specified at creation +of the HMAC. Only people with that key can verify the hash. HMACs are useful +when authentication but not secrecy of a message is required.

              The +sender appends to the message data an authentication tag (which is a function +of the data and the shared key). The recipient recomputes the authentication +tag on the received message using the shared key. The integrity of the message +is deemed valid only if the two authentication tags match.

              For further +details see RFC +2104.

              +
              The Hash API

              CMessageDigest is +the base class for all hash algorithms.

              The diagram below show the +main classes used in the hash framework. For information on each class see +the Cryptography API Reference material.

              + Inheritance diagram for the Hash API + +

              The hash API is used internally by the Security components: AppInst, +Certman (Certificate Management) and Cryptography. Networking/TLS uses a pseudo-random +function (PRF) based on HMAC. Both MD5 and SHA-1 are used in TLS.

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-736F9C4B-7C70-5927-A9C9-21A127C431AF_d0e31753_href.png Binary file Symbian3/SDK/Source/GUID-736F9C4B-7C70-5927-A9C9-21A127C431AF_d0e31753_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-736F9C4B-7C70-5927-A9C9-21A127C431AF_d0e37319_href.png Binary file Symbian3/SDK/Source/GUID-736F9C4B-7C70-5927-A9C9-21A127C431AF_d0e37319_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-738FADA9-E26F-53F1-A6D6-2E82019DDA1F.dita --- a/Symbian3/SDK/Source/GUID-738FADA9-E26F-53F1-A6D6-2E82019DDA1F.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-738FADA9-E26F-53F1-A6D6-2E82019DDA1F.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,1061 +1,1061 @@ - - - - - -Turkish -National Language Support -

              This section describes the plug-in converters for Turkish national language -support and the alphabet each converter supports.

              -
              Introduction

              To convert a Turkish SMS message using -the National Language Encoding, Symbian provides three Turkish plug-in converters:

                -

              • Default GSM7 Turkish -Single Converter. The highlighted boxes in Figure 1 show that it supports -the default GSM 7-bit alphabet, the Turkish single shift alphabet and the -set of lossy conversions supported by the standard converter. This converter -is identified by the KCharacterSetIdentifierTurkishSingleSms7Bit UID, -which is defined in the charconv.h header file.

                Figure -1

                - Alphabet of the Default GSM7 Turkish Single Converter - - -
                • -

              • Turkish Locking GSM7 -Extension Converter. The highlighted boxes in Figure 2 show that it supports -the Turkish locking shift alphabet, default GSM extension alphabet and the -set of lossy conversions supported by the standard converter. This converter -is identified by the KCharacterSetIdentifierTurkishLockingSms7Bit UID, -which is defined in the charconv.h header file.

                Figure -2

                - Alphabet of the Turkish Locking GSM7 Extension Converter - - -
                • -

              • Turkish Locking Single -Converter. The highlighted boxes in Figure 3 show that it supports the Turkish -locking shift alphabet, Turkish single shift alphabet and the set of lossy -conversions supported by the standard converter. This converter is identified -by the KCharacterSetIdentifierTurkishLockingAndSingleSms7Bit UID, -which is defined in the charconv.h header file.

                Figure -3

                - Alphabet of the Turkish Locking Single Converter - - -
                • -

              Note: For all of the converters, any undefined Unicode is -converted to a question mark (?)–GSM code 0x37. Any code -outside GSM 0x00 ~0x7F is converted to the -Unicode replacement character 0xFFFD.

              -
              Alphabet

              To -better understand the different character set of each converter, the Standard -SMS Converter is set as the baseline. The following comparison tables help -identify the different character set supported by each Turkish converter as -a comparison to the standard SMS converter.

              Table 1A Default GSM7 Turkish Single Converter vs. Standard SMS Converter -– Unicode to GSM Code

              Table -1B Default GSM7 Turkish Single Converter vs. Standard SMS Converter – GSM -Code to Unicode

              Table -2A Turkish Locking GSM7 Extension Converter vs. Standard SMS Converter – Unicode -to GSM Code

              Table -2B Turkish Locking GSM7 Extension Converter vs. Standard SMS Converter – GSM -Code to Unicode

              Table -3A Turkish Locking Single Converter vs. Standard SMS Converter – Unicode to -GSM Code

              Table -3B Turkish Locking Single Converter vs. Standard SMS Converter – GSM Code -to Unicode

              Default -GSM7 Turkish Single Converter vs. Standard SMS Converter – Unicode to GSM -Code

              Table 1A

              - - - -

              Default GSM7 Turkish Single Converter

              -

               -

               -

               - -

              Standard SMS Converter

              -

               -

               -

               -               - -

              Original Character

              -

              Unicode

              -

              GSM

              -

              Converted Character

              -

               -

              Character

              -

              Unicode

              -

              GSM

              -

              Converted Character

              -               - - - - - - -

              ç LATIN SMALL LETTER C WITH CEDILLA

              -

              0x00E7

              -

              0x09

              -

              Ç LATIN CAPITAL LETTER C WITH CEDILLA

              -               - -

              G LATIN CAPITAL LETTER G WITH BREVE

              -

              0x011E

              -

              0x1B47

              -

              G LATIN CAPITAL LETTER G WITH BREVE

              -

               

               - - - - -               - -

              G LATIN CAPITAL LETTER G WITH CARON

              -

              0x01E6

              -

              0x1B47

              -

              G LATIN CAPITAL LETTER G WITH BREVE

              - - - - - -               - -

              I LATIN CAPITAL LETTER I WITH DOT ABOVE

              -

              0x0130

              -

              0x1B49

              -

              I LATIN CAPITAL LETTER I WITH DOT ABOVE

              -

               

               - - - - -               - -

              S LATIN CAPITAL LETTER S WITH CEDILLA *

              -

              0x015E

              -

              0x1B53

              -

              S LATIN CAPITAL LETTER S WITH CEDILLA *

              -

               

               - - - - -               - -

              ç LATIN SMALL LETTER C WITH CEDILLA

              -

              0x00E7

              -

              0x1B63

              -

              ç LATIN SMALL LETTER C WITH CEDILLA

              -

               

               - - - - -               - -

              g LATIN SMALL LETTER G WITH BREVE

              -

              0x011F

              -

              0x1B67

              -

              g LATIN SMALL LETTER G WITH BREVE

              -

               

               - - - - -               - -

              g LATIN SMALL LETTER G WITH CARON

              -

              0x01E7

              -

              0x1B67

              -

              g LATIN SMALL LETTER G WITH BREVE

              - - - - - -               - -

              i LATIN SMALL LETTER DOTLESS

              -

              0x0131

              -

              0x1B69

              -

              i LATIN SMALL LETTER DOTLESS

              -

               

               - - - - -               - -

              s LATIN SMALL LETTER S WITH CEDILLA *

              -

              0x015F

              -

              0x1B73

              -

              s LATIN SMALL LETTER S WITH CEDILLA *

              -

               

               - - - - -               -               - -

              Default GSM7 -Turkish Single Converter vs. Standard SMS Converter – GSM Code to Unicode

              Table -1B

              - - - -

              Default GSM7 Turkish Single Converter

              -

               -

               -

               -

               -

              Standard SMS Converter

              -

               -

               -

               -               - -

              Character

              -

              GSM

              -

              Unicode

              -

              Converted Character

              -

               -

              Character

              -

              GSM

              -

              Unicode

              -

              Converted Character

              -               - -

              Ç LATIN CAPITAL LETTER C WITH CEDILLA

              -

              0x09

              -

              0x00C7

              -

              Ç LATIN CAPITAL LETTER C WITH CEDILLA

              - -

              Ç LATIN CAPITAL LETTER C WITH CEDILLA

              -

              0x09

              -

              0x00E7

              -

              ç LATIN SMALL LETTER C WITH CEDILLA

              -               - -

              FORM FEED

              -

              0x1B0A

              -

              0x000C

              -

              FORM FEED

              - -

              (PAGE BREAK)

              -

              0x1B0A

              -

              0x000C

              -

              (PAGE BREAK)

              -               - -

              G LATIN CAPITAL LETTER G WITH BREVE

              -

              0x1B47

              -

              0x011E

              -

              G LATIN CAPITAL LETTER G WITH BREVE

              - - -

              0x1B47

              -

              0x0047

              -

              G LATIN CAPITAL LETTER G

              -               - -

              I LATIN CAPITAL LETTER I WITH DOT ABOVE

              -

              0x1B49

              -

              0x0130

              -

              I LATIN CAPITAL LETTER I WITH DOT ABOVE

              - - -

              0x1B49

              -

              0x0049

              -

              I LATIN CAPITAL LETTER I

              -               - -

              S LATIN CAPITAL LETTER S WITH CEDILLA *

              -

              0x1B53

              -

              0x015E

              -

              S LATIN CAPITAL LETTER S WITH CEDILLA *

              - - -

              0x1B53

              -

              0x0053

              -

              S LATIN CAPITAL LETTER S

              -               - -

              g LATIN SMALL LETTER G WITH BREVE

              -

              0x1B67

              -

              0x011F

              -

              g LATIN SMALL LETTER G WITH BREVE

              - - -

              0x1B67

              -

              0x0067

              -

              g LATIN SMALL LETTER G

              -               - -

              i LATIN SMALL LETTER DOTLESS

              -

              0x1B69

              -

              0x0131

              -

              i LATIN SMALL LETTER DOTLESS

              - - -

              0x1B69

              -

              0x0069

              -

              i LATIN SMALL LETTER I

              -               - -

              s LATIN SMALL LETTER S WITH CEDILLA *

              -

              0x1B73

              -

              0x015F

              -

              s LATIN SMALL LETTER S WITH CEDILLA *

              - - -

              0x1B73

              -

              0x0073

              -

              s LATIN SMALL LETTER S

              -               -               - -

              Turkish Locking -GSM7 Extension Converter vs. Standard SMS Converter – Unicode to GSM Code

              Table -2A

              - - - -

              Turkish Locking GSM7 Extension Converter

              - -

               -

               -

               -

              Standard SMS Converter

              -

               -

               -

               -               - -

              Character

              -

              Unicode

              -

              GSM

              -

              Converted Character

              - -

              Character

              -

              Unicode

              -

              GSM

              -

              Converted Character

              -               - -

              € EURO SIGN

              -

              0x20AC

              -

              0x04

              -

              € EURO SIGN

              - -

              è LATIN SMALL LETTER E WITH GRAVE

              -

              0x00E8

              -

              0x04

              -

              è LATIN SMALL LETTER E WITH GRAVE

              -               - -

              i LATIN SMALL LETTER DOTLESS

              -

              0x0131

              -

              0x07

              -

              i LATIN SMALL LETTER DOTLESS

              - -

              ì LATIN SMALL LETTER I WITH GRAVE

              -

              0x00EC

              -

              0x07

              -

              ì LATIN SMALL LETTER I WITH GRAVE

              -               - -

              G LATIN CAPITAL LETTER G WITH BREVE

              -

              0x011E

              -

              0x0B

              -

              G LATIN CAPITAL LETTER G WITH BREVE

              - -

              ç LATIN SMALL LETTER C WITH CEDILLA

              -

              0x00E7

              -

              0x09

              -

              Ç LATIN CAPITAL LETTER C WITH CEDILLA

              -               - -

              G LATIN CAPITAL LETTER G WITH CARON

              -

              0x01E6

              -

              0x0B

              -

              G LATIN CAPITAL LETTER G WITH BREVE

              - -

              Ø LATIN CAPITAL LETTER O WITH STROKE

              -

              0x00D8

              -

              0x0B

              -

              Ø LATIN CAPITAL LETTER O WITH STROKE

              -               - -

              g LATIN SMALL LETTER G WITH BREVE

              -

              0x011F

              -

              0x0C

              -

              g LATIN SMALL LETTER G WITH BREVE

              - -

              ø LATIN SMALL LETTER O WITH STROKE

              -

              0x00F8

              -

              0x0C

              -

              ø LATIN SMALL LETTER O WITH STROKE

              -               - -

              g LATIN SMALL LETTER G WITH CARON

              -

              0x01E7

              -

              0x0C

              -

              g LATIN SMALL LETTER G WITH BREVE

              - -

              (FORM FEED)

              -

              0x000C

              -

              0x1B0A

              -

              (PAGE BREAK)

              -               - -

              S LATIN CAPITAL LETTER S WITH CEDILLA *

              -

              0x015E

              -

              0x1C

              -

              S LATIN CAPITAL LETTER S WITH CEDILLA *

              - -

              € EURO SIGN

              -

              0x20AC

              -

              0x1B65

              -

              € EURO SIGN

              -               - -

              S LATIN CAPITAL LETTER S WITH CEDILLA *

              -

              0x015F

              -

              0x1D

              -

              S LATIN CAPITAL LETTER S WITH CEDILLA *

              - -

              Æ LATIN CAPITAL LETTER AE

              -

              0x00C6

              -

              0x1C

              -

              Æ LATIN CAPITAL LETTER AE

              -               - -

              I LATIN CAPITAL LETTER I WITH DOT ABOVE

              -

              0x0130

              -

              0x40

              -

              I LATIN CAPITAL LETTER I WITH DOT ABOVE

              - -

              æ LATIN SMALL LETTER AE

              -

              0x00E6

              -

              0x1D

              -

              æ LATIN SMALL LETTER AE

              -               - -

              ç LATIN SMALL LETTER C WITH CEDILLA

              -

              0x00E7

              -

              0x60

              -

              ç LATIN SMALL LETTER C WITH CEDILLA

              - -

              ¡ INVERTED EXCLAMATION MARK

              -

              0x00A1

              -

              0x40

              -

              ¡ INVERTED EXCLAMATION MARK

              -               - - - - - - -

              Í LATIN CAPITAL LETTER I WITH ACUTE

              -

              0x00CD

              -

              0x49

              -

              I LATIN CAPITAL LETTER I

              -               - - - - - - -

              ¿ INVERTED QUESTION MARK

              -

              0x00BF

              -

              0x60

              -

              ¿ INVERTED QUESTION MARK

              -               -               - -

              Turkish Locking -GSM7 Extension Converter vs. Standard SMS Converter – GSM Code to Unicode

              Table -2B

              - - - -

              Turkish Locking GSM7 Extension Converter

              - -

               -

               -

               -

              Standard SMS Converter

              -

               -

               -

               -               - -

              Character

              -

              GSM

              -

              Unicode

              -

              Converted Character

              -

               -

              Character

              -

              GSM

              -

              Unicode

              -

              Converted Character

              -               - -

              Ç LATIN CAPITAL LETTER C WITH CEDILLA

              -

              0x09

              -

              0x00C7

              -

              Ç LATIN CAPITAL LETTER C WITH CEDILLA

              - -

              Ç LATIN CAPITAL LETTER C WITH CEDILLA

              -

              0x09

              -

              0x00E7

              -

              ç LATIN SMALL LETTER C WITH CEDILLA

              -               - -

              G LATIN CAPITAL LETTER G WITH BREVE

              -

              0x0B

              -

              0x011E

              -

              G LATIN CAPITAL LETTER G WITH BREVE

              - -

              Ø LATIN CAPITAL LETTER O WITH STROKE

              -

              0x0B

              -

              0x00D8

              -

              Ø LATIN CAPITAL LETTER O WITH STROKE

              -               - -

              g LATIN SMALL LETTER G WITH BREVE

              -

              0x0C

              -

              0x011F

              -

              g LATIN SMALL LETTER G WITH BREVE

              - -

              ø LATIN SMALL LETTER O WITH STROKE

              -

              0x0C

              -

              0x00F8

              -

              ø LATIN SMALL LETTER O WITH STROKE

              -               - - -

              0x1B07

              -

              0x0131

              -

              i LATIN SMALL LETTER DOTLESS

              - - -

              0x1B07

              -

              0x00EC

              -

              ì LATIN SMALL LETTER I WITH GRAVE

              -               - - -

              0x1B0A

              -

              0x000C

              -

              (FORM FEED)

              - -

              (PAGE BREAK)

              -

              0x1B0A

              -

              0x000C

              -

              (PAGE BREAK)

              -               - - -

              0x1B0B

              -

              0x011E

              -

              G LATIN CAPITAL LETTER G WITH BREVE

              - - -

              0x1B0B

              -

              0x00D8

              -

              Ø LATIN CAPITAL LETTER O WITH STROKE

              -               - - -

              0x1B0C

              -

              0x011F

              -

              g LATIN SMALL LETTER G WITH CARON

              - - -

              0x1B0C

              -

              0x00F8

              -

              ø LATIN SMALL LETTER O WITH STROKE

              -               - - -

              0x1B1C

              -

              0x015E

              -

              S LATIN CAPITAL LETTER S WITH CEDILLA *

              - - -

              0x1B1C

              -

              0x00C6

              -

              Æ LATIN CAPITAL LETTER AE (ash) *

              -               - - -

              0x1B1D

              -

              0x015F

              -

              s LATIN SMALL LETTER S WITH CEDILLA *

              - - -

              0x1B1D

              -

              0x00E6

              -

              æ LATIN SMALL LETTER AE (ash) *

              -               - - -

              0x1B60

              -

              0x00E7

              -

              ç LATIN SMALL LETTER C WITH CEDILLA

              - - -

              0x1B60

              -

              0x00BF

              -

              ¿ INVERTED QUESTION MARK

              -               - -

              S LATIN CAPITAL LETTER S WITH CEDILLA *

              -

              0x1C

              -

              0x015E

              -

              S LATIN CAPITAL LETTER S WITH CEDILLA *

              - -

              Æ LATIN CAPITAL LETTER AE

              -

              0x1C

              -

              0x00C6

              -

              Æ LATIN CAPITAL LETTER AE

              -               - -

              s LATIN SMALL LETTER S WITH CEDILLA *

              -

              0x1D

              -

              0x015F

              -

              s LATIN SMALL LETTER S WITH CEDILLA *

              - -

              æ LATIN SMALL LETTER AE

              -

              0x1D

              -

              0x00E6

              -

              æ LATIN SMALL LETTER AE

              -               - -

              I LATIN CAPITAL LETTER I WITH DOT ABOVE

              -

              0x40

              -

              0x0130

              -

              I LATIN CAPITAL LETTER I WITH DOT ABOVE

              - -

              ¡ INVERTED EXCLAMATION MARK

              -

              0x40

              -

              0x00A1

              -

              ¡ INVERTED EXCLAMATION MARK

              -               -               - -

              Turkish Locking -Single Converter vs. Standard SMS Converter – Unicode to GSM Code

              Table -3A

              - - - -

              Turkish Locking Single Converter

              -

               -

               -

               -

               -

              Standard SMS Converter

              -

               -

               -

               -               - -

              Character

              -

              Unicode

              -

              GSM

              -

              Converted Character

              -

               -

              Character

              -

              Unicode

              -

              GSM

              -

              Converted Character

              -               - -

              € EURO SIGN

              -

              0x20AC

              -

              0x04

              -

              € EURO SIGN

              - -

              è LATIN SMALL LETTER E WITH GRAVE

              -

              0x00E8

              -

              0x04

              -

              è LATIN SMALL LETTER E WITH GRAVE

              -               - -

              i LATIN SMALL LETTER DOTLESS

              -

              0x0131

              -

              0x07

              -

              i LATIN SMALL LETTER DOTLESS

              - -

              ì LATIN SMALL LETTER I WITH GRAVE

              -

              0x00EC

              -

              0x07

              -

              ì LATIN SMALL LETTER I WITH GRAVE

              -               - -

              G LATIN CAPITAL LETTER G WITH BREVE

              -

              0x011E

              -

              0x0B

              -

              G LATIN CAPITAL LETTER G WITH BREVE

              - -

              ç LATIN SMALL LETTER C WITH CEDILLA

              -

              0x00E7

              -

              0x09

              -

              Ç LATIN CAPITAL LETTER C WITH CEDILLA

              -               - -

              G LATIN CAPITAL LETTER G WITH CARON

              -

              0x01E6

              -

              0x0B

              -

              G LATIN CAPITAL LETTER G WITH BREVE

              - -

              Ø LATIN CAPITAL LETTER O WITH STROKE

              -

              0x00D8

              -

              0x0B

              -

              Ø LATIN CAPITAL LETTER O WITH STROKE

              -               - -

              g LATIN SMALL LETTER G WITH BREVE

              -

              0x011F

              -

              0x0C

              -

              g LATIN SMALL LETTER G WITH BREVE

              - -

              ø LATIN SMALL LETTER O WITH STROKE

              -

              0x00F8

              -

              0x0C

              -

              ø LATIN SMALL LETTER O WITH STROKE

              -               - -

              g LATIN SMALL LETTER G WITH CARON

              -

              0x01E7

              -

              0x0C

              -

              g LATIN SMALL LETTER G WITH BREVE

              - -

              (FORM FEED)

              -

              0x000C

              -

              0x1B0A

              -

              (PAGE BREAK)

              -               - -

              S LATIN CAPITAL LETTER S WITH CEDILLA *

              -

              0x015E

              -

              0x1C

              -

              S LATIN CAPITAL LETTER S WITH CEDILLA *

              - -

              € EURO SIGN

              -

              0x20AC

              -

              0x1B65

              -

              € EURO SIGN

              -               - -

              s LATIN SMALL LETTER S WITH CEDILLA *

              -

              0x015F

              -

              0x1D

              -

              s LATIN SMALL LETTER S WITH CEDILLA *

              - -

              Æ LATIN CAPITAL LETTER AE

              -

              0x00C6

              -

              0x1C

              -

              Æ LATIN CAPITAL LETTER AE

              -               - -

              I LATIN CAPITAL LETTER I WITH DOT ABOVE

              -

              0x0130

              -

              0x40

              -

              I LATIN CAPITAL LETTER I WITH DOT ABOVE

              - -

              æ LATIN SMALL LETTER AE

              -

              0x00E6

              -

              0x1D

              -

              æ LATIN SMALL LETTER AE

              -               - -

              ç LATIN SMALL LETTER C WITH CEDILLA

              -

              0x00E7

              -

              0x60

              -

              ç LATIN SMALL LETTER C WITH CEDILLA

              - -

              ¡ INVERTED EXCLAMATION MARK

              -

              0x00A1

              -

              0x40

              -

              ¡ INVERTED EXCLAMATION MARK

              -               - - - - - - -

              ¿ INVERTED QUESTION MARK

              -

              0x00BF

              -

              0x60

              -

              ¿ INVERTED QUESTION MARK

              -               -               - -

              Turkish Locking -Single Converter vs. Standard SMS Converter – GSM Code to Unicode

              Table -3B

              - - - -

              Turkish Locking Single Converter

              -

               -

               -

               -

               -

              Standard SMS Converter

              -

               -

               -

               -               - -

              Character

              -

              GSM

              -

              Unicode

              -

              Converted Character

              -

               -

              Character

              -

              GSM

              -

              Unicode

              -

              Converted Character

              -               - -

              € EURO SIGN

              -

              0x04

              -

              0x20AC

              -

              € EURO SIGN

              - -

              è LATIN SMALL LETTER E WITH GRAVE

              -

              0x04

              -

              0x00E8

              -

              è LATIN SMALL LETTER E WITH GRAVE

              -               - -

              i LATIN SMALL LETTER DOTLESS

              -

              0x07

              -

              0x0131

              -

              i LATIN SMALL LETTER DOTLESS

              - -

              ì LATIN SMALL LETTER I WITH GRAVE

              -

              0x07

              -

              0x00EC

              -

              ì LATIN SMALL LETTER I WITH GRAVE

              -               - -

              Ç LATIN CAPITAL LETTER C WITH CEDILLA

              -

              0x09

              -

              0x00C7

              -

              Ç LATIN CAPITAL LETTER C WITH CEDILLA

              - -

              Ç LATIN CAPITAL LETTER C WITH CEDILLA

              -

              0x09

              -

              0x00E7

              -

              ç LATIN SMALL LETTER C WITH CEDILLA

              -               - -

              G LATIN CAPITAL LETTER G WITH BREVE

              -

              0x0B

              -

              0x011E

              -

              G LATIN CAPITAL LETTER G WITH BREVE

              - -

              Ø LATIN CAPITAL LETTER O WITH STROKE

              -

              0x0B

              -

              0x00D8

              -

              Ø LATIN CAPITAL LETTER O WITH STROKE

              -               - -

              g LATIN SMALL LETTER G WITH BREVE

              -

              0x0C

              -

              0x011F

              -

              g LATIN SMALL LETTER G WITH BREVE

              - -

              ø LATIN SMALL LETTER O WITH STROKE

              -

              0x0C

              -

              0x00F8

              -

              ø LATIN SMALL LETTER O WITH STROKE

              -               - - -

              0x1B04

              -

              0x20AC

              -

              € EURO SIGN

              - - -

              0x1B04

              -

              0x00E8

              -

              è LATIN SMALL LETTER E WITH GRAVE

              -               - - -

              0x1B07

              -

              0x0131

              -

              i LATIN SMALL LETTER DOTLESS

              - - -

              0x1B07

              -

              0x00EC

              -

              ì LATIN SMALL LETTER I WITH GRAVE

              -               - - -

              0x1B0B

              -

              0x011E

              -

              G LATIN CAPITAL LETTER G WITH BREVE

              - - -

              0x1B0B

              -

              0x00D8

              -

              Ø LATIN CAPITAL LETTER O WITH STROKE

              -               - - -

              0x1B0C

              -

              0x011F

              -

              g LATIN SMALL LETTER G WITH CARON

              - - -

              0x1B0C

              -

              0x00F8

              -

              ø LATIN SMALL LETTER O WITH STROKE

              -               - - -

              0x1B1C

              -

              0x015E

              -

              S LATIN CAPITAL LETTER S WITH CEDILLA *

              - - -

              0x1B1C

              -

              0x00C6

              -

              Æ LATIN CAPITAL LETTER AE (ash) *

              -               - - -

              0x1B1D

              -

              0x015F

              -

              ç LATIN SMALL LETTER C WITH CEDILLA *

              - - -

              0x1B1D

              -

              0x00E6

              -

              æ LATIN SMALL LETTER AE (ash) *

              -               - - -

              0x1B47

              -

              0x011E

              -

              G LATIN CAPITAL LETTER G WITH BREVE

              - - -

              0x1B47

              -

              0x0047

              -

              G LATIN CAPITAL LETTER G

              -               - - -

              0x1B49

              -

              0x0130

              -

              I LATIN CAPITAL LETTER I WITH DOT ABOVE

              - - -

              0x1B49

              -

              0x0049

              -

              I LATIN CAPITAL LETTER I

              -               - - -

              0x1B53

              -

              0x015E

              -

              S LATIN CAPITAL LETTER S WITH CEDILLA *

              - - -

              0x1B53

              -

              0x0053

              -

              S LATIN CAPITAL LETTER S

              -               - - -

              0x1B60

              -

              0x00E7

              -

              ç LATIN SMALL LETTER C WITH CEDILLA

              - - -

              0x1B60

              -

              0x00BF

              -

              ¿ INVERTED QUESTION MARK

              -               - - -

              0x1B67

              -

              0x011F

              -

              g LATIN SMALL LETTER G WITH BREVE

              - - -

              0x1B67

              -

              0x0067

              -

              g LATIN SMALL LETTER G

              -               - - -

              0x1B69

              -

              0x0131

              -

              i LATIN SMALL LETTER DOTLESS

              - - -

              0x1B69

              -

              0x0069

              -

              i LATIN SMALL LETTER I

              -               - -

              S LATIN CAPITAL LETTER S WITH CEDILLA *

              -

              0x1C

              -

              0x015E

              -

              S LATIN CAPITAL LETTER S WITH CEDILLA *

              - -

              Æ LATIN CAPITAL LETTER AE

              -

              0x1C

              -

              0x00C6

              -

              Æ LATIN CAPITAL LETTER AE

              -               - -

              s LATIN SMALL LETTER S WITH CEDILLA *

              -

              0x1D

              -

              0x015F

              -

              s LATIN SMALL LETTER S WITH CEDILLA *

              - -

              æ LATIN SMALL LETTER AE

              -

              0x1D

              -

              0x00E6

              -

              æ LATIN SMALL LETTER AE

              -               - -

              ç LATIN SMALL LETTER C WITH CEDILLA

              -

              0x60

              -

              0x00E7

              -

              ç LATIN SMALL LETTER C WITH CEDILLA

              - -

              ¿ INVERTED QUESTION MARK

              -

              0x60

              -

              0x00BF

              -

              ¿ INVERTED QUESTION MARK

              -               -               - -
              -
              See also

              SMS -Encodings and Converters Overview

              + + + + + +Turkish +National Language Support +

              This section describes the plug-in converters for Turkish national language +support and the alphabet each converter supports.

              +
              Introduction

              To convert a Turkish SMS message using +the National Language Encoding, Symbian provides three Turkish plug-in converters:

                +

              • Default GSM7 Turkish +Single Converter. The highlighted boxes in Figure 1 show that it supports +the default GSM 7-bit alphabet, the Turkish single shift alphabet and the +set of lossy conversions supported by the standard converter. This converter +is identified by the KCharacterSetIdentifierTurkishSingleSms7Bit UID, +which is defined in the charconv.h header file.

                Figure +1

                + Alphabet of the Default GSM7 Turkish Single Converter + + +
                • +

              • Turkish Locking GSM7 +Extension Converter. The highlighted boxes in Figure 2 show that it supports +the Turkish locking shift alphabet, default GSM extension alphabet and the +set of lossy conversions supported by the standard converter. This converter +is identified by the KCharacterSetIdentifierTurkishLockingSms7Bit UID, +which is defined in the charconv.h header file.

                Figure +2

                + Alphabet of the Turkish Locking GSM7 Extension Converter + + +
                • +

              • Turkish Locking Single +Converter. The highlighted boxes in Figure 3 show that it supports the Turkish +locking shift alphabet, Turkish single shift alphabet and the set of lossy +conversions supported by the standard converter. This converter is identified +by the KCharacterSetIdentifierTurkishLockingAndSingleSms7Bit UID, +which is defined in the charconv.h header file.

                Figure +3

                + Alphabet of the Turkish Locking Single Converter + + +
                • +

              Note: For all of the converters, any undefined Unicode is +converted to a question mark (?)–GSM code 0x37. Any code +outside GSM 0x00 ~0x7F is converted to the +Unicode replacement character 0xFFFD.

              +
              Alphabet

              To +better understand the different character set of each converter, the Standard +SMS Converter is set as the baseline. The following comparison tables help +identify the different character set supported by each Turkish converter as +a comparison to the standard SMS converter.

              Table 1A Default GSM7 Turkish Single Converter vs. Standard SMS Converter +– Unicode to GSM Code

              Table +1B Default GSM7 Turkish Single Converter vs. Standard SMS Converter – GSM +Code to Unicode

              Table +2A Turkish Locking GSM7 Extension Converter vs. Standard SMS Converter – Unicode +to GSM Code

              Table +2B Turkish Locking GSM7 Extension Converter vs. Standard SMS Converter – GSM +Code to Unicode

              Table +3A Turkish Locking Single Converter vs. Standard SMS Converter – Unicode to +GSM Code

              Table +3B Turkish Locking Single Converter vs. Standard SMS Converter – GSM Code +to Unicode

              Default +GSM7 Turkish Single Converter vs. Standard SMS Converter – Unicode to GSM +Code

              Table 1A

              + + + +

              Default GSM7 Turkish Single Converter

              +

               +

               +

               + +

              Standard SMS Converter

              +

               +

               +

               +               + +

              Original Character

              +

              Unicode

              +

              GSM

              +

              Converted Character

              +

               +

              Character

              +

              Unicode

              +

              GSM

              +

              Converted Character

              +               + + + + + + +

              ç LATIN SMALL LETTER C WITH CEDILLA

              +

              0x00E7

              +

              0x09

              +

              Ç LATIN CAPITAL LETTER C WITH CEDILLA

              +               + +

              G LATIN CAPITAL LETTER G WITH BREVE

              +

              0x011E

              +

              0x1B47

              +

              G LATIN CAPITAL LETTER G WITH BREVE

              +

               

               + + + + +               + +

              G LATIN CAPITAL LETTER G WITH CARON

              +

              0x01E6

              +

              0x1B47

              +

              G LATIN CAPITAL LETTER G WITH BREVE

              + + + + + +               + +

              I LATIN CAPITAL LETTER I WITH DOT ABOVE

              +

              0x0130

              +

              0x1B49

              +

              I LATIN CAPITAL LETTER I WITH DOT ABOVE

              +

               

               + + + + +               + +

              S LATIN CAPITAL LETTER S WITH CEDILLA *

              +

              0x015E

              +

              0x1B53

              +

              S LATIN CAPITAL LETTER S WITH CEDILLA *

              +

               

               + + + + +               + +

              ç LATIN SMALL LETTER C WITH CEDILLA

              +

              0x00E7

              +

              0x1B63

              +

              ç LATIN SMALL LETTER C WITH CEDILLA

              +

               

               + + + + +               + +

              g LATIN SMALL LETTER G WITH BREVE

              +

              0x011F

              +

              0x1B67

              +

              g LATIN SMALL LETTER G WITH BREVE

              +

               

               + + + + +               + +

              g LATIN SMALL LETTER G WITH CARON

              +

              0x01E7

              +

              0x1B67

              +

              g LATIN SMALL LETTER G WITH BREVE

              + + + + + +               + +

              i LATIN SMALL LETTER DOTLESS

              +

              0x0131

              +

              0x1B69

              +

              i LATIN SMALL LETTER DOTLESS

              +

               

               + + + + +               + +

              s LATIN SMALL LETTER S WITH CEDILLA *

              +

              0x015F

              +

              0x1B73

              +

              s LATIN SMALL LETTER S WITH CEDILLA *

              +

               

               + + + + +               +               + +

              Default GSM7 +Turkish Single Converter vs. Standard SMS Converter – GSM Code to Unicode

              Table +1B

              + + + +

              Default GSM7 Turkish Single Converter

              +

               +

               +

               +

               +

              Standard SMS Converter

              +

               +

               +

               +               + +

              Character

              +

              GSM

              +

              Unicode

              +

              Converted Character

              +

               +

              Character

              +

              GSM

              +

              Unicode

              +

              Converted Character

              +               + +

              Ç LATIN CAPITAL LETTER C WITH CEDILLA

              +

              0x09

              +

              0x00C7

              +

              Ç LATIN CAPITAL LETTER C WITH CEDILLA

              + +

              Ç LATIN CAPITAL LETTER C WITH CEDILLA

              +

              0x09

              +

              0x00E7

              +

              ç LATIN SMALL LETTER C WITH CEDILLA

              +               + +

              FORM FEED

              +

              0x1B0A

              +

              0x000C

              +

              FORM FEED

              + +

              (PAGE BREAK)

              +

              0x1B0A

              +

              0x000C

              +

              (PAGE BREAK)

              +               + +

              G LATIN CAPITAL LETTER G WITH BREVE

              +

              0x1B47

              +

              0x011E

              +

              G LATIN CAPITAL LETTER G WITH BREVE

              + + +

              0x1B47

              +

              0x0047

              +

              G LATIN CAPITAL LETTER G

              +               + +

              I LATIN CAPITAL LETTER I WITH DOT ABOVE

              +

              0x1B49

              +

              0x0130

              +

              I LATIN CAPITAL LETTER I WITH DOT ABOVE

              + + +

              0x1B49

              +

              0x0049

              +

              I LATIN CAPITAL LETTER I

              +               + +

              S LATIN CAPITAL LETTER S WITH CEDILLA *

              +

              0x1B53

              +

              0x015E

              +

              S LATIN CAPITAL LETTER S WITH CEDILLA *

              + + +

              0x1B53

              +

              0x0053

              +

              S LATIN CAPITAL LETTER S

              +               + +

              g LATIN SMALL LETTER G WITH BREVE

              +

              0x1B67

              +

              0x011F

              +

              g LATIN SMALL LETTER G WITH BREVE

              + + +

              0x1B67

              +

              0x0067

              +

              g LATIN SMALL LETTER G

              +               + +

              i LATIN SMALL LETTER DOTLESS

              +

              0x1B69

              +

              0x0131

              +

              i LATIN SMALL LETTER DOTLESS

              + + +

              0x1B69

              +

              0x0069

              +

              i LATIN SMALL LETTER I

              +               + +

              s LATIN SMALL LETTER S WITH CEDILLA *

              +

              0x1B73

              +

              0x015F

              +

              s LATIN SMALL LETTER S WITH CEDILLA *

              + + +

              0x1B73

              +

              0x0073

              +

              s LATIN SMALL LETTER S

              +               +               + +

              Turkish Locking +GSM7 Extension Converter vs. Standard SMS Converter – Unicode to GSM Code

              Table +2A

              + + + +

              Turkish Locking GSM7 Extension Converter

              + +

               +

               +

               +

              Standard SMS Converter

              +

               +

               +

               +               + +

              Character

              +

              Unicode

              +

              GSM

              +

              Converted Character

              + +

              Character

              +

              Unicode

              +

              GSM

              +

              Converted Character

              +               + +

              € EURO SIGN

              +

              0x20AC

              +

              0x04

              +

              € EURO SIGN

              + +

              è LATIN SMALL LETTER E WITH GRAVE

              +

              0x00E8

              +

              0x04

              +

              è LATIN SMALL LETTER E WITH GRAVE

              +               + +

              i LATIN SMALL LETTER DOTLESS

              +

              0x0131

              +

              0x07

              +

              i LATIN SMALL LETTER DOTLESS

              + +

              ì LATIN SMALL LETTER I WITH GRAVE

              +

              0x00EC

              +

              0x07

              +

              ì LATIN SMALL LETTER I WITH GRAVE

              +               + +

              G LATIN CAPITAL LETTER G WITH BREVE

              +

              0x011E

              +

              0x0B

              +

              G LATIN CAPITAL LETTER G WITH BREVE

              + +

              ç LATIN SMALL LETTER C WITH CEDILLA

              +

              0x00E7

              +

              0x09

              +

              Ç LATIN CAPITAL LETTER C WITH CEDILLA

              +               + +

              G LATIN CAPITAL LETTER G WITH CARON

              +

              0x01E6

              +

              0x0B

              +

              G LATIN CAPITAL LETTER G WITH BREVE

              + +

              Ø LATIN CAPITAL LETTER O WITH STROKE

              +

              0x00D8

              +

              0x0B

              +

              Ø LATIN CAPITAL LETTER O WITH STROKE

              +               + +

              g LATIN SMALL LETTER G WITH BREVE

              +

              0x011F

              +

              0x0C

              +

              g LATIN SMALL LETTER G WITH BREVE

              + +

              ø LATIN SMALL LETTER O WITH STROKE

              +

              0x00F8

              +

              0x0C

              +

              ø LATIN SMALL LETTER O WITH STROKE

              +               + +

              g LATIN SMALL LETTER G WITH CARON

              +

              0x01E7

              +

              0x0C

              +

              g LATIN SMALL LETTER G WITH BREVE

              + +

              (FORM FEED)

              +

              0x000C

              +

              0x1B0A

              +

              (PAGE BREAK)

              +               + +

              S LATIN CAPITAL LETTER S WITH CEDILLA *

              +

              0x015E

              +

              0x1C

              +

              S LATIN CAPITAL LETTER S WITH CEDILLA *

              + +

              € EURO SIGN

              +

              0x20AC

              +

              0x1B65

              +

              € EURO SIGN

              +               + +

              S LATIN CAPITAL LETTER S WITH CEDILLA *

              +

              0x015F

              +

              0x1D

              +

              S LATIN CAPITAL LETTER S WITH CEDILLA *

              + +

              Æ LATIN CAPITAL LETTER AE

              +

              0x00C6

              +

              0x1C

              +

              Æ LATIN CAPITAL LETTER AE

              +               + +

              I LATIN CAPITAL LETTER I WITH DOT ABOVE

              +

              0x0130

              +

              0x40

              +

              I LATIN CAPITAL LETTER I WITH DOT ABOVE

              + +

              æ LATIN SMALL LETTER AE

              +

              0x00E6

              +

              0x1D

              +

              æ LATIN SMALL LETTER AE

              +               + +

              ç LATIN SMALL LETTER C WITH CEDILLA

              +

              0x00E7

              +

              0x60

              +

              ç LATIN SMALL LETTER C WITH CEDILLA

              + +

              ¡ INVERTED EXCLAMATION MARK

              +

              0x00A1

              +

              0x40

              +

              ¡ INVERTED EXCLAMATION MARK

              +               + + + + + + +

              Í LATIN CAPITAL LETTER I WITH ACUTE

              +

              0x00CD

              +

              0x49

              +

              I LATIN CAPITAL LETTER I

              +               + + + + + + +

              ¿ INVERTED QUESTION MARK

              +

              0x00BF

              +

              0x60

              +

              ¿ INVERTED QUESTION MARK

              +               +               + +

              Turkish Locking +GSM7 Extension Converter vs. Standard SMS Converter – GSM Code to Unicode

              Table +2B

              + + + +

              Turkish Locking GSM7 Extension Converter

              + +

               +

               +

               +

              Standard SMS Converter

              +

               +

               +

               +               + +

              Character

              +

              GSM

              +

              Unicode

              +

              Converted Character

              +

               +

              Character

              +

              GSM

              +

              Unicode

              +

              Converted Character

              +               + +

              Ç LATIN CAPITAL LETTER C WITH CEDILLA

              +

              0x09

              +

              0x00C7

              +

              Ç LATIN CAPITAL LETTER C WITH CEDILLA

              + +

              Ç LATIN CAPITAL LETTER C WITH CEDILLA

              +

              0x09

              +

              0x00E7

              +

              ç LATIN SMALL LETTER C WITH CEDILLA

              +               + +

              G LATIN CAPITAL LETTER G WITH BREVE

              +

              0x0B

              +

              0x011E

              +

              G LATIN CAPITAL LETTER G WITH BREVE

              + +

              Ø LATIN CAPITAL LETTER O WITH STROKE

              +

              0x0B

              +

              0x00D8

              +

              Ø LATIN CAPITAL LETTER O WITH STROKE

              +               + +

              g LATIN SMALL LETTER G WITH BREVE

              +

              0x0C

              +

              0x011F

              +

              g LATIN SMALL LETTER G WITH BREVE

              + +

              ø LATIN SMALL LETTER O WITH STROKE

              +

              0x0C

              +

              0x00F8

              +

              ø LATIN SMALL LETTER O WITH STROKE

              +               + + +

              0x1B07

              +

              0x0131

              +

              i LATIN SMALL LETTER DOTLESS

              + + +

              0x1B07

              +

              0x00EC

              +

              ì LATIN SMALL LETTER I WITH GRAVE

              +               + + +

              0x1B0A

              +

              0x000C

              +

              (FORM FEED)

              + +

              (PAGE BREAK)

              +

              0x1B0A

              +

              0x000C

              +

              (PAGE BREAK)

              +               + + +

              0x1B0B

              +

              0x011E

              +

              G LATIN CAPITAL LETTER G WITH BREVE

              + + +

              0x1B0B

              +

              0x00D8

              +

              Ø LATIN CAPITAL LETTER O WITH STROKE

              +               + + +

              0x1B0C

              +

              0x011F

              +

              g LATIN SMALL LETTER G WITH CARON

              + + +

              0x1B0C

              +

              0x00F8

              +

              ø LATIN SMALL LETTER O WITH STROKE

              +               + + +

              0x1B1C

              +

              0x015E

              +

              S LATIN CAPITAL LETTER S WITH CEDILLA *

              + + +

              0x1B1C

              +

              0x00C6

              +

              Æ LATIN CAPITAL LETTER AE (ash) *

              +               + + +

              0x1B1D

              +

              0x015F

              +

              s LATIN SMALL LETTER S WITH CEDILLA *

              + + +

              0x1B1D

              +

              0x00E6

              +

              æ LATIN SMALL LETTER AE (ash) *

              +               + + +

              0x1B60

              +

              0x00E7

              +

              ç LATIN SMALL LETTER C WITH CEDILLA

              + + +

              0x1B60

              +

              0x00BF

              +

              ¿ INVERTED QUESTION MARK

              +               + +

              S LATIN CAPITAL LETTER S WITH CEDILLA *

              +

              0x1C

              +

              0x015E

              +

              S LATIN CAPITAL LETTER S WITH CEDILLA *

              + +

              Æ LATIN CAPITAL LETTER AE

              +

              0x1C

              +

              0x00C6

              +

              Æ LATIN CAPITAL LETTER AE

              +               + +

              s LATIN SMALL LETTER S WITH CEDILLA *

              +

              0x1D

              +

              0x015F

              +

              s LATIN SMALL LETTER S WITH CEDILLA *

              + +

              æ LATIN SMALL LETTER AE

              +

              0x1D

              +

              0x00E6

              +

              æ LATIN SMALL LETTER AE

              +               + +

              I LATIN CAPITAL LETTER I WITH DOT ABOVE

              +

              0x40

              +

              0x0130

              +

              I LATIN CAPITAL LETTER I WITH DOT ABOVE

              + +

              ¡ INVERTED EXCLAMATION MARK

              +

              0x40

              +

              0x00A1

              +

              ¡ INVERTED EXCLAMATION MARK

              +               +               + +

              Turkish Locking +Single Converter vs. Standard SMS Converter – Unicode to GSM Code

              Table +3A

              + + + +

              Turkish Locking Single Converter

              +

               +

               +

               +

               +

              Standard SMS Converter

              +

               +

               +

               +               + +

              Character

              +

              Unicode

              +

              GSM

              +

              Converted Character

              +

               +

              Character

              +

              Unicode

              +

              GSM

              +

              Converted Character

              +               + +

              € EURO SIGN

              +

              0x20AC

              +

              0x04

              +

              € EURO SIGN

              + +

              è LATIN SMALL LETTER E WITH GRAVE

              +

              0x00E8

              +

              0x04

              +

              è LATIN SMALL LETTER E WITH GRAVE

              +               + +

              i LATIN SMALL LETTER DOTLESS

              +

              0x0131

              +

              0x07

              +

              i LATIN SMALL LETTER DOTLESS

              + +

              ì LATIN SMALL LETTER I WITH GRAVE

              +

              0x00EC

              +

              0x07

              +

              ì LATIN SMALL LETTER I WITH GRAVE

              +               + +

              G LATIN CAPITAL LETTER G WITH BREVE

              +

              0x011E

              +

              0x0B

              +

              G LATIN CAPITAL LETTER G WITH BREVE

              + +

              ç LATIN SMALL LETTER C WITH CEDILLA

              +

              0x00E7

              +

              0x09

              +

              Ç LATIN CAPITAL LETTER C WITH CEDILLA

              +               + +

              G LATIN CAPITAL LETTER G WITH CARON

              +

              0x01E6

              +

              0x0B

              +

              G LATIN CAPITAL LETTER G WITH BREVE

              + +

              Ø LATIN CAPITAL LETTER O WITH STROKE

              +

              0x00D8

              +

              0x0B

              +

              Ø LATIN CAPITAL LETTER O WITH STROKE

              +               + +

              g LATIN SMALL LETTER G WITH BREVE

              +

              0x011F

              +

              0x0C

              +

              g LATIN SMALL LETTER G WITH BREVE

              + +

              ø LATIN SMALL LETTER O WITH STROKE

              +

              0x00F8

              +

              0x0C

              +

              ø LATIN SMALL LETTER O WITH STROKE

              +               + +

              g LATIN SMALL LETTER G WITH CARON

              +

              0x01E7

              +

              0x0C

              +

              g LATIN SMALL LETTER G WITH BREVE

              + +

              (FORM FEED)

              +

              0x000C

              +

              0x1B0A

              +

              (PAGE BREAK)

              +               + +

              S LATIN CAPITAL LETTER S WITH CEDILLA *

              +

              0x015E

              +

              0x1C

              +

              S LATIN CAPITAL LETTER S WITH CEDILLA *

              + +

              € EURO SIGN

              +

              0x20AC

              +

              0x1B65

              +

              € EURO SIGN

              +               + +

              s LATIN SMALL LETTER S WITH CEDILLA *

              +

              0x015F

              +

              0x1D

              +

              s LATIN SMALL LETTER S WITH CEDILLA *

              + +

              Æ LATIN CAPITAL LETTER AE

              +

              0x00C6

              +

              0x1C

              +

              Æ LATIN CAPITAL LETTER AE

              +               + +

              I LATIN CAPITAL LETTER I WITH DOT ABOVE

              +

              0x0130

              +

              0x40

              +

              I LATIN CAPITAL LETTER I WITH DOT ABOVE

              + +

              æ LATIN SMALL LETTER AE

              +

              0x00E6

              +

              0x1D

              +

              æ LATIN SMALL LETTER AE

              +               + +

              ç LATIN SMALL LETTER C WITH CEDILLA

              +

              0x00E7

              +

              0x60

              +

              ç LATIN SMALL LETTER C WITH CEDILLA

              + +

              ¡ INVERTED EXCLAMATION MARK

              +

              0x00A1

              +

              0x40

              +

              ¡ INVERTED EXCLAMATION MARK

              +               + + + + + + +

              ¿ INVERTED QUESTION MARK

              +

              0x00BF

              +

              0x60

              +

              ¿ INVERTED QUESTION MARK

              +               +               + +

              Turkish Locking +Single Converter vs. Standard SMS Converter – GSM Code to Unicode

              Table +3B

              + + + +

              Turkish Locking Single Converter

              +

               +

               +

               +

               +

              Standard SMS Converter

              +

               +

               +

               +               + +

              Character

              +

              GSM

              +

              Unicode

              +

              Converted Character

              +

               +

              Character

              +

              GSM

              +

              Unicode

              +

              Converted Character

              +               + +

              € EURO SIGN

              +

              0x04

              +

              0x20AC

              +

              € EURO SIGN

              + +

              è LATIN SMALL LETTER E WITH GRAVE

              +

              0x04

              +

              0x00E8

              +

              è LATIN SMALL LETTER E WITH GRAVE

              +               + +

              i LATIN SMALL LETTER DOTLESS

              +

              0x07

              +

              0x0131

              +

              i LATIN SMALL LETTER DOTLESS

              + +

              ì LATIN SMALL LETTER I WITH GRAVE

              +

              0x07

              +

              0x00EC

              +

              ì LATIN SMALL LETTER I WITH GRAVE

              +               + +

              Ç LATIN CAPITAL LETTER C WITH CEDILLA

              +

              0x09

              +

              0x00C7

              +

              Ç LATIN CAPITAL LETTER C WITH CEDILLA

              + +

              Ç LATIN CAPITAL LETTER C WITH CEDILLA

              +

              0x09

              +

              0x00E7

              +

              ç LATIN SMALL LETTER C WITH CEDILLA

              +               + +

              G LATIN CAPITAL LETTER G WITH BREVE

              +

              0x0B

              +

              0x011E

              +

              G LATIN CAPITAL LETTER G WITH BREVE

              + +

              Ø LATIN CAPITAL LETTER O WITH STROKE

              +

              0x0B

              +

              0x00D8

              +

              Ø LATIN CAPITAL LETTER O WITH STROKE

              +               + +

              g LATIN SMALL LETTER G WITH BREVE

              +

              0x0C

              +

              0x011F

              +

              g LATIN SMALL LETTER G WITH BREVE

              + +

              ø LATIN SMALL LETTER O WITH STROKE

              +

              0x0C

              +

              0x00F8

              +

              ø LATIN SMALL LETTER O WITH STROKE

              +               + + +

              0x1B04

              +

              0x20AC

              +

              € EURO SIGN

              + + +

              0x1B04

              +

              0x00E8

              +

              è LATIN SMALL LETTER E WITH GRAVE

              +               + + +

              0x1B07

              +

              0x0131

              +

              i LATIN SMALL LETTER DOTLESS

              + + +

              0x1B07

              +

              0x00EC

              +

              ì LATIN SMALL LETTER I WITH GRAVE

              +               + + +

              0x1B0B

              +

              0x011E

              +

              G LATIN CAPITAL LETTER G WITH BREVE

              + + +

              0x1B0B

              +

              0x00D8

              +

              Ø LATIN CAPITAL LETTER O WITH STROKE

              +               + + +

              0x1B0C

              +

              0x011F

              +

              g LATIN SMALL LETTER G WITH CARON

              + + +

              0x1B0C

              +

              0x00F8

              +

              ø LATIN SMALL LETTER O WITH STROKE

              +               + + +

              0x1B1C

              +

              0x015E

              +

              S LATIN CAPITAL LETTER S WITH CEDILLA *

              + + +

              0x1B1C

              +

              0x00C6

              +

              Æ LATIN CAPITAL LETTER AE (ash) *

              +               + + +

              0x1B1D

              +

              0x015F

              +

              ç LATIN SMALL LETTER C WITH CEDILLA *

              + + +

              0x1B1D

              +

              0x00E6

              +

              æ LATIN SMALL LETTER AE (ash) *

              +               + + +

              0x1B47

              +

              0x011E

              +

              G LATIN CAPITAL LETTER G WITH BREVE

              + + +

              0x1B47

              +

              0x0047

              +

              G LATIN CAPITAL LETTER G

              +               + + +

              0x1B49

              +

              0x0130

              +

              I LATIN CAPITAL LETTER I WITH DOT ABOVE

              + + +

              0x1B49

              +

              0x0049

              +

              I LATIN CAPITAL LETTER I

              +               + + +

              0x1B53

              +

              0x015E

              +

              S LATIN CAPITAL LETTER S WITH CEDILLA *

              + + +

              0x1B53

              +

              0x0053

              +

              S LATIN CAPITAL LETTER S

              +               + + +

              0x1B60

              +

              0x00E7

              +

              ç LATIN SMALL LETTER C WITH CEDILLA

              + + +

              0x1B60

              +

              0x00BF

              +

              ¿ INVERTED QUESTION MARK

              +               + + +

              0x1B67

              +

              0x011F

              +

              g LATIN SMALL LETTER G WITH BREVE

              + + +

              0x1B67

              +

              0x0067

              +

              g LATIN SMALL LETTER G

              +               + + +

              0x1B69

              +

              0x0131

              +

              i LATIN SMALL LETTER DOTLESS

              + + +

              0x1B69

              +

              0x0069

              +

              i LATIN SMALL LETTER I

              +               + +

              S LATIN CAPITAL LETTER S WITH CEDILLA *

              +

              0x1C

              +

              0x015E

              +

              S LATIN CAPITAL LETTER S WITH CEDILLA *

              + +

              Æ LATIN CAPITAL LETTER AE

              +

              0x1C

              +

              0x00C6

              +

              Æ LATIN CAPITAL LETTER AE

              +               + +

              s LATIN SMALL LETTER S WITH CEDILLA *

              +

              0x1D

              +

              0x015F

              +

              s LATIN SMALL LETTER S WITH CEDILLA *

              + +

              æ LATIN SMALL LETTER AE

              +

              0x1D

              +

              0x00E6

              +

              æ LATIN SMALL LETTER AE

              +               + +

              ç LATIN SMALL LETTER C WITH CEDILLA

              +

              0x60

              +

              0x00E7

              +

              ç LATIN SMALL LETTER C WITH CEDILLA

              + +

              ¿ INVERTED QUESTION MARK

              +

              0x60

              +

              0x00BF

              +

              ¿ INVERTED QUESTION MARK

              +               +               + +
              +
              See also

              SMS +Encodings and Converters Overview

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-739556F5-A2F3-5548-943C-7D50785DFB48_d0e360653_href.png Binary file Symbian3/SDK/Source/GUID-739556F5-A2F3-5548-943C-7D50785DFB48_d0e360653_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-739556F5-A2F3-5548-943C-7D50785DFB48_d0e366733_href.png Binary file Symbian3/SDK/Source/GUID-739556F5-A2F3-5548-943C-7D50785DFB48_d0e366733_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-73A431EF-44CA-5E62-AF3F-1601CFD2484F_d0e323663_href.jpg Binary file Symbian3/SDK/Source/GUID-73A431EF-44CA-5E62-AF3F-1601CFD2484F_d0e323663_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-73A431EF-44CA-5E62-AF3F-1601CFD2484F_d0e329820_href.jpg Binary file Symbian3/SDK/Source/GUID-73A431EF-44CA-5E62-AF3F-1601CFD2484F_d0e329820_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7461BD6A-F50B-5E14-8995-CF3F2D8F5F14-master.png Binary file Symbian3/SDK/Source/GUID-7461BD6A-F50B-5E14-8995-CF3F2D8F5F14-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7461BD6A-F50B-5E14-8995-CF3F2D8F5F14_d0e382693_href.png Binary file Symbian3/SDK/Source/GUID-7461BD6A-F50B-5E14-8995-CF3F2D8F5F14_d0e382693_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-74B329CD-4640-5636-9D8D-20F0D7E09EB4_d0e189164_href.png Binary file Symbian3/SDK/Source/GUID-74B329CD-4640-5636-9D8D-20F0D7E09EB4_d0e189164_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-74B329CD-4640-5636-9D8D-20F0D7E09EB4_d0e194226_href.png Binary file Symbian3/SDK/Source/GUID-74B329CD-4640-5636-9D8D-20F0D7E09EB4_d0e194226_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-74F1EBB6-293A-4B33-A08F-46F3C23B37CE.dita --- a/Symbian3/SDK/Source/GUID-74F1EBB6-293A-4B33-A08F-46F3C23B37CE.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-74F1EBB6-293A-4B33-A08F-46F3C23B37CE.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,30 +1,29 @@ - - - - - -Adaptive -search -

              Adaptive Search is an application independent Find -pane based filtering method for known content. The content may be presented -in list or grid format.

              -

              The search selects the characters, symbols and numbers from the items of -known content, and displays them in a grid format on top of the content. User -is able to select them one by one and content is filtered to show matching -items accordingly.

              - -Adaptive search - - -
              Using -adaptive search in C++ applications

              The APIs to use for adaptive -search is the Searchfield API which is used for providing the -searchfield component and has been extended to include the adaptive search -functionality.

              + + + + + +Adaptive +search +

              Adaptive Search is an application independent Find +pane based filtering method for known content. The content may be presented +in list or grid format.

              +

              The search selects the characters, symbols and numbers from the items of +known content, and displays them in a grid format on top of the content. User +is able to select them one by one and content is filtered to show matching +items accordingly.

              + +Adaptive search + + +
              Using +adaptive search in applications

              The APIs to use for +adaptive search is the Searchfield API which is used for providing the searchfield +component and has been extended to include the adaptive search functionality.

               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7501D3AC-16FB-58E9-B55C-2598ECCD2FFA-master.png Binary file Symbian3/SDK/Source/GUID-7501D3AC-16FB-58E9-B55C-2598ECCD2FFA-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7501D3AC-16FB-58E9-B55C-2598ECCD2FFA_d0e381250_href.png Binary file Symbian3/SDK/Source/GUID-7501D3AC-16FB-58E9-B55C-2598ECCD2FFA_d0e381250_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-75553219-500C-487F-8D7E-0FAF48CF1872.dita --- a/Symbian3/SDK/Source/GUID-75553219-500C-487F-8D7E-0FAF48CF1872.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-75553219-500C-487F-8D7E-0FAF48CF1872.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,36 +1,44 @@ - - - - - -Submenus -

              An item in the Options menu can be a submenu title, leading to additional -choices that are displayed in another pop-up window (on top of the Options -menu pop-up window) as a submenu.

              - -Submenu in the Options menu - - -

              The submenu is opened by pressing either the left softkey (Select), -the Selection key, or the Arrow right key.

              -

              The user can close the submenu window by pressing the Arrow left key. The -main menu window remains open, with the focus on the submenu title.

              -

              When an item in a submenu is selected, both the submenu and main menu windows -are closed.

              -

              The following rules apply to submenus:

              -
                -

              • The number of items should be low, so that the user does not need to -scroll in order to see all of them.

                • -

              • Functions should not occur sometimes in the main level and at other -times in a submenu. Items that are in a submenu should always be found in -the same submenu.

                • -

              • Only one submenu level is allowed; that is, a submenu cannot contain -another submenu.

                • -
              + + + + + +Submenus +

              An item in the Options menu can be a submenu title, leading to additional +choices that are displayed in another pop-up window (on top of the Options +menu pop-up window) as a submenu.

              + +Submenu in the Options menu + + +

              The submenu is opened by pressing either the left softkey (Select), +the Selection key, or the Arrow right key. In touch enabled device, submenu +is displayed with touch down and release on the Options menu item. +Scrolling and selecting within submenu window is done as in Options menu.

              +

              The user can close the submenu window when:

                +

              • Arrow left key is pressed.

                • +

              • touch is moved to another menu list item.

                • +

              • touch down and release from the Options menu item that it was +launched from.

                • +

              • touch down anywhere outside the submenu window.

                • +

              +

              The main menu window remains open, with the focus on the submenu title.

              +

              When an item in a submenu is selected, both the submenu and main menu windows +are closed.

              +

              The following rules apply to submenus:

              +
                +

              • The number of items should be low, so that the user does not need to +scroll in order to see all of them.

                • +

              • Functions should not occur sometimes in the main level and at other +times in a submenu. Items that are in a submenu should always be found in +the same submenu.

                • +

              • Only one submenu level is allowed; that is, a submenu cannot contain +another submenu.

                • +
               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7594A012-166F-5F10-A3ED-256465B4623E-GENID-1-8-1-18-1-1-4-1-8-1.dita --- a/Symbian3/SDK/Source/GUID-7594A012-166F-5F10-A3ED-256465B4623E-GENID-1-8-1-18-1-1-4-1-8-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,27 +0,0 @@ - - - - - -S60 -Platform: Image Converter Example -
              Description

              This example demonstrates how to use -the image conversion APIs available in the S60 platform (Image Conversion -Library, ICL). These APIs include important classes, such as CBitmapRotator -and CBitmapScaler to be used for rotating and scaling images, respectively. -CImageEncoder and CImageDecoder classes are used to access image encoders -and decoders available in the ICL. Images can be opened, rotated, scaled, -and saved in the same or a different format. The UI of the updated application -has been optimised for touch using, for example, long taps and tactile feedback. -The example project supports building for both S60 5th Edition with touch -UI and S60 3rd Edition with a traditional keypad. For more information, click -on this link : Image Converter Example

              -
              Download

              Click on the following link to download -the example: ImageConverter.zip file

              Click: browse to view the example code.

              -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7594A012-166F-5F10-A3ED-256465B4623E-GENID-1-8-1-18-1-1-5-1-6-1-5-1-4-1.dita --- a/Symbian3/SDK/Source/GUID-7594A012-166F-5F10-A3ED-256465B4623E-GENID-1-8-1-18-1-1-5-1-6-1-5-1-4-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,27 +0,0 @@ - - - - - -S60 -Platform: Image Converter Example -
              Description

              This example demonstrates how to use -the image conversion APIs available in the S60 platform (Image Conversion -Library, ICL). These APIs include important classes, such as CBitmapRotator -and CBitmapScaler to be used for rotating and scaling images, respectively. -CImageEncoder and CImageDecoder classes are used to access image encoders -and decoders available in the ICL. Images can be opened, rotated, scaled, -and saved in the same or a different format. The UI of the updated application -has been optimised for touch using, for example, long taps and tactile feedback. -The example project supports building for both S60 5th Edition with touch -UI and S60 3rd Edition with a traditional keypad. For more information, click -on this link : Image Converter Example

              -
              Download

              Click on the following link to download -the example: ImageConverter.zip file

              Click: browse to view the example code.

              -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7594A012-166F-5F10-A3ED-256465B4623E.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-7594A012-166F-5F10-A3ED-256465B4623E.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,24 @@ + + + + + +Image +Converter Example +
              Description

              This +example demonstrates how to use the image conversion APIs available in the +Image Conversion Library). These APIs include important classes, such as CBitmapRotator and CBitmapScaler to +be used for rotating and scaling images, respectively. CImageEncoder and CImageDecoder, +classes are used to access image encoders and decoders available in the ICL. +Images can be opened, rotated, scaled, and saved in the same or a different +format.

              +
              Download

              Click +on the following link to download the example: ImageConverter.zip file

              Click: browse to view the example code.

              +
              Class Summary

              CBitmapRotator

              CBitmapScaler

              CImageEncoder

              CImageDecoder

              +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-75A70663-4DF2-4055-BF3E-8D9D8D0FEFB3.dita --- a/Symbian3/SDK/Source/GUID-75A70663-4DF2-4055-BF3E-8D9D8D0FEFB3.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-75A70663-4DF2-4055-BF3E-8D9D8D0FEFB3.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,31 +1,31 @@ - - - - - -Discarding -soft notifications -

              The application that launched a soft notification can discard it without -user intervention when the notification becomes obsolete. A soft notification -should remain pending until the user has responded to it, or started using -the corresponding application so that in effect the notification becomes obsolete. -In that case, the application can discard the notification even though the -user may not have actually seen it.

              -

              When the user reacts to a soft notification by pressing the left softkey -(for example Read), or selects one item of a grouped soft notification, the -item becomes interpreted as obsolete, and will not reappear. If a soft notification -contained more than one item, the other ones remain pending and reappear when -the user returns to the Idle state.

              -

              The user can dismiss the notification by pressing the right softkey, labeled -Exit. After this, the notification does not reappear until new events cause -a new notification to be created. In case of a grouped soft notification, -all items it contains are discarded.

              -

              Please note that discarding a soft notification does not mean that the -received content is lost.

              + + + + + +Discarding +soft notifications +

              The application that launched a soft notification can discard it without +user intervention when the notification becomes obsolete. A soft notification +should remain pending until the user has responded to it, or started using +the corresponding application so that in effect the notification becomes obsolete. +In that case, the application can discard the notification even though the +user may not have actually seen it.

              +

              When the user reacts to a soft notification by pressing the left softkey +(for example Read), or selects one item of a grouped soft notification, the +item becomes interpreted as obsolete, and will not reappear. If a soft notification +contained more than one item, the other ones remain pending and reappear when +the user returns to the home screen.

              +

              The user can dismiss the notification by pressing the right softkey, labeled +Exit. After this, the notification does not reappear until new events cause +a new notification to be created. In case of a grouped soft notification, +all items it contains are discarded.

              +

              Please note that discarding a soft notification does not mean that the +received content is lost.

               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-762A665F-43D0-53ED-B698-0CBD3AC46391.dita --- a/Symbian3/SDK/Source/GUID-762A665F-43D0-53ED-B698-0CBD3AC46391.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-762A665F-43D0-53ED-B698-0CBD3AC46391.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,23 +1,23 @@ - - - - - -Font and Text -Services CollectionThe Font and Text Services Collection contains the Font Store and -related plug-ins and the Text Rendering component. Application developers -can select fonts from the Font Store. Device creators can create and add fonts. - - The Font and Text Services collection - - - -Font and -Bitmap Server Component + + + + + +Font and Text +Services CollectionThe Font and Text Services Collection contains the Font Store and +related plug-ins and the Text Rendering component. Application developers +can select fonts from the Font Store. Device creators can create and add fonts. + + The Font and Text Services collection + + + +Font and +Bitmap Server Component \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-768CCC6E-16D2-50E8-8EED-EB2C2AF0E9BE.dita --- a/Symbian3/SDK/Source/GUID-768CCC6E-16D2-50E8-8EED-EB2C2AF0E9BE.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-768CCC6E-16D2-50E8-8EED-EB2C2AF0E9BE.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,99 +1,99 @@ - - - - - -Overview -

              The SIP Client Resolver defines the architecture used to resolve or identify -the target client when SIP requests are received from the default port. The -Symbian SIP stack is implemented as a Symbian server and uses the default -UDP and TCP port 5060 to send and receive SIP messages. Many applications -or target clients receive SIP messages that use the default port, and the -correct target client must be determined.

              -

              The SIP Client Resolver determines the target client based on the SIP request -and the XML-description provided by every SIP Client Resolver API implementation. -It requests the resolved ECOM plug-in to connect to the SIP or another server -which uses SIP.

              -
              Architectural relationships

              The Client Resolver -API requires the SIP Codec API and the SIP Codec API.

              The target clients -that receive SIP requests must implement the API Client Resolver API. The -following are the two methods in which a target client can receive SIP requests:

                -

              • Implement the CSIPResolvedClient -interface and provide an XML description with their capabilities

                The -XML description describes the supported content-types and media formats that -use SIP headers and SDP m-lines in the ECOM resource file. Client Resolver -framework determines the target client by comparing the incoming SIP request -to the XML descriptions provided by the CSIPResolvedClient implementation.

                • -

              • Implement the CSIPResolvedClient2 interface -and add Request-URIs user-part, plug-ins UID, and the client UID to the SIP -Client Resolver mapping table in the Central Repository

                The table -maps the user-part of the incoming SIP request’s Request-URI to the related CSIPResolvedClient2 implementation’s -UID. SIP Client Resolver framework gives the SIP request to only the plug-ins -for which a mapping entry is found in the Central Repository.

                • -

              This implies that every target client must provide an ECOM plug-in -that is used by the Client Resolver Framework. The Client Resolver Framework -uses the information in the SIP request and matches it with the XML description -or the mapping table entry provided by the target clients. It then decides -which target client plug-in to load.

              -
              Class structure

              SIP Client Resolver must create -a class derived from CSIPResolvedClient or CSIPResolvedClient2 to -receive requests outside the SIP dialogs. If the target client is not running, -it must be started to enable it to receive SIP requests.

              - -

              CSIPResolvedClient

              The target clients must implement -the CSIPResolvedClient interface to receive SIP requests -outside SIP dialogs and enable the client resolution mechanism.

              SIP -uses the data provided in the ECOM resource file or, as requested by the implementation -to decide which target client is used.

              CSIPResolvedClient2

              The -target clients must implement the CSIPResolvedClient2 interface -to receive SIP requests outside SIP dialogs and enable the client resolution -mechanism.

              The SIP stack uses the plug-ins that implement this interface -as follows:

                -

              1. If the SIP request does -not contain the Accept-Contact-header, go to step 2. If it does, the SIP stack -calls the CSIPResolvedClient2::MatchAcceptContactsL() method -on all the plug-ins and applies the following logic:

                  -

                • If none of the clients -match, go to step 2.

                  • -

                • If one of the clients -match, send the SIP request to the matching client.

                  • -

                • If more than one of -the clients match, go to step 2.

                  • -
                2. -

              2. If the SIP request does -not contain the Event-header, go to step 3. If it does, SIP stack calls the CSIPResolvedClient2::MatchEventL() method -on all the plug-ins and applies the following logic:

                  -

                • If none of the clients -match, go to step 3.

                  • -

                • If one of the clients -match, send the SIP request to the matching client.

                  • -

                • If more than one of -the clients match, go to step 3.

                  • -
                3. -

              3. The SIP stack calls -the CSIPResolvedClient2::MatchRequestL() method on all -the plug-ins and applies the following logic:

                  -

                • If none of the clients -match, an error response is generated.

                  • -

                • If one of the clients -matches, send the SIP request to the matching client.

                  • -

                • If more than one of -the clients match, one of the client is randomly selected and the SIP request -is sent to it. Normally, the ROM-based clients are preferred.

                  • -
                4. -

              The channel UIDs must be unique across all SIP clients. The clients -may use UIDs assigned for the binaries.

              -               -How - the target client is resolved using CSIPResolvedClient - -How - the target client is resolved using CSIPResolvedClient2 - + + + + + +Overview +

              The SIP Client Resolver defines the architecture used to resolve or identify +the target client when SIP requests are received from the default port. The +Symbian SIP stack is implemented as a Symbian server and uses the default +UDP and TCP port 5060 to send and receive SIP messages. Many applications +or target clients receive SIP messages that use the default port, and the +correct target client must be determined.

              +

              The SIP Client Resolver determines the target client based on the SIP request +and the XML-description provided by every SIP Client Resolver API implementation. +It requests the resolved ECOM plug-in to connect to the SIP or another server +which uses SIP.

              +
              Architectural relationships

              The Client Resolver +API requires the SIP Codec API and the SIP Codec API.

              The target clients +that receive SIP requests must implement the API Client Resolver API. The +following are the two methods in which a target client can receive SIP requests:

                +

              • Implement the CSIPResolvedClient +interface and provide an XML description with their capabilities

                The +XML description describes the supported content-types and media formats that +use SIP headers and SDP m-lines in the ECOM resource file. Client Resolver +framework determines the target client by comparing the incoming SIP request +to the XML descriptions provided by the CSIPResolvedClient implementation.

                • +

              • Implement the CSIPResolvedClient2 interface +and add Request-URIs user-part, plug-ins UID, and the client UID to the SIP +Client Resolver mapping table in the Central Repository

                The table +maps the user-part of the incoming SIP request’s Request-URI to the related CSIPResolvedClient2 implementation’s +UID. SIP Client Resolver framework gives the SIP request to only the plug-ins +for which a mapping entry is found in the Central Repository.

                • +

              This implies that every target client must provide an ECOM plug-in +that is used by the Client Resolver Framework. The Client Resolver Framework +uses the information in the SIP request and matches it with the XML description +or the mapping table entry provided by the target clients. It then decides +which target client plug-in to load.

              +
              Class structure

              SIP Client Resolver must create +a class derived from CSIPResolvedClient or CSIPResolvedClient2 to +receive requests outside the SIP dialogs. If the target client is not running, +it must be started to enable it to receive SIP requests.

              + +

              CSIPResolvedClient

              The target clients must implement +the CSIPResolvedClient interface to receive SIP requests +outside SIP dialogs and enable the client resolution mechanism.

              SIP +uses the data provided in the ECOM resource file or, as requested by the implementation +to decide which target client is used.

              CSIPResolvedClient2

              The +target clients must implement the CSIPResolvedClient2 interface +to receive SIP requests outside SIP dialogs and enable the client resolution +mechanism.

              The SIP stack uses the plug-ins that implement this interface +as follows:

                +

              1. If the SIP request does +not contain the Accept-Contact-header, go to step 2. If it does, the SIP stack +calls the CSIPResolvedClient2::MatchAcceptContactsL() method +on all the plug-ins and applies the following logic:

                  +

                • If none of the clients +match, go to step 2.

                  • +

                • If one of the clients +match, send the SIP request to the matching client.

                  • +

                • If more than one of +the clients match, go to step 2.

                  • +
                2. +

              2. If the SIP request does +not contain the Event-header, go to step 3. If it does, SIP stack calls the CSIPResolvedClient2::MatchEventL() method +on all the plug-ins and applies the following logic:

                  +

                • If none of the clients +match, go to step 3.

                  • +

                • If one of the clients +match, send the SIP request to the matching client.

                  • +

                • If more than one of +the clients match, go to step 3.

                  • +
                3. +

              3. The SIP stack calls +the CSIPResolvedClient2::MatchRequestL() method on all +the plug-ins and applies the following logic:

                  +

                • If none of the clients +match, an error response is generated.

                  • +

                • If one of the clients +matches, send the SIP request to the matching client.

                  • +

                • If more than one of +the clients match, one of the client is randomly selected and the SIP request +is sent to it. Normally, the ROM-based clients are preferred.

                  • +
                4. +

              The channel UIDs must be unique across all SIP clients. The clients +may use UIDs assigned for the binaries.

              +               +How + the target client is resolved using CSIPResolvedClient + +How + the target client is resolved using CSIPResolvedClient2 +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-76901D63-BDA2-4DCA-A66C-7BAFD7E211EB_d0e57233_href.png Binary file Symbian3/SDK/Source/GUID-76901D63-BDA2-4DCA-A66C-7BAFD7E211EB_d0e57233_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-76901D63-BDA2-4DCA-A66C-7BAFD7E211EB_d0e68916_href.png Binary file Symbian3/SDK/Source/GUID-76901D63-BDA2-4DCA-A66C-7BAFD7E211EB_d0e68916_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-76901D63-BDA2-4DCA-A66C-7BAFD7E211EB_d0e74059_href.png Binary file Symbian3/SDK/Source/GUID-76901D63-BDA2-4DCA-A66C-7BAFD7E211EB_d0e74059_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-76B4C4D2-75A5-4139-9186-23443C68CD8F_d0e36126_href.png Binary file Symbian3/SDK/Source/GUID-76B4C4D2-75A5-4139-9186-23443C68CD8F_d0e36126_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-76B4C4D2-75A5-4139-9186-23443C68CD8F_d0e41693_href.png Binary file Symbian3/SDK/Source/GUID-76B4C4D2-75A5-4139-9186-23443C68CD8F_d0e41693_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-76D01385-17CD-5F9A-B3B5-88D77773AA8E-GENID-1-8-1-18-1-1-4-1-6-1.dita --- a/Symbian3/SDK/Source/GUID-76D01385-17CD-5F9A-B3B5-88D77773AA8E-GENID-1-8-1-18-1-1-4-1-6-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,34 +0,0 @@ - - - - - -ICLCodec: -Image Converter Library encoder/decoder plug-ins example -
              Description

              ICLCodec demonstrates -how to implement encoder and decoder plug-ins for the Image Converter Library. -A decoder converts an image in a particular format into a CFbsBitmap object; -an encoder does the reverse. In the example, the Portable Network Graphics -(PNG) format is handled.

              The program is an ECom plug-in that implements:

                -

              • the decoder plug-in -interface CImageDecoderPlugin by the class CPngDecoder

                • -

              • the decoder data reader -interface CImageReadCodec by the class CPngReadCodec

                • -

              • the encoder plug-in -interface CImageEncoderPlugin by the class CPngEncoder

                • -

              • the encoder data writer -interface CImageWriteCodec by the class CPngWriteCodec

                • -

              The PNG format allows data to be stored in a number of different -scanline formats (colour/grey-scale depths), so specialist classes are provided -to read and write these formats. Scanline reader classes are derived from CPngReadSubCodec; -writer classes from CPngWriteSubCodec.

              -
              Download

              Click -on the following link to download the example: ICLCodec.zip file

              Click: browse to view the example code.

              -
              Class summary

              CImageDecoderPlugin CImageReadCodec CImageEncoderPlugin CImageWriteCodec

              -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-76D01385-17CD-5F9A-B3B5-88D77773AA8E-GENID-1-8-1-18-1-1-5-1-6-1-5-1-5-1.dita --- a/Symbian3/SDK/Source/GUID-76D01385-17CD-5F9A-B3B5-88D77773AA8E-GENID-1-8-1-18-1-1-5-1-6-1-5-1-5-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,34 +0,0 @@ - - - - - -ICLCodec: -Image Converter Library encoder/decoder plug-ins example -
              Description

              ICLCodec demonstrates -how to implement encoder and decoder plug-ins for the Image Converter Library. -A decoder converts an image in a particular format into a CFbsBitmap object; -an encoder does the reverse. In the example, the Portable Network Graphics -(PNG) format is handled.

              The program is an ECom plug-in that implements:

                -

              • the decoder plug-in -interface CImageDecoderPlugin by the class CPngDecoder

                • -

              • the decoder data reader -interface CImageReadCodec by the class CPngReadCodec

                • -

              • the encoder plug-in -interface CImageEncoderPlugin by the class CPngEncoder

                • -

              • the encoder data writer -interface CImageWriteCodec by the class CPngWriteCodec

                • -

              The PNG format allows data to be stored in a number of different -scanline formats (colour/grey-scale depths), so specialist classes are provided -to read and write these formats. Scanline reader classes are derived from CPngReadSubCodec; -writer classes from CPngWriteSubCodec.

              -
              Download

              Click -on the following link to download the example: ICLCodec.zip file

              Click: browse to view the example code.

              -
              Class summary

              CImageDecoderPlugin CImageReadCodec CImageEncoderPlugin CImageWriteCodec

              -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-76D01385-17CD-5F9A-B3B5-88D77773AA8E.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-76D01385-17CD-5F9A-B3B5-88D77773AA8E.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,34 @@ + + + + + +ICLCodec: +Image Converter Library encoder/decoder plug-ins example +
              Description

              ICLCodec demonstrates +how to implement encoder and decoder plug-ins for the Image Converter Library. +A decoder converts an image in a particular format into a CFbsBitmap object; +an encoder does the reverse. In the example, the Portable Network Graphics +(PNG) format is handled.

              The program is an ECom plug-in that implements:

                +

              • the decoder plug-in +interface CImageDecoderPlugin by the class CPngDecoder

                • +

              • the decoder data reader +interface CImageReadCodec by the class CPngReadCodec

                • +

              • the encoder plug-in +interface CImageEncoderPlugin by the class CPngEncoder

                • +

              • the encoder data writer +interface CImageWriteCodec by the class CPngWriteCodec

                • +

              The PNG format allows data to be stored in a number of different +scanline formats (colour/grey-scale depths), so specialist classes are provided +to read and write these formats. Scanline reader classes are derived from CPngReadSubCodec; +writer classes from CPngWriteSubCodec.

              +
              Download

              Click +on the following link to download the example: ICLCodec.zip file

              Click: browse to view the example code.

              +
              Class summary

              CImageDecoderPlugin CImageReadCodec CImageEncoderPlugin CImageWriteCodec

              +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-76FD2A71-E8A3-4C82-9704-3F7F6AD4DFD8.dita --- a/Symbian3/SDK/Source/GUID-76FD2A71-E8A3-4C82-9704-3F7F6AD4DFD8.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-76FD2A71-E8A3-4C82-9704-3F7F6AD4DFD8.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,138 +1,134 @@ - - - - - -Navi -pane -

              The principal uses of the Navi pane are to display information about the -current state and view, and to help the user to navigate in the application.

              - -Navi pane - - -

              Depending on the context, the Navi pane contains elements presented in -the following table.

              -Possible Navi -pane content - - - -Component -Description - - - - -

              Tabs

               -

              Tabs are used to view parallel data views alternatively. Arrow indicators -are shown at both ends of the pane when there are further tabs to scroll in -the corresponding direction. Each tab has either a graphic or a text (or both) -as a label. The following tab layouts can be used:

                -

              • Two tabs

                • -

              • Three tabs

                • -

              • Four tabs

                • -

              • Two long tabs

                • -

              • Three long tabs (stacked so that only one is fully visible at a time)

                • -
              The currently active tab is highlighted.

              More than four tabs can -exist simultaneously. They can be scrolled horizontally. However, as a design -guideline, the number of tabs should be kept small (the maximum of six tabs -is recommended), and the number should not be dynamic. See Navigation -using tabs for -a description of the effect of tabs on the navigation within an application.

               -               - -

              Navigation text (icon+text)

              - -               -

              Navigation text is displayed in the Navi pane when -similar items can be browsed by scrolling horizontally, such as dates in Calendar. -Arrow indicators at both ends of the pane indicate the possibility to scroll.

               -               - -

              Indicators

              - -               -

              In editors, the Navi pane contains editing -indicators. See Indicators for -a more detailed description of the Navi pane indicators.

               -               - -

              Folder structure indication

              - -               -

              Opened subfolders are indicated in the Navi pane.

               -               - -

              Application-specific content

               -

              When none of the above content types is suitable, the Navi -pane content can be designed specifically for an application.

               -               - - -

              Empty pane

              - -               -

              The Navi pane can be empty.

               -               - - -
              -

              -Default touch -events for ungrouped soft notification - - - - - - -

              User action

               -

              State change

               -

              Feedback

               -               - - - -

              Touch down on navigation text or navigation arrow

               -

              Application specific

               -

              Tactile: In case of activity, basic button effect and audio feedback -is provided.

               -               - -

              Touch down and hold on navigation text

               -

              Inactive

               -

              Tactile: No effect

               -               - -

              Touch down and hold on arrows

               -

              This action performs a “key repeat”, similar to many touch downs -and releases on arrow

               -

              Tactile: Sensitive button effect and audio feedback is provided -with key repeat action.

               -               - -

              Touch release

               -

              No effect

               -

              Tactile: No effect

               -               - - -
              -

              Using -the navi pane in C++ applications

              The API to use for the Navi pane -is the Navigation pane API. If you use tabs in the Navi pane, -the API for controlling the tabs is the Tabs API.

              For the indicators in the Navi pane, use -the Indicators API.

              For implementation information on the Navi pane, -see Using the Navigation pane API. For implementation information -on tabs, see Using the Tabs API.

              The class MAknNaviDecoratorObserver provides touch support -for the tab arrows in the Navi pane. To set the observer, use the method CAknNavigationDecorator::SetNaviDecoratorObserver().

              To create a tab group in the Navi pane, use the -method CreateTabGroupL() in the class CAknNavigationControlContainer. This is a factory -method for a pre-implemented navigation pane tab group control.

              + + + + + +Navi +pane +

              The principal uses of the Navi pane are to display information about the +current state and view, and to help the user to navigate in the application.

              + +Navi pane + + +

              Depending on the context, the Navi pane contains elements presented in +the following table.

              +Possible Navi +pane content + + + +Component +Description + + + + +

              Tabs

               +

              Tabs are used to view parallel data views alternatively. Arrow indicators +are used only for navigation texts.

              Each tab has either a graphic or +a text (or both) as a label. The following tab layouts can be used:

                +

              • Two tabs

                • +

              • Three tabs

                • +

              • Four tabs

                • +

              • Two long tabs

                • +

              • Three long tabs (stacked so that only one is fully visible at a time)

                • +
              The currently active tab is highlighted.

              More than four tabs can +exist simultaneously. They can be scrolled horizontally. However, as a design +guideline, the number of tabs should be kept small (the maximum of six tabs +is recommended), and the number should not be dynamic. See for +a description of the effect of tabs on the navigation within an application.

               +               + +

              Navigation text (icon+text)

              + +               +

              Navigation text is displayed in the Navi pane when +similar items can be browsed by scrolling horizontally, such as dates in Calendar. +Arrow indicators at both ends of the pane indicate the possibility to scroll.

               +               + +

              Indicators

              + +               +

              In editors, the Navi pane contains editing +indicators. See Indicators for +a more detailed description of the Navi pane indicators.

               +               + +

              Folder structure indication

              + +               +

              Opened sub-folders are indicated in the Navi pane.

               +               + +

              Application-specific content

               +

              When none of the above content types is suitable, the Navi +pane content can be designed specifically for an application.

               +               + +

              Empty pane

              + +               +

              The Navi pane can be empty.

               +               + + +
              +

              +Default touch +events for ungrouped soft notification + + + +

              User action

               +

              State change

               +

              Feedback

               +               + + + +

              Touch down on navigation text or navigation arrow

               +

              Application specific

               +

              Tactile: In case of activity, basic button effect and audio feedback +is provided.

               +               + +

              Touch down and hold on navigation text

               +

              Inactive

               +

              Tactile: No effect

               +               + +

              Touch down and hold on arrows

               +

              This action performs a “key repeat”, similar to many touch downs +and releases on arrow

               +

              Tactile: Sensitive button effect and audio feedback is provided +with key repeat action.

               +               + +

              Touch release

               +

              No effect

               +

              Tactile: No effect

               +               + + +
              +

              Using +the navi pane in applications

              The API to use for the Navi pane is +the Navigation pane API. If you use tabs in the Navi pane, +the API for controlling the tabs is the Tabs API. Applications can implement an observer to handle +the touch events in the Navi pane area.

              For the indicators +in the Navi pane, use the Indicators API.

              For implementation information +on the Navi pane, see Using the Navigation pane API. For implementation information +on tabs, see Using the Tabs API.

              The MAknNaviDecoratorObserver class +provides touch support for the tab arrows in the Navi pane. To set the observer, +use the CAknNavigationDecorator::SetNaviDecoratorObserver() method.

              To +create a tab group in the Navi pane, use the CAknNavigationControlContainer::CreateTabGroupL(). +This is a factory method for a pre-implemented navigation pane tab group control.

               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7712BAB3-5F48-5A28-9EA9-104D8B4A0431_d0e333424_href.png Binary file Symbian3/SDK/Source/GUID-7712BAB3-5F48-5A28-9EA9-104D8B4A0431_d0e333424_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7712BAB3-5F48-5A28-9EA9-104D8B4A0431_d0e339581_href.png Binary file Symbian3/SDK/Source/GUID-7712BAB3-5F48-5A28-9EA9-104D8B4A0431_d0e339581_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-771AF721-E2D7-41C8-BF97-5BD30D1A28AD.dita --- a/Symbian3/SDK/Source/GUID-771AF721-E2D7-41C8-BF97-5BD30D1A28AD.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-771AF721-E2D7-41C8-BF97-5BD30D1A28AD.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,92 +1,106 @@ - - - - - - Status -pane -

              The Status pane displays status information of the current application -and state, as well as general information about the device status, such as -signal strength and battery charge. The Status pane may also be totally left -out in certain applications or situations.

              -

              There are three different variations of the Status pane:

                -

              • Normal status pane (includes both Title and Navi pane).

                • -

              • Flat status pane (includes only the Title pane).

                • -

              • Thin status pane (special status pane used, for example, in the Browser -application)

                • -
              Flat and thin Status panes can be used in cases where it is important -to maximize Main pane area (for example, Browser).

              -

              The Status pane contains the following sub-panes:

              -
                -

              • Title pane

                • -

              • Navi pane

                • -

              • Signal pane

                • -

              • Battery pane

                • -

              • Universal indicator pane

                • -
              - -Status pane areas - - -
              Using -the status pane in C++ applications

              The API to use for the status -pane is the Status pane API. For implementation information, see Using the status pane API.

              Use the Status pane API -for the following tasks:

                -

              • Creating the status pane using a resource file

                • -

              • Accessing the status pane

                • -

              • Accessing controls in the status pane's subpanes

                • -

              • Showing and hiding the status pane

                • -

              • Dynamically changing status pane layout

                • -

              • Observing status pane events

                • -

              Applications can define and modify the title and navi sub-panes. For -implementation information on the sub-panes in the status pane, see the following -APIs:

                -

              • Title pane API for the title pane

                • -

              • Navigation pane API for the navi pane

                • -

              Use the method CEikStatusPaneBase::IsAppOwned() in -the class CEikStatusPaneBase::TPaneCapabilities() to test -whether the pane is owned by the application or the server. Applications can -only interact directly with application owned subpanes.

              CEikStatusPane is -the interface through which applications use the status pane. This class synchronizes -the status pane layout with the server side status pane object. To do this, -the method CEikStatusPane::ApplyCurrentSettingsL() must -be called whenever the owner application switches to the foreground.

              Relationship between events/similar for entire status -pane and sub-panes: should be clearer on what's done where

              The -following options are available for modifying the default behavior of the -status pane:

                -

              • Since the status pane is a compound control, it can be made visible -or invisible like an other control with CCoeControl::MakeVisible(). CCoeControl::MakeVisible() can -be called before or after the control is activated. An example of a call to -make the status pane invisible is as follows:

                CEikStatusPane* sp = StatusPane();// Gets a pointer to the status pane in the UI controller -StatusPane()->MakeVisible(EFalse); //make pane invisible somewhere in your code
                • -

              • Accessing and modifying controls inside the status pane.

                The -Status Pane API provides methods for accessing the status pane control and -modifying the status pane layout.

                If you wish to modify panes within -the status pane, you need to get a pointer to the status pane and then use -one of the following classes and methods:

                  -

                • CAknTitlePane for -the title sub-pane

                  • -

                • Methods defined by the Navigation pane API for accessing the navi sub-pane

                  • -

                • The Tabs API for accessing tabs in the navi sub-pane.

                  • -
                • -

              • Defining new resources for the status pane to override the default -behavior

                Once you have defined your resources, you may need to use -some of the status pane APIs to achieve the desired effect in your application. -

                For more information, see the Status pane API and Navigation pane API reference documentation.

                • -

              • You can also derive your own classes from the available classes or -their base classes to customize your own controls.

                • -
              -

              For more information on the panes, refer the following:

               -               -Related APIs -Skins API - for providing themes support for the status pane - - + + + + + + Status pane +

              The Status pane displays status information of the current application +and state, as well as general information about the device status, +such as signal strength and battery charge. The Status pane may also +be totally left out in certain applications or situations.

              +

              There are three different variations of the Status pane:

                +

              • Normal status pane (includes both Title and Navi pane).

                • +

              • Flat status pane (includes only the Title pane).

                • +

              • Thin status pane (special status pane used, for example, in +the Browser application)

                • +
              Flat and thin Status panes can be used in cases where it is important +to maximize Main pane area (for example, Browser).

              +

              The Status pane contains the following sub-panes:

              +
                +

              • Battery pane

                • +

              • Clock pane

                • +

              • Navi pane

                • +

              • Signal pane

                • +

              • Title pane

                • +

              • Universal indicator pane

                • +
              + +Status pane areas + + +

              Status pane items

              +

              A single tap on:

              +
                +

              • Navi +pane: common items (such as tabs) should perform a function +that is obvious and clear. Common AVKON interaction does not change. +However, it an application can assign an appropriate function to its +Navi pane items. It is also possible not to assign any function where +appropriate.

                • +

              • Universal +indicator pane: opens a pop-up with more information on Status pane indicators. It always includes battery and signal indicators and +a small digital clock. The user can tap any of those for more information. +For each visible universal indicator, there is one row reserved in +the pop-up for displaying the icon and a description text. The description +text may also inform about the current status and/or it may be a link +to a view in corresponding application. For example, a tap on "3 new +messages" opens the relevant view from the messaging application, +and "Bluetooth active" switches view to the Bluetooth settings. Content +of the row is determined by the application originating the indicator.

                • +

              • Clock in the home screen opens the Clock application.

                • +
              +
              Using the status pane +in applications

              The API to use for the status pane is the Status pane API. For implementation information, +see Using the status pane API.

              Use the Status +pane API for the following tasks:

                +

              • Creating the status pane using a resource file

                • +

              • Accessing the status pane

                • +

              • Accessing controls in the status pane's subpanes

                • +

              • Showing and hiding the status pane

                • +

              • Dynamically changing status pane layout

                • +

              • Observing status pane events

                • +

              Applications can define and modify the title and navi sub-panes. +For implementation information on the sub-panes in the status pane, +see the following APIs:

                +

              • Title pane API for the title pane

                • +

              • Navigation pane API for the Navi pane

                • +

              CEikStatusPane is the interface through +which applications use the status pane. Use the method CEikStatusPaneBase::IsAppOwned() in the class CEikStatusPaneBase::TPaneCapabilities() to test whether the pane is owned by the application or the server. +Applications can only interact directly with application owned sub-panes.

              Relationship between events/similar +for entire status pane and sub-panes: should be clearer on what's +done where

              The following options are available +for modifying the default behavior of the status pane:

                +

              • Since the status pane is a compound control, it can be made +visible or invisible like an other control with CCoeControl::MakeVisible(). CCoeControl::MakeVisible() can be called before +or after the control is activated. An example of a call to make the +status pane invisible is as follows:

                CEikStatusPane* sp = StatusPane();// Gets a pointer to the status pane in the UI controller +StatusPane()->MakeVisible(EFalse); //make pane invisible somewhere in your code
                • +

              • Accessing and modifying controls inside the status pane.

                The Status Pane API provides methods for accessing the status +pane control and modifying the status pane layout.

                If you +want to modify panes within the status pane, you need to get a pointer +to the status pane and then use one of the following classes and methods:

                  +

                • CAknTitlePane for the title sub-pane

                  • +

                • Methods defined by the Navigation pane API for accessing the navi sub-pane

                  • +

                • The Tabs API for accessing tabs in the navi sub-pane.

                  • +
                • +

              • Defining new resources for the status pane to override the +default behavior

                Once you have defined your resources, you +may need to use some of the status pane APIs to achieve the desired +effect in your application.

                For more information, see the Status pane API and Navigation pane API reference documentation. +

                • +

              • You can also derive your own classes from the available classes +or their base classes to customize your own controls.

                • +

              For more information on the panes, refer the following:

              +               +Related APIs +Skins API + for providing themes support for the status pane + +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-773A0EDC-F17C-553B-BEC3-DA990F5064B7_d0e214491_href.png Binary file Symbian3/SDK/Source/GUID-773A0EDC-F17C-553B-BEC3-DA990F5064B7_d0e214491_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-773A0EDC-F17C-553B-BEC3-DA990F5064B7_d0e218228_href.png Binary file Symbian3/SDK/Source/GUID-773A0EDC-F17C-553B-BEC3-DA990F5064B7_d0e218228_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7767599C-7B77-5DD1-8E3E-7AD01EC6F6A1.dita --- a/Symbian3/SDK/Source/GUID-7767599C-7B77-5DD1-8E3E-7AD01EC6F6A1.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-7767599C-7B77-5DD1-8E3E-7AD01EC6F6A1.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,82 +1,82 @@ - - - - - -How to store a compound object

              The protocol for storing a compound object follows a standard pattern. However, the design of some compound objects may force deviations from this.

              A compound object can be stored either in-line or out-of-line.

              The basic protocol for storing is the StoreL() function. This is true whether the object is stored in-line or out-of-line and should be prototyped as:

              TStreamId StoreL(CStreamStore& aStore) const;

              The function takes a reference to the store in which the stream or stream network is to be stored and returns the stream ID through which the object can be restored later.

              Storing components in-line

              Storing a compound object’s component objects in-line means writing all of these components to the same stream.

              In general, this is achieved by defining and implementing a StoreL() member function for the compound object's class.

              For example, for a class CCompound defined as:

              CCompound class : public CBase - { - ... - TInt iDdata; - CComponentA* iCompA; - CComponentB* iCompB; - ... - }

              where CComponentA and CComponentB are classes, the object's component objects can be stored in the same stream as the remainder of the component's data. The StoreL() implementation is:

              TStreamId CCompound::StoreL(CStreamStore& aStore) - { - RStoreWriteStream outstream; - TStreamId id = outstream.CreateLC(aStore); // Creates the write stream - ExternalizeL(outstream); // Externalises the object and all of its components - outstream.CommitL(); // Commits the stream - CleanupStack::PopAndDestroy(); // Performs cleanup on the write stream object - return id; // Returns the stream ID - }

              ExternalizeL() externalises CCompound ’s data members and components; the implementation is:

              void CCompound::ExternalizeL(RWriteStream& aStream) const - { - aStream << iData; - aStream << *iCompA; - aStream << *iCompB; - }

              The stream can be visualised as:

              Storing components out-of-line

              Storing a compound object’s component objects out-of-line means writing all of its component objects to a different stream from that to which it, itself, is written. Each component may be written to its own stream or to its own network of streams. The main advantage of this is that it allows for deferred loading of streams.

              It is important to note that components are stored before the containing object.

              The following code fragment defines an example class, CCompound, having two components, CComponentA and CComponentB. The components are defined as instances of the templated class TSwizzle.

              CCompound class : public CBase - { - ... - TInt iDdata; - TSwizzle<CComponentA> iCompA; - TSwizzle<CComponentB> iCompB; - ... - }

              Storing is achieved by defining and implementing a StoreL() member function for the compound object's class. In this example, the StoreL() implementation is:

              TStreamId CCompound::StoreL(CStreamStore& aStore) - { - CStoreMap* map=CStoreMap::NewLC(aStore); - StoreComponentsL(*map); - RStoreWriteStream stream(*map); - TStreamId id=stream.CreateLC(aStore); - ExternalizeL(stream); - stream.CommitL(); - map->Reset(); - CleanupStack::PopAndDestroy(2); - return id; - }

              The StoreL() function:

              • writes the CCompound components to their own streams.

              • writes CCompound itself and its components’ stream IDs to a single stream.

              • returns the ID of the top-level stream.

              This can be visualised as:

              CCompound ’s components are stored to their own streams by defining and implementing a StoreComponentsL() member function; this is prototyped as:

              void StoreComponentsL(CStreamStore& aStore,CStoreMap& aMap)

              and implemented as:

              void CCompound::StoreComponentsL(CStreamStore& aStore,CStoreMap& aMap) - { - TStreamId id; - - if (iCompA) - { - id = iCompA->StoreL(aStore); // store component - aMap.BindL(iCompA,id); // connect the resulting stream id and component - } - if (iCompB) - { - id = iCompB->StoreL(aStore); // store component - aMap.BindL(iCompB,id); // connect the resulting stream id and component - } - }

              The condition: if (iCompA) is equivalent to: if - (iCompA.IsPtr()), and returns true only if the Swizzle represents the CComponentA object as a pointer. In an application where deferred loading is important, this allows for the possibility that the CComponentA object is not loaded when the attempt to store the CCompound object is made.

              Although each of CCompound's components are shown stored in their own respective single streams, they may be stored into their own respective network of streams and the resulting stream IDs may be the IDs of head streams. A component can consist of further components.

              StoreComponentsL() takes a reference to a store map, as well as the store. The store map is constructed by StoreL() and is used to contain the association between internal objects and stored components (represented in the store by their stream IDs). These IDs are written by CCompound's ExternalizeL() function and is implemented:

              void CCompound::ExternalizeL(RWriteStream& aStream) const - { - aStream << iDdata; - aStream << iCompA; - aStream << iCompB; - }

              This simplicity is due to RStoreWriteStream behaviour. The pointers are automatically looked up in the map associated with the stream, as they are being externalised.

              The store map must be reset before destroying it because the store map’s destructor deletes any streams from the store that are still referenced in the map. This means that, should a leave occur during the storing operation, any streams that have been written are automatically cleaned up.

              It is legitimate to define the CCompound class without using Swizzles. If the class is defined as:

              CCompound class : public CBase - { - ... - TInt iDdata; - CComponentA* iCompA; - CComponentB* iCompB; - ... - }

              then the implementations of CCompound::StoreL(), CCompound::StoreComponentsL() remain the same, but CCompound::ExternalizeL() has to change to:

              void CCompound::ExternalizeL(RWriteStream& aStream) const - { - aStream << iDdata; - aStream << *iCompA; - aStream << *iCompB; + + + + + +How to store a compound object

              The protocol for storing a compound object follows a standard pattern. However, the design of some compound objects may force deviations from this.

              A compound object can be stored either in-line or out-of-line.

              The basic protocol for storing is the StoreL() function. This is true whether the object is stored in-line or out-of-line and should be prototyped as:

              TStreamId StoreL(CStreamStore& aStore) const;

              The function takes a reference to the store in which the stream or stream network is to be stored and returns the stream ID through which the object can be restored later.

              Storing components in-line

              Storing a compound object’s component objects in-line means writing all of these components to the same stream.

              In general, this is achieved by defining and implementing a StoreL() member function for the compound object's class.

              For example, for a class CCompound defined as:

              CCompound class : public CBase + { + ... + TInt iDdata; + CComponentA* iCompA; + CComponentB* iCompB; + ... + }

              where CComponentA and CComponentB are classes, the object's component objects can be stored in the same stream as the remainder of the component's data. The StoreL() implementation is:

              TStreamId CCompound::StoreL(CStreamStore& aStore) + { + RStoreWriteStream outstream; + TStreamId id = outstream.CreateLC(aStore); // Creates the write stream + ExternalizeL(outstream); // Externalises the object and all of its components + outstream.CommitL(); // Commits the stream + CleanupStack::PopAndDestroy(); // Performs cleanup on the write stream object + return id; // Returns the stream ID + }

              ExternalizeL() externalises CCompound ’s data members and components; the implementation is:

              void CCompound::ExternalizeL(RWriteStream& aStream) const + { + aStream << iData; + aStream << *iCompA; + aStream << *iCompB; + }

              The stream can be visualised as:

              Storing components out-of-line

              Storing a compound object’s component objects out-of-line means writing all of its component objects to a different stream from that to which it, itself, is written. Each component may be written to its own stream or to its own network of streams. The main advantage of this is that it allows for deferred loading of streams.

              It is important to note that components are stored before the containing object.

              The following code fragment defines an example class, CCompound, having two components, CComponentA and CComponentB. The components are defined as instances of the templated class TSwizzle.

              CCompound class : public CBase + { + ... + TInt iDdata; + TSwizzle<CComponentA> iCompA; + TSwizzle<CComponentB> iCompB; + ... + }

              Storing is achieved by defining and implementing a StoreL() member function for the compound object's class. In this example, the StoreL() implementation is:

              TStreamId CCompound::StoreL(CStreamStore& aStore) + { + CStoreMap* map=CStoreMap::NewLC(aStore); + StoreComponentsL(*map); + RStoreWriteStream stream(*map); + TStreamId id=stream.CreateLC(aStore); + ExternalizeL(stream); + stream.CommitL(); + map->Reset(); + CleanupStack::PopAndDestroy(2); + return id; + }

              The StoreL() function:

              • writes the CCompound components to their own streams.

              • writes CCompound itself and its components’ stream IDs to a single stream.

              • returns the ID of the top-level stream.

              This can be visualised as:

              CCompound ’s components are stored to their own streams by defining and implementing a StoreComponentsL() member function; this is prototyped as:

              void StoreComponentsL(CStreamStore& aStore,CStoreMap& aMap)

              and implemented as:

              void CCompound::StoreComponentsL(CStreamStore& aStore,CStoreMap& aMap) + { + TStreamId id; + + if (iCompA) + { + id = iCompA->StoreL(aStore); // store component + aMap.BindL(iCompA,id); // connect the resulting stream id and component + } + if (iCompB) + { + id = iCompB->StoreL(aStore); // store component + aMap.BindL(iCompB,id); // connect the resulting stream id and component + } + }

              The condition: if (iCompA) is equivalent to: if + (iCompA.IsPtr()), and returns true only if the Swizzle represents the CComponentA object as a pointer. In an application where deferred loading is important, this allows for the possibility that the CComponentA object is not loaded when the attempt to store the CCompound object is made.

              Although each of CCompound's components are shown stored in their own respective single streams, they may be stored into their own respective network of streams and the resulting stream IDs may be the IDs of head streams. A component can consist of further components.

              StoreComponentsL() takes a reference to a store map, as well as the store. The store map is constructed by StoreL() and is used to contain the association between internal objects and stored components (represented in the store by their stream IDs). These IDs are written by CCompound's ExternalizeL() function and is implemented:

              void CCompound::ExternalizeL(RWriteStream& aStream) const + { + aStream << iDdata; + aStream << iCompA; + aStream << iCompB; + }

              This simplicity is due to RStoreWriteStream behaviour. The pointers are automatically looked up in the map associated with the stream, as they are being externalised.

              The store map must be reset before destroying it because the store map’s destructor deletes any streams from the store that are still referenced in the map. This means that, should a leave occur during the storing operation, any streams that have been written are automatically cleaned up.

              It is legitimate to define the CCompound class without using Swizzles. If the class is defined as:

              CCompound class : public CBase + { + ... + TInt iDdata; + CComponentA* iCompA; + CComponentB* iCompB; + ... + }

              then the implementations of CCompound::StoreL(), CCompound::StoreComponentsL() remain the same, but CCompound::ExternalizeL() has to change to:

              void CCompound::ExternalizeL(RWriteStream& aStream) const + { + aStream << iDdata; + aStream << *iCompA; + aStream << *iCompB; }

              However, this makes it more difficult to implement deferred loading.

              See also

              Store map

              Swizzles and deferred loading

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE-GENID-1-8-1-3-1-1-7-1-11-1.dita --- a/Symbian3/SDK/Source/GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE-GENID-1-8-1-3-1-1-7-1-11-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,145 +0,0 @@ - - - - - -How to -- Multiple screens -
              Contents
                -

              • Introduction

                • -

              • Configuration

                • -

              • Building the ROM image

                • -

              • Example Code

                • -

              • Limitations

                • -
              -
              Introduction

              Purpose and scope

              This -document explains how an application can draw to multiple screens. It is aimed -at a developer who is already familiar with creating a simple application -GUI. In this document, the CONE and WSERV interfaces that support multiple -screens are referred to.

              -
              How to create -multiple screens

              Configuration

              The -first screen is indexed as zero and the nth screen is indexed as n-1. The -changes below should be made to the wsini.ini file which -resides under \epoc32\data\z\system\data.

              [screen 0] -[screen 1] -[screen n-1]

              Building -the ROM image

              The secondary screen is supported through TV-OUT -on H4 board. The H4 base port only supports landscape mode with 16 bpp resolution. -The ROM image must be built with -DWITH_TVOUT as a parameter.

              Example Code

              Setup example code

              The -following code is the basis for the examples that follow.

              This is a wsini.ini file -used to create two fixed screens:

              AUTOCLEAR 1 -STARTUP \SYS\BIN\Start -WINDOWMODE COLOR64K -KEYCLICKPLUGIN KeyClickRef -TRANSPARENCY -MULTIFOCUSPOLICY -[screen 0] -[screen 1]

              This is a class CTRedControl, which -draws a rectangle on the second screen:

              const TInt KSndScreenNo = 1; - -class CTRedControl : public CCoeControl - { -public: - CTRedControl(){}; - ~CTRedControl(){}; - void ConstructL(RWindowGroup* aWinGp); - -private: // From CCoeControl - void Draw(const TRect& aRect) const; - }; - -void CTRedControl::ConstructL(RWindowGroup* aWinGp) - { - CreateWindowL(aWinGp); - SetExtent(TPoint(20,20),TSize(100,100)); - SetFocus(ETrue); - ActivateL(); - } - -void CTRedControl::Draw(const TRect& aRect) const - { - CWindowGc& gc=SystemGc(); - if (IsFocused()) - { - gc.SetPenColor(KRgbRed); - } - - gc.DrawRect(aRect); - }

              Windows -on multiple screens

              Using the above example code as a basis, the -following methods can be used to facilitate access to multiple screens:

              Class RWsSession provides -the interface to query WSERV about window groups on a particular screen and -the number of screens in the system. The application calls the function below -to get the number of screens supported on the phone:

              iCoeEnv->WsSession().NumberOfScreens();

              The class CWsScreenDevice provides the interface to -query the physical limitations of the screen and set the parameters of the -corresponding logical screen. The class RWindowGroup is the -client side handle to the server side window group. A pair of screen device -and window group is required to draw on a screen.

              CONE maintains an -array of screen devices and window groups. The screen number is used to index -this array to retrieve a particular window group and its corresponding screen -device.

              The application calls ScreenDevice() to get -the second screen device:

              iCoeEnv->ScreenDevice(KSndScreenNo);

              The -application calls RootWin() to get the window group on the -second screen:

              iCoeEnv->RootWin(KSndScreenNo);

              The -application calls NumWindowGroups( ) to -get the number of window groups with EAllPriorities on the -second screen:

              iCoeEnv->WsSession().NumWindowGroups(KSndScreenNo,EAllPriorities);

              The application creates a new list and then populates it with WindowGroupList() to -get the list of window groups with EAllPriorities on the -second screen:

              CArrayFixFlat<TInt>* list = new(ELeave) CArrayFixFlat<TInt>(1); -iCoeEnv->WsSession().WindowGroupList(list,KSndScreenNo,EAllPriorities);

              The -application calls GetFocusWindowGroup() to get the window -group that has the keyboard focus on the second screen:

              iCoeEnv->WsSession().GetFocusWindowGroup(KSndScreenNo);

              Each screen has a default owning window group. The application calls GetDefaultOwningWindow() to -get the default owning window group on the second screen:

              iCoeEnv ->WsSession().GetDefaultOwningWindow(KSndScreenNo);

              The application calls GetDefModeMaxNumColors() to get -the maximum colour and display mode supported on the second screen:

              TInt colour, grey; -iCoeEnv->WsSession().GetDefModeMaxNumColors(KSndScreenNo,colour,grey);

              The -application calls GetColorModeList() to get the list of colour -modes supported on the second screen:

              CArrayFixFlat<TInt>* list = new(Eleave) CArrayFixFlat<TInt>(1); -iCoeEnv ->WsSession().GetColorModeList(KSndScreenNo, list);

              Creating a control on a -particular screen

              A window group is associated with a screen device, -which in turn is associated to a screen. A control is associated with a window -group. Therefore a control is constructed on the second screen using the function -below, in the control’s ConstructL():

              CTRedControl redControl=new(Eleave) CTRedControl(); -redControl->ConstructL(CCoeEnv::Static()->RootWin(KSndScreenNo));

              Graphics Context

              The -class CWindowGc provides the interface for the application’s -window graphics context and can be activated on any window in the application. -This means that it can be used on any screen on the phone. The function call -below is used to find the screen device on which the graphics context was -last activated.

              CCoeEnv::Static()->SystemGc().Device();

              Window Group Focus Policy

              There -are two focus policies supported by WSERV. The default focus policy is that -there is only the focused window group on the focused screen receives key -events. The new policy is that any window group can receive key events and -can be switched on by defining the keyword MULTIFOCUSPOLICY in -the wsini.ini file.

              Limitations

              Pointer Events

              The -first screen created is also the primary screen in the system. It is important -to note that only the primary screen can respond to pointer events. This is -due to the fact that the kernel supports only one screen digitiser.

              Cone-Based UI

              Due -to limitations in the legacy implementation of Cone and the control sets implemented -on top of it (for example, Eikon, Avkon or Qikon), it is nearly impossible -to make the same application draw Cone-based UI on two different screens at -the same time. However, a secondary screen can be used to draw non-Cone-based -graphics (for example, a picture or PowerPoint slide-show, or a UI not using -Cone for its widgets). If it must appear as if an application supports displaying -itself on the secondary screen, then this can be done by moving that UI into -a second application instance. This second instance could be a server application -that only acts as a slave UI of the main application. In any case, that secondary -application instance would have to set the secondary screen as its default -screen. There are two main problems:

                -

              1. All controls have to -be associated with a window, and window owning controls do not currently try -to make sure that the window they create is associated with the screen that -they should appear on. This means, for example, that a pop-out window created -by a choice list widget will always appear on the application's primary screen, -rather than on the screen on which the choice list itself is located.

                2. -

              2. None of the legacy -widget implementations referencing the screen device take into consideration -that there might be more than one screen on the device. These include CCoeControl's SetExtentToWholeScreen(), SetCornerAndSize(), AccumulatedZoom(), PositionRelativeToScreen(), -and CEikAppUi's ClientRect() and ApplicationRect()).

                3. -

              Neither of these problems can be solved currently.

              -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE-GENID-1-8-1-6-1-1-4-1-6-1-11-1.dita --- a/Symbian3/SDK/Source/GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE-GENID-1-8-1-6-1-1-4-1-6-1-11-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,145 +0,0 @@ - - - - - -How to -- Multiple screens -
              Contents
                -

              • Introduction

                • -

              • Configuration

                • -

              • Building the ROM image

                • -

              • Example Code

                • -

              • Limitations

                • -
              -
              Introduction

              Purpose and scope

              This -document explains how an application can draw to multiple screens. It is aimed -at a developer who is already familiar with creating a simple application -GUI. In this document, the CONE and WSERV interfaces that support multiple -screens are referred to.

              -
              How to create -multiple screens

              Configuration

              The -first screen is indexed as zero and the nth screen is indexed as n-1. The -changes below should be made to the wsini.ini file which -resides under \epoc32\data\z\system\data.

              [screen 0] -[screen 1] -[screen n-1]

              Building -the ROM image

              The secondary screen is supported through TV-OUT -on H4 board. The H4 base port only supports landscape mode with 16 bpp resolution. -The ROM image must be built with -DWITH_TVOUT as a parameter.

              Example Code

              Setup example code

              The -following code is the basis for the examples that follow.

              This is a wsini.ini file -used to create two fixed screens:

              AUTOCLEAR 1 -STARTUP \SYS\BIN\Start -WINDOWMODE COLOR64K -KEYCLICKPLUGIN KeyClickRef -TRANSPARENCY -MULTIFOCUSPOLICY -[screen 0] -[screen 1]

              This is a class CTRedControl, which -draws a rectangle on the second screen:

              const TInt KSndScreenNo = 1; - -class CTRedControl : public CCoeControl - { -public: - CTRedControl(){}; - ~CTRedControl(){}; - void ConstructL(RWindowGroup* aWinGp); - -private: // From CCoeControl - void Draw(const TRect& aRect) const; - }; - -void CTRedControl::ConstructL(RWindowGroup* aWinGp) - { - CreateWindowL(aWinGp); - SetExtent(TPoint(20,20),TSize(100,100)); - SetFocus(ETrue); - ActivateL(); - } - -void CTRedControl::Draw(const TRect& aRect) const - { - CWindowGc& gc=SystemGc(); - if (IsFocused()) - { - gc.SetPenColor(KRgbRed); - } - - gc.DrawRect(aRect); - }

              Windows -on multiple screens

              Using the above example code as a basis, the -following methods can be used to facilitate access to multiple screens:

              Class RWsSession provides -the interface to query WSERV about window groups on a particular screen and -the number of screens in the system. The application calls the function below -to get the number of screens supported on the phone:

              iCoeEnv->WsSession().NumberOfScreens();

              The class CWsScreenDevice provides the interface to -query the physical limitations of the screen and set the parameters of the -corresponding logical screen. The class RWindowGroup is the -client side handle to the server side window group. A pair of screen device -and window group is required to draw on a screen.

              CONE maintains an -array of screen devices and window groups. The screen number is used to index -this array to retrieve a particular window group and its corresponding screen -device.

              The application calls ScreenDevice() to get -the second screen device:

              iCoeEnv->ScreenDevice(KSndScreenNo);

              The -application calls RootWin() to get the window group on the -second screen:

              iCoeEnv->RootWin(KSndScreenNo);

              The -application calls NumWindowGroups( ) to -get the number of window groups with EAllPriorities on the -second screen:

              iCoeEnv->WsSession().NumWindowGroups(KSndScreenNo,EAllPriorities);

              The application creates a new list and then populates it with WindowGroupList() to -get the list of window groups with EAllPriorities on the -second screen:

              CArrayFixFlat<TInt>* list = new(ELeave) CArrayFixFlat<TInt>(1); -iCoeEnv->WsSession().WindowGroupList(list,KSndScreenNo,EAllPriorities);

              The -application calls GetFocusWindowGroup() to get the window -group that has the keyboard focus on the second screen:

              iCoeEnv->WsSession().GetFocusWindowGroup(KSndScreenNo);

              Each screen has a default owning window group. The application calls GetDefaultOwningWindow() to -get the default owning window group on the second screen:

              iCoeEnv ->WsSession().GetDefaultOwningWindow(KSndScreenNo);

              The application calls GetDefModeMaxNumColors() to get -the maximum colour and display mode supported on the second screen:

              TInt colour, grey; -iCoeEnv->WsSession().GetDefModeMaxNumColors(KSndScreenNo,colour,grey);

              The -application calls GetColorModeList() to get the list of colour -modes supported on the second screen:

              CArrayFixFlat<TInt>* list = new(Eleave) CArrayFixFlat<TInt>(1); -iCoeEnv ->WsSession().GetColorModeList(KSndScreenNo, list);

              Creating a control on a -particular screen

              A window group is associated with a screen device, -which in turn is associated to a screen. A control is associated with a window -group. Therefore a control is constructed on the second screen using the function -below, in the control’s ConstructL():

              CTRedControl redControl=new(Eleave) CTRedControl(); -redControl->ConstructL(CCoeEnv::Static()->RootWin(KSndScreenNo));

              Graphics Context

              The -class CWindowGc provides the interface for the application’s -window graphics context and can be activated on any window in the application. -This means that it can be used on any screen on the phone. The function call -below is used to find the screen device on which the graphics context was -last activated.

              CCoeEnv::Static()->SystemGc().Device();

              Window Group Focus Policy

              There -are two focus policies supported by WSERV. The default focus policy is that -there is only the focused window group on the focused screen receives key -events. The new policy is that any window group can receive key events and -can be switched on by defining the keyword MULTIFOCUSPOLICY in -the wsini.ini file.

              Limitations

              Pointer Events

              The -first screen created is also the primary screen in the system. It is important -to note that only the primary screen can respond to pointer events. This is -due to the fact that the kernel supports only one screen digitiser.

              Cone-Based UI

              Due -to limitations in the legacy implementation of Cone and the control sets implemented -on top of it (for example, Eikon, Avkon or Qikon), it is nearly impossible -to make the same application draw Cone-based UI on two different screens at -the same time. However, a secondary screen can be used to draw non-Cone-based -graphics (for example, a picture or PowerPoint slide-show, or a UI not using -Cone for its widgets). If it must appear as if an application supports displaying -itself on the secondary screen, then this can be done by moving that UI into -a second application instance. This second instance could be a server application -that only acts as a slave UI of the main application. In any case, that secondary -application instance would have to set the secondary screen as its default -screen. There are two main problems:

                -

              1. All controls have to -be associated with a window, and window owning controls do not currently try -to make sure that the window they create is associated with the screen that -they should appear on. This means, for example, that a pop-out window created -by a choice list widget will always appear on the application's primary screen, -rather than on the screen on which the choice list itself is located.

                2. -

              2. None of the legacy -widget implementations referencing the screen device take into consideration -that there might be more than one screen on the device. These include CCoeControl's SetExtentToWholeScreen(), SetCornerAndSize(), AccumulatedZoom(), PositionRelativeToScreen(), -and CEikAppUi's ClientRect() and ApplicationRect()).

                3. -

              Neither of these problems can be solved currently.

              -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-779893C2-A9B5-591A-8A5B-6419C4244ACE.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,145 @@ + + + + + +How to +- Multiple screens +
              Contents
                +

              • Introduction

                • +

              • Configuration

                • +

              • Building the ROM image

                • +

              • Example Code

                • +

              • Limitations

                • +
              +
              Introduction

              Purpose and scope

              This +document explains how an application can draw to multiple screens. It is aimed +at a developer who is already familiar with creating a simple application +GUI. In this document, the CONE and WSERV interfaces that support multiple +screens are referred to.

              +
              How to create +multiple screens

              Configuration

              The +first screen is indexed as zero and the nth screen is indexed as n-1. The +changes below should be made to the wsini.ini file which +resides under \epoc32\data\z\system\data.

              [screen 0] +[screen 1] +[screen n-1]

              Building +the ROM image

              The secondary screen is supported through TV-OUT +on H4 board. The H4 base port only supports landscape mode with 16 bpp resolution. +The ROM image must be built with -DWITH_TVOUT as a parameter.

              Example Code

              Setup example code

              The +following code is the basis for the examples that follow.

              This is a wsini.ini file +used to create two fixed screens:

              AUTOCLEAR 1 +STARTUP \SYS\BIN\Start +WINDOWMODE COLOR64K +KEYCLICKPLUGIN KeyClickRef +TRANSPARENCY +MULTIFOCUSPOLICY +[screen 0] +[screen 1]

              This is a class CTRedControl, which +draws a rectangle on the second screen:

              const TInt KSndScreenNo = 1; + +class CTRedControl : public CCoeControl + { +public: + CTRedControl(){}; + ~CTRedControl(){}; + void ConstructL(RWindowGroup* aWinGp); + +private: // From CCoeControl + void Draw(const TRect& aRect) const; + }; + +void CTRedControl::ConstructL(RWindowGroup* aWinGp) + { + CreateWindowL(aWinGp); + SetExtent(TPoint(20,20),TSize(100,100)); + SetFocus(ETrue); + ActivateL(); + } + +void CTRedControl::Draw(const TRect& aRect) const + { + CWindowGc& gc=SystemGc(); + if (IsFocused()) + { + gc.SetPenColor(KRgbRed); + } + + gc.DrawRect(aRect); + }

              Windows +on multiple screens

              Using the above example code as a basis, the +following methods can be used to facilitate access to multiple screens:

              Class RWsSession provides +the interface to query WSERV about window groups on a particular screen and +the number of screens in the system. The application calls the function below +to get the number of screens supported on the phone:

              iCoeEnv->WsSession().NumberOfScreens();

              The class CWsScreenDevice provides the interface to +query the physical limitations of the screen and set the parameters of the +corresponding logical screen. The class RWindowGroup is the +client side handle to the server side window group. A pair of screen device +and window group is required to draw on a screen.

              CONE maintains an +array of screen devices and window groups. The screen number is used to index +this array to retrieve a particular window group and its corresponding screen +device.

              The application calls ScreenDevice() to get +the second screen device:

              iCoeEnv->ScreenDevice(KSndScreenNo);

              The +application calls RootWin() to get the window group on the +second screen:

              iCoeEnv->RootWin(KSndScreenNo);

              The +application calls NumWindowGroups( ) to +get the number of window groups with EAllPriorities on the +second screen:

              iCoeEnv->WsSession().NumWindowGroups(KSndScreenNo,EAllPriorities);

              The application creates a new list and then populates it with WindowGroupList() to +get the list of window groups with EAllPriorities on the +second screen:

              CArrayFixFlat<TInt>* list = new(ELeave) CArrayFixFlat<TInt>(1); +iCoeEnv->WsSession().WindowGroupList(list,KSndScreenNo,EAllPriorities);

              The +application calls GetFocusWindowGroup() to get the window +group that has the keyboard focus on the second screen:

              iCoeEnv->WsSession().GetFocusWindowGroup(KSndScreenNo);

              Each screen has a default owning window group. The application calls GetDefaultOwningWindow() to +get the default owning window group on the second screen:

              iCoeEnv ->WsSession().GetDefaultOwningWindow(KSndScreenNo);

              The application calls GetDefModeMaxNumColors() to get +the maximum colour and display mode supported on the second screen:

              TInt colour, grey; +iCoeEnv->WsSession().GetDefModeMaxNumColors(KSndScreenNo,colour,grey);

              The +application calls GetColorModeList() to get the list of colour +modes supported on the second screen:

              CArrayFixFlat<TInt>* list = new(Eleave) CArrayFixFlat<TInt>(1); +iCoeEnv ->WsSession().GetColorModeList(KSndScreenNo, list);

              Creating a control on a +particular screen

              A window group is associated with a screen device, +which in turn is associated to a screen. A control is associated with a window +group. Therefore a control is constructed on the second screen using the function +below, in the control’s ConstructL():

              CTRedControl redControl=new(Eleave) CTRedControl(); +redControl->ConstructL(CCoeEnv::Static()->RootWin(KSndScreenNo));

              Graphics Context

              The +class CWindowGc provides the interface for the application’s +window graphics context and can be activated on any window in the application. +This means that it can be used on any screen on the phone. The function call +below is used to find the screen device on which the graphics context was +last activated.

              CCoeEnv::Static()->SystemGc().Device();

              Window Group Focus Policy

              There +are two focus policies supported by WSERV. The default focus policy is that +there is only the focused window group on the focused screen receives key +events. The new policy is that any window group can receive key events and +can be switched on by defining the keyword MULTIFOCUSPOLICY in +the wsini.ini file.

              Limitations

              Pointer Events

              The +first screen created is also the primary screen in the system. It is important +to note that only the primary screen can respond to pointer events. This is +due to the fact that the kernel supports only one screen digitiser.

              Cone-Based UI

              Due +to limitations in the legacy implementation of Cone and the control sets implemented +on top of it (for example, Eikon, Avkon or Qikon), it is nearly impossible +to make the same application draw Cone-based UI on two different screens at +the same time. However, a secondary screen can be used to draw non-Cone-based +graphics (for example, a picture or PowerPoint slide-show, or a UI not using +Cone for its widgets). If it must appear as if an application supports displaying +itself on the secondary screen, then this can be done by moving that UI into +a second application instance. This second instance could be a server application +that only acts as a slave UI of the main application. In any case, that secondary +application instance would have to set the secondary screen as its default +screen. There are two main problems:

                +

              1. All controls have to +be associated with a window, and window owning controls do not currently try +to make sure that the window they create is associated with the screen that +they should appear on. This means, for example, that a pop-out window created +by a choice list widget will always appear on the application's primary screen, +rather than on the screen on which the choice list itself is located.

                2. +

              2. None of the legacy +widget implementations referencing the screen device take into consideration +that there might be more than one screen on the device. These include CCoeControl's SetExtentToWholeScreen(), SetCornerAndSize(), AccumulatedZoom(), PositionRelativeToScreen(), +and CEikAppUi's ClientRect() and ApplicationRect()).

                3. +

              Neither of these problems can be solved currently.

              +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-77AD4D8C-08CA-45C4-B5E7-04B4C7958A1A_d0e81736_href.png Binary file Symbian3/SDK/Source/GUID-77AD4D8C-08CA-45C4-B5E7-04B4C7958A1A_d0e81736_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-77EC9F20-32F4-5A1D-B183-75838EBA30B1_d0e176330_href.png Binary file Symbian3/SDK/Source/GUID-77EC9F20-32F4-5A1D-B183-75838EBA30B1_d0e176330_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-77EC9F20-32F4-5A1D-B183-75838EBA30B1_d0e182924_href.png Binary file Symbian3/SDK/Source/GUID-77EC9F20-32F4-5A1D-B183-75838EBA30B1_d0e182924_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-77F02412-00E1-59F9-A875-3147529F83F5_d0e110965_href.png Binary file Symbian3/SDK/Source/GUID-77F02412-00E1-59F9-A875-3147529F83F5_d0e110965_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-77F02412-00E1-59F9-A875-3147529F83F5_d0e117503_href.png Binary file Symbian3/SDK/Source/GUID-77F02412-00E1-59F9-A875-3147529F83F5_d0e117503_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-781F53F0-0F84-4BF9-A565-C2E7333521CE.dita --- a/Symbian3/SDK/Source/GUID-781F53F0-0F84-4BF9-A565-C2E7333521CE.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-781F53F0-0F84-4BF9-A565-C2E7333521CE.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,31 +1,31 @@ - - - - - -Data -queries with multiple fields -

              It is possible to have two input fields in a Data query. An example of -this is a user name and password query: one field is a normal alphanumeric -editor and the other a password editor. In this case, a press of the Selection -key moves the insertion point from the first field to the next; in the second -field it accepts the query. The left softkey always accepts the query. The -user can also move from one field to the other using the Arrow up and Arrow -down keys. Note that in landscape orientation it may not be feasible to use -a query with multiple fields and alternative solutions may be necessary, for -example, launching one query first for user name and on pressing Ok' another -query is launched for password.

              - -Data query with two input fields - - -
              Using data queries with -multiple fields in C++ applications

              For implementation information, -see Queries.

              + + + + + +Data +queries with multiple fields +

              It is possible to have two input fields in a Data query. An example of +this is a user name and password query: one field is a normal alphanumeric +editor and the other a password editor. In this case, a press of the Selection +key moves the insertion point from the first field to the next; in the second +field it accepts the query. The left softkey always accepts the query. The +user can also move from one field to the other using the Arrow up and Arrow +down keys. Note that in landscape orientation it may not be feasible to use +a query with multiple fields and alternative solutions may be necessary, for +example, launching one query first for user name and on pressing OK another +query is launched for password.

              + +Data query with two input fields + + +
              Using +data queries with multiple fields in applications

              For implementation +information, see Queries.

               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-783161AE-708E-4FB4-8219-EEC0F9939E9B-master.png Binary file Symbian3/SDK/Source/GUID-783161AE-708E-4FB4-8219-EEC0F9939E9B-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-783161AE-708E-4FB4-8219-EEC0F9939E9B_d0e55932_href.png Binary file Symbian3/SDK/Source/GUID-783161AE-708E-4FB4-8219-EEC0F9939E9B_d0e55932_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-783161AE-708E-4FB4-8219-EEC0F9939E9B_d0e63641_href.png Binary file Symbian3/SDK/Source/GUID-783161AE-708E-4FB4-8219-EEC0F9939E9B_d0e63641_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-78453EBD-B4F3-4A78-AEAE-3D126DFED31F.dita --- a/Symbian3/SDK/Source/GUID-78453EBD-B4F3-4A78-AEAE-3D126DFED31F.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-78453EBD-B4F3-4A78-AEAE-3D126DFED31F.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,38 +1,38 @@ - - - - - -Disabling -stylus popup menus in AVKON listsThis document describes how to disable stylus popup menus in AVKON -lists. -

              In some -views, stylus popup menus must not be displayed with a long tap. For example, -when a view has both a stylus popup menu and a context sensitive menu with -the same commands.

              If the context sensitive menu is required to remain, -the stylus popup menu must be disabled. This way the item-specific commands -are available only in the context sensitive menu, which is launched with both -single and long tap.

               - -You can disable -the stylus popup menu in either of the following ways: - -

              Dynamically during construction.

              iListBox->ConstructL(this, EAknListBoxItemSpecificMenuDisabled); -               -

              In the list box resource

              LISTBOX -{ - flags = EAknListBoxItemSpecificMenuDisabled; - height = 3; - width = 3; -}; -               -               -               -               + + + + + +Disabling +stylus popup menus in AVKON listsThis document describes how to disable stylus popup menus in AVKON +lists. +

              In some +views, stylus popup menus must not be displayed with a long tap. For example, +when a view has both a stylus popup menu and a context sensitive menu with +the same commands.

              If the context sensitive menu is required to remain, +the stylus popup menu must be disabled. This way the item-specific commands +are available only in the context sensitive menu, which is launched with both +single and long tap.

               + +You can disable +the stylus popup menu in either of the following ways: + +

              Dynamically during construction.

              iListBox->ConstructL(this, EAknListBoxItemSpecificMenuDisabled); +               +

              In the list box resource

              LISTBOX +{ + flags = EAknListBoxItemSpecificMenuDisabled; + height = 3; + width = 3; +}; +               +               +               +                             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-785160B9-A6BC-47FA-957E-5BB87E79B4E7-master.png Binary file Symbian3/SDK/Source/GUID-785160B9-A6BC-47FA-957E-5BB87E79B4E7-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-785160B9-A6BC-47FA-957E-5BB87E79B4E7_d0e69648_href.png Binary file Symbian3/SDK/Source/GUID-785160B9-A6BC-47FA-957E-5BB87E79B4E7_d0e69648_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-785160B9-A6BC-47FA-957E-5BB87E79B4E7_d0e74811_href.png Binary file Symbian3/SDK/Source/GUID-785160B9-A6BC-47FA-957E-5BB87E79B4E7_d0e74811_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-786D76B7-B827-43B7-8202-BA7A7E5EE03E.dita --- a/Symbian3/SDK/Source/GUID-786D76B7-B827-43B7-8202-BA7A7E5EE03E.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-786D76B7-B827-43B7-8202-BA7A7E5EE03E.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,99 +1,99 @@ - - - - - -Providing -tactile feedback for touch events -

              The Tactile feedback client API provides area registry based feedback and -direct feedback to Symbian applications and UI components. You can use the -API to add, modify and remove feedback areas, trigger direct feedback and -disable feedback for certain UI components or the whole application.

              -

              To provide tactile -feedback using the using the Tactile feedback client API, follow the steps -below:

                -
              1. Include the Tactile Feedback -Client library touchfeedback.lib in your .mmp file.
                2. -

              2. Include the header files touchfeedback.h and touchlogicalfeedback.h.

                3. -
              3. Use the MTouchFeedback::Instance function -for acquiring a pointer to the interface.
                4. -
              4. Set feedback areas for -your UI controls using the SizeChanged function (or in another -approriate place).
                5. -
              5. Update the feedback areas -using the PositionChanged function (for non-window-owning -controls).
                6. -
              6. Call RemoveFeedbackForControl in -your control's destructor.
                7. -
              7. If you want to use direct -feedback, trigger it in the HandlePointerEventL function -with a call to InstantFeedback.
                8. -
              -
              Use cases -Tactile feedback client API use cases - -

              To provide tactile feedback for touch events in your applications, -implement the following use cases:

                -

              • Using direct -feedback

                  -
                • Feedback effect is played according to given logical feedback type.
                  • -
                • -

              • Using area registry -based feedback

                  -

                • Set feedback area

                    -
                  • New feedback area is added to area registry.
                    • -
                  • Can also be used for modifying existing feedback area.
                    • -
                  • -

                • Change feedback area

                    -
                  • Change feedback area coordinates, or feedback type for a given area.
                    • -
                  • -

                • Remove feedback area

                    -
                  • Given feedback area is removed from the registry
                    • -
                  • -
                • -

              • Removing feedback -from a control

                  -
                • All feedback areas belonging to given control are removed from registry.
                  • -
                • All cached information about the control is also removed.
                  • -
                • -

              The following use cases are optional, allowing you to use additional -tactile feedback features:

                -

              • Disabling and -enabling feedback

                  -

                • Enable or disable feedback for you application

                    -
                  • Disable feedback for this application at run-time.
                    • -
                  • Enable feedback for this application at run-time.
                    • -
                  • Query whether feedback is currently enabled for this application.
                    • -
                  • Enable only audio- or vibra feedback for this application at run-time.
                    • -
                  • -

                • Enable or disable feedback for a control

                    -
                  • Temporarily disable feedback for given control.
                    • -
                  • Re-enable feedback for given control.
                    • -
                  • Temporarily enable only audio or vibra feedback.
                    • -
                  • -
                • -

              • Querying if -feedback is supported

                  -
                • Check if tactile feedback is supported in this device.
                  • -
                • -

              • Managing feedback -areas

                  -
                • You can sort feedback areas for achieving desired functionality in case -of overlapping areas.
                  • -
                • -

              • Optimizing feedback -latency

                • -
              -

              For an overview -of using tactile feedback in your application, see Tactile -feedback implementation example.

              -
              Main implementation -files

              The implementation files for the Tactile feedback client API -are touchfeedback.h and touchlogicalfeedback.h.

              + + + + + +Providing +tactile feedback for touch events +

              The Tactile feedback client API provides area registry based feedback and +direct feedback to Symbian applications and UI components. You can use the +API to add, modify and remove feedback areas, trigger direct feedback and +disable feedback for certain UI components or the whole application.

              +

              To provide tactile +feedback using the using the Tactile feedback client API, follow the steps +below:

                +
              1. Include the Tactile Feedback +Client library touchfeedback.lib in your .mmp file.
                2. +

              2. Include the header files touchfeedback.h and touchlogicalfeedback.h.

                3. +
              3. Use the MTouchFeedback::Instance function +for acquiring a pointer to the interface.
                4. +
              4. Set feedback areas for +your UI controls using the SizeChanged function (or in another +approriate place).
                5. +
              5. Update the feedback areas +using the PositionChanged function (for non-window-owning +controls).
                6. +
              6. Call RemoveFeedbackForControl in +your control's destructor.
                7. +
              7. If you want to use direct +feedback, trigger it in the HandlePointerEventL function +with a call to InstantFeedback.
                8. +
              +
              Use cases +Tactile feedback client API use cases + +

              To provide tactile feedback for touch events in your applications, +implement the following use cases:

                +

              • Using direct +feedback

                  +
                • Feedback effect is played according to given logical feedback type.
                  • +
                • +

              • Using area registry +based feedback

                  +

                • Set feedback area

                    +
                  • New feedback area is added to area registry.
                    • +
                  • Can also be used for modifying existing feedback area.
                    • +
                  • +

                • Change feedback area

                    +
                  • Change feedback area coordinates, or feedback type for a given area.
                    • +
                  • +

                • Remove feedback area

                    +
                  • Given feedback area is removed from the registry
                    • +
                  • +
                • +

              • Removing feedback +from a control

                  +
                • All feedback areas belonging to given control are removed from registry.
                  • +
                • All cached information about the control is also removed.
                  • +
                • +

              The following use cases are optional, allowing you to use additional +tactile feedback features:

                +

              • Disabling and +enabling feedback

                  +

                • Enable or disable feedback for you application

                    +
                  • Disable feedback for this application at run-time.
                    • +
                  • Enable feedback for this application at run-time.
                    • +
                  • Query whether feedback is currently enabled for this application.
                    • +
                  • Enable only audio- or vibra feedback for this application at run-time.
                    • +
                  • +

                • Enable or disable feedback for a control

                    +
                  • Temporarily disable feedback for given control.
                    • +
                  • Re-enable feedback for given control.
                    • +
                  • Temporarily enable only audio or vibra feedback.
                    • +
                  • +
                • +

              • Querying if +feedback is supported

                  +
                • Check if tactile feedback is supported in this device.
                  • +
                • +

              • Managing feedback +areas

                  +
                • You can sort feedback areas for achieving desired functionality in case +of overlapping areas.
                  • +
                • +

              • Optimizing feedback +latency

                • +
              +

              For an overview +of using tactile feedback in your application, see Tactile +feedback implementation example.

              +
              Main implementation +files

              The implementation files for the Tactile feedback client API +are touchfeedback.h and touchlogicalfeedback.h.

               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-788BC010-536D-4089-9B12-4A43A9C1C82B.dita --- a/Symbian3/SDK/Source/GUID-788BC010-536D-4089-9B12-4A43A9C1C82B.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-788BC010-536D-4089-9B12-4A43A9C1C82B.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,23 +1,22 @@ - - - - - -Application-specific -indicators -

              Applications may need indicators specific to their own purposes. Such indicators -can be placed into the Navi pane, if it is available, or into some part of -the main pane. However, using the main pane this way may require the use of -a specific main pane layout. Notice also that the icons present in many list -item layouts can be utilized as indicators.

              -
              Using -application-specific indicators in C++ applications

              The API to use -for indicators is the Indicators API. For the navi pane, use -the Navigation pane API. For implementation information, see Using the Navigation pane API.

              + + + + + +Application-specific +indicators +

              Applications may need indicators specific to their own purposes. Such indicators +can be placed into the Navi pane, if it is available, or into some part of +the main pane. However, using the main pane this way may require the use of +a specific main pane layout. Notice also that the icons present in many list +item layouts can be utilized as indicators.

              +
              Using +application-specific indicators in applications

              The API to use for +indicators is the Indicators API. For the navi pane, use the Navigation pane API. For implementation information, see Using the Navigation pane API.

               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-78989363-A405-4A1D-8F13-DC52FE6FAD80_d0e75280_href.png Binary file Symbian3/SDK/Source/GUID-78989363-A405-4A1D-8F13-DC52FE6FAD80_d0e75280_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-78989363-A405-4A1D-8F13-DC52FE6FAD80_d0e80408_href.png Binary file Symbian3/SDK/Source/GUID-78989363-A405-4A1D-8F13-DC52FE6FAD80_d0e80408_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-78AAEDF8-6C31-53E3-B411-3463DDAAC902_d0e79683_href.png Binary file Symbian3/SDK/Source/GUID-78AAEDF8-6C31-53E3-B411-3463DDAAC902_d0e79683_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-78AAEDF8-6C31-53E3-B411-3463DDAAC902_d0e86395_href.png Binary file Symbian3/SDK/Source/GUID-78AAEDF8-6C31-53E3-B411-3463DDAAC902_d0e86395_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-78AC068A-C858-41E9-94A8-32C8A8581BF8_d0e68959_href.png Binary file Symbian3/SDK/Source/GUID-78AC068A-C858-41E9-94A8-32C8A8581BF8_d0e68959_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-78B63C44-7765-5408-A611-DFE8709196F8_d0e195032_href.png Binary file Symbian3/SDK/Source/GUID-78B63C44-7765-5408-A611-DFE8709196F8_d0e195032_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-78B63C44-7765-5408-A611-DFE8709196F8_d0e200040_href.png Binary file Symbian3/SDK/Source/GUID-78B63C44-7765-5408-A611-DFE8709196F8_d0e200040_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-79009102-0490-5C61-9722-C5EE49A1AF2B_d0e184827_href.png Binary file Symbian3/SDK/Source/GUID-79009102-0490-5C61-9722-C5EE49A1AF2B_d0e184827_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-79009102-0490-5C61-9722-C5EE49A1AF2B_d0e191423_href.png Binary file Symbian3/SDK/Source/GUID-79009102-0490-5C61-9722-C5EE49A1AF2B_d0e191423_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-79100974-CAE1-5451-9ED7-E06C9B27131B.dita --- a/Symbian3/SDK/Source/GUID-79100974-CAE1-5451-9ED7-E06C9B27131B.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-79100974-CAE1-5451-9ED7-E06C9B27131B.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,125 +1,125 @@ - - - - - -Build -Process -
                -

              • Introduction

                • -

              • P.I.P.S. target types

                • -

              • Symbol information

                • -

              • Mapping POSIX handles to the Symbian platform resource objects

                  -

                • Using non-system calls

                  • -

                • Using the System Call Adaptation Layer

                  • -
                • -
              -
              Introduction

              Symbian -currently builds its emulator code with the Metrowerks CodeWarrior compiler. -This is known as the WINSCW build target. Binaries built -with this compiler are put in the epoc32\release\winscw and epoc32\winscw directory -trees.

              You can build your programs for the emulator using Metrowerks -CodeWarrior. The build tools also support the Microsoft® Visual Studio .NET -2003 and Microsoft Visual Studio v6 IDEs. For further information, see the Build tools guide section. -Note that licensees or third-parties may supply additional tools, or extend -support to additional compilers, which are not described here.

              The -following sections describe the Symbian platform target types -introduced with P.I.P.S.. For further information see the -native build targets section.

              When using tool chains for pre-Symbian -OS v9.3, the .mmp file has to be manually changed to -link in various libraries.

              For Symbian OS v9.3 onwards the tool chain -supports the new STDEXE and STDDLL target -types for P.I.P.S. EXEs and DLLs. See the Generation -of STDEXE, STDDLL and STDLIB section for further explanation of the -new target types introduced with P.I.P.S..

              -
              P.I.P.S. target -types

              P.I.P.S. EXEs require adaptation logic to set up the C program -environment and the P.I.P.S. run-time C library context - this is performed -by the CRT0 library (also known as glue code, see the Glue -code (CRT0) section for further details).

              P.I.P.S. executables -are implemented using native Symbian platform executables linked statically -to the glue code. The new target types for P.I.P.S. include the glue code -by default. The glue code provides the linking code between the E32Main() entry -point and the main() entry point used in 'C' P.I.P.S. EXEs.

              For -further information see the Target -Types section.

              -
              Symbol information

              When -building a P.I.P.S. DLL (that is, when the target type is STDDLL), -function and data symbols with extern linkage will be exported -or imported by default, without any requirement for IMPORT_C /EXPORT_C declarations -in the header or source files.

              Exporting of symbols with extern linkage -is the assumed default on other platforms and enables the source code to be -easily ported. Although this may normally be undesirable in the embedded world, -it is supported for STDDLL to avoid portable source code -having to include excessive decoration (that is, the IMPORT_C /EXPORT_C macros) -for the Symbian platform.

              STDEXE and STDDLL provide -symbol name information. For more information on the Symbian platform target -types see the Generation -of STDEXE, STDDLL and STDLIB section.

              -
              Mapping POSIX -handles to the Symbian platform resource objects

              Using -non-system calls

              Several P.I.P.S. APIs that directly manipulate -the Symbian platform (native) resources are implemented in the System Call -Adaptation Layer (SCAL). The exceptions to this are pthread s, -and memory maps. The pthread APIs use RThread s -and RMutex es directly from within libpthread. -Similarly, RChunk s that are used to provide support for -memory maps are directly manipulated from within libc. Note -that none of these APIs allow direct access to the underlying native resources. -References to these are wrapped in POSIX-defined data structures. These data -structures are intended to be treated as opaque and no attempt must be made -to dereference or use the underlying resource reference directly.

              All -IPC calls enter the SCAL, but are handled in a separate IPC library. This -is a component distinction. The IPC library is logically still part of the -SCAL.

              Using the -System Call Adaptation Layer

              One of the supports provided by the -System Call Adaptation Layer (SCAL) is the mapping of operations on UNIX® -file descriptors to the corresponding Symbian platform resource objects. The -section below discusses the file descriptors case.

              Creating -a new file descriptor

              The porting of the 'C' POSIX fopen() function, -below, is a good example of mapping POSIX handles to native Symbian platform -resource objects. The mapping is done through a file descriptor table. As -a reminder, every application/process has its own file descriptor table.

              This -example shows a call to the fopen() function:

              //myapp.cpp -int foo() -{ - //open the test.tx , fd=7 in this example - int fd = fopen("c:/test.txt", "r+"); - ... - //writes to file referenced by the file descriptor - ret = write (fd, buf, size_t); - -}

              When myapp tries to open the file with fopen(), -the application makes a call to the equivalent Symbian platform function, RFile::Open(), -and returns the next free entry in the file descriptor table.

              In each -table, the values 0, 1 and 2 are -reserved for stdin(), sdtout() and stderr(). -The figure below shows an example file descriptor table.

              - -

              According to the descriptor table the file descriptor equals 7, -as this was the next free entry in the table, and the write function will -be writing to the file referenced by 7.

              Note: A -POSIX descriptor is an index in the process open file table and represents, -for example, an open file, socket or pipe. A Symbian descriptor represents -data which can reside in any memory location, either in ROM or RAM. A descriptor -object maintains pointer and length information to describe the data. All -access to the data is made through the descriptor object.

              Descriptors -shared across multiple threads within the same process

              Originally -on the Symbian platform, resources were thread specific and multi-tasking -was achieved using servers and active objects. In other operating systems, -such as Linux, resources are process-local and multi-tasking is achieved by -multi-threading. The purpose of the POSIX server in the original STDLIB was -to allow system-wide data, resources and descriptors to be shared across multiple -threads. This means there was context switching between the calling thread -and the server thread which added latency.

              With the introduction of -the EKA2 kernel, session handles can now be shared across multiple threads -and processes.

              P.I.P.S. takes advantage of EKA2 and re-factors the -SCAL to allow descriptors to be shared across multiple threads within the -same process, without the use of the POSIX server.

              + + + + + +Build +Process +
                +

              • Introduction

                • +

              • P.I.P.S. target types

                • +

              • Symbol information

                • +

              • Mapping POSIX handles to the Symbian platform resource objects

                  +

                • Using non-system calls

                  • +

                • Using the System Call Adaptation Layer

                  • +
                • +
              +
              Introduction

              Symbian +currently builds its emulator code with the Metrowerks CodeWarrior compiler. +This is known as the WINSCW build target. Binaries built +with this compiler are put in the epoc32\release\winscw and epoc32\winscw directory +trees.

              You can build your programs for the emulator using Metrowerks +CodeWarrior. The build tools also support the Microsoft® Visual Studio .NET +2003 and Microsoft Visual Studio v6 IDEs. For further information, see the Build tools guide section. +Note that licensees or third-parties may supply additional tools, or extend +support to additional compilers, which are not described here.

              The +following sections describe the Symbian platform target types +introduced with P.I.P.S.. For further information see the +native build targets section.

              When using tool chains for pre-Symbian +OS v9.3, the .mmp file has to be manually changed to +link in various libraries.

              For Symbian OS v9.3 onwards the tool chain +supports the new STDEXE and STDDLL target +types for P.I.P.S. EXEs and DLLs. See the Generation +of STDEXE, STDDLL and STDLIB section for further explanation of the +new target types introduced with P.I.P.S..

              +
              P.I.P.S. target +types

              P.I.P.S. EXEs require adaptation logic to set up the C program +environment and the P.I.P.S. run-time C library context - this is performed +by the CRT0 library (also known as glue code, see the Glue +code (CRT0) section for further details).

              P.I.P.S. executables +are implemented using native Symbian platform executables linked statically +to the glue code. The new target types for P.I.P.S. include the glue code +by default. The glue code provides the linking code between the E32Main() entry +point and the main() entry point used in 'C' P.I.P.S. EXEs.

              For +further information see the Target +Types section.

              +
              Symbol information

              When +building a P.I.P.S. DLL (that is, when the target type is STDDLL), +function and data symbols with extern linkage will be exported +or imported by default, without any requirement for IMPORT_C /EXPORT_C declarations +in the header or source files.

              Exporting of symbols with extern linkage +is the assumed default on other platforms and enables the source code to be +easily ported. Although this may normally be undesirable in the embedded world, +it is supported for STDDLL to avoid portable source code +having to include excessive decoration (that is, the IMPORT_C /EXPORT_C macros) +for the Symbian platform.

              STDEXE and STDDLL provide +symbol name information. For more information on the Symbian platform target +types see the Generation +of STDEXE, STDDLL and STDLIB section.

              +
              Mapping POSIX +handles to the Symbian platform resource objects

              Using +non-system calls

              Several P.I.P.S. APIs that directly manipulate +the Symbian platform (native) resources are implemented in the System Call +Adaptation Layer (SCAL). The exceptions to this are pthread s, +and memory maps. The pthread APIs use RThread s +and RMutex es directly from within libpthread. +Similarly, RChunk s that are used to provide support for +memory maps are directly manipulated from within libc. Note +that none of these APIs allow direct access to the underlying native resources. +References to these are wrapped in POSIX-defined data structures. These data +structures are intended to be treated as opaque and no attempt must be made +to dereference or use the underlying resource reference directly.

              All +IPC calls enter the SCAL, but are handled in a separate IPC library. This +is a component distinction. The IPC library is logically still part of the +SCAL.

              Using the +System Call Adaptation Layer

              One of the supports provided by the +System Call Adaptation Layer (SCAL) is the mapping of operations on UNIX® +file descriptors to the corresponding Symbian platform resource objects. The +section below discusses the file descriptors case.

              Creating +a new file descriptor

              The porting of the 'C' POSIX fopen() function, +below, is a good example of mapping POSIX handles to native Symbian platform +resource objects. The mapping is done through a file descriptor table. As +a reminder, every application/process has its own file descriptor table.

              This +example shows a call to the fopen() function:

              //myapp.cpp +int foo() +{ + //open the test.tx , fd=7 in this example + int fd = fopen("c:/test.txt", "r+"); + ... + //writes to file referenced by the file descriptor + ret = write (fd, buf, size_t); + +}

              When myapp tries to open the file with fopen(), +the application makes a call to the equivalent Symbian platform function, RFile::Open(), +and returns the next free entry in the file descriptor table.

              In each +table, the values 0, 1 and 2 are +reserved for stdin(), sdtout() and stderr(). +The figure below shows an example file descriptor table.

              + +

              According to the descriptor table the file descriptor equals 7, +as this was the next free entry in the table, and the write function will +be writing to the file referenced by 7.

              Note: A +POSIX descriptor is an index in the process open file table and represents, +for example, an open file, socket or pipe. A Symbian descriptor represents +data which can reside in any memory location, either in ROM or RAM. A descriptor +object maintains pointer and length information to describe the data. All +access to the data is made through the descriptor object.

              Descriptors +shared across multiple threads within the same process

              Originally +on the Symbian platform, resources were thread specific and multi-tasking +was achieved using servers and active objects. In other operating systems, +such as Linux, resources are process-local and multi-tasking is achieved by +multi-threading. The purpose of the POSIX server in the original STDLIB was +to allow system-wide data, resources and descriptors to be shared across multiple +threads. This means there was context switching between the calling thread +and the server thread which added latency.

              With the introduction of +the EKA2 kernel, session handles can now be shared across multiple threads +and processes.

              P.I.P.S. takes advantage of EKA2 and re-factors the +SCAL to allow descriptors to be shared across multiple threads within the +same process, without the use of the POSIX server.

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-795B41AF-FBEA-56CE-AE20-EF17BE754723.dita --- a/Symbian3/SDK/Source/GUID-795B41AF-FBEA-56CE-AE20-EF17BE754723.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-795B41AF-FBEA-56CE-AE20-EF17BE754723.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,303 +1,303 @@ - - - - - -HTTP -Utilities Library Overview -
              Purpose

              The InetProtUtils API -provides functionality to handle URIs, such as extracting URI components, -constructing and modifying a URI, text utilities, and URI component utilities -required to work with URIs.

              -
              Required background

              The clients that make use of -this API must be familiar with the following standards:

                -

              • RFC 2396, for Uniform Resource Identifiers (URI)

                • -

              • RFC 1123 for internet date and time specifications

                • -

              • WAP WSP for HTTP functionality.

                • -
              -
              Key concepts

              The component has the following key -concepts:

              - -
              URI
              -

              Universal Resource Identifier (URI) is a formatted string that identifies -the location and name of a resource, for instance a web page address.

              -               - -
              URI components
              -

              Let us consider the following URI:

              http://user:info@waterlang.org:80/top_path/foo.htm?checkme#ref

              The -URI can be split into components as follows:

              - - - -URI Component -Example - - - - -

              Scheme (protocol)

              -

              http

              -               - -

              Authority

                -

              • User Information

                • -

              • Host

                • -

              • Port

                • -
               -

                -

              • user:info

                • -

              • waterlang.org

                • -

              • 80

                • -
               -               - -

              Path

              -

              top_path/foo.htm

              -               - -

              Query

              -

              checkme

              -               - -

              Segment

              -

              ref

              -               - - -
              -               - -
              Authority component
              -

              In an URI, the user information, host and port information put together -is called authority. Format for authority appears as the following:

              [user-info@]host[:port]

              where, user-info may consist of a user name and, optionally, scheme-specific information -about how to gain authorization to access the server, for example, password. port specifies -the port number.

              -               -
              -
              Architectural relationships

              The InetProtUtils API -(inetprotutils.dll) is used by the following components:

                -

              • App services

                  -

                • DM / DS

                  • -

                • Content Handling Framework

                  • -
                • -

              • Symbian platform services:

                  -

                • Certificate lib

                  • -

                • Multimedia

                  • -
                • -
              -
              API summary

              The following classes are used for -creating, parsing and modifying the URI:

              - - - -Class Name -Description - - - - -

              CUri8

              -

              Creates URI from parts and modifies the URI.

              -               - -

              CAuthority8

              -

              Modifies the authority and creates authority from parts.

              -               - -

              TUriC8

              -

              Retrieves information about the URI such as extract, compare, validate -etc. (the non-modifying functionality).

              -               - -

              TAuthorityC8

              -

              Retrieves information about the authority URI such as extract, compare, -validate etc.

              -               - -

              TUriParser8

              -

              Parses a text URI.

              -               - -

              TAuthorityParser8

              -

              Parses a text authority.

              -               - - -

              The following classes are used for parsing delimited data in the -URI:

              - - - -Class Name -Description - - - - -

              CDelimitedPath8

              -

              Creates a delimited path, where components of the path are delimited -by '/' .

              -               - -

              CDelimitedQuery8

              -

              Creates a delimited query, where components of the query are delimited -by '&'.

              -               - -

              CDelimitedPathSegment8

              -

              Creates a delimited path segment, where components of the path segment -are delimited by ';'.

              -               - -

              TDelimitedPathParser8

              -

              Parses path delimited by a '/'.

              -               - -

              TDelimitedQueryParser8

              -

              Parses query delimited by a '&'.

              -               - -

              TDelimitedPathSegmentParser8

              -

              Parses path segments delimited by a ';'.

              -               - -

              EscapeUtils

              -

              Encodes and decodes excluded and reserved URI characters. It can -be used with 8 bit and 16 bit descriptors.

              -               - -

              InetProtTextUtils

              -

              Parses HTTP header text.

              -               - -

              UriUtils

              -

              Provides extra utilities for URI/Authority classes such as creating -URI from Unicode descriptor.

              -               - - -

              The following classes are used for encoding and decoding WSP headers:

              - - - -Class Name -Description - - - - -

              CWspHeaderEncoder

              -

              The class is used to encode one header field at a time with all -its values and parameters.

              -               - -

              TWspHeaderSegmenter

              -

              The class is used to separate a WSP buffer into WSP header name/value -pairs.

              -               - -

              TWspPrimitiveEncoder

              -

              The class is used to convert WSP header data into binary strings.

              -               - -

              TWspPrimitiveDecoder

              -

              The class is used to convert the binary data into integers, strings, -dates, etc.

              -               - -

              TWspField

              -

              The class holds the name and value pair of WSP header field.

              -               - - -

              The following diagram shows the InetProtUtils classes -and their relationships.

              - Class diagram for InetProtUtils - -
              -
              Typical uses

              Applications that use HTTP transport -framework use InetProtUtils API. The utilities may also -be useful for applications which deal with internet strings or URIs, such -as mail or IM applications.

              The following tasks can be performed using InetProtUtils:

              Creating -an URI

              URI can be created in different ways. It can be created -from parts, from file or by resolving two URIs using CUri8 class.

              For -more information on creating a URI, refer to Creating -an URI tutorial.

              Parsing an URI

              To check if -the components in the URI are syntactically correct as per the four main components -and fragment identifier, parse the URI. Use TUriParser8 class -to parse an URI.

              For more information on parsing, refer to Parsing -an URI tutorial.

              URI classes namely, CUri8, TUriC8 and TUriParser8 provide -functionalities for parsing generic and SIP URIs. CUri8 class -provides a reference to a TUriC8 object so that the non-modifying -functionality can be used. TUriC8 is used to obtain information -about an URI.

              Extracting URI components

              TUriC8 class -provides extracting methods to extract components from the URI. TAuthority8 class -extracts the authority component.

              For more information on getting -URI components, refer to Extracting -the URI Components tutorial.

              Generating the filename from -an URI

              A fully qualified file name can be generated from a file -URI object. TUriC8::GetFileNameL() provides this functionality. -The path component encodes the file's location on the file system.

              For -more information, refer to Generating -File Name from URI tutorial.

              Validating a URI

              Use TUriParser8::Validate() to -check if components in a given URI are valid. This validates only SIP and -SIPS scheme components.

              For more information, refer to Validating -an URI tutorial.

              Parsing delimited data

              URI -components are separated into segments using delimiters. Parse this delimited -data. TDelimitedXxxxParser8 classes provide the functionality -to parse the delimited data, extract the current segment and parse the string -for the next segment.

              For more information, refer to Parsing -Delimited Data tutorial.

              Modifying the data -and the delimiter

              The delimiters and segments of data within -an URI can be added, removed and parsed. This functionality is provided by CDelimitedXxxx8 classes.

              For -more information, refer to Modifying -the Data and Delimiter tutorial.

              Escape encoding and decoding -unsafe characters in an URI

              The reserved and unsafe data in the -URI is escape encoded and decoded using EscapeUtils class. -It also supports converting Unicode data (16-bit descriptor) into UTF8 data -(8-bit descriptor) and vice-versa. For more information, refer to Escape -Encoding and Decoding and Converting -between Unicode and Utf8 tutorials.

              Manipulating the URI -data

              The data in an URI can be manipulated using various text -parsing utilities that are used typically in HTTP headers. InetProtTextUtils provides -functionality to:

                -

              • remove the leading/trailing -contiguous white space characters from the descriptors

                • -

              • convert the decimal/hexadecimal -value to descriptor and vice versa.

                • -

              • extract tokens from:

                  -

                • a list, which is a string -separated with a character, for example, abc, def, ghi.

                  • -

                • quoted strings in text.

                  • -
                • -

              It supports both Unicode and UTF-8 formats. For more information -on text manipulations, refer to Manipulating -URI Data tutorial.

              Using URI utilities

              Additional -functionality to create an URI from unicode descriptor is provided by UriUtils class. -It also allows to translate unsafe characters to UTF8 and escape-encode.

              For -more information, refer to Using -URI utilities.

              Using datetime utilities

              To -store dates in universal times and parse the internet dates into TDateTime dates, -use TInternetDate.

              For more information, refer -to Using Date and Time -Utilities tutorial.

              Escape encoding and decoding the WSP -header

              The WSP header information is encoded and decoded using CWspHeaderEncoder. -It uses TWspPrimitiveEncoder to convert the data into binary -strings.

              For more information, refer to Encoding -and Decoding WSP Header.

              Use Cxxx classes -to create text from parts and TxxParser classes to parse -text into components.
              -               -HTTP Utilities -Library Concepts -HTTP Utilities -Library Tutorials -HTTP Utilities -Library Example + + + + + +HTTP +Utilities Library Overview +
              Purpose

              The InetProtUtils API +provides functionality to handle URIs, such as extracting URI components, +constructing and modifying a URI, text utilities, and URI component utilities +required to work with URIs.

              +
              Required background

              The clients that make use of +this API must be familiar with the following standards:

                +

              • RFC 2396, for Uniform Resource Identifiers (URI)

                • +

              • RFC 1123 for internet date and time specifications

                • +

              • WAP WSP for HTTP functionality.

                • +
              +
              Key concepts

              The component has the following key +concepts:

              + +
              URI
              +

              Universal Resource Identifier (URI) is a formatted string that identifies +the location and name of a resource, for instance a web page address.

              +               + +
              URI components
              +

              Let us consider the following URI:

              http://user:info@waterlang.org:80/top_path/foo.htm?checkme#ref

              The +URI can be split into components as follows:

              + + + +URI Component +Example + + + + +

              Scheme (protocol)

              +

              http

              +               + +

              Authority

                +

              • User Information

                • +

              • Host

                • +

              • Port

                • +
               +

                +

              • user:info

                • +

              • waterlang.org

                • +

              • 80

                • +
               +               + +

              Path

              +

              top_path/foo.htm

              +               + +

              Query

              +

              checkme

              +               + +

              Segment

              +

              ref

              +               + + +
              +               + +
              Authority component
              +

              In an URI, the user information, host and port information put together +is called authority. Format for authority appears as the following:

              [user-info@]host[:port]

              where, user-info may consist of a user name and, optionally, scheme-specific information +about how to gain authorization to access the server, for example, password. port specifies +the port number.

              +               +
              +
              Architectural relationships

              The InetProtUtils API +(inetprotutils.dll) is used by the following components:

                +

              • App services

                  +

                • DM / DS

                  • +

                • Content Handling Framework

                  • +
                • +

              • Symbian platform services:

                  +

                • Certificate lib

                  • +

                • Multimedia

                  • +
                • +
              +
              API summary

              The following classes are used for +creating, parsing and modifying the URI:

              + + + +Class Name +Description + + + + +

              CUri8

              +

              Creates URI from parts and modifies the URI.

              +               + +

              CAuthority8

              +

              Modifies the authority and creates authority from parts.

              +               + +

              TUriC8

              +

              Retrieves information about the URI such as extract, compare, validate +etc. (the non-modifying functionality).

              +               + +

              TAuthorityC8

              +

              Retrieves information about the authority URI such as extract, compare, +validate etc.

              +               + +

              TUriParser8

              +

              Parses a text URI.

              +               + +

              TAuthorityParser8

              +

              Parses a text authority.

              +               + + +

              The following classes are used for parsing delimited data in the +URI:

              + + + +Class Name +Description + + + + +

              CDelimitedPath8

              +

              Creates a delimited path, where components of the path are delimited +by '/' .

              +               + +

              CDelimitedQuery8

              +

              Creates a delimited query, where components of the query are delimited +by '&'.

              +               + +

              CDelimitedPathSegment8

              +

              Creates a delimited path segment, where components of the path segment +are delimited by ';'.

              +               + +

              TDelimitedPathParser8

              +

              Parses path delimited by a '/'.

              +               + +

              TDelimitedQueryParser8

              +

              Parses query delimited by a '&'.

              +               + +

              TDelimitedPathSegmentParser8

              +

              Parses path segments delimited by a ';'.

              +               + +

              EscapeUtils

              +

              Encodes and decodes excluded and reserved URI characters. It can +be used with 8 bit and 16 bit descriptors.

              +               + +

              InetProtTextUtils

              +

              Parses HTTP header text.

              +               + +

              UriUtils

              +

              Provides extra utilities for URI/Authority classes such as creating +URI from Unicode descriptor.

              +               + + +

              The following classes are used for encoding and decoding WSP headers:

              + + + +Class Name +Description + + + + +

              CWspHeaderEncoder

              +

              The class is used to encode one header field at a time with all +its values and parameters.

              +               + +

              TWspHeaderSegmenter

              +

              The class is used to separate a WSP buffer into WSP header name/value +pairs.

              +               + +

              TWspPrimitiveEncoder

              +

              The class is used to convert WSP header data into binary strings.

              +               + +

              TWspPrimitiveDecoder

              +

              The class is used to convert the binary data into integers, strings, +dates, etc.

              +               + +

              TWspField

              +

              The class holds the name and value pair of WSP header field.

              +               + + +

              The following diagram shows the InetProtUtils classes +and their relationships.

              + Class diagram for InetProtUtils + +
              +
              Typical uses

              Applications that use HTTP transport +framework use InetProtUtils API. The utilities may also +be useful for applications which deal with internet strings or URIs, such +as mail or IM applications.

              The following tasks can be performed using InetProtUtils:

              Creating +an URI

              URI can be created in different ways. It can be created +from parts, from file or by resolving two URIs using CUri8 class.

              For +more information on creating a URI, refer to Creating +an URI tutorial.

              Parsing an URI

              To check if +the components in the URI are syntactically correct as per the four main components +and fragment identifier, parse the URI. Use TUriParser8 class +to parse an URI.

              For more information on parsing, refer to Parsing +an URI tutorial.

              URI classes namely, CUri8, TUriC8 and TUriParser8 provide +functionalities for parsing generic and SIP URIs. CUri8 class +provides a reference to a TUriC8 object so that the non-modifying +functionality can be used. TUriC8 is used to obtain information +about an URI.

              Extracting URI components

              TUriC8 class +provides extracting methods to extract components from the URI. TAuthority8 class +extracts the authority component.

              For more information on getting +URI components, refer to Extracting +the URI Components tutorial.

              Generating the filename from +an URI

              A fully qualified file name can be generated from a file +URI object. TUriC8::GetFileNameL() provides this functionality. +The path component encodes the file's location on the file system.

              For +more information, refer to Generating +File Name from URI tutorial.

              Validating a URI

              Use TUriParser8::Validate() to +check if components in a given URI are valid. This validates only SIP and +SIPS scheme components.

              For more information, refer to Validating +an URI tutorial.

              Parsing delimited data

              URI +components are separated into segments using delimiters. Parse this delimited +data. TDelimitedXxxxParser8 classes provide the functionality +to parse the delimited data, extract the current segment and parse the string +for the next segment.

              For more information, refer to Parsing +Delimited Data tutorial.

              Modifying the data +and the delimiter

              The delimiters and segments of data within +an URI can be added, removed and parsed. This functionality is provided by CDelimitedXxxx8 classes.

              For +more information, refer to Modifying +the Data and Delimiter tutorial.

              Escape encoding and decoding +unsafe characters in an URI

              The reserved and unsafe data in the +URI is escape encoded and decoded using EscapeUtils class. +It also supports converting Unicode data (16-bit descriptor) into UTF8 data +(8-bit descriptor) and vice-versa. For more information, refer to Escape +Encoding and Decoding and Converting +between Unicode and Utf8 tutorials.

              Manipulating the URI +data

              The data in an URI can be manipulated using various text +parsing utilities that are used typically in HTTP headers. InetProtTextUtils provides +functionality to:

                +

              • remove the leading/trailing +contiguous white space characters from the descriptors

                • +

              • convert the decimal/hexadecimal +value to descriptor and vice versa.

                • +

              • extract tokens from:

                  +

                • a list, which is a string +separated with a character, for example, abc, def, ghi.

                  • +

                • quoted strings in text.

                  • +
                • +

              It supports both Unicode and UTF-8 formats. For more information +on text manipulations, refer to Manipulating +URI Data tutorial.

              Using URI utilities

              Additional +functionality to create an URI from unicode descriptor is provided by UriUtils class. +It also allows to translate unsafe characters to UTF8 and escape-encode.

              For +more information, refer to Using +URI utilities.

              Using datetime utilities

              To +store dates in universal times and parse the internet dates into TDateTime dates, +use TInternetDate.

              For more information, refer +to Using Date and Time +Utilities tutorial.

              Escape encoding and decoding the WSP +header

              The WSP header information is encoded and decoded using CWspHeaderEncoder. +It uses TWspPrimitiveEncoder to convert the data into binary +strings.

              For more information, refer to Encoding +and Decoding WSP Header.

              Use Cxxx classes +to create text from parts and TxxParser classes to parse +text into components.
              +               +HTTP Utilities +Library Concepts +HTTP Utilities +Library Tutorials +HTTP Utilities +Library Example               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-795ED4C0-7C82-41DE-AD5B-AC69A426E2A5.dita --- a/Symbian3/SDK/Source/GUID-795ED4C0-7C82-41DE-AD5B-AC69A426E2A5.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,16 +0,0 @@ - - - - - -Streaming video -

              The CVideoPlayerUtility::OpenUrlL method supports the real time streaming protocol (RTSP) for streaming video content. For more information on CVideoPlayerUtility, see Playing -a video clip.

              -

              For more information on streaming, see Streaming video in the Design and User Experience Library.

              -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-79B02562-B6E6-5DF9-BF98-F015C73A448C-GENID-1-8-1-3-1-1-3-1-3-1-3-1-3-1.dita --- a/Symbian3/SDK/Source/GUID-79B02562-B6E6-5DF9-BF98-F015C73A448C-GENID-1-8-1-3-1-1-3-1-3-1-3-1-3-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,41 +0,0 @@ - - - - - -Clock: -Analog and Digital Clocks example -
              Purpose

              This -example shows how to create and display a digital and analog clock. For more -information about the API, see Clock -Overview.

              -
              Download

              Click -on the following link to download the example: ClockExample.zip

              Click: browse to view the example code.

              -
              Class Summary

              CWsScreenDevice

              CFbsFont

              -TRgb

              TAnalogDisplayHand

              -STimeDeviceShadow

              RAnimDll

              -RDigitalClock

              RAnalogClock

              -
              Building and -configuring

              To build the example:

                -

              • You can build the example -from your IDE or the command line.

                If you use an IDE, import the bld.inf file -of the example into your IDE, and use the build command of the IDE.

                If -you use the command line, open a command prompt, and set the current directory -to the source code directory of the example. You can then build the example -with the SBSv1 build tools with the following commands:

                bldmake -bldfiles

                abld build

                How to use bldmake and How to use abld describe -how to use the SBSv1 build tools.

                • -

              • For the emulator, the -example builds an executable called clockexample.exe in -the epoc32\release\winscw\<udeb or urel>\ folder.

                • -
              -               -Clock Overview - -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-79B02562-B6E6-5DF9-BF98-F015C73A448C-GENID-1-8-1-6-1-1-4-1-9-1-4-1.dita --- a/Symbian3/SDK/Source/GUID-79B02562-B6E6-5DF9-BF98-F015C73A448C-GENID-1-8-1-6-1-1-4-1-9-1-4-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,41 +0,0 @@ - - - - - -Clock: -Analog and Digital Clocks example -
              Purpose

              This -example shows how to create and display a digital and analog clock. For more -information about the API, see Clock -Overview.

              -
              Download

              Click -on the following link to download the example: ClockExample.zip

              Click: browse to view the example code.

              -
              Class Summary

              CWsScreenDevice

              CFbsFont

              -TRgb

              TAnalogDisplayHand

              -STimeDeviceShadow

              RAnimDll

              -RDigitalClock

              RAnalogClock

              -
              Building and -configuring

              To build the example:

                -

              • You can build the example -from your IDE or the command line.

                If you use an IDE, import the bld.inf file -of the example into your IDE, and use the build command of the IDE.

                If -you use the command line, open a command prompt, and set the current directory -to the source code directory of the example. You can then build the example -with the SBSv1 build tools with the following commands:

                bldmake -bldfiles

                abld build

                How to use bldmake and How to use abld describe -how to use the SBSv1 build tools.

                • -

              • For the emulator, the -example builds an executable called clockexample.exe in -the epoc32\release\winscw\<udeb or urel>\ folder.

                • -
              -               -Clock Overview - -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-79B02562-B6E6-5DF9-BF98-F015C73A448C.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-79B02562-B6E6-5DF9-BF98-F015C73A448C.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,44 @@ + + + + + +Clock: Analog and Digital Clocks example +
              Purpose

              This example shows how to create and display a digital and analog +clock. For more information about the API, see Clock Overview.

              +
              Download

              Click on the following link to download the example: ClockExample.zip

              Click: browse to view the example code.

              +
              Class Summary
                +

              • CWsScreenDevice

                • +

              • CFbsFont

                • +

              • TRgb

                • +

              • TAnalogDisplayHand

                • +

              • STimeDeviceShadow

                • +

              • RAnimDll

                • +

              • RDigitalClock

                • +

              • RAnalogClock

                • +
              +
              Building +and configuring

              To build the example:

                +

              • You can build +the example from your IDE or the command line.

                If you use +an IDE, import the bld.inf file of the example +into your IDE, and use the build command of the IDE.

                If you +use the command line, open a command prompt, and set the current directory +to the source code directory of the example. You can then build the +example with the SBSv1 build tools with the following commands:

                bldmake bldfiles

                abld +build

                How to use bldmake and How to +use abld describe how to use the SBSv1 build tools.

                • +

              • For the emulator, +the example builds an executable called clockexample.exe in the epoc32\release\winscw\<udeb or + urel>\ folder.

                • +
              +               +Clock +Overview +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-79C82F78-471B-521F-A0CA-968C8BF33B48_d0e189034_href.png Binary file Symbian3/SDK/Source/GUID-79C82F78-471B-521F-A0CA-968C8BF33B48_d0e189034_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-79C82F78-471B-521F-A0CA-968C8BF33B48_d0e194096_href.png Binary file Symbian3/SDK/Source/GUID-79C82F78-471B-521F-A0CA-968C8BF33B48_d0e194096_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7A2A9222-7D10-4007-95AB-C9584EC54698_d0e51559_href.png Binary file Symbian3/SDK/Source/GUID-7A2A9222-7D10-4007-95AB-C9584EC54698_d0e51559_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7A2A9222-7D10-4007-95AB-C9584EC54698_d0e55550_href.png Binary file Symbian3/SDK/Source/GUID-7A2A9222-7D10-4007-95AB-C9584EC54698_d0e55550_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7A2A9222-7D10-4007-95AB-C9584EC54698_d0e57111_href.png Binary file Symbian3/SDK/Source/GUID-7A2A9222-7D10-4007-95AB-C9584EC54698_d0e57111_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7A2A9222-7D10-4007-95AB-C9584EC54698_d0e68820_href.png Binary file Symbian3/SDK/Source/GUID-7A2A9222-7D10-4007-95AB-C9584EC54698_d0e68820_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7A2A9222-7D10-4007-95AB-C9584EC54698_d0e73964_href.png Binary file Symbian3/SDK/Source/GUID-7A2A9222-7D10-4007-95AB-C9584EC54698_d0e73964_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7A552BC6-419F-4FD9-8D63-828E37982FD8.dita --- a/Symbian3/SDK/Source/GUID-7A552BC6-419F-4FD9-8D63-828E37982FD8.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-7A552BC6-419F-4FD9-8D63-828E37982FD8.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,33 +1,33 @@ - - - - - -Editing -indicators -

              The status of the editor is displayed using graphic indicators. They inform -the user about things such as:

              -
                -

              • Editing mode (numeric/alphanumeric, language-specific modes)

                • -

              • Character case

                • -

              • Predictive Text status

                • -

              • Available space

                • -
              -

              When the editor is in the main pane, the indicators are located in the -Navi pane. A Data query that resides in a pop-up window has its indicators -within the window.

              - -Editing indicators a) in the Navi pane and b) above the editor field -in a pop-up window - - -
              Using -editing indicators in C++ applications

              The API to use for editing -indicators is the Indicators API. For the navi pane, use the Navigation pane API.

              + + + + + +Editing +indicators +

              The status of the editor is displayed using graphic indicators. They inform +the user about things such as:

              +
                +

              • Editing mode (numeric/alphanumeric, language-specific modes)

                • +

              • Character case

                • +

              • Predictive Text status

                • +

              • Available space

                • +
              +

              When the editor is in the main pane, the indicators are located in the +Navi pane. A Data query that resides in a pop-up window has its indicators +within the window.

              + +Editing indicators a) in the Navi pane and b) above the editor field +in a pop-up window + + +
              Using +editing indicators in applications

              The API to use for +editing indicators is the Indicators API. For the navi pane, use the Navigation pane API.

               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7A6342C7-DED3-5BE0-AB1C-F2C7BC57D1D2_d0e409504_href.png Binary file Symbian3/SDK/Source/GUID-7A6342C7-DED3-5BE0-AB1C-F2C7BC57D1D2_d0e409504_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7A6342C7-DED3-5BE0-AB1C-F2C7BC57D1D2_d0e409666_href.png Binary file Symbian3/SDK/Source/GUID-7A6342C7-DED3-5BE0-AB1C-F2C7BC57D1D2_d0e409666_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7AC4C1C2-D796-508F-93CF-21F061F49A30_d0e16895_href.png Binary file Symbian3/SDK/Source/GUID-7AC4C1C2-D796-508F-93CF-21F061F49A30_d0e16895_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7AC4C1C2-D796-508F-93CF-21F061F49A30_d0e47241_href.png Binary file Symbian3/SDK/Source/GUID-7AC4C1C2-D796-508F-93CF-21F061F49A30_d0e47241_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7AC4C1C2-D796-508F-93CF-21F061F49A30_d0e52797_href.png Binary file Symbian3/SDK/Source/GUID-7AC4C1C2-D796-508F-93CF-21F061F49A30_d0e52797_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7AE4D17F-728A-5B7E-A3F9-A903E64731B1_d0e189172_href.png Binary file Symbian3/SDK/Source/GUID-7AE4D17F-728A-5B7E-A3F9-A903E64731B1_d0e189172_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7AE4D17F-728A-5B7E-A3F9-A903E64731B1_d0e194234_href.png Binary file Symbian3/SDK/Source/GUID-7AE4D17F-728A-5B7E-A3F9-A903E64731B1_d0e194234_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7AE7EAE1-BA90-446E-AAAF-01794EF96576.dita --- a/Symbian3/SDK/Source/GUID-7AE7EAE1-BA90-446E-AAAF-01794EF96576.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-7AE7EAE1-BA90-446E-AAAF-01794EF96576.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,23 +1,22 @@ - - - - - -Highlighting -

              When a list or grid is in use, one item in it is always in focus. The item -in focus is indicated by a graphical means called highlighting.

              -

              The appearance of highlighting on a list item is a colored (theme related) -bar, which completely occupies the item in focus. The item text and graphics -are displayed on the bar.

              -

              Grid item highlighting is a frame over the item in focus.

              - -List highlighting (a) and grid highlighting (b) - - + + + + + +Highlighting +

              On a single tap, an item gets highlighted and activated on direct +selection. The appearance of highlighting on a list item is a colored +(theme related) bar, which completely occupies the item in focus. +The item text and graphics are displayed on the bar.

              +

              Grid item highlighting is a frame over the item in focus.

              + +List highlighting (a) and grid highlighting (b) + +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7B173E02-9697-51F4-A7E8-795AEF547109.dita --- a/Symbian3/SDK/Source/GUID-7B173E02-9697-51F4-A7E8-795AEF547109.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-7B173E02-9697-51F4-A7E8-795AEF547109.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,177 +1,177 @@ - - - - - -Thread -Priority SchemeExplains the factors involved in allocating thread priority. -

              At any given time, the thread running on Symbian platform is the one with -the highest priority that is ready to run. The priority of a thread is simply -a number; the value determines the priority; the greater the number, the higher -the priority. We call this the true or absolute priority of -the thread.

              -

              The Kernel schedules a fixed amount of time called a quantum for -a thread to run on the CPU, and the scheduler chooses the highest priority -thread that is ready to run. Threads of equal priority are executed on a round -robin basis.

              -

              The true priority values range from 0 (lowest) to 63 (highest).

              -

              The priority range divides into four broad categories:

              - - - - -

              0

               -

              This is reserved for the null thread, which puts the processor -into idle mode to save power when no other threads are ready to run.

              -               - -

              1 - 23

              -

              Used by kernel side threads and user-side applications and servers

              -               - -

              24 -31

              -

              Used by kernel side threads and protected system servers, i.e. servers -with the ProtServ capability.

              -               - -

              32 - 63

              -

              Reserved for real-time threads running on the kernel side.

              -               - - -
              - - - -
                -

              • Priority scheme for general user-side threads

                • -

              • Priority scheme for real-time user-side threads

                • -

              • Thread priority value mapping table

                • -

              • Platform security notes

                • -
              -
              Priority scheme -for general user-side threads

              User-side threads do not allocate true priority -values directly. Instead, they allocate priorities using symbolic values defined -by enums. Symbian platform maps these values to the true value.

              There -are two priority allocation schemes:

                -

              • Process-relative scheme

                • -

              • Process-independent scheme for general user threads

                • -

              Process-relative scheme

              This -scheme bases the true priority of a thread on the priority of its owning -process and the priority of the thread relative to the process. This means -that changing the process priority results in a change to the true priority -of the thread.

              A process can be assigned one of eight discrete priorities -represented by the individual enumerators of TProcessPriority, -and range from EPriorityLow, the lowest, to EPrioritySupervisor, -the highest.

              In practice, user processes can only be assigned -priorities that are one of the values:

                -

              • EPriorityLow

                • -

              • EPriorityBackground

                • -

              • EPriorityForeGround

                • -

              • EPriorityHigh

                • -

              There are a further four process priorities that a user process is -not permitted to set: EPriorityWindowServer, EPriorityFileServer, EPriorityRealTimeServer and EPrioritySupervisor.

              A process priority can be assigned:

                -

              • when the associated .exe is -built; this is done by specifying the value in the .mmp file -that defines the project.

                • -

              • by calling RProcess::SetPriority() and -passing one of the TProcessPriority enum values.

                • -

              See also : Using -Makmake in the Build -Tools Guide.

              The priority of a thread relative to a -process is assigned by calling RThread::SetPriority() and -passing one of the five TThreadPriority enum values:

                -

              • EPriorityMuchLess

                • -

              • EPriorityLess

                • -

              • EPriorityNormal

                • -

              • EPriorityMore

                • -

              • EPriorityMuchMore

                • -

              The thread -priority value mapping table shows the true priority of a thread -based on the combination of process priority and process-relative thread priority

              Process-independent scheme -for general user threads

              In this scheme, the true priority -of a thread is independent of the priority of its owning process. Changing -the priority of the underlying process has no effect on the true priority -of the thread.

              The priority of a thread is assigned by calling RThread::SetPriority() and -passing one of the TThreadPriority enum values listed below. -Note that the set of enum values splits into two logical groupings based on -their equivalence to process-relative values. See the thread priority value mapping table.

              - - - -

              Group 1

              -

              Group 2

              -               - -
                -

              • EPriorityAbsoluteVeryLow

                • -

              • EPriorityAbsoluteLow

                • -

              • EPriorityAbsoluteBackground

                • -

              • EPriorityAbsoluteForeground

                • -

              • EPriorityAbsoluteHigh

                • -
               -
                -

              • EPriorityAbsoluteLowNormal

                • -

              • EPriorityAbsoluteBackgroundNormal

                • -

              • EPriorityAbsoluteForegroundNormal

                • -

              • EPriorityAbsoluteHighNormal

                • -
               -               - - -

              The thread -priority value mapping table shows the resulting true priority -of the thread.

              -
              Priority scheme -for real-time user-side threads

              This scheme is the same as the process-independent -scheme for general user threads, but with one essential difference -- the range of TThreadPriority enum values to be passed -to RThread::SetPriority() is as shown below. These priorities -map to the true priority values in the range 24 -31, and can only be -set by executables having the ProtServ capability. This range -is referred to as the real time range.

                -

              • EPriorityAbsoluteRealTime1

                • -

              • EPriorityAbsoluteRealTime2

                • -

              • EPriorityAbsoluteRealTime3

                • -

              • EPriorityAbsoluteRealTime4

                • -

              • EPriorityAbsoluteRealTime5

                • -

              • EPriorityAbsoluteRealTime6

                • -

              • EPriorityAbsoluteRealTime7

                • -

              • EPriorityAbsoluteRealTime8

                • -

              The thread -priority value mapping table shows the resulting true priority -of the thread.

              -
              Thread priority -value mapping table

              This table shows the effect of setting priorities, -and the resulting true priority values. You need to be aware that this -may change in the future, and you should never synchronise threads on the -basis of thread priorities. If you need to synchronise threads, use mutexes -or semaphores.

              Notes

                -

              • True priority values -in the shaded region can only be accessed by threads running in processes -with the ProtServ capability.

                • -

              • The process-priority -values : EPriorityWindowServer, EPriorityFileServer and EPrioritySupervisor all -map to the same range of priorities. Along with EPriorityRealTimeServer, -these have historically been used for system servers and other processes needing -access to high priorities suitable for real-time tasks, and their use requires ProtServ capability.

                • -

              • Note that ProtServ capability -will not be granted to general applications for the purpose of gaining access -to the very high thread priorities. This risks breaking important system functionality.

                • -
              - -

              Note that we have used E' as an abbreviation for EPriority in -this diagram.

              -
              Platform security -notes

              Platform security restrictions prevent thread and process -priorities from being modified by another user process. There is one exception: -by default, applications have “Priority Control” enabled for them which allows -the window server to switch them between foreground and background process -priorities depending on which has foreground focus.

              + + + + + +Thread +Priority SchemeExplains the factors involved in allocating thread priority. +

              At any given time, the thread running on Symbian platform is the one with +the highest priority that is ready to run. The priority of a thread is simply +a number; the value determines the priority; the greater the number, the higher +the priority. We call this the true or absolute priority of +the thread.

              +

              The Kernel schedules a fixed amount of time called a quantum for +a thread to run on the CPU, and the scheduler chooses the highest priority +thread that is ready to run. Threads of equal priority are executed on a round +robin basis.

              +

              The true priority values range from 0 (lowest) to 63 (highest).

              +

              The priority range divides into four broad categories:

              + + + + +

              0

               +

              This is reserved for the null thread, which puts the processor +into idle mode to save power when no other threads are ready to run.

              +               + +

              1 - 23

              +

              Used by kernel side threads and user-side applications and servers

              +               + +

              24 -31

              +

              Used by kernel side threads and protected system servers, i.e. servers +with the ProtServ capability.

              +               + +

              32 - 63

              +

              Reserved for real-time threads running on the kernel side.

              +               + + +
              + + + +
                +

              • Priority scheme for general user-side threads

                • +

              • Priority scheme for real-time user-side threads

                • +

              • Thread priority value mapping table

                • +

              • Platform security notes

                • +
              +
              Priority scheme +for general user-side threads

              User-side threads do not allocate true priority +values directly. Instead, they allocate priorities using symbolic values defined +by enums. Symbian platform maps these values to the true value.

              There +are two priority allocation schemes:

                +

              • Process-relative scheme

                • +

              • Process-independent scheme for general user threads

                • +

              Process-relative scheme

              This +scheme bases the true priority of a thread on the priority of its owning +process and the priority of the thread relative to the process. This means +that changing the process priority results in a change to the true priority +of the thread.

              A process can be assigned one of eight discrete priorities +represented by the individual enumerators of TProcessPriority, +and range from EPriorityLow, the lowest, to EPrioritySupervisor, +the highest.

              In practice, user processes can only be assigned +priorities that are one of the values:

                +

              • EPriorityLow

                • +

              • EPriorityBackground

                • +

              • EPriorityForeGround

                • +

              • EPriorityHigh

                • +

              There are a further four process priorities that a user process is +not permitted to set: EPriorityWindowServer, EPriorityFileServer, EPriorityRealTimeServer and EPrioritySupervisor.

              A process priority can be assigned:

                +

              • when the associated .exe is +built; this is done by specifying the value in the .mmp file +that defines the project.

                • +

              • by calling RProcess::SetPriority() and +passing one of the TProcessPriority enum values.

                • +

              See also : Using +Makmake in the Build +Tools Guide.

              The priority of a thread relative to a +process is assigned by calling RThread::SetPriority() and +passing one of the five TThreadPriority enum values:

                +

              • EPriorityMuchLess

                • +

              • EPriorityLess

                • +

              • EPriorityNormal

                • +

              • EPriorityMore

                • +

              • EPriorityMuchMore

                • +

              The thread +priority value mapping table shows the true priority of a thread +based on the combination of process priority and process-relative thread priority

              Process-independent scheme +for general user threads

              In this scheme, the true priority +of a thread is independent of the priority of its owning process. Changing +the priority of the underlying process has no effect on the true priority +of the thread.

              The priority of a thread is assigned by calling RThread::SetPriority() and +passing one of the TThreadPriority enum values listed below. +Note that the set of enum values splits into two logical groupings based on +their equivalence to process-relative values. See the thread priority value mapping table.

              + + + +

              Group 1

              +

              Group 2

              +               + +
                +

              • EPriorityAbsoluteVeryLow

                • +

              • EPriorityAbsoluteLow

                • +

              • EPriorityAbsoluteBackground

                • +

              • EPriorityAbsoluteForeground

                • +

              • EPriorityAbsoluteHigh

                • +
               +
                +

              • EPriorityAbsoluteLowNormal

                • +

              • EPriorityAbsoluteBackgroundNormal

                • +

              • EPriorityAbsoluteForegroundNormal

                • +

              • EPriorityAbsoluteHighNormal

                • +
               +               + + +

              The thread +priority value mapping table shows the resulting true priority +of the thread.

              +
              Priority scheme +for real-time user-side threads

              This scheme is the same as the process-independent +scheme for general user threads, but with one essential difference +- the range of TThreadPriority enum values to be passed +to RThread::SetPriority() is as shown below. These priorities +map to the true priority values in the range 24 -31, and can only be +set by executables having the ProtServ capability. This range +is referred to as the real time range.

                +

              • EPriorityAbsoluteRealTime1

                • +

              • EPriorityAbsoluteRealTime2

                • +

              • EPriorityAbsoluteRealTime3

                • +

              • EPriorityAbsoluteRealTime4

                • +

              • EPriorityAbsoluteRealTime5

                • +

              • EPriorityAbsoluteRealTime6

                • +

              • EPriorityAbsoluteRealTime7

                • +

              • EPriorityAbsoluteRealTime8

                • +

              The thread +priority value mapping table shows the resulting true priority +of the thread.

              +
              Thread priority +value mapping table

              This table shows the effect of setting priorities, +and the resulting true priority values. You need to be aware that this +may change in the future, and you should never synchronise threads on the +basis of thread priorities. If you need to synchronise threads, use mutexes +or semaphores.

              Notes

                +

              • True priority values +in the shaded region can only be accessed by threads running in processes +with the ProtServ capability.

                • +

              • The process-priority +values : EPriorityWindowServer, EPriorityFileServer and EPrioritySupervisor all +map to the same range of priorities. Along with EPriorityRealTimeServer, +these have historically been used for system servers and other processes needing +access to high priorities suitable for real-time tasks, and their use requires ProtServ capability.

                • +

              • Note that ProtServ capability +will not be granted to general applications for the purpose of gaining access +to the very high thread priorities. This risks breaking important system functionality.

                • +
              + +

              Note that we have used E' as an abbreviation for EPriority in +this diagram.

              +
              Platform security +notes

              Platform security restrictions prevent thread and process +priorities from being modified by another user process. There is one exception: +by default, applications have “Priority Control” enabled for them which allows +the window server to switch them between foreground and background process +priorities depending on which has foreground focus.

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7B275129-5EF7-4B27-B603-3BDE2C650A93.dita --- a/Symbian3/SDK/Source/GUID-7B275129-5EF7-4B27-B603-3BDE2C650A93.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-7B275129-5EF7-4B27-B603-3BDE2C650A93.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,115 +1,115 @@ - - - - - -Queries -

              A query is a state where the software waits for user input. Queries are -used in situations with more than one ways to proceed, when the application -needs data from the user, or when it is necessary to make sure the user knows -what is happening. A query must be exited before the application can proceed.

              -

              Queries are displayed in pop-up windows. The following query types can -be used:

              - - - - -

              Query types

               -

              Description

               -               - - - -

              Confirmation query

               -

              A question or notice with one or two possible responses.

              -               - -

              List query

               -

              A question with a selection of more than two possible (pre-defined) -responses in a list.

              -               - -

              Grid query

               -

              A question with a selection of more than two possible (pre-defined) -responses in a grid.

               -               - -

              Multi-selection list query

               -

              Presents a list of items; the user can select any number of them.

              -               - -

              Data query

               -

              Used for numeric or textual input.

               -               - -

              Message query

               -

              Used for various purposes in queries that are longer than one screen.

               -               - - -
              -
              Using -queries in C++ applications

              The APIs to use for queries are the -Queries API, Dialogs API, and the Popups API. For implementation information, see Using the Dialogs API.

              Query dialogs are dialogs -that can be used to require user input or user selection. All query dialogs -derive from CAknQueryDialog, which inherits CAknDialog. -There are two types of queries: local and global queries. Local query dialogs -are local to a certain application. That means they are only displayed within -this application. Global query dialogs are system-wide queries, and are shown -topmost even when another application moves to the foreground. Query dialogs -require resource definitions when they are used in your code.

              To -have a header pane, the AVKON_HEADING component should be -specified as the first dialog line in the resource description.

              At -runtime, the dialog's header pane (CAknPopupHeadingPane) -can be obtained by calling the method CAknQueryDialog::QueryHeading().

              The -following parts are available for modification from the class CAknQueryDialog:

                -

              • Data query

                  -

                • Header text

                  • -

                • Header image/animation

                  • -

                • Prompt text

                  • -

                • Edit indicator (can be removed)

                  • -
                • -

              • Confirmation query

                  -

                • Prompt text

                  • -

                • Image/animation

                  • -
                • -

              • List query

                  -

                • Header text

                  • -

                • Header image/animation

                  • -

                • List type (Single, SingleHeading, SingleGraphic, SingleGraphicHeading)

                  • -
                • -

              The following example illustrates the resource definition for the -Secret Editor Query, which contains a Secret Editor, resides inside the dialog. -The values for flags, type, id, and control are specific to the query dialog. -These values are enumerated in the file avkon.hrh, which -is in the ./epoc32/include folder.

              RESOURCE DIALOG r_aknexquery_code_query - { - flags = EGeneralQueryFlags - buttons = R_AVKON_SOFTKEYS_OK_CANCEL; - items = - { - DLG_LINE - { - type = EAknCtQuery; - id = EGeneralQuery; - control = EGeneralQueryFlags - { - layout = ECodeLayout; - label = label_text; - control = SECRETED - { - num_letters = 8; - }; - }; - } - }; - } -

              The query in the above example includes a secret editor. For -information on implementing secret editors, see the Editors API.

              See also:

              + + + + + +Queries +

              A query is a state where the software waits for user input. Queries are +used in situations with more than one ways to proceed, when the application +needs data from the user, or when it is necessary to make sure the user knows +what is happening. A query must be exited before the application can proceed.

              +

              Queries are displayed in pop-up windows. The following query types can +be used:

              + + + + +

              Query types

               +

              Description

               +               + + + +

              Confirmation query

               +

              A question or notice with one or two possible responses.

              +               + +

              List query

               +

              A question with a selection of more than two possible (pre-defined) +responses in a list.

              +               + +

              Grid query

               +

              A question with a selection of more than two possible (pre-defined) +responses in a grid.

               +               + +

              Multi-selection list query

               +

              Presents a list of items; the user can select any number of them.

              +               + +

              Data query

               +

              Used for numeric or textual input.

               +               + +

              Message query

               +

              Used for various purposes in queries that are longer than one screen.

               +               + + +
              +
              Using +queries in applications

              The APIs to use for queries +are the Queries API, Dialogs API, and the Popups API. For implementation information, see Using the Dialogs API.

              Query dialogs are dialogs +that can be used to require user input or user selection. All query dialogs +derive from CAknQueryDialog, which inherits CAknDialog. +There are two types of queries: local and global queries. Local query dialogs +are local to a certain application. That means they are only displayed within +this application. Global query dialogs are system-wide queries, and are shown +topmost even when another application moves to the foreground. Query dialogs +require resource definitions when they are used in your code.

              To +have a header pane, the AVKON_HEADING component should be +specified as the first dialog line in the resource description.

              At +runtime, the dialog's header pane (CAknPopupHeadingPane) +can be obtained by calling the method CAknQueryDialog::QueryHeading().

              The +following parts are available for modification from the class CAknQueryDialog:

                +

              • Data query

                  +

                • Header text

                  • +

                • Header image/animation

                  • +

                • Prompt text

                  • +

                • Edit indicator (can be removed)

                  • +
                • +

              • Confirmation query

                  +

                • Prompt text

                  • +

                • Image/animation

                  • +
                • +

              • List query

                  +

                • Header text

                  • +

                • Header image/animation

                  • +

                • List type (Single, SingleHeading, SingleGraphic, SingleGraphicHeading)

                  • +
                • +

              The following example illustrates the resource definition for the +Secret Editor Query, which contains a Secret Editor, resides inside the dialog. +The values for flags, type, id, and control are specific to the query dialog. +These values are enumerated in the file avkon.hrh, which +is in the ./epoc32/include folder.

              RESOURCE DIALOG r_aknexquery_code_query + { + flags = EGeneralQueryFlags + buttons = R_AVKON_SOFTKEYS_OK_CANCEL; + items = + { + DLG_LINE + { + type = EAknCtQuery; + id = EGeneralQuery; + control = EGeneralQueryFlags + { + layout = ECodeLayout; + label = label_text; + control = SECRETED + { + num_letters = 8; + }; + }; + } + }; + } +

              The query in the above example includes a secret editor. For +information on implementing secret editors, see the Editors API.

              See also:

               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7B2AA498-5E73-4CC4-91DF-5F07F452F0BF.dita --- a/Symbian3/SDK/Source/GUID-7B2AA498-5E73-4CC4-91DF-5F07F452F0BF.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-7B2AA498-5E73-4CC4-91DF-5F07F452F0BF.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,24 +1,24 @@ - - - - - -Setting -pop-up -

              Setting pages are placed inside pop-ups. The settings are displayed normally -inside the pop-up with the control pane layout described in Control -pane with pop-up. When user taps outside the pop-up, the -area is inactive and the pop-up does not close. Refer to Settings for -more detailed information for the display and functional descriptions of the -setting types.

              - -Example image of a setting in a pop-up - - + + + + + +Setting +pop-up +

              Setting pages are placed inside pop-ups. The settings are displayed normally +inside the pop-up with the control pane layout described in Control +pane with pop-up. When user taps outside the pop-up, the +area is inactive and the pop-up does not close. Refer to Settings for +more detailed information for the display and functional descriptions of the +setting types.

              + +Example image of a setting in a pop-up + +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7B3578A0-7E2E-508A-A355-A39AEE0307AD_d0e304342_href.jpg Binary file Symbian3/SDK/Source/GUID-7B3578A0-7E2E-508A-A355-A39AEE0307AD_d0e304342_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7B3578A0-7E2E-508A-A355-A39AEE0307AD_d0e310357_href.jpg Binary file Symbian3/SDK/Source/GUID-7B3578A0-7E2E-508A-A355-A39AEE0307AD_d0e310357_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7B589949-2784-5B77-959E-99F8733A8853_d0e230612_href.png Binary file Symbian3/SDK/Source/GUID-7B589949-2784-5B77-959E-99F8733A8853_d0e230612_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7B589949-2784-5B77-959E-99F8733A8853_d0e234349_href.png Binary file Symbian3/SDK/Source/GUID-7B589949-2784-5B77-959E-99F8733A8853_d0e234349_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7B5A854B-A9A0-557E-9970-9B13D7EE251E.dita --- a/Symbian3/SDK/Source/GUID-7B5A854B-A9A0-557E-9970-9B13D7EE251E.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-7B5A854B-A9A0-557E-9970-9B13D7EE251E.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,88 +1,88 @@ - - - - - -Using -the MIME Framework

              The MIME -recognizers are used by the client applications for data type recognition. -When there is a client request to the AppArc for -data type recognition, AppArc internally uses the MIME recognition framework -for processing the request.

              -

              The client connects -to AppArc and creates a session using the class RApaLsSession. -Apparc provides access to the MIME framework via RApaLsSession APIs. -The class provides the APIs for data type recognition.

              All MIME (data) -recognizers are derived from the abstract base class, CApaDataRecognizerType. -The RApaLsSession data recognition APIs access the properties -of CApaDataRecognizerType for data type recognition.

              - - -Connect and create a session with AppArc server using RApaLsSession::Connect(). -RApaLsSession aLs; -TInt ret; -// Client session with the server created. -ret=aLs.Connect(); - - - -Invoke RApaLsSession::RecognizeData() or RApaLsSession::RecognizeSpecificData(). -These APIs internally invoke the implementation for CApaDataRecognizerType::DoRecognizeL(). - DoRecognizeL() of the class derived from CApaDataRecognizerType implements -the data recognition behaviour. -// Implementation of RecognizeData() - -RecognizeData(const TDesC &aName, const TDesC8 &aBuffer, TDataRecognitionResult &aDataType) - { - - CExampleRecognizer *myrecognizer= CExampleRecognizer::CreateRecognizerL(); - myrecognize->DoRecognizeL(aName,aBuffer); - - } - - -// The RApaLsSession object invokes RecognizeData() for data type recognition. - -_LIT(KMyFile, "Myfile.example"); - -_LIT(KMyBufer, "serach for example string in the file buffer"); - -TInt ret=aLs.RecognizeData(KMyFile,KMyBufer,result); - - - - -For more details about refer Writing -MIME Recognizers . - - -

              A TDataRecognitionResult object is returned to -AppArc. The object contains the data (MIME) type and the confidence of recognition.

              AppArc -attempts to find the application that can best handle the identified data -type. It is not guaranteed that an application will be available -to handle a data type, even after successful recognition.

              Notes:

              In -addition to the overloads of RApaLsSession::RecognizeData() or RApaLsSession::RecognizeSpecificData() the -following functions of the RApaLsSession also support the -processing of data type recognition request.

                -

              • The overloads of RApaLsSession::RecognizeFilesL() are -used to recognize all files contained in a specified directory.

                • -

              • RApaLsSession::GetAcceptedConfidence() and RApaLsSession::SetAcceptedConfidence() retrieve and set the accepted confidence level of the MIME framework. The -default value is ECertain.

                • -

              • RApaLsSession::GetSupportedDataTypesL() retrieves -the list of data types supported by all recognizers in the recognizer list -of the MIME framework.

                • -

              • The preferred buffer -size determines the amount of data passed to DoRecognizeL() function. -The preferred buffer size can be retrieved using RApaLsSession::GetPreferredBufSize(). -This value cannot be greater than the maximum buffer value.

                The maximum -value for the buffer is set by using RApaLsSession::SetMaxDataBufSize(). -If the maximum buffer size is not set by the client, the default value is -256 bytes. The maximum buffer size can be retrieved using RApaLsSession::GetMaxDataBufSize().

                • -

               + + + + + +Using +the MIME Framework

              The MIME +recognizers are used by the client applications for data type recognition. +When there is a client request to the AppArc for +data type recognition, AppArc internally uses the MIME recognition framework +for processing the request.

              +

              The client connects +to AppArc and creates a session using the class RApaLsSession. +Apparc provides access to the MIME framework via RApaLsSession APIs. +The class provides the APIs for data type recognition.

              All MIME (data) +recognizers are derived from the abstract base class, CApaDataRecognizerType. +The RApaLsSession data recognition APIs access the properties +of CApaDataRecognizerType for data type recognition.

              + + +Connect and create a session with AppArc server using RApaLsSession::Connect(). +RApaLsSession aLs; +TInt ret; +// Client session with the server created. +ret=aLs.Connect(); + + + +Invoke RApaLsSession::RecognizeData() or RApaLsSession::RecognizeSpecificData(). +These APIs internally invoke the implementation for CApaDataRecognizerType::DoRecognizeL(). + DoRecognizeL() of the class derived from CApaDataRecognizerType implements +the data recognition behaviour. +// Implementation of RecognizeData() + +RecognizeData(const TDesC &aName, const TDesC8 &aBuffer, TDataRecognitionResult &aDataType) + { + + CExampleRecognizer *myrecognizer= CExampleRecognizer::CreateRecognizerL(); + myrecognize->DoRecognizeL(aName,aBuffer); + + } + + +// The RApaLsSession object invokes RecognizeData() for data type recognition. + +_LIT(KMyFile, "Myfile.example"); + +_LIT(KMyBufer, "serach for example string in the file buffer"); + +TInt ret=aLs.RecognizeData(KMyFile,KMyBufer,result); + + + + +For more details about refer Writing +MIME Recognizers . + + +

              A TDataRecognitionResult object is returned to +AppArc. The object contains the data (MIME) type and the confidence of recognition.

              AppArc +attempts to find the application that can best handle the identified data +type. It is not guaranteed that an application will be available +to handle a data type, even after successful recognition.

              Notes:

              In +addition to the overloads of RApaLsSession::RecognizeData() or RApaLsSession::RecognizeSpecificData() the +following functions of the RApaLsSession also support the +processing of data type recognition request.

                +

              • The overloads of RApaLsSession::RecognizeFilesL() are +used to recognize all files contained in a specified directory.

                • +

              • RApaLsSession::GetAcceptedConfidence() and RApaLsSession::SetAcceptedConfidence() retrieve and set the accepted confidence level of the MIME framework. The +default value is ECertain.

                • +

              • RApaLsSession::GetSupportedDataTypesL() retrieves +the list of data types supported by all recognizers in the recognizer list +of the MIME framework.

                • +

              • The preferred buffer +size determines the amount of data passed to DoRecognizeL() function. +The preferred buffer size can be retrieved using RApaLsSession::GetPreferredBufSize(). +This value cannot be greater than the maximum buffer value.

                The maximum +value for the buffer is set by using RApaLsSession::SetMaxDataBufSize(). +If the maximum buffer size is not set by the client, the default value is +256 bytes. The maximum buffer size can be retrieved using RApaLsSession::GetMaxDataBufSize().

                • +

                             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7C061090-83A8-5E0F-B42B-2D722BE054EE_d0e243007_href.png Binary file Symbian3/SDK/Source/GUID-7C061090-83A8-5E0F-B42B-2D722BE054EE_d0e243007_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7C061090-83A8-5E0F-B42B-2D722BE054EE_d0e246744_href.png Binary file Symbian3/SDK/Source/GUID-7C061090-83A8-5E0F-B42B-2D722BE054EE_d0e246744_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7C51BC7A-CB97-5A7E-A5EF-BB3623DFFFED_d0e189683_href.png Binary file Symbian3/SDK/Source/GUID-7C51BC7A-CB97-5A7E-A5EF-BB3623DFFFED_d0e189683_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7C51BC7A-CB97-5A7E-A5EF-BB3623DFFFED_d0e194738_href.png Binary file Symbian3/SDK/Source/GUID-7C51BC7A-CB97-5A7E-A5EF-BB3623DFFFED_d0e194738_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7C75642D-C0C9-5392-9354-711F42DC2C61.dita --- a/Symbian3/SDK/Source/GUID-7C75642D-C0C9-5392-9354-711F42DC2C61.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-7C75642D-C0C9-5392-9354-711F42DC2C61.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,144 +1,144 @@ - - - - - -Server-Initiated -vs. Application-Initiated RedrawingThis topic introduces the reasons that the screen display may need -to be updated and the difference between redrawing that is initiated by an -application and that initiated by the Window Server. -

              Variant: Both (ScreenPlay and non-ScreenPlay). Target -audience: Application developers.

              -
              Introduction

              The Window Server maintains the UI -display taking into account the region, ordinal position and visibility requirements -of all displayable windows. The UI may be updated for several reasons:

                -

              • at direct application -request by an application drawing to a window through a CWindowGc

                • -

              • due to regions of the -display becoming invalid

                • -

              • due to actions internal -to the Window Server, such as pointer cursor movements.

                • -

              When a window is moved, resized, or otherwise manipulated by an application, -it may cause parts of other windows to become invalid so that they must be -redrawn. The Window Server maintains a list of all invalid regions and causes -them to be redrawn in one of several ways:

                -

              • for a region with no -window, the Window Server redraws the invalid region in the default background -color

                • -

              • for a blank window, -the Window Server redraws the invalid region in the window's color

                • -

              • for a backed-up window, -the invalid region is redrawn from a backup bitmap maintained by the Window -Server

                • -

              • if the invalid region -is owned by an animation DLL, the Window Server invokes the animation DLL -directly to redraw the area: the region is then valid again

                • -

              • for a normal RWindow, -whenever possible, the Window Server replays the sequence of drawing commands -stored in the redraw stores. However, sometimes this is not possible, because, -for example, the redraw stores have been lost due to low memory conditions. -In these circumstances, the Window Server generates a redraw event and sends -it to the application. This is described in more detail below.

                • -
              -
              Window Server-initiated redrawing

              When the Window -Server needs to repaint a standard RWindow window and it -is not possible to do this by replaying the drawing commands stored in the -redraw stores, it sends a TWsRedrawEvent message to the -client.

              It is part of the client's contract with the Window Server -to listen for these events and respond to them by performing a redraw. The -normal way for a client application to do this is through an active object, -which is sometimes called a redrawer. This is normally provided by -the application framework and should have a lower priority than the active -objects for standard events. The client issues an asynchronous request for -the next redraw event, calling the RWsSession::RedrawReady() function.

              The -redrawer's RunL() function (which handles the completed -request) calls RWsSession::GetRedraw(). This gets the TWsRedrawEvent, -which contains the handle of the window and the rectangle within it that needs -to be redrawn and then does the redraw. This involves:

                -

              1. Calling RWindow::BeginRedraw() on -the relevant window and passing in the rectangle.

                2. -

              2. Issuing the CWindowGc drawing -commands that define how to draw the area of the window specified by the rectangle -passed in the TWsRedrawEvent. These drawing commands must -exactly match what was drawn originally, because the Window Server clips the -drawing to the passed rectangle.

                3. -

              3. Calling RWindow::EndRedraw().

                4. -

              At the end of the redrawer’s RunL(), a call is -made to RWsSession::RedrawReady() to enable the client -to listen for further requests from the Window Server.

              The following -diagram demonstrates that typically the RunL() starts with -a GetRedraw() and ends with a call to RedrawReady().

              - Window Server-initiated redraw - -

              A redrawer's RunL() function must not perform -any non-redraw drawing (that is, any drawing operations that are not bracketed -within the calls to BeginRedraw() and EndRedraw()). -If it does, this causes a panic with code 79 (EWservPanicWindowBeginRedrawNotCalled) -in the ScreenPlay variant. This is to avoid the infinite loop that would otherwise -be caused by an endless cycle of the non-redraw drawing within the RunL() triggering -a Window Server-initiated redraw.

              -
              Application-initiated redrawing

              An application -initiates redrawing when it wants to update the UI to reflect a change of -state. There are two scenarios, which we describe under separate headings -below.

              The "draw now" scenario

              The "draw now" redraw scenario is -when an application wants to push a state change to a window immediately. -Typically the application does this by calling CCoeControl::DrawNow(). -However, it is possible to achieve the same results using RWindow and CWindowGc calls -directly. To illustrate how to do this, consider a digital clock application -that updates the time displayed in the window from 12:02 to 12:03.

              The -application does the following:

                -

              1. Calls RWindow::Invalidate(), -optionally passing in the bounding rectangle. When called without passing -in a rectangle, this function invalidates the entire window.

                2. -

              2. Calls RWindow::BeginRedraw(). -If the application passed a bounding rectangle to Invalidate(), -it must pass the same bounding rectangle to BeginRedraw(). -If the application did not pass a bounding rectangle to Invalidate(), -it must not pass one to BeginRedraw().

                3. -

              3. Issues the CWindowGc draw -commands.

                4. -

              4. Calls RWindow::EndRedraw().

                5. -
              - Application-initiated redrawing, "draw now" scenario - - -

              The "draw deferred" scenario

              The "draw deferred" redraw scenario -is when an application simply marks a window or a rectangle within a window -as invalid. This eventually triggers a Window Server-initiated redraw. Typically -the application does this by calling CCoeControl::DrawDeferred(). -However, it is also possible to do this by calling RWindow::Invalidate().

              - Application-initiated redrawing, "draw deferred" scenario - - -

              This approach is useful when the data to be displayed might be updated -frequently but it is not necessary to update the display instantaneously.

              To -illustrate how it works, consider a window that has a rectangle that is used -to display icons (a star, a cross and a triangle) that represent three different -events that can occur in the application. Suppose the events can occur in -quick succession. If you use the "draw now" approach when each event occurs, -the Window Server updates the display separately for each one, as shown in -the following diagram.

              - Icons displayed using the "draw now" approach - - -

              However, if you use the "draw deferred" approach when each event -occurs, the Window Server may not update the display for each one. For example, -the Window Server does not update the display when it is superceded by a later -call.

              - Icons displayed using the "draw deferred" approach - - -

              If it is important that the display is updated immediately, you -would generally use the "draw now" approach. However, if a short delay in -the display being updated is unlikely to inconvenience the user, the "draw -deferred" approach might be appropriate and has a performance advantage.

              -               -Graphics -and Drawing + + + + + +Server-Initiated +vs. Application-Initiated RedrawingThis topic introduces the reasons that the screen display may need +to be updated and the difference between redrawing that is initiated by an +application and that initiated by the Window Server. +

              Variant: Both (ScreenPlay and non-ScreenPlay). Target +audience: Application developers.

              +
              Introduction

              The Window Server maintains the UI +display taking into account the region, ordinal position and visibility requirements +of all displayable windows. The UI may be updated for several reasons:

                +

              • at direct application +request by an application drawing to a window through a CWindowGc

                • +

              • due to regions of the +display becoming invalid

                • +

              • due to actions internal +to the Window Server, such as pointer cursor movements.

                • +

              When a window is moved, resized, or otherwise manipulated by an application, +it may cause parts of other windows to become invalid so that they must be +redrawn. The Window Server maintains a list of all invalid regions and causes +them to be redrawn in one of several ways:

                +

              • for a region with no +window, the Window Server redraws the invalid region in the default background +color

                • +

              • for a blank window, +the Window Server redraws the invalid region in the window's color

                • +

              • for a backed-up window, +the invalid region is redrawn from a backup bitmap maintained by the Window +Server

                • +

              • if the invalid region +is owned by an animation DLL, the Window Server invokes the animation DLL +directly to redraw the area: the region is then valid again

                • +

              • for a normal RWindow, +whenever possible, the Window Server replays the sequence of drawing commands +stored in the redraw stores. However, sometimes this is not possible, because, +for example, the redraw stores have been lost due to low memory conditions. +In these circumstances, the Window Server generates a redraw event and sends +it to the application. This is described in more detail below.

                • +
              +
              Window Server-initiated redrawing

              When the Window +Server needs to repaint a standard RWindow window and it +is not possible to do this by replaying the drawing commands stored in the +redraw stores, it sends a TWsRedrawEvent message to the +client.

              It is part of the client's contract with the Window Server +to listen for these events and respond to them by performing a redraw. The +normal way for a client application to do this is through an active object, +which is sometimes called a redrawer. This is normally provided by +the application framework and should have a lower priority than the active +objects for standard events. The client issues an asynchronous request for +the next redraw event, calling the RWsSession::RedrawReady() function.

              The +redrawer's RunL() function (which handles the completed +request) calls RWsSession::GetRedraw(). This gets the TWsRedrawEvent, +which contains the handle of the window and the rectangle within it that needs +to be redrawn and then does the redraw. This involves:

                +

              1. Calling RWindow::BeginRedraw() on +the relevant window and passing in the rectangle.

                2. +

              2. Issuing the CWindowGc drawing +commands that define how to draw the area of the window specified by the rectangle +passed in the TWsRedrawEvent. These drawing commands must +exactly match what was drawn originally, because the Window Server clips the +drawing to the passed rectangle.

                3. +

              3. Calling RWindow::EndRedraw().

                4. +

              At the end of the redrawer’s RunL(), a call is +made to RWsSession::RedrawReady() to enable the client +to listen for further requests from the Window Server.

              The following +diagram demonstrates that typically the RunL() starts with +a GetRedraw() and ends with a call to RedrawReady().

              + Window Server-initiated redraw + +

              A redrawer's RunL() function must not perform +any non-redraw drawing (that is, any drawing operations that are not bracketed +within the calls to BeginRedraw() and EndRedraw()). +If it does, this causes a panic with code 79 (EWservPanicWindowBeginRedrawNotCalled) +in the ScreenPlay variant. This is to avoid the infinite loop that would otherwise +be caused by an endless cycle of the non-redraw drawing within the RunL() triggering +a Window Server-initiated redraw.

              +
              Application-initiated redrawing

              An application +initiates redrawing when it wants to update the UI to reflect a change of +state. There are two scenarios, which we describe under separate headings +below.

              The "draw now" scenario

              The "draw now" redraw scenario is +when an application wants to push a state change to a window immediately. +Typically the application does this by calling CCoeControl::DrawNow(). +However, it is possible to achieve the same results using RWindow and CWindowGc calls +directly. To illustrate how to do this, consider a digital clock application +that updates the time displayed in the window from 12:02 to 12:03.

              The +application does the following:

                +

              1. Calls RWindow::Invalidate(), +optionally passing in the bounding rectangle. When called without passing +in a rectangle, this function invalidates the entire window.

                2. +

              2. Calls RWindow::BeginRedraw(). +If the application passed a bounding rectangle to Invalidate(), +it must pass the same bounding rectangle to BeginRedraw(). +If the application did not pass a bounding rectangle to Invalidate(), +it must not pass one to BeginRedraw().

                3. +

              3. Issues the CWindowGc draw +commands.

                4. +

              4. Calls RWindow::EndRedraw().

                5. +
              + Application-initiated redrawing, "draw now" scenario + + +

              The "draw deferred" scenario

              The "draw deferred" redraw scenario +is when an application simply marks a window or a rectangle within a window +as invalid. This eventually triggers a Window Server-initiated redraw. Typically +the application does this by calling CCoeControl::DrawDeferred(). +However, it is also possible to do this by calling RWindow::Invalidate().

              + Application-initiated redrawing, "draw deferred" scenario + + +

              This approach is useful when the data to be displayed might be updated +frequently but it is not necessary to update the display instantaneously.

              To +illustrate how it works, consider a window that has a rectangle that is used +to display icons (a star, a cross and a triangle) that represent three different +events that can occur in the application. Suppose the events can occur in +quick succession. If you use the "draw now" approach when each event occurs, +the Window Server updates the display separately for each one, as shown in +the following diagram.

              + Icons displayed using the "draw now" approach + + +

              However, if you use the "draw deferred" approach when each event +occurs, the Window Server may not update the display for each one. For example, +the Window Server does not update the display when it is superceded by a later +call.

              + Icons displayed using the "draw deferred" approach + + +

              If it is important that the display is updated immediately, you +would generally use the "draw now" approach. However, if a short delay in +the display being updated is unlikely to inconvenience the user, the "draw +deferred" approach might be appropriate and has a performance advantage.

              +               +Graphics +and Drawing               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7C87B04A-1CCC-47D2-9B53-4E341412EFD2-master.png Binary file Symbian3/SDK/Source/GUID-7C87B04A-1CCC-47D2-9B53-4E341412EFD2-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7C87B04A-1CCC-47D2-9B53-4E341412EFD2_d0e66044_href.png Binary file Symbian3/SDK/Source/GUID-7C87B04A-1CCC-47D2-9B53-4E341412EFD2_d0e66044_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7C87B04A-1CCC-47D2-9B53-4E341412EFD2_d0e71293_href.png Binary file Symbian3/SDK/Source/GUID-7C87B04A-1CCC-47D2-9B53-4E341412EFD2_d0e71293_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7D025BEF-61B9-4EF1-AFF7-604B500A8F2C-master.png Binary file Symbian3/SDK/Source/GUID-7D025BEF-61B9-4EF1-AFF7-604B500A8F2C-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7D025BEF-61B9-4EF1-AFF7-604B500A8F2C_d0e64446_href.png Binary file Symbian3/SDK/Source/GUID-7D025BEF-61B9-4EF1-AFF7-604B500A8F2C_d0e64446_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7D025BEF-61B9-4EF1-AFF7-604B500A8F2C_d0e69665_href.png Binary file Symbian3/SDK/Source/GUID-7D025BEF-61B9-4EF1-AFF7-604B500A8F2C_d0e69665_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7D13B61C-0C9E-5098-87F0-BB9D741E9281_d0e267163_href.png Binary file Symbian3/SDK/Source/GUID-7D13B61C-0C9E-5098-87F0-BB9D741E9281_d0e267163_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7D13B61C-0C9E-5098-87F0-BB9D741E9281_d0e270871_href.png Binary file Symbian3/SDK/Source/GUID-7D13B61C-0C9E-5098-87F0-BB9D741E9281_d0e270871_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7D53E323-CF8D-5C4D-ABCD-4D95C7A4A5B5.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-7D53E323-CF8D-5C4D-ABCD-4D95C7A4A5B5.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,111 @@ + + + + + +Secure store encryption example support code

              Below is the supporting code for the secure store example code.

              <codeblock id="GUID-36F57493-4F6E-559A-B51B-7261F57AF1B1" xml:space="preserve"> +#include "e32std.h" +#include "f32file.h" +#include "s32file.h" +#include "pbe.h" +#include "pbedata.h" +#include "s32crypt.h" + </codeblock> <codeblock id="GUID-EE52D935-4E72-5D4A-809C-BA0FEE19C90F" xml:space="preserve"> +/* + * Class to demonstrate the use of secure store APIs. + */ +class CSecureStoreExample : public CBase + { +public: + static CSecureStoreExample* NewLC(const TDesC& aFilename); + virtual ~CSecureStoreExample(); + + void CreateNewStoreL(const TDesC& aPassword); + TStreamId WriteEncryptedDataL(const TDesC8& aInput); + void OpenExistingStoreL(const TDesC& aPassword); + HBufC8* ReadEncryptedDataLC(TStreamId aStreamId); + void CloseStore(); + void ChangePasswordL(const TDesC& aNewPassword); +private: + CSecureStoreExample(const TDesC& aFilename); + void ConstructL(); +private: + RFs iFs; + const TDesC& iFilename; + CPermanentFileStore* iFileStore; + CPBEncryptSet* iEncryptSet; + CSecureStore* iSecureStore; + }; + </codeblock> <codeblock id="GUID-DB3DBE48-DCEC-5CDD-9066-246AD37A5C12" xml:space="preserve"> +CSecureStoreExample* CSecureStoreExample::NewLC(const TDesC& aFilename) + { + CSecureStoreExample* self = new (ELeave) CSecureStoreExample(aFilename); + CleanupStack::PushL(self); + self->ConstructL(); + return self; + } + +CSecureStoreExample::CSecureStoreExample(const TDesC& aFilename) + : iFilename(aFilename) + { + } + +void CSecureStoreExample::ConstructL() + { + User::LeaveIfError(iFs.Connect()); + } + +CSecureStoreExample::~CSecureStoreExample() + { + CloseStore(); + iFs.Close(); + } + </codeblock> <codeblock id="GUID-4485993E-0561-5688-85FA-3914AECDF12B" xml:space="preserve"> +LOCAL_D void RunPBEExampleL() + { + _LIT(KFilename, "c:\\pbe_example_data.dat"); + _LIT8(KInputData, "This is the data to be encrypted."); + _LIT(KPassword, "pa55w0rd"); + _LIT(KNewPassword, "chang3m3"); + + CSecureStoreExample* main = CSecureStoreExample::NewLC(KFilename); + + // Create a secure store and write some data to it + main->CreateNewStoreL(KPassword); + TStreamId streamId = main->WriteEncryptedDataL(KInputData); + main->CloseStore(); + + // Open it again, and read the data back out + main->OpenExistingStoreL(KPassword); + HBufC8* outputData = main->ReadEncryptedDataLC(streamId); + ASSERT(*outputData == KInputData); + CleanupStack::PopAndDestroy(outputData); + + // Change the password + main->ChangePasswordL(KNewPassword); + + // Check we can still read the data + outputData = main->ReadEncryptedDataLC(streamId); + ASSERT(*outputData == KInputData); + main->CloseStore(); + + CleanupStack::PopAndDestroy(2, main); + } + </codeblock> <codeblock id="GUID-7FF91AD3-106A-56EA-9199-0E261B8D044C" xml:space="preserve"> +GLDEF_C TInt E32Main() // main function called by E32 + { + __UHEAP_MARK; + CTrapCleanup* cleanup = CTrapCleanup::New(); // get clean-up stack + TRAPD(error, RunPBEExampleL()); + __ASSERT_ALWAYS(!error,User::Panic(_L("pbe_example_code"),error)); + delete cleanup; // destroy clean-up stack + __UHEAP_MARKEND; + return 0; + } + </codeblock> </section> </conbody></concept> \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7DDC1BC6-A100-5B50-ABFE-B4AA466716A6_d0e287350_href.png Binary file Symbian3/SDK/Source/GUID-7DDC1BC6-A100-5B50-ABFE-B4AA466716A6_d0e287350_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7DDC1BC6-A100-5B50-ABFE-B4AA466716A6_d0e290983_href.png Binary file Symbian3/SDK/Source/GUID-7DDC1BC6-A100-5B50-ABFE-B4AA466716A6_d0e290983_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7DDEE87B-7056-5AAA-91A1-33D3D0D50041.dita --- a/Symbian3/SDK/Source/GUID-7DDEE87B-7056-5AAA-91A1-33D3D0D50041.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-7DDEE87B-7056-5AAA-91A1-33D3D0D50041.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,38 +1,38 @@ -<?xml version="1.0" encoding="utf-8"?> -<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> -<!-- This component and the accompanying materials are made available under the terms of the License -"Eclipse Public License v1.0" which accompanies this distribution, -and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> -<!-- Initial Contributors: - Nokia Corporation - initial contribution. -Contributors: ---> -<!DOCTYPE concept - PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> -<concept id="GUID-7DDEE87B-7056-5AAA-91A1-33D3D0D50041" xml:lang="en"><title>Array -of packed elements, flat arrayDescribes arrays of packed elements in a flat. -

              This is a CArrayPakFlat<class T> object whose -elements can have different lengths but are physically contiguous within a -flat array buffer. Each element is preceded by a TInt value -to record the length of that element.

              -

              A flat buffer always occupies a single cell allocated from the heap and -is always extended by the process of reallocation. A flat array buffer is -implemented using a CBufFlat object.

              -

              The following diagram illustrates how elements are organised within the -array buffer:

              - - - -

              This kind of array is suitable for a small number of objects or for a moderately -large but fixed maximum number of objects. It is not suitable for large arrays -with a high turnover of elements.

              -

              A packed array has the advantage over a variable flat array in having a -smaller memory overhead for each element. The disadvantage is that the elements -and their preceding TInt values occupy a single cell which -has a higher risk of reallocation failure in times of low memory availability.

              -

              This class is immediately derived from the abstract template -base class CArrayPak<class T> which is itself derived -from the abstract non-templated base class CArrayPakBase.

              -
              See also

              Using -Dynamic Buffers.

              + + + + + +Array +of packed elements, flat arrayDescribes arrays of packed elements in a flat. +

              This is a CArrayPakFlat<class T> object whose +elements can have different lengths but are physically contiguous within a +flat array buffer. Each element is preceded by a TInt value +to record the length of that element.

              +

              A flat buffer always occupies a single cell allocated from the heap and +is always extended by the process of reallocation. A flat array buffer is +implemented using a CBufFlat object.

              +

              The following diagram illustrates how elements are organised within the +array buffer:

              + + + +

              This kind of array is suitable for a small number of objects or for a moderately +large but fixed maximum number of objects. It is not suitable for large arrays +with a high turnover of elements.

              +

              A packed array has the advantage over a variable flat array in having a +smaller memory overhead for each element. The disadvantage is that the elements +and their preceding TInt values occupy a single cell which +has a higher risk of reallocation failure in times of low memory availability.

              +

              This class is immediately derived from the abstract template +base class CArrayPak<class T> which is itself derived +from the abstract non-templated base class CArrayPakBase.

              +
              See also

              Using +Dynamic Buffers.

               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7DFA1B74-5BD1-494D-9BBA-B2D6F258C5F1.dita --- a/Symbian3/SDK/Source/GUID-7DFA1B74-5BD1-494D-9BBA-B2D6F258C5F1.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-7DFA1B74-5BD1-494D-9BBA-B2D6F258C5F1.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,52 +1,52 @@ - - - - - -Indicators -in the Navi pane -

              The Navi pane can contain several kinds of indicators, depending on which -way the pane is used in the particular context:

              -Navi pane indicators - - - -Indicators -

              Description

               -               - - - -

              Left and right arrows

              -Arrows in the Navi pane - -               -

              When horizontal navigation between different main pane views is -used, the Navi pane displays the navigation information (tabs or text may -be used). The arrow icons on the left and right ends of the Navi pane indicate -the possibility to move in the corresponding directions (with tabs, the arrows -are only displayed when all tabs are not visible).

               -               - -

              Editing indicators

              -Editing indicators in the Navi pane - -               -

              When an editor is in use in the main pane, the indicators related -to editing parameters are displayed in the Navi pane. They indicate things -such as the editing mode (numeric/alphanumeric), character case, Predictive -Text status, and the available space.

               -               - - -
              -
              Using -navi pane indicators in C++ applications

              The API to use for indicators -is the Indicators API. For the navi pane, use the Navigation pane API. For implementation information, see Using the Navigation pane API.

              + + + + + +Indicators +in the Navi pane +

              The Navi pane can contain several kinds of indicators, depending on which +way the pane is used in the particular context:

              +Navi pane indicators + + + +Indicators +

              Description

               +               + + + +

              Left and right arrows

              +Arrows in the Navi pane + +               +

              When horizontal navigation between different main pane views is +used, the Navi pane displays the navigation information (tabs or text may +be used). The arrow icons on the left and right ends of the Navi pane indicate +the possibility to move in the corresponding directions.

              Navi +arrows are not used with tabs.

               +               + +

              Editing indicators

              +Editing indicators in the Navi pane + +               +

              When an editor is in use in the main pane, the indicators related +to editing parameters are displayed in the Navi pane. They indicate things +such as the editing mode (numeric/alphanumeric), character case, Predictive +Text status, and the available space.

               +               + + +
              +
              Using +navi pane indicators in applications

              The API to use for indicators +is the Indicators API. For the navi pane, use the Navigation pane API. For implementation information, see Using the Navigation pane API.

               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7E6634DC-7F07-5687-AFEE-D5BD268B8E1D_d0e34576_href.png Binary file Symbian3/SDK/Source/GUID-7E6634DC-7F07-5687-AFEE-D5BD268B8E1D_d0e34576_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7E6634DC-7F07-5687-AFEE-D5BD268B8E1D_d0e40142_href.png Binary file Symbian3/SDK/Source/GUID-7E6634DC-7F07-5687-AFEE-D5BD268B8E1D_d0e40142_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7E7BCC57-E14F-56A4-B948-B9FB9E7AB598_d0e7115_href.png Binary file Symbian3/SDK/Source/GUID-7E7BCC57-E14F-56A4-B948-B9FB9E7AB598_d0e7115_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7E7BCC57-E14F-56A4-B948-B9FB9E7AB598_d0e8390_href.png Binary file Symbian3/SDK/Source/GUID-7E7BCC57-E14F-56A4-B948-B9FB9E7AB598_d0e8390_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7E801A44-4509-5AC0-88D5-7DEA1AF7969D_d0e5815_href.png Binary file Symbian3/SDK/Source/GUID-7E801A44-4509-5AC0-88D5-7DEA1AF7969D_d0e5815_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7E801A44-4509-5AC0-88D5-7DEA1AF7969D_d0e7090_href.png Binary file Symbian3/SDK/Source/GUID-7E801A44-4509-5AC0-88D5-7DEA1AF7969D_d0e7090_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7E8C363C-5908-445D-8595-D53F217186ED_d0e73606_href.png Binary file Symbian3/SDK/Source/GUID-7E8C363C-5908-445D-8595-D53F217186ED_d0e73606_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7E8C363C-5908-445D-8595-D53F217186ED_d0e78726_href.png Binary file Symbian3/SDK/Source/GUID-7E8C363C-5908-445D-8595-D53F217186ED_d0e78726_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7F0EC737-F5EE-5B58-B9EB-4D8A058E3A49_d0e195421_href.jpg Binary file Symbian3/SDK/Source/GUID-7F0EC737-F5EE-5B58-B9EB-4D8A058E3A49_d0e195421_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7F0EC737-F5EE-5B58-B9EB-4D8A058E3A49_d0e200429_href.jpg Binary file Symbian3/SDK/Source/GUID-7F0EC737-F5EE-5B58-B9EB-4D8A058E3A49_d0e200429_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7F3F89C0-999A-552E-90BB-17D720C53DE6_d0e184682_href.png Binary file Symbian3/SDK/Source/GUID-7F3F89C0-999A-552E-90BB-17D720C53DE6_d0e184682_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7F3F89C0-999A-552E-90BB-17D720C53DE6_d0e191278_href.png Binary file Symbian3/SDK/Source/GUID-7F3F89C0-999A-552E-90BB-17D720C53DE6_d0e191278_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7F6283C0-46E8-427C-B6A9-FB274A7D2C15.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-7F6283C0-46E8-427C-B6A9-FB274A7D2C15.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,51 @@ + + + + + +Opening +a Connection to a SNAP by specifying SNAP TypeExtended Connection Preferences API can be used by applications +to set the SNAP type prior to establishing a connection. +

              Specifying +SNAP type enables the applications to start a connection to a specific SNAP +(For example, Internet SNAP or Intranet SNAP) without iterating through the +SNAP list to identify the appropriate type.

               + +Connect to socket server . + RSocketServ ss; +ss.Connect(); + + Open a RConnection object. + RConnection conn; +conn.Open( ss ); + +Create a connection +preference list and extended connection preferences object. + TConnPrefList prefList; +TExtendedConnPref preferences; + +Set the SNAP type +using TExtendedConnPref::SetSnapPurpose(). +preferences.SetSnapPurpose( CMManager::ESnapPurposeInternet ); + +Append the extended +connection preferences into connection preference list. +prefList.AppendL( &preferences ); + +Start a connection +with connection preferences. +conn.Start( prefList ); + + +

              The application +is connected to Internet SNAP.

               +               +Additional +Connection Preferences +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7F8F6ABB-8F46-5486-A116-6965787BC539_d0e177349_href.png Binary file Symbian3/SDK/Source/GUID-7F8F6ABB-8F46-5486-A116-6965787BC539_d0e177349_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7F8F6ABB-8F46-5486-A116-6965787BC539_d0e183943_href.png Binary file Symbian3/SDK/Source/GUID-7F8F6ABB-8F46-5486-A116-6965787BC539_d0e183943_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7FCFB114-B186-5615-9134-08612BB675EE.dita --- a/Symbian3/SDK/Source/GUID-7FCFB114-B186-5615-9134-08612BB675EE.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-7FCFB114-B186-5615-9134-08612BB675EE.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,84 +1,84 @@ - - - - - -tcharexample: -TChar exampleThis example application demonstrates how to use TChar, TCharF, TCharLC and TCharUC classes. -
              -
              Purpose

              TChar represents -a single character. It stores the character's value as a 32-bit unsigned integer -and it provides various functions to manipulate the character and retrieve -its properties.

              TChar and its derived classes can be used to represent -Unicode values outside plane 0 (that is, Unicode values within the -extended Unicode range from 0x10000 to 0xFFFFF). -This differentiates them from the related class TText, which -can only be used for 16-bit Unicode character values.

              -
              Class summary
                -

              • TChar - Holds a character value and provides a number -of utility functions to manipulate it and test its properties.

                • -

              • TCharF - Folds a specified character and provides -functions to fold additional characters after construction of the object.

                • -

              • TCharLC - Converts a specified character to lower -case and provides functions to convert additional characters after construction -of the object.

                • -

              • TCharUC - Converts a specified character to upper -case and provides functions to convert additional characters after construction -of the object.

                • -
              -
              Download

              Click -on the following link to download the example: tcharexample.zip.

              click: browse to view the example code.

              -
              Design and -implementation

              Using TChar

              The example retrieves -information about a character using:

                -

              • various Is...() functions, -for instance its case (e.g. TChar::IsLower()), whether -it is alphabetic (TChar::IsAlpha()), a decimal digit (TChar::IsDigit()), -and whether it is printable (TChar::IsPrint()).

                • -

              • various Get...() functions, -for instance its upper, lower and title case versions, e.g. (TChar::GetUpperCase()), -and the character width for Chinese, Japanese and Korean characters (TChar::GetCjkWidth()).

                • -

              • the TChar::TCharInfo struct. -This struct holds most of the information about the character, including its -Unicode category, and is populated by calling TChar::GetInfo().

                • -

              Using TCharF, TCharLC and TCharUC

              Related APIs

                -

              • TChar::GetCjkWidth()

                • -

              • TChar::GetInfo()

                • -

              • TChar::GetUpperCase()

                • -

              • TChar::IsAlpha()

                • -

              • TChar::IsDigit()

                • -

              • TChar::IsLower()

                • -

              • TChar::IsPrint()

                • -

              • TChar::TCharInfo - A structure to hold information -about a Unicode character.

                • -

              TCharF represents a folded character. The example -demonstrates how folding a character removes case and accent distinctions.

              The -example also demonstrates converting characters between lower and upper case -using TCharLC and TCharUC.

              -
              Building and -configuring

              To build the example:

                -

              • You can build the example -from your IDE or the command line.

                If you use an IDE, import the bld.inf file -of the example into your IDE, and use the build command of the IDE.

                If -you use the command line, open a command prompt, and set the current directory -to the source code directory of the example. You can then build the example -with the SBSv1 build tools with the following commands:

                bldmake -bldfiles

                abld build

                How to use bldmake and How to use abld describe -how to use the SBSv1 build tools.

                • -

              • For the emulator, the -example builds an executable called tcharexample.exe in -the epoc32\release\winscw\<udeb or urel>\ folder.

                • -
              -
              Running the -example

              The example application displays a list of options and -sub options to the user and takes input from the user.

              - Screenshot for TChar example - -
              + + + + + +tcharexample: +TChar exampleThis example application demonstrates how to use TChar, TCharF, TCharLC and TCharUC classes. +
              +
              Purpose

              TChar represents +a single character. It stores the character's value as a 32-bit unsigned integer +and it provides various functions to manipulate the character and retrieve +its properties.

              TChar and its derived classes can be used to represent +Unicode values outside plane 0 (that is, Unicode values within the +extended Unicode range from 0x10000 to 0xFFFFF). +This differentiates them from the related class TText, which +can only be used for 16-bit Unicode character values.

              +
              Class summary
                +

              • TChar - Holds a character value and provides a number +of utility functions to manipulate it and test its properties.

                • +

              • TCharF - Folds a specified character and provides +functions to fold additional characters after construction of the object.

                • +

              • TCharLC - Converts a specified character to lower +case and provides functions to convert additional characters after construction +of the object.

                • +

              • TCharUC - Converts a specified character to upper +case and provides functions to convert additional characters after construction +of the object.

                • +
              +
              Download

              Click +on the following link to download the example: tcharexample.zip.

              click: browse to view the example code.

              +
              Design and +implementation

              Using TChar

              The example retrieves +information about a character using:

                +

              • various Is...() functions, +for instance its case (e.g. TChar::IsLower()), whether +it is alphabetic (TChar::IsAlpha()), a decimal digit (TChar::IsDigit()), +and whether it is printable (TChar::IsPrint()).

                • +

              • various Get...() functions, +for instance its upper, lower and title case versions, e.g. (TChar::GetUpperCase()), +and the character width for Chinese, Japanese and Korean characters (TChar::GetCjkWidth()).

                • +

              • the TChar::TCharInfo struct. +This struct holds most of the information about the character, including its +Unicode category, and is populated by calling TChar::GetInfo().

                • +

              Using TCharF, TCharLC and TCharUC

              Related APIs

                +

              • TChar::GetCjkWidth()

                • +

              • TChar::GetInfo()

                • +

              • TChar::GetUpperCase()

                • +

              • TChar::IsAlpha()

                • +

              • TChar::IsDigit()

                • +

              • TChar::IsLower()

                • +

              • TChar::IsPrint()

                • +

              • TChar::TCharInfo - A structure to hold information +about a Unicode character.

                • +

              TCharF represents a folded character. The example +demonstrates how folding a character removes case and accent distinctions.

              The +example also demonstrates converting characters between lower and upper case +using TCharLC and TCharUC.

              +
              Building and +configuring

              To build the example:

                +

              • You can build the example +from your IDE or the command line.

                If you use an IDE, import the bld.inf file +of the example into your IDE, and use the build command of the IDE.

                If +you use the command line, open a command prompt, and set the current directory +to the source code directory of the example. You can then build the example +with the SBSv1 build tools with the following commands:

                bldmake +bldfiles

                abld build

                How to use bldmake and How to use abld describe +how to use the SBSv1 build tools.

                • +

              • For the emulator, the +example builds an executable called tcharexample.exe in +the epoc32\release\winscw\<udeb or urel>\ folder.

                • +
              +
              Running the +example

              The example application displays a list of options and +sub options to the user and takes input from the user.

              + Screenshot for TChar example + +
              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-7FD49142-23DC-44FC-BA7D-C11E0559C8CF.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-7FD49142-23DC-44FC-BA7D-C11E0559C8CF.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,50 @@ + + + + + +Opening +a Connection to a SNAP by specifying SNAP IDExtended Connection Preferences API can be used by applications +to set the SNAP ID prior to establishing a connection. +

              Specifying +SNAP ID enables the applications to start a connection to a specific SNAP.

              +               + +Connect to socket server . + RSocketServ ss; +ss.Connect(); + + Open a RConnection object. + RConnection conn; +conn.Open( ss ); + +Create a connection +preference list and extended connection preferences object. + TConnPrefList prefList; +TExtendedConnPref preferences; + +Set the SNAP ID +using TExtendedConnPref::SetSnapId(). +preference.SetSnapId( 4 ); + +Append the extended +connection preferences to connection preference list. +prefList.AppendL( &preferences ); + + Start a connection +with connection preferences. +conn.Start( prefList ); + + +

              The application +is connected to the specified SNAP ID.

               +               +Additional +Connection Preferences +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-803D895B-E22F-5ADE-9BA6-F2EB20856541_d0e402303_href.png Binary file Symbian3/SDK/Source/GUID-803D895B-E22F-5ADE-9BA6-F2EB20856541_d0e402303_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-803D895B-E22F-5ADE-9BA6-F2EB20856541_d0e402465_href.png Binary file Symbian3/SDK/Source/GUID-803D895B-E22F-5ADE-9BA6-F2EB20856541_d0e402465_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-80E8BA3A-FDF3-50A5-BF44-181C40C31F09.dita --- a/Symbian3/SDK/Source/GUID-80E8BA3A-FDF3-50A5-BF44-181C40C31F09.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-80E8BA3A-FDF3-50A5-BF44-181C40C31F09.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,13 +1,13 @@ - - - - - -Video Subtitle CRP Overview

              This document introduces you to the Video Subtitle CRP component.

              Purpose

              The Video Subtitle CRP component is used for displaying subtitles artwork on a video window.

              Architectural relationship

              Video Subtitle CRP interacts with WServ Process; and Client Process interacts with Controller Process by a client thread and controller thread respectively.

              CRP is a plug-in framework provided by Window Server (WServ). WServ is the server side process which allows the artwork providers to render content to the application window within the WServ process.

              Client Process is the client side implementation of subtitle support using CVideoPlayerUtility2 class.

              Control Process contains Video Player Controller and Subtitle Decoder and Render to process the subtitle artwork on a video window.

              For information about Video Client API see Video Client Overview and for Multimedia Framework see Multimedia Framework Overview

              The architectural relationship between WServ Process, Client Process and Controller Process is shown below:

              Library summary

              The Video Subtitle CRP component consists of the following libraries:

              Library Description

              subtitlegraphic.dll

              The Subtitle Graphic library is used to add subtitle CRP for MMF. For more information, see Subtitle Graphic Overview.

              Typical uses

              The Video Subtitle CRP Component is used to add subtitle for a video.

              Subtitle Graphic Overview Video Subtitle CRP Support From + + + + + +Video Subtitle CRP Overview

              This document introduces you to the Video Subtitle CRP component.

              Purpose

              The Video Subtitle CRP component is used for displaying subtitles artwork on a video window.

              Architectural relationship

              Video Subtitle CRP interacts with WServ Process; and Client Process interacts with Controller Process by a client thread and controller thread respectively.

              CRP is a plug-in framework provided by Window Server (WServ). WServ is the server side process which allows the artwork providers to render content to the application window within the WServ process.

              Client Process is the client side implementation of subtitle support using CVideoPlayerUtility2 class.

              Control Process contains Video Player Controller and Subtitle Decoder and Render to process the subtitle artwork on a video window.

              For information about Video Client API see Video Client Overview and for Multimedia Framework see Multimedia Framework Overview

              The architectural relationship between WServ Process, Client Process and Controller Process is shown below:

              Library summary

              The Video Subtitle CRP component consists of the following libraries:

              Library Description

              subtitlegraphic.dll

              The Subtitle Graphic library is used to add subtitle CRP for MMF. For more information, see Subtitle Graphic Overview.

              Typical uses

              The Video Subtitle CRP Component is used to add subtitle for a video.

              Subtitle Graphic Overview Video Subtitle CRP Support From MMF               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-80EC80E2-E197-50F7-B1FD-720A00AC3B4D.dita --- a/Symbian3/SDK/Source/GUID-80EC80E2-E197-50F7-B1FD-720A00AC3B4D.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-80EC80E2-E197-50F7-B1FD-720A00AC3B4D.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,12 +1,136 @@ - - - - - -Onboard Camera Overview

              This document introduces you to the Onboard Ecam API.

              Purpose

              The Onboard Camera provides functionality to control a digital camera and to request and receive specific image data from it. Still or video images may be captured. A camera may be controlled with its output media going into a non-Symbian platform sink (for example, into hardware), or it may be controlled with output going into the Symbian platform.

              The API defines basic common operations, but is also extensible to allow for proprietary properties.

              Onboard Ecam API Library Details

              The DLL that provides the functionality and the library to which your code must link is identified below.

              DLL LIB Short Description

              ecam.dll

              ecam.lib

              These files are used for implementing the Onboard Camera functions.

              Architectural Relationship

              The Onboard Camera provides images to clients. A client may be an application with image requirements, or the Multimedia Framework. Clients have specific priorities and may pre-empt others in their interactions with the camera.

              Licensees and partners implement the camera functionality for the camera hardware on their phone. All cameras are ECom plug-ins sub-classed from the CCameraPlugin class.

              When a new camera object is required, the ECam library requests a camera plug-in from the ECom framework. When more than one ROM based plug-ins have been registered on the platform, the one with the highest version defined in its resource file is selected.

              Description

              Client Applications can use the onboard camera function for a number of tasks, including:

              Controlling camera power, using the view finder, making basic camera image settings, capturing a still image, capturing video, making advanced settings, getting snapshots, getting image histograms, using image overlays, using preset camera settings, image processing on the camera.

              Key Onboard Ecam API Classes

              The key classes that make up the Onboard Camera are as follows:

              • CCamera

                It provides the base class for camera devices. This is the interface that the client application uses to communicate with the camera. It provides all the functions necessary to control, and acquire images from, the camera.

              • MCameraObserver2

                It is an observer class which permits access to picture data as descriptors, bitmaps or chunks. It defines an event-handling interface that is called when events are generated from use of the camera functions, or from external sources such as the camera being plugged or unplugged.

                MCameraObserver is an earlier version of this callback interface.

              • TCameraInfo

                It provides information about the camera. This includes: the version number and name of camera hardware, camera orientation, whether the camera supports still image capture and so on.

              • MCameraBuffer

                It is the buffer class used by MCameraObserver2 to pass back view finder data, images and video frames. It enables the client to choose in which way it accesses the picture data (descriptor, bitmap or kernel chunk).

              • TECAMEvent

                It is a simple event class containing a UID to identify the event and a status code. It is passed to MCameraObserver2 as functional argument using HandleEvent method, when a request is completed. The request is complete, if a control of the camera switches, camera hardware settings changes, or due to external events such as the camera being plugged in.

                Use a derived version of TECAMEvent and TECAMEvent2 to pass additional information required by extended API to the API client along with the error event code.

              • CCamera::CCameraAdvancedSettings

                It provides domain specific get and set methods for well known camera hardware settings that relate directly to the image acquisition phase for both still images and video.

              • CCamera::CCameraPresets

                It associates a single command with setting of several camera parameters to specific values (and ranges). The class allows clients without knowledge of the camera specifics to achieve comparable results for different cameras.

              • CCamera::CCameraImageProcessing

                It is used to perform image processing operations on still images, video, viewfinder (both client and direct). These include brightness, contrast, gamma, hue, sharpness and saturation adjustments on the camera. The client is also able to perform simple image transformations like cropping, rotation, mirroring, scaling, noise reduction and glare reduction.

              • CCamera::CCameraOverlay

                It allows the client to overlay an image onto the view finder, snapshots, still images, and video.

              • CCamera::CCameraHistogram allows the client to get histogram data (MHistogramBuffer) in a specified format for an image, such as a luminance-based, or average colour value histogram.

                This class is deprecated, so useCCamera::CCameraV2Histogram class.

              • CCamera::CCameraSnapshot

                It allows the client to request snapshot data in a specified image format for both still images and video. Snapshot object can be created specifically for still images and video APIs.

              • CCamera::CCameraDirectViewFinder used for those viewfinders that use only viewfinder APIs of Ccamera. It provides support for Direct View Finder functionalities, such as pause and resume. see also Viewfinder API Overview.

              • CCamera::CCameraClientViewFinder

                It provides support for multiple client View Finder.

              • CCamera::CCameraPreImageCaptureControl

                It allows to control image operations or its settings prior to image capture.

              • CCamera::CCameraImageCapture

                It captures the image and controls the overall capture.

              • CCamera::CCameraPostImageCaptureControl

                It retrieves the image data from individual images and also controls the captured images individually.

              • CCamera::CCameraVideoCaptureControl

                It controls the operations related to video capture.

              The class diagram of CCamera is shown below:

              Using Onboard Ecam API

              The clients can use CCamera function to control and acquire image data from the camera.

              See also

              Camera Framework Overview

              Camera Tutorial

              \ No newline at end of file + + + + + +Onboard +Camera Overview +

              This document introduces you to the Onboard Ecam API.

              +
              Purpose

              The Onboard Camera provides functionality +to control a digital camera and to request and receive specific image data +from it. Still or video images may be captured. A camera may be controlled +with its output media going into a non-Symbian platform sink (for example, +into hardware), or it may be controlled with output going into the Symbian +platform.

              The API defines basic common operations, but is also extensible +to allow for proprietary properties.

              Onboard +Ecam API Library Details

              The DLL that provides the functionality +and the library to which your code must link is identified below.

              + + + +DLL +LIB +Short Description + + + + +

              ecam.dll

              +

              ecam.lib

              +

              These files are used for implementing the Onboard Camera functions.

              +               + + +
              +
              Architectural Relationship

              The Onboard Camera provides +images to clients. A client may be an application with image requirements, +or the Multimedia Framework. Clients have specific priorities and may pre-empt +others in their interactions with the camera.

              Licensees and partners +implement the camera functionality for the camera hardware on their phone. +All cameras are ECom plug-ins sub-classed from the CCameraPlugin class.

              When +a new camera object is required, the ECam library requests a camera plug-in +from the ECom framework. When more than one ROM based plug-ins have been registered +on the platform, the one with the highest version defined in its resource +file is selected.

              +
              Description

              Client Applications can use the onboard +camera function for a number of tasks, including:

              Controlling camera +power, using the view finder, making basic camera image settings, capturing +a still image, capturing video, making advanced settings, getting snapshots, +getting image histograms, using image overlays, using preset camera settings, +image processing on the camera.

              +
              Key Onboard +Ecam API Classes

              The key classes that make up the Onboard Camera +are as follows:

                +

              • CCamera

                It +provides the base class for camera devices. This is the interface that the +client application uses to communicate with the camera. It provides all the +functions necessary to control, and acquire images from, the camera.

                • +

              • MCameraObserver2

                It +is an observer class which permits access to picture data as descriptors, +bitmaps or chunks. It defines an event-handling interface that is called when +events are generated from use of the camera functions, or from external sources +such as the camera being plugged or unplugged.

                MCameraObserver is +an earlier version of this callback interface.

                • +

              • TCameraInfo

                It +provides information about the camera. This includes: the version number and +name of camera hardware, camera orientation, whether the camera supports still +image capture and so on.

                • +

              • MCameraBuffer

                It +is the buffer class used by MCameraObserver2 to pass back +view finder data, images and video frames. It enables the client to choose +in which way it accesses the picture data (descriptor, bitmap or kernel chunk).

                • +

              • TECAMEvent

                It +is a simple event class containing a UID to identify the event and a status +code. It is passed to MCameraObserver2 as functional argument +using HandleEvent method, when a request is completed. +The request is complete, if a control of the camera switches, camera hardware +settings changes, or due to external events such as the camera being plugged +in.

                Use a derived version of TECAMEvent and TECAMEvent2 to +pass additional information required by extended API to the API client along +with the error event code.

                • +

              • CCamera::CCameraAdvancedSettings

                It +provides domain specific get and set methods for well known camera hardware +settings that relate directly to the image acquisition phase for both still +images and video.

                • +

              • CCamera::CCameraPresets

                It +associates a single command with setting of several camera parameters to specific +values (and ranges). The class allows clients without knowledge of the camera +specifics to achieve comparable results for different cameras.

                • +

              • CCamera::CCameraImageProcessing

                It +is used to perform image processing operations on still images, video, viewfinder +(both client and direct). These include brightness, contrast, gamma, hue, +sharpness and saturation adjustments on the camera. The client is also able +to perform simple image transformations like cropping, rotation, mirroring, +scaling, noise reduction and glare reduction.

                • +

              • CCamera::CCameraOverlay

                It +allows the client to overlay an image onto the view finder, snapshots, still +images, and video.

                • +

              • CCamera::CCameraHistogram allows +the client to get histogram data (MHistogramBuffer) in +a specified format for an image, such as a luminance-based, or average colour +value histogram.

                This class is deprecated, so useCCamera::CCameraV2Histogram class.

                • +

              • CCamera::CCameraSnapshot

                It +allows the client to request snapshot data in a specified image format for +both still images and video. Snapshot object can be created specifically for +still images and video APIs.

                • +

              • CCamera::CCameraDirectViewFinder used +for those viewfinders that use only viewfinder APIs of Ccamera. It provides +support for Direct View Finder functionalities, such as pause and resume. +see also Viewfinder +API Overview.

                • +

              • CCamera::CCameraClientViewFinder

                It +provides support for multiple client View Finder.

                • +

              • CCamera::CCameraPreImageCaptureControl

                It +allows to control image operations or its settings prior to image capture.

                • +

              • CCamera::CCameraImageCapture

                It +captures the image and controls the overall capture.

                • +

              • CCamera::CCameraPostImageCaptureControl

                It +retrieves the image data from individual images and also controls the captured +images individually.

                • +

              • CCamera::CCameraVideoCaptureControl

                It +controls the operations related to video capture.

                • +

              The class diagram of CCamera is shown below:

              + +
              +
              Using Onboard Ecam API

              The clients can use CCamera +function to control and acquire image data from the camera.

              +
              See also

              Camera +Framework Overview

              Camera +Tutorials

              +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-80F2A7AC-6E86-54F2-96F0-4417A2AEA017.dita --- a/Symbian3/SDK/Source/GUID-80F2A7AC-6E86-54F2-96F0-4417A2AEA017.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-80F2A7AC-6E86-54F2-96F0-4417A2AEA017.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,58 +1,58 @@ - - - - - -Handle-numbersThis document describes the use of handle-numbers to identify handles. -

              A handle is a way in which a thread or process can identify an object that -is owned or managed by another thread or process. Such objects are Kernel -side objects.

              -

              A handle uses a number, the handle-number, to identify the associated Kernel -side object. The handle, an instance of a RHandleBase derived -class, encapsulates the handle-number.

              -

              The objects referred to by handles are always instances of CObject derived -classes, i.e. they are reference counting objects. The handle-number is created -when the object is created (or opened, if the object already exists) and added -to an object index.

              -

              Typically, calling Open() or Create() or -a similarly named function on an RHandleBase derived class -causes the associated object to be created or opened and added to an object -index, owned either by the thread or the process. Adding the object to the -object index creates a handle-number and this is returned to, and encapsulated -by, the handle.

              -

              For example, RMutex is the handle for a mutex; all user -side interaction with a specific mutex is directed through an instance of RMutex. -The RMutex object exists on the user side; the corresponding -mutex (a DMutex object) exists on the Kernel side.

              - - - -

              Here, code running on the user side constructs an RMutex and -calls its Create() member function. This causes the Kernel -to:

              -
                -

              • construct the corresponding -Kernel object, a DMutex

                • -

              • add the DMutex to -the current thread's object index (a CObjectIx)

                • -

              • return the handle-number -to the RMutex.

                • -
              -... -RMutex m; -m.Create(); -... -

              See also:

              -
                -

              • The -object index

                The -handle-number and the object index

                Reference -counting objects

                • -
              + + + + + +Handle-numbersThis document describes the use of handle-numbers to identify handles. +

              A handle is a way in which a thread or process can identify an object that +is owned or managed by another thread or process. Such objects are Kernel +side objects.

              +

              A handle uses a number, the handle-number, to identify the associated Kernel +side object. The handle, an instance of a RHandleBase derived +class, encapsulates the handle-number.

              +

              The objects referred to by handles are always instances of CObject derived +classes, i.e. they are reference counting objects. The handle-number is created +when the object is created (or opened, if the object already exists) and added +to an object index.

              +

              Typically, calling Open() or Create() or +a similarly named function on an RHandleBase derived class +causes the associated object to be created or opened and added to an object +index, owned either by the thread or the process. Adding the object to the +object index creates a handle-number and this is returned to, and encapsulated +by, the handle.

              +

              For example, RMutex is the handle for a mutex; all user +side interaction with a specific mutex is directed through an instance of RMutex. +The RMutex object exists on the user side; the corresponding +mutex (a DMutex object) exists on the Kernel side.

              + + + +

              Here, code running on the user side constructs an RMutex and +calls its Create() member function. This causes the Kernel +to:

              +
                +

              • construct the corresponding +Kernel object, a DMutex

                • +

              • add the DMutex to +the current thread's object index (a CObjectIx)

                • +

              • return the handle-number +to the RMutex.

                • +
              +... +RMutex m; +m.Create(); +... +

              See also:

              +
                +

              • The +object index

                The +handle-number and the object index

                Reference +counting objects

                • +
               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-80F2DEC8-152F-4681-A9D0-8EB776131313.dita --- a/Symbian3/SDK/Source/GUID-80F2DEC8-152F-4681-A9D0-8EB776131313.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-80F2DEC8-152F-4681-A9D0-8EB776131313.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,247 +1,247 @@ - - - - - -String -ConversionsIn case the developer is developing applications where P.I.P.S.-based -functionality is called from a Symbian/S60 application, the need for conversions -between Symbian descriptors and different string types provided by P.I.P.S. -is needed. -
              Symbian -descriptors and C strings compared

              The main difference between -Symbian descriptors and C strings is that the Symbian descriptors know how -many characters are in a data array. A C string does not know its length, -so when length is needed the NULL character that indicates the end of the -string has to be scanned.

              Another difference arises with buffers. -When C code reserves a buffer from the heap or stack, it has to keep the maximum -length somewhere. Many C methods that alter the buffer contents do not respect -the maximum size of the buffer and can override the reserved memory, causing -unknown behavior. Some methods take the maximum length as a parameter but -it is difficult to use those types in functions, since a pointer to an array -and maximum length have to be passed separately. Buffer descriptors can tell -the maximum length, and all the methods they provide respect the buffer limits. -

              When using neutral descriptor types there is no need to worry about -character widths. In a C program, the programmer has to explicitly specify -which method to use, for example strcat or wcscat.

              The -table below contains a comparison of standard C string functions and Symbian -counter parts:

              - - - -

              C function

               -

              Symbian

               -

              Description

               -               - -sprintf, swprintf -TDes::Format -

              Write formatted data to a string.

               -               - -strcat, wcscat, strncat, wcsncat -TDes::Append -

              Append a string to another.

              -               - -strcmp, strncmp, wcsncmp -TDesC::Compare -

              Compare strings lexicographically.

              -               - -strcpy, wcscpy strncpy, wcsncpy -TDes::Copy -

              Copy a string to another.

              -               - -strchr, wcschr -TDesC::Locate -

              Find a character in a string.

              -               - -strrchr, wcsrchr -TDesC:: LocateReverse -

              Scan the index of the first character from a string that does not -exist in the alphabet array.

              -               - -strspn, wcsspn -

              None

              -

              Scan index of the first character from string that doesn't exist -in alphabet array.

              -               - -strcspn, wcscspn -

              None

              -

              Scan the index of the first occurrence of a character in a string -that belongs to the set of characters.

              -               - -strstr, wcsstr -TDesC::Find -

              Find a substring.

              -               - -strtok, wcstok -TLex:: -

              Find the next token in a string.

              -               - -strlen, wcslen -TDesC::Length -

              Get the length of a string.

              -               - -strcoll, wcscoll -TDesC::CompareC -

              Compare strings using locale-specific information.

              -               - -strftime, wcsftime -

              Using TDes::Format and TTime

              -

              Format a time string.

              -               - - -
              -
              How -to convert <codeph>TBuf16</codeph> to a <codeph>char</codeph> buffer -

              A TBuf16 buffer can be converted to a char buffer -using the wcstombs API. The example below illustrates how -the conversion can be done.

              #include <e32base.h> -#include <sys/types.h> -#include <stdio.h> -#include <stdlib.h> -#include <wchar.h> - -#define SIZE 20 -_LIT(KData,"hello"); - -int main (void) -{ - TBuf16<SIZE> buf(KData); - size_t ret; - char carray[SIZE]; - - ret = wcstombs(carray, (const wchar_t *)buf.PtrZ(), SIZE ); - printf("TBuf converted to char buffer : %s\n",carray); - getchar(); - return (1); -} -
              -
              How -to convert <codeph>TBuf8</codeph> to <codeph>wchar_t</codeph> -

              A TBuf8 buffer can be converted to wchar_t using -the mbstowcs API.

              #include <e32base.h> -#include <sys/types.h> -#include <stdio.h> -#include <stdlib.h> -#include <wchar.h> - -#define SIZE 20 - - int main (void) - { - TBuf8<SIZE> buf(_L8("hello")); - size_t ret; - wchar_t warray[SIZE]; - - ret = mbstowcs(warray, (const char *)buf.PtrZ(), SIZE ); - printf("TBuf8 converted to wchar buffer : %ls\n",warray); - getchar(); - - return (1); - } -
              -
              How -to convert <codeph>TText16</codeph> to <codeph>char</codeph> -

              The wcstombs API can be used to convert a TText16 buffer -to a char buffer. This is one of the examples of converting -from a Symbian data type to a C data type.

              #include <e32def.h> -#include <sys/types.h> -#include <stdio.h> -#include <stdlib.h> -#include <wchar.h> - -#define SIZE 32 - -int main (void) -{ - TText arr[SIZE] = L"abcdef"; - char carray[SIZE]; - size_t ret; - - ret = wcstombs(carray, (const wchar_t *)arr, SIZE); - printf("TText converted to char buffer : %s",carray); - getchar(); - - return (1); -} -
              -
              How -to convert a <codeph>char</codeph> array and a <codeph>wide char</codeph> array -

              To use both char and wide char pointers -or array in the program, the user must convert buffers from a char to -a wide char and vice versa. Wide character APIs provide methods -to:

                -

              • convert a char array to a wide char array

                • -

              • convert a wide char array to a char array

                • -

              Converting a char array to a wide char array

              The mbstowcs API -can be used to convert a char array to a wide char array.

              #include <stdlib.h> -#include <wchar.h> - -#define ARRAY_SIZE 32 - -int main(void) -{ - char *carray = "char array"; - wchar_t warray[ARRAY_SIZE]; - size_t ret; - - ret = mbstowcs(warray, (const char *)carray, ARRAY_SIZE); - wprintf(L"character array contents : %s\n",carray); - wprintf(L"wide char array contents : %ls\n",warray); - getwchar(); - - return (1); -} -

              Converting a wide char array to a char array

              The wcstombs API -can be used to convert a wide char array to a char array.

              #include <stdlib.h> -#include <wchar.h> - -#define ARRAY_SIZE 32 - -int main(void) -{ - wchar_t *warray = L"wide array"; - char carray[ARRAY_SIZE]; - size_t ret; - - ret = wcstombs(carray, (const wchar_t *)warray, ARRAY_SIZE); - wprintf(L"wide char array contents : %ls\n",warray); - wprintf(L"character array contents : %s\n",carray); - getwchar(); - - return (1); -} -
              -
              How -to declare a <codeph>wide-char</codeph> string

              To declare -a wide-char string, prefix the string with 'L' -[Capital L].

              #include <wchar.h> - -int main(void) -{ - wchar_t *wptr = L"This is a wide char string"; - - wprintf(L"%ls\n",wptr); - getwchar(); -} -
              + + + + + +String +ConversionsIn case the developer is developing applications where P.I.P.S.-based +functionality is called from a Symbian/S60 application, the need for conversions +between Symbian descriptors and different string types provided by P.I.P.S. +is needed. +
              Symbian +descriptors and C strings compared

              The main difference between +Symbian descriptors and C strings is that the Symbian descriptors know how +many characters are in a data array. A C string does not know its length, +so when length is needed the NULL character that indicates the end of the +string has to be scanned.

              Another difference arises with buffers. +When C code reserves a buffer from the heap or stack, it has to keep the maximum +length somewhere. Many C methods that alter the buffer contents do not respect +the maximum size of the buffer and can override the reserved memory, causing +unknown behavior. Some methods take the maximum length as a parameter but +it is difficult to use those types in functions, since a pointer to an array +and maximum length have to be passed separately. Buffer descriptors can tell +the maximum length, and all the methods they provide respect the buffer limits. +

              When using neutral descriptor types there is no need to worry about +character widths. In a C program, the programmer has to explicitly specify +which method to use, for example strcat or wcscat.

              The +table below contains a comparison of standard C string functions and Symbian +counter parts:

              + + + +

              C function

               +

              Symbian

               +

              Description

               +               + +sprintf, swprintf +TDes::Format +

              Write formatted data to a string.

               +               + +strcat, wcscat, strncat, wcsncat +TDes::Append +

              Append a string to another.

              +               + +strcmp, strncmp, wcsncmp +TDesC::Compare +

              Compare strings lexicographically.

              +               + +strcpy, wcscpy strncpy, wcsncpy +TDes::Copy +

              Copy a string to another.

              +               + +strchr, wcschr +TDesC::Locate +

              Find a character in a string.

              +               + +strrchr, wcsrchr +TDesC:: LocateReverse +

              Scan the index of the first character from a string that does not +exist in the alphabet array.

              +               + +strspn, wcsspn +

              None

              +

              Scan index of the first character from string that doesn't exist +in alphabet array.

              +               + +strcspn, wcscspn +

              None

              +

              Scan the index of the first occurrence of a character in a string +that belongs to the set of characters.

              +               + +strstr, wcsstr +TDesC::Find +

              Find a substring.

              +               + +strtok, wcstok +TLex:: +

              Find the next token in a string.

              +               + +strlen, wcslen +TDesC::Length +

              Get the length of a string.

              +               + +strcoll, wcscoll +TDesC::CompareC +

              Compare strings using locale-specific information.

              +               + +strftime, wcsftime +

              Using TDes::Format and TTime

              +

              Format a time string.

              +               + + +
              +
              How +to convert <codeph>TBuf16</codeph> to a <codeph>char</codeph> buffer +

              A TBuf16 buffer can be converted to a char buffer +using the wcstombs API. The example below illustrates how +the conversion can be done.

              #include <e32base.h> +#include <sys/types.h> +#include <stdio.h> +#include <stdlib.h> +#include <wchar.h> + +#define SIZE 20 +_LIT(KData,"hello"); + +int main (void) +{ + TBuf16<SIZE> buf(KData); + size_t ret; + char carray[SIZE]; + + ret = wcstombs(carray, (const wchar_t *)buf.PtrZ(), SIZE ); + printf("TBuf converted to char buffer : %s\n",carray); + getchar(); + return (1); +} +
              +
              How +to convert <codeph>TBuf8</codeph> to <codeph>wchar_t</codeph> +

              A TBuf8 buffer can be converted to wchar_t using +the mbstowcs API.

              #include <e32base.h> +#include <sys/types.h> +#include <stdio.h> +#include <stdlib.h> +#include <wchar.h> + +#define SIZE 20 + + int main (void) + { + TBuf8<SIZE> buf(_L8("hello")); + size_t ret; + wchar_t warray[SIZE]; + + ret = mbstowcs(warray, (const char *)buf.PtrZ(), SIZE ); + printf("TBuf8 converted to wchar buffer : %ls\n",warray); + getchar(); + + return (1); + } +
              +
              How +to convert <codeph>TText16</codeph> to <codeph>char</codeph> +

              The wcstombs API can be used to convert a TText16 buffer +to a char buffer. This is one of the examples of converting +from a Symbian data type to a C data type.

              #include <e32def.h> +#include <sys/types.h> +#include <stdio.h> +#include <stdlib.h> +#include <wchar.h> + +#define SIZE 32 + +int main (void) +{ + TText arr[SIZE] = L"abcdef"; + char carray[SIZE]; + size_t ret; + + ret = wcstombs(carray, (const wchar_t *)arr, SIZE); + printf("TText converted to char buffer : %s",carray); + getchar(); + + return (1); +} +
              +
              How +to convert a <codeph>char</codeph> array and a <codeph>wide char</codeph> array +

              To use both char and wide char pointers +or array in the program, the user must convert buffers from a char to +a wide char and vice versa. Wide character APIs provide methods +to:

                +

              • convert a char array to a wide char array

                • +

              • convert a wide char array to a char array

                • +

              Converting a char array to a wide char array

              The mbstowcs API +can be used to convert a char array to a wide char array.

              #include <stdlib.h> +#include <wchar.h> + +#define ARRAY_SIZE 32 + +int main(void) +{ + char *carray = "char array"; + wchar_t warray[ARRAY_SIZE]; + size_t ret; + + ret = mbstowcs(warray, (const char *)carray, ARRAY_SIZE); + wprintf(L"character array contents : %s\n",carray); + wprintf(L"wide char array contents : %ls\n",warray); + getwchar(); + + return (1); +} +

              Converting a wide char array to a char array

              The wcstombs API +can be used to convert a wide char array to a char array.

              #include <stdlib.h> +#include <wchar.h> + +#define ARRAY_SIZE 32 + +int main(void) +{ + wchar_t *warray = L"wide array"; + char carray[ARRAY_SIZE]; + size_t ret; + + ret = wcstombs(carray, (const wchar_t *)warray, ARRAY_SIZE); + wprintf(L"wide char array contents : %ls\n",warray); + wprintf(L"character array contents : %s\n",carray); + getwchar(); + + return (1); +} +
              +
              How +to declare a <codeph>wide-char</codeph> string

              To declare +a wide-char string, prefix the string with 'L' +[Capital L].

              #include <wchar.h> + +int main(void) +{ + wchar_t *wptr = L"This is a wide char string"; + + wprintf(L"%ls\n",wptr); + getwchar(); +} +
              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-81767E3E-BE4D-40D9-A4F2-3801BCCC1EA7-master.png Binary file Symbian3/SDK/Source/GUID-81767E3E-BE4D-40D9-A4F2-3801BCCC1EA7-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-81767E3E-BE4D-40D9-A4F2-3801BCCC1EA7_d0e51653_href.png Binary file Symbian3/SDK/Source/GUID-81767E3E-BE4D-40D9-A4F2-3801BCCC1EA7_d0e51653_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-81767E3E-BE4D-40D9-A4F2-3801BCCC1EA7_d0e57208_href.png Binary file Symbian3/SDK/Source/GUID-81767E3E-BE4D-40D9-A4F2-3801BCCC1EA7_d0e57208_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-81767E3E-BE4D-40D9-A4F2-3801BCCC1EA7_d0e64462_href.png Binary file Symbian3/SDK/Source/GUID-81767E3E-BE4D-40D9-A4F2-3801BCCC1EA7_d0e64462_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-81767E3E-BE4D-40D9-A4F2-3801BCCC1EA7_d0e68897_href.png Binary file Symbian3/SDK/Source/GUID-81767E3E-BE4D-40D9-A4F2-3801BCCC1EA7_d0e68897_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-81767E3E-BE4D-40D9-A4F2-3801BCCC1EA7_d0e69700_href.png Binary file Symbian3/SDK/Source/GUID-81767E3E-BE4D-40D9-A4F2-3801BCCC1EA7_d0e69700_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-81767E3E-BE4D-40D9-A4F2-3801BCCC1EA7_d0e74040_href.png Binary file Symbian3/SDK/Source/GUID-81767E3E-BE4D-40D9-A4F2-3801BCCC1EA7_d0e74040_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-817D677C-2422-52B1-8D44-D15A0351FDC6_d0e169014_href.jpg Binary file Symbian3/SDK/Source/GUID-817D677C-2422-52B1-8D44-D15A0351FDC6_d0e169014_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-817D677C-2422-52B1-8D44-D15A0351FDC6_d0e175615_href.jpg Binary file Symbian3/SDK/Source/GUID-817D677C-2422-52B1-8D44-D15A0351FDC6_d0e175615_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-81A5784D-A0C6-5108-9E7B-5D39C6743B1A_d0e216847_href.png Binary file Symbian3/SDK/Source/GUID-81A5784D-A0C6-5108-9E7B-5D39C6743B1A_d0e216847_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-81A5784D-A0C6-5108-9E7B-5D39C6743B1A_d0e220584_href.png Binary file Symbian3/SDK/Source/GUID-81A5784D-A0C6-5108-9E7B-5D39C6743B1A_d0e220584_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-81E33E18-D390-4110-8D85-1FCDA9CC311E.dita --- a/Symbian3/SDK/Source/GUID-81E33E18-D390-4110-8D85-1FCDA9CC311E.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-81E33E18-D390-4110-8D85-1FCDA9CC311E.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,52 +1,62 @@ - - - - - -Progress -note -

              Progress notes contain a progress graphic of definite duration. They are -used during operations that take a long time when it is possible to estimate -the duration of the operation. Whenever possible, the user should be able -to stop the operation. For this, a softkey labeled e.g. Cancel is -provided.

              - -Progress note - - -
              Using -progress notes in C++ applications

              You can create either a -basic wait note that is displayed only when your application is in the foreground -or a global note that stays displayed even if the application launching the -note is not in the foreground. The related APIs are the Notes -API (for basic notes) and the Notifiers API (for global notes).

              Progress notes -are predefined notes that cannot be used just by instantiating a simple note -class. These notes' lifetime is based on a background process, and client -code has to provide an interface to retrieve this information. For implementation -information, see Creating a progress note.

              To create -a global progress note, use the class CAknGlobalProgressDialog in the Notifiers API. For implementation information, see Using global notes and Using global notes with user interaction.

              For basic -notes, you can change the icon or text displayed in the note, use a different -kind of sound, or change the note duration using the setter methods in the -class CAknNoteDialog: SetIconL(), SetTextL(), SetTone(), and SetTimeout().

              For information on customizing global notes, see Enhancing global notes. You can change the graphic, animation, -tone, and softkeys using the methods in the class CAknGlobalNote: SetGraphic(), SetAnimation(), SetTone(), and SetSoftkeys().

              - -               -Confirmation -note -Information -note -Warning note - -Error note - -Permanent -note -Wait note - + + + + + +Progress +note +

              Progress notes contain a progress graphic of definite duration. They are +used during operations that take a long time when it is possible to estimate +the duration of the operation. Whenever possible, the user should be able +to stop the operation. For this, a softkey labeled, example, Cancel is +provided.

              + +Progress note + + +
              Using +progress notes in applications

              You can create either a basic +wait note that is displayed only when your application is in the foreground +or a global note that stays displayed even if the application launching the +note is not in the foreground. The related APIs are the Notes +API (for basic notes) and the Notifiers API (for global notes).

              Progress notes +are predefined notes that cannot be used just by instantiating a simple note +class. These notes' lifetime is based on a background process, and client +code has to provide an interface to retrieve this information. For implementation +information, see Creating a progress note.

              To create a global progress +note, use the class CAknGlobalProgressDialog in the Notifiers API. For implementation information, see Using global notes and Using global notes with user interaction.

              For basic +notes, you can change the icon or text displayed in the note, use a different +kind of sound, or change the note duration using the setter methods in the +class CAknNoteDialog:

                +

              • CAknNoteDialog::SetIconL()

                • +

              • CAknNoteDialog::SetTextL()

                • +

              • CAknNoteDialog::SetTone()

                • +

              • CAknNoteDialog::SetTimeout()

                • +

              For information on customizing global notes, see Enhancing global notes. You can change the graphic, animation, +tone, and softkeys using the methods in the class CAknGlobalNote:

                +

              • CAknGlobalNote::SetGraphic()

                • +

              • CAknGlobalNote::SetAnimation()

                • +

              • CAknGlobalNote::SetTone()

                • +

              • CAknGlobalNote::SetSoftkeys()

                • +

              + +               +Confirmation +note +Information +note +Warning note + +Error note + +Permanent +note +Wait note +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-821FEEDD-81B8-5511-AC4E-B673A96F8CB4_d0e312224_href.png Binary file Symbian3/SDK/Source/GUID-821FEEDD-81B8-5511-AC4E-B673A96F8CB4_d0e312224_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-821FEEDD-81B8-5511-AC4E-B673A96F8CB4_d0e318618_href.png Binary file Symbian3/SDK/Source/GUID-821FEEDD-81B8-5511-AC4E-B673A96F8CB4_d0e318618_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-829761B6-ECF7-5E15-A475-AEE357687067-GENID-1-8-1-3-1-1-4-1-3-1.dita --- a/Symbian3/SDK/Source/GUID-829761B6-ECF7-5E15-A475-AEE357687067-GENID-1-8-1-3-1-1-4-1-3-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,147 +0,0 @@ - - - - - -Animation -overview -
              Purpose

              The animation component is a framework -that provides support to build animated graphics applications. It provides -the basic data types that allow animations to be incorporated into the normal -drawing of a window from the client, or to be managed on the server as a sprite.

              -
              Required background

              Windows -server component knowledge is recommended before using this component.

              -
              Key concepts

              The component has the following key -concepts:

              - -
              Animation
              -

              The animation is a fairly abstract interface owned by a client application. -The interface is independent of the source of the data it uses, as the data -providers are responsible for providing data to the animation.

              -               - -
              Animator
              -

              The animator represents each data type supported by the animation framework. -It can handle data interpretation, timing and control of the animation. An -animator is not be visible to the owner of the animation, but is controlled -through it using a standard interface. The animators can either reside on -the client or on the server. Each animation selects an animator plug-in to -be used by providing an appropriate string obtained from the data provider.

              -               - -
              Data provider
              -

              A data provider is a generic interface to handle different kinds of -data, which has different structures and behaviours, for example, GIFs and -SVG (Scalable Vector Graphics). Animations access the data providers they -own through an observer interface, which reports events to the animation. -The interface in turn reports these events to the respective animators.

              -               - -
              Observer
              -

              An observer acts as an interface and is responsible for reporting events. -The animation framework provides two such observers: a data provider observer, -and an animation observer. The data provider observer is an interface between -the animation and the data provider. Using this observer the animation can -receive data and events from the data provider. The animation observer is -an interface between the animation and the client application, and is used -to report events to the client application. In Symbian OS v9.1, the animation -observer is implemented to report only errors to the client application.

              -               -
              -
              Architectural relationships

              The animation component -provides a set of abstract classes with some basic functionality required -for any type of animation. Implementors have to derive their own classes using -these abstract classes to support specific animation types such as bitmap -animation, sprite animation and so on.

              The animation framework also -provides concrete implementations of the abstract classes. The concrete implementations -of the CAnimation class are:

                -

              • CBasicAnimation

                This -is a client-side animation class which can also act as a data provider observer -and an animation drawer. It provides a bitmap and a mask on which the animation -is submitted. This class establishes a session with the windows server before -submitting the animation to a particular window.

                • -

              • CSpriteAnimation

                This -is a server-side animation class for sprite based animations. The client has -limited control over the animation, as sprites are server-side graphic objects -and are controlled by the server. This class makes use of the windows server -animation API to submit sprite animations. For more information on these APIs, -refer to Using Window -Server (WSERV).

                • -

              • CAnimationGroup

                This -class is not an animation class by itself, but is a collection of animations -grouped together. It provides access to an array of animation references and -handles all synchronisation issues among the animations in the group, provided -all the animations are of the same type. For example, if a set of client-side -animations are grouped together, they respond to commands collectively in -synchronisation with each other. If the group includes both sprite and client-side -animations, they will respond to commands collectively in asynchronous mode.

                • -

              The framework provides the following concrete implementations for -the other two abstract classes, CAnimationDataProvider and CAnimator:

                -

              • CICLAnimationDataProvider

                This -class interprets various data types including animated GIFs using the Image Conversion Library (ICL). -It provides data to the animation class in the form of individual frames using -the CAnimationFrame object which contains a bitmap, a mask, -and frame information.

                • -

              • CBitmapAnimator

                This -class can handle fixed sequence of bitmap frames passed by the data provider.

                • -
              -
              API summary

              - - - -Class Name -Description - - - - -

              CAnimation

              -

              This is an abstract generic class which provides the basic functionality -for all types of animations.

              -               - -

              CAnimator

              -

              This is an abstract class, which represents each type of data supported -by the animation framework. This class is implemented as an ECOM plug-in.

              -               - -

              CAnimationDataProvider

              -

              This is an abstract class, which takes the animation data and converts -it into a format recognized by the animator.

              -               - -

              CBasicAnimation

              -

              This is a concrete implementation class of the CAnimation class. -This class is used for basic client-side animations.

              -               - -

              CSpriteAnimation

              -

              This is a concrete implementation class of the CAnimation class. -This class is used for sprite animations.

              -               - - -
              -
              Typical uses

              Creating a basic animation

              The -animation framework can be used to create a basic client-side animation using -the CBasicAnimation class. You can also have your own implementation -for other type of animations. For more information, refer to How -to create a basic animation.

              Creating a sprite animation

              The -animation framework supports server-side sprite animations using the CSpriteAnimation class. -The procedure to create a sprite animation is the same as that for creating -a basic client-side animation. The only difference between a client-side animation -and a sprite animation is that client-side animations are redrawn by the client -application. Whereas, for sprite animations redraws are handled automatically, -as they run in the window server's high priority thread.

              -               -How to create -a basic animation -Using Window -Server (WSERV) -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-829761B6-ECF7-5E15-A475-AEE357687067-GENID-1-8-1-6-1-1-4-1-3-1-3-1.dita --- a/Symbian3/SDK/Source/GUID-829761B6-ECF7-5E15-A475-AEE357687067-GENID-1-8-1-6-1-1-4-1-3-1-3-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,147 +0,0 @@ - - - - - -Animation -overview -
              Purpose

              The animation component is a framework -that provides support to build animated graphics applications. It provides -the basic data types that allow animations to be incorporated into the normal -drawing of a window from the client, or to be managed on the server as a sprite.

              -
              Required background

              Windows -server component knowledge is recommended before using this component.

              -
              Key concepts

              The component has the following key -concepts:

              - -
              Animation
              -

              The animation is a fairly abstract interface owned by a client application. -The interface is independent of the source of the data it uses, as the data -providers are responsible for providing data to the animation.

              -               - -
              Animator
              -

              The animator represents each data type supported by the animation framework. -It can handle data interpretation, timing and control of the animation. An -animator is not be visible to the owner of the animation, but is controlled -through it using a standard interface. The animators can either reside on -the client or on the server. Each animation selects an animator plug-in to -be used by providing an appropriate string obtained from the data provider.

              -               - -
              Data provider
              -

              A data provider is a generic interface to handle different kinds of -data, which has different structures and behaviours, for example, GIFs and -SVG (Scalable Vector Graphics). Animations access the data providers they -own through an observer interface, which reports events to the animation. -The interface in turn reports these events to the respective animators.

              -               - -
              Observer
              -

              An observer acts as an interface and is responsible for reporting events. -The animation framework provides two such observers: a data provider observer, -and an animation observer. The data provider observer is an interface between -the animation and the data provider. Using this observer the animation can -receive data and events from the data provider. The animation observer is -an interface between the animation and the client application, and is used -to report events to the client application. In Symbian OS v9.1, the animation -observer is implemented to report only errors to the client application.

              -               -
              -
              Architectural relationships

              The animation component -provides a set of abstract classes with some basic functionality required -for any type of animation. Implementors have to derive their own classes using -these abstract classes to support specific animation types such as bitmap -animation, sprite animation and so on.

              The animation framework also -provides concrete implementations of the abstract classes. The concrete implementations -of the CAnimation class are:

                -

              • CBasicAnimation

                This -is a client-side animation class which can also act as a data provider observer -and an animation drawer. It provides a bitmap and a mask on which the animation -is submitted. This class establishes a session with the windows server before -submitting the animation to a particular window.

                • -

              • CSpriteAnimation

                This -is a server-side animation class for sprite based animations. The client has -limited control over the animation, as sprites are server-side graphic objects -and are controlled by the server. This class makes use of the windows server -animation API to submit sprite animations. For more information on these APIs, -refer to Using Window -Server (WSERV).

                • -

              • CAnimationGroup

                This -class is not an animation class by itself, but is a collection of animations -grouped together. It provides access to an array of animation references and -handles all synchronisation issues among the animations in the group, provided -all the animations are of the same type. For example, if a set of client-side -animations are grouped together, they respond to commands collectively in -synchronisation with each other. If the group includes both sprite and client-side -animations, they will respond to commands collectively in asynchronous mode.

                • -

              The framework provides the following concrete implementations for -the other two abstract classes, CAnimationDataProvider and CAnimator:

                -

              • CICLAnimationDataProvider

                This -class interprets various data types including animated GIFs using the Image Conversion Library (ICL). -It provides data to the animation class in the form of individual frames using -the CAnimationFrame object which contains a bitmap, a mask, -and frame information.

                • -

              • CBitmapAnimator

                This -class can handle fixed sequence of bitmap frames passed by the data provider.

                • -
              -
              API summary

              - - - -Class Name -Description - - - - -

              CAnimation

              -

              This is an abstract generic class which provides the basic functionality -for all types of animations.

              -               - -

              CAnimator

              -

              This is an abstract class, which represents each type of data supported -by the animation framework. This class is implemented as an ECOM plug-in.

              -               - -

              CAnimationDataProvider

              -

              This is an abstract class, which takes the animation data and converts -it into a format recognized by the animator.

              -               - -

              CBasicAnimation

              -

              This is a concrete implementation class of the CAnimation class. -This class is used for basic client-side animations.

              -               - -

              CSpriteAnimation

              -

              This is a concrete implementation class of the CAnimation class. -This class is used for sprite animations.

              -               - - -
              -
              Typical uses

              Creating a basic animation

              The -animation framework can be used to create a basic client-side animation using -the CBasicAnimation class. You can also have your own implementation -for other type of animations. For more information, refer to How -to create a basic animation.

              Creating a sprite animation

              The -animation framework supports server-side sprite animations using the CSpriteAnimation class. -The procedure to create a sprite animation is the same as that for creating -a basic client-side animation. The only difference between a client-side animation -and a sprite animation is that client-side animations are redrawn by the client -application. Whereas, for sprite animations redraws are handled automatically, -as they run in the window server's high priority thread.

              -               -How to create -a basic animation -Using Window -Server (WSERV) -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-829761B6-ECF7-5E15-A475-AEE357687067.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-829761B6-ECF7-5E15-A475-AEE357687067.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,147 @@ + + + + + +Animation +overview +
              Purpose

              The animation component is a framework +that provides support to build animated graphics applications. It provides +the basic data types that allow animations to be incorporated into the normal +drawing of a window from the client, or to be managed on the server as a sprite.

              +
              Required background

              Windows +server component knowledge is recommended before using this component.

              +
              Key concepts

              The component has the following key +concepts:

              + +
              Animation
              +

              The animation is a fairly abstract interface owned by a client application. +The interface is independent of the source of the data it uses, as the data +providers are responsible for providing data to the animation.

              +               + +
              Animator
              +

              The animator represents each data type supported by the animation framework. +It can handle data interpretation, timing and control of the animation. An +animator is not be visible to the owner of the animation, but is controlled +through it using a standard interface. The animators can either reside on +the client or on the server. Each animation selects an animator plug-in to +be used by providing an appropriate string obtained from the data provider.

              +               + +
              Data provider
              +

              A data provider is a generic interface to handle different kinds of +data, which has different structures and behaviours, for example, GIFs and +SVG (Scalable Vector Graphics). Animations access the data providers they +own through an observer interface, which reports events to the animation. +The interface in turn reports these events to the respective animators.

              +               + +
              Observer
              +

              An observer acts as an interface and is responsible for reporting events. +The animation framework provides two such observers: a data provider observer, +and an animation observer. The data provider observer is an interface between +the animation and the data provider. Using this observer the animation can +receive data and events from the data provider. The animation observer is +an interface between the animation and the client application, and is used +to report events to the client application. In Symbian OS v9.1, the animation +observer is implemented to report only errors to the client application.

              +               +
              +
              Architectural relationships

              The animation component +provides a set of abstract classes with some basic functionality required +for any type of animation. Implementors have to derive their own classes using +these abstract classes to support specific animation types such as bitmap +animation, sprite animation and so on.

              The animation framework also +provides concrete implementations of the abstract classes. The concrete implementations +of the CAnimation class are:

                +

              • CBasicAnimation

                This +is a client-side animation class which can also act as a data provider observer +and an animation drawer. It provides a bitmap and a mask on which the animation +is submitted. This class establishes a session with the windows server before +submitting the animation to a particular window.

                • +

              • CSpriteAnimation

                This +is a server-side animation class for sprite based animations. The client has +limited control over the animation, as sprites are server-side graphic objects +and are controlled by the server. This class makes use of the windows server +animation API to submit sprite animations. For more information on these APIs, +refer to Using Window +Server (WSERV).

                • +

              • CAnimationGroup

                This +class is not an animation class by itself, but is a collection of animations +grouped together. It provides access to an array of animation references and +handles all synchronisation issues among the animations in the group, provided +all the animations are of the same type. For example, if a set of client-side +animations are grouped together, they respond to commands collectively in +synchronisation with each other. If the group includes both sprite and client-side +animations, they will respond to commands collectively in asynchronous mode.

                • +

              The framework provides the following concrete implementations for +the other two abstract classes, CAnimationDataProvider and CAnimator:

                +

              • CICLAnimationDataProvider

                This +class interprets various data types including animated GIFs using the Image Conversion Library (ICL). +It provides data to the animation class in the form of individual frames using +the CAnimationFrame object which contains a bitmap, a mask, +and frame information.

                • +

              • CBitmapAnimator

                This +class can handle fixed sequence of bitmap frames passed by the data provider.

                • +
              +
              API summary

              + + + +Class Name +Description + + + + +

              CAnimation

              +

              This is an abstract generic class which provides the basic functionality +for all types of animations.

              +               + +

              CAnimator

              +

              This is an abstract class, which represents each type of data supported +by the animation framework. This class is implemented as an ECOM plug-in.

              +               + +

              CAnimationDataProvider

              +

              This is an abstract class, which takes the animation data and converts +it into a format recognized by the animator.

              +               + +

              CBasicAnimation

              +

              This is a concrete implementation class of the CAnimation class. +This class is used for basic client-side animations.

              +               + +

              CSpriteAnimation

              +

              This is a concrete implementation class of the CAnimation class. +This class is used for sprite animations.

              +               + + +
              +
              Typical uses

              Creating a basic animation

              The +animation framework can be used to create a basic client-side animation using +the CBasicAnimation class. You can also have your own implementation +for other type of animations. For more information, refer to How +to create a basic animation.

              Creating a sprite animation

              The +animation framework supports server-side sprite animations using the CSpriteAnimation class. +The procedure to create a sprite animation is the same as that for creating +a basic client-side animation. The only difference between a client-side animation +and a sprite animation is that client-side animations are redrawn by the client +application. Whereas, for sprite animations redraws are handled automatically, +as they run in the window server's high priority thread.

              +               +How to create +a basic animation +Using Window +Server (WSERV) +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-829C15B1-0769-4E90-935D-4DCA58895E81-master.png Binary file Symbian3/SDK/Source/GUID-829C15B1-0769-4E90-935D-4DCA58895E81-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-829C15B1-0769-4E90-935D-4DCA58895E81_d0e58353_href.png Binary file Symbian3/SDK/Source/GUID-829C15B1-0769-4E90-935D-4DCA58895E81_d0e58353_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-829C15B1-0769-4E90-935D-4DCA58895E81_d0e61742_href.png Binary file Symbian3/SDK/Source/GUID-829C15B1-0769-4E90-935D-4DCA58895E81_d0e61742_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-82B73D69-0176-5CBB-B3ED-5CA7F5CCD5D9.dita --- a/Symbian3/SDK/Source/GUID-82B73D69-0176-5CBB-B3ED-5CA7F5CCD5D9.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-82B73D69-0176-5CBB-B3ED-5CA7F5CCD5D9.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,45 +1,45 @@ - - - - - -The -relationship between descriptor classesDescribes inheritance relationship between the descriptor classes -and associated abstract base classes. -

              The following diagram shows the inheritance relationship between the concrete -descriptor classes and their abstract base classes.

              -

              The diagram uses the 16-bit variant types:

              -
                -

              • TPtrC16

                • -

              • TPtr16

                • -

              • TBufC16 <TInt>

                • -

              • TBuf16 <TInt>

                • -

              • RBuf

                • -

              • HBufC16

                • -
              -

              but the relationship is exactly the same for the 8-bit variants. The class -names can also be replaced by the build independent types and the relationships -remains valid.

              -

              The TBufBase16 and TBufCBase16 classes -are an implementation convenience and are not part of the public API.

              -

              TDesC16 and TDes16 are abstract -classes and cannot be instantiated, However, these types can be passed as -arguments to functions.

              - - -

              Inheritance relationship between the concrete descriptor classes and their -abstract base classes

              -               -

              Because descriptors are widely used (especially on the stack), the size -of descriptor objects must be kept to a minimum. To help with this, no virtual -functions are defined in order to avoid the overhead of a virtual function -table pointer in each descriptor object.

              -

              As a consequence, the base classes have implicit knowledge of the classes -derived from them.

              + + + + + +The +relationship between descriptor classesDescribes inheritance relationship between the descriptor classes +and associated abstract base classes. +

              The following diagram shows the inheritance relationship between the concrete +descriptor classes and their abstract base classes.

              +

              The diagram uses the 16-bit variant types:

              +
                +

              • TPtrC16

                • +

              • TPtr16

                • +

              • TBufC16 <TInt>

                • +

              • TBuf16 <TInt>

                • +

              • RBuf

                • +

              • HBufC16

                • +
              +

              but the relationship is exactly the same for the 8-bit variants. The class +names can also be replaced by the build independent types and the relationships +remains valid.

              +

              The TBufBase16 and TBufCBase16 classes +are an implementation convenience and are not part of the public API.

              +

              TDesC16 and TDes16 are abstract +classes and cannot be instantiated, However, these types can be passed as +arguments to functions.

              + + +

              Inheritance relationship between the concrete descriptor classes and their +abstract base classes

              +               +

              Because descriptors are widely used (especially on the stack), the size +of descriptor objects must be kept to a minimum. To help with this, no virtual +functions are defined in order to avoid the overhead of a virtual function +table pointer in each descriptor object.

              +

              As a consequence, the base classes have implicit knowledge of the classes +derived from them.

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-82B8C95E-F7E7-59C2-A71A-4C882653D555.dita --- a/Symbian3/SDK/Source/GUID-82B8C95E-F7E7-59C2-A71A-4C882653D555.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-82B8C95E-F7E7-59C2-A71A-4C882653D555.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,45 +1,45 @@ - - - - - -Continuous Digital ZoomingThis tutorial describes how to perform continuous digital zooming using the Ecam API.

              Before you start you should understand the following topics:

              • Overview of the advanced Camera settings functionality.

              • Tutorial of the advanced Camera settings functionality.

              For advanced camera settings, the continuous digital zooming API provides a greater control over continuous zoom by allowing you to specify the speed and acceleration of each continuous zoom operation. The minimum speed for zooming is zero and the minimum acceleration is a negative value (which means deceleration).

              For continuous zooming, you need to provide a concrete implementation of MCameraContinuousZoom.

              Call CCameraAdvancedSettings::NewL(CCamera&) to create a CCameraAdvancedSettings object. Call CCameraAdvancedSettings::GetSupportedContinuousZoomTypeL(TUint&) to retrieve supported continuous zoom options for CCameraAdvancedSettings. Call CCameraAdvancedSettings::CreateContinuousZoomL(MContinuousZoomObserver&, - TContinuousZoomType, CCameraContinuousZoom*&) to create a continuous zoom object. Call CCameraContinuousZoom::GetContinuousZoomSupportInfoL(CCameraAdvancedSettings::TContinuousZoomSupportInfo&) to retrieve information about the supported settings related to continuous zoom. Call CCameraAdvancedSettings::StartContinuousZoomL(CCameraAdvancedSettings::TContinuousZoomParameters) to start the continuous zoom operation. Call the CCameraContinuousZoom::ContinuousZoomProgress(CCameraContinuousZoom&, - TInt, TInt) function when a new zoom factor has achieved during the current continuous zoom operation. Call the CCameraAdvancedSettings::GetContinuousZoomId - (TInt aZoomId) function when you use more than one continuous zoom operation. This function is used to retrieve a unique ID which you can use to determine the callback function (like ContinuousZoomProgress() or ContinuousZoomCompleted()) is associated with which continuous zoom object. Call CCameraContinuousZoom::ContinuousZoomCompleted() to inform you that the continuous zoom function has either completed successfully or to report an error that has caused the operation to fail. Note: This callback function does not actually stop the continuous zoom. Call CCameraAdvancedSettings::StopContinuousZoom() to stop continuous zooming, if the continuous zoom function has not already completed. Example

              The following example shows you how to perform continuous digital zooming using the Ecam API:

              - -CCamera* camera; -MCameraObserver2* observer2; -Camera = CCamera::New2L(*observer2, 0); -CCamera::CCameraAdvancedSettings* settings = CCamera::CCameraAdvancedSettings::NewL(*camera); - -TUint supportedContinuousZoomType; -settings->GetSupportedContinuousZoomTypeL(supportedContinuousZoomType); - -CCamera::CCameraAdvancedSettings::TContinuousZoomType continuousZoomType = - CCamera::CCameraAdvancedSettings::EContinuousZoomMixed; - -MContinuousZoomObserver* continuousZoomObserver; -CCamera::CCameraContinuousZoom* continuousZoom = NULL; -settings->CreateContinuousZoomL(*continuousZoomObserver, continuousZoomType, continuousZoom); - -CCamera::CCameraAdvancedSettings::TContinuousZoomSupportInfo info; -continuousZoom->GetContinuousZoomSupportInfoL(info); - -CCamera::CCameraAdvancedSettings::TContinuousZoomParameters param; -param.iContinuousZoomType = continuousZoomType; -param.iContinuousZoomAcceleration = 0; -param.iContinuousZoomSpeed = 1; -param.iContinuousZoomLimit = 5; -param.iZoomDirection = CCamera::CCameraAdvancedSettings::EZoomDirectionWide; - -continuousZoom->StartContinuousZoomL(param); - -               Advanced Settings for Focus, Drive Modes, + + + + + +Continuous Digital ZoomingThis tutorial describes how to perform continuous digital zooming using the Ecam API.

              Before you start you should understand the following topics:

              • Overview of the advanced Camera settings functionality.

              • Tutorial of the advanced Camera settings functionality.

              For advanced camera settings, the continuous digital zooming API provides a greater control over continuous zoom by allowing you to specify the speed and acceleration of each continuous zoom operation. The minimum speed for zooming is zero and the minimum acceleration is a negative value (which means deceleration).

              For continuous zooming, you need to provide a concrete implementation of MCameraContinuousZoom.

              Call CCameraAdvancedSettings::NewL(CCamera&) to create a CCameraAdvancedSettings object. Call CCameraAdvancedSettings::GetSupportedContinuousZoomTypeL(TUint&) to retrieve supported continuous zoom options for CCameraAdvancedSettings. Call CCameraAdvancedSettings::CreateContinuousZoomL(MContinuousZoomObserver&, + TContinuousZoomType, CCameraContinuousZoom*&) to create a continuous zoom object. Call CCameraContinuousZoom::GetContinuousZoomSupportInfoL(CCameraAdvancedSettings::TContinuousZoomSupportInfo&) to retrieve information about the supported settings related to continuous zoom. Call CCameraAdvancedSettings::StartContinuousZoomL(CCameraAdvancedSettings::TContinuousZoomParameters) to start the continuous zoom operation. Call the CCameraContinuousZoom::ContinuousZoomProgress(CCameraContinuousZoom&, + TInt, TInt) function when a new zoom factor has achieved during the current continuous zoom operation. Call the CCameraAdvancedSettings::GetContinuousZoomId + (TInt aZoomId) function when you use more than one continuous zoom operation. This function is used to retrieve a unique ID which you can use to determine the callback function (like ContinuousZoomProgress() or ContinuousZoomCompleted()) is associated with which continuous zoom object. Call CCameraContinuousZoom::ContinuousZoomCompleted() to inform you that the continuous zoom function has either completed successfully or to report an error that has caused the operation to fail. Note: This callback function does not actually stop the continuous zoom. Call CCameraAdvancedSettings::StopContinuousZoom() to stop continuous zooming, if the continuous zoom function has not already completed. Example

              The following example shows you how to perform continuous digital zooming using the Ecam API:

              + +CCamera* camera; +MCameraObserver2* observer2; +Camera = CCamera::New2L(*observer2, 0); +CCamera::CCameraAdvancedSettings* settings = CCamera::CCameraAdvancedSettings::NewL(*camera); + +TUint supportedContinuousZoomType; +settings->GetSupportedContinuousZoomTypeL(supportedContinuousZoomType); + +CCamera::CCameraAdvancedSettings::TContinuousZoomType continuousZoomType = + CCamera::CCameraAdvancedSettings::EContinuousZoomMixed; + +MContinuousZoomObserver* continuousZoomObserver; +CCamera::CCameraContinuousZoom* continuousZoom = NULL; +settings->CreateContinuousZoomL(*continuousZoomObserver, continuousZoomType, continuousZoom); + +CCamera::CCameraAdvancedSettings::TContinuousZoomSupportInfo info; +continuousZoom->GetContinuousZoomSupportInfoL(info); + +CCamera::CCameraAdvancedSettings::TContinuousZoomParameters param; +param.iContinuousZoomType = continuousZoomType; +param.iContinuousZoomAcceleration = 0; +param.iContinuousZoomSpeed = 1; +param.iContinuousZoomLimit = 5; +param.iZoomDirection = CCamera::CCameraAdvancedSettings::EZoomDirectionWide; + +continuousZoom->StartContinuousZoomL(param); + +               Advanced Settings for Focus, Drive Modes, and Bracket Modes               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8300FD98-38D7-43EF-A71E-A7BEBFC3F8ED-master.png Binary file Symbian3/SDK/Source/GUID-8300FD98-38D7-43EF-A71E-A7BEBFC3F8ED-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8300FD98-38D7-43EF-A71E-A7BEBFC3F8ED_d0e61693_href.png Binary file Symbian3/SDK/Source/GUID-8300FD98-38D7-43EF-A71E-A7BEBFC3F8ED_d0e61693_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8305F179-8F26-4B38-8523-066D1B0B7A62_d0e212256_href.png Binary file Symbian3/SDK/Source/GUID-8305F179-8F26-4B38-8523-066D1B0B7A62_d0e212256_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-830E40D0-7DEE-5EFB-BCC6-EC0AA7FF7A02.dita --- a/Symbian3/SDK/Source/GUID-830E40D0-7DEE-5EFB-BCC6-EC0AA7FF7A02.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-830E40D0-7DEE-5EFB-BCC6-EC0AA7FF7A02.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,67 +1,67 @@ - - - - - -View -Server Overview -
              Purpose

              This API allows applications to make and -receive requests to show a particular view of data. Small amounts of data -may be passed in such requests. The view architecture allows a high level -of integration between applications. This is particularly useful for enabling -users to navigate through the UI on the basis of the tasks they are working -on, rather than perceiving separate applications.

              -
              Architectural relationships

              Views are UI classes -(almost invariably controls) that implement the Symbian view interface. They -display application data and are owned by the application's main user interface -class (the AppUi).

              The inter-process communication required to make -and receive requests to display particular views is handled by a dedicated -server. The client/server interface is not to be used directly by applications, -but through framework functions in the AppUi (CCoeAppUi).

              - View Server architecture - -
              -
              Description

              The API has several key concepts:

              Abstract -view interface

              The abstract view interface is implemented by application -views to receive activation and deactivation requests from the view server. -The activation method allows a message (a Direct Navigational Link, or DNL), -encapsulated in a descriptor, to be passed to the view (for example, the name -of a file that should be displayed in the view). Note that although view classes -are usually derived from CCoeControl the view architecture -does not impose any restriction on which type of object implements the view -interface.

              The abstract view interface is provided by MCoeView.

              View -ID

              The view ID identifies a view uniquely. It consists of two -UIDs: the application's UID, which is allocated by Symbian, and a view UID, -which is allocated by the Symbian developer. The view UID is not strictly -a UID (though it is of the the same TUid type) and needs -only to be unique within the application and different from the application -UID.

              The view ID is provided by TVwsViewId.

              Registration

              Views -are registered with the View Server. There are functions in CCoeAppUi to -do this. Once registered other applications may activate them by specifying -their view IDs. Applications which do not implement views may still participate -in the view architecture, though to a lesser degree, by registering themselves -using their application UID.

              Activation, deactivation & screen -device change

              Activation is the process of switching, or linking -to a view. Again, there are functions in CCoeAppUi to activate -and deactivate a specified view. The new view is activated and the old view -is deactivated. Activation and deactivation events enable to actions to be -performed by both new and old views. Similarly views need to know when screen -orientation (portrait to landscape) or size (flip closed to flip open) has -changed.

              Observation

              Besides creating events and calling -framework functions on activation, deactivation and screen device change the -view architecture also supports three view observer interfaces which are also -notified when such actions occur, namely MCoeViewObserver, MCoeViewActivationObserver & MCoeViewDeactivationObserver.

              -
              See also
                -

              • UI Control Framework -Overview

                • -

              • Uikon Overview

                • -

              • Application -UI

                • -
              + + + + + +View +Server Overview +
              Purpose

              This API allows applications to make and +receive requests to show a particular view of data. Small amounts of data +may be passed in such requests. The view architecture allows a high level +of integration between applications. This is particularly useful for enabling +users to navigate through the UI on the basis of the tasks they are working +on, rather than perceiving separate applications.

              +
              Architectural relationships

              Views are UI classes +(almost invariably controls) that implement the Symbian view interface. They +display application data and are owned by the application's main user interface +class (the AppUi).

              The inter-process communication required to make +and receive requests to display particular views is handled by a dedicated +server. The client/server interface is not to be used directly by applications, +but through framework functions in the AppUi (CCoeAppUi).

              + View Server architecture + +
              +
              Description

              The API has several key concepts:

              Abstract +view interface

              The abstract view interface is implemented by application +views to receive activation and deactivation requests from the view server. +The activation method allows a message (a Direct Navigational Link, or DNL), +encapsulated in a descriptor, to be passed to the view (for example, the name +of a file that should be displayed in the view). Note that although view classes +are usually derived from CCoeControl the view architecture +does not impose any restriction on which type of object implements the view +interface.

              The abstract view interface is provided by MCoeView.

              View +ID

              The view ID identifies a view uniquely. It consists of two +UIDs: the application's UID, which is allocated by Symbian, and a view UID, +which is allocated by the Symbian developer. The view UID is not strictly +a UID (though it is of the the same TUid type) and needs +only to be unique within the application and different from the application +UID.

              The view ID is provided by TVwsViewId.

              Registration

              Views +are registered with the View Server. There are functions in CCoeAppUi to +do this. Once registered other applications may activate them by specifying +their view IDs. Applications which do not implement views may still participate +in the view architecture, though to a lesser degree, by registering themselves +using their application UID.

              Activation, deactivation & screen +device change

              Activation is the process of switching, or linking +to a view. Again, there are functions in CCoeAppUi to activate +and deactivate a specified view. The new view is activated and the old view +is deactivated. Activation and deactivation events enable to actions to be +performed by both new and old views. Similarly views need to know when screen +orientation (portrait to landscape) or size (flip closed to flip open) has +changed.

              Observation

              Besides creating events and calling +framework functions on activation, deactivation and screen device change the +view architecture also supports three view observer interfaces which are also +notified when such actions occur, namely MCoeViewObserver, MCoeViewActivationObserver & MCoeViewDeactivationObserver.

              +
              See also
                +

              • UI Control Framework +Overview

                • +

              • Uikon Overview

                • +

              • Application +UI

                • +
               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-83630B57-D842-4B60-8AF0-D2965251DE29.dita --- a/Symbian3/SDK/Source/GUID-83630B57-D842-4B60-8AF0-D2965251DE29.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-83630B57-D842-4B60-8AF0-D2965251DE29.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,98 +1,98 @@ - - - - - -Retrieving -Channel PropertiesA sensor channel is associated with properties such as channel -availability status, data transmission rate, data format and so on. Also, -each field in the data type supplied by a sensor channel can have its own -properties. The channel properties can be retrieved using the CSensrvChannel::GetPropertyL() and CSensrvChannel::GetAllPropertiesL() functions. -

              Before retrieving -channel properties, you must open -the sensor channel.

               -

              A channel property -is referenced by its property id and an index. The parameters of the CSensrvChannel::GetPropertyL() are -listed with their meanings in the following table.

              - - - -Parameter -Meaning - - - - -First parameter -specifies the id of the property to retrieve. - - -Second parameter -is an index that specifies the property to be retrieved, if there are -several properties associated with a particular property id. - - -Third parameter - is a TSensrvProperty that is passed by reference -and populated by CSensrvChannel::GetPropertyL(). - - - -

              The following list shows the different possible values of the index -:

                -

              • When the property id is for a simple property, that is, there is only -one property item for the id (for example, KSensrvPropIdChannelAccuracy), -the second parameter must be specified as ESensrvSingleProperty.

                • -

              • When the given property id has an array of TSensrvProperty items, -the index parameter indicates which item in the array to retrieve. One such -case is when you want to retrieve a property of a particular data field that -is supplied by the channel. For example, if you want to find out if the X -axis of the accelerometer is enabled, you must specify KSensrvPropIdAxisActive as -the property id, and TSensrvAccelerometerAxisData::iAxisX as -the index. For details, see Array -Properties.

                • -

              • When the given property id has an array of TSensrvProperty items, -information about the array can be retrieved by specifying ESensrvArrayPropertyInfo as -the index parameter. For example, when a channel can provide data at discrete -data rates, the information for each data rate is stored in a TSensrvProperty item. -You can use KSensrvPropIdDataRate as the property id -and ESensrvArrayPropertyInfo as the index to retrieve -the property item that contains this information.

                • -
               - -Create an instance -of TSensrvProperty. -TSensrvProperty property; -

              Each channel property is encapsulated by the TSensrvProperty class. -Therefore, the details of the retrieved property can be accessed using the -functions of the TSensrvProperty class.

               -               -Use the CSensrvChannel::GetPropertyL() function -to retrieve the property item for a particular property id. For example, to -check for the accuracy of a channel, pass the KSensrvPropIdChannelAccuracy as -a property id. -... - -CSensrvChannel* iSensorChannel; -.... -iSensorChannel->GetPropertyL( KSensrvPropIdChannelAccuracy, - KSensrvItemIndexNone, - property ); - -.... - You can retrieve all the properties associated with a particular -sensor channel using the CSensrvChannel::GetAllPropertiesL() function. - -               -
                -
              • End the session with the sensor channel using the CSensrvChannel::CloseChannel() function.
                • -
              • You can set the required channel properties. For details, see Setting -Channel Properties.
                • -
               + + + + + +Retrieving +Channel PropertiesA sensor channel is associated with properties such as channel +availability status, data transmission rate, data format and so on. Also, +each field in the data type supplied by a sensor channel can have its own +properties. The channel properties can be retrieved using the CSensrvChannel::GetPropertyL() and CSensrvChannel::GetAllPropertiesL() functions. +

              Before retrieving +channel properties, you must open +the sensor channel.

               +

              A channel property +is referenced by its property id and an index. The parameters of the CSensrvChannel::GetPropertyL() are +listed with their meanings in the following table.

              + + + +Parameter +Meaning + + + + +First parameter +specifies the id of the property to retrieve. + + +Second parameter +is an index that specifies the property to be retrieved, if there are +several properties associated with a particular property id. + + +Third parameter + is a TSensrvProperty that is passed by reference +and populated by CSensrvChannel::GetPropertyL(). + + + +

              The following list shows the different possible values of the index +:

                +

              • When the property id is for a simple property, that is, there is only +one property item for the id (for example, KSensrvPropIdChannelAccuracy), +the second parameter must be specified as ESensrvSingleProperty.

                • +

              • When the given property id has an array of TSensrvProperty items, +the index parameter indicates which item in the array to retrieve. One such +case is when you want to retrieve a property of a particular data field that +is supplied by the channel. For example, if you want to find out if the X +axis of the accelerometer is enabled, you must specify KSensrvPropIdAxisActive as +the property id, and TSensrvAccelerometerAxisData::iAxisX as +the index. For details, see Array +Properties.

                • +

              • When the given property id has an array of TSensrvProperty items, +information about the array can be retrieved by specifying ESensrvArrayPropertyInfo as +the index parameter. For example, when a channel can provide data at discrete +data rates, the information for each data rate is stored in a TSensrvProperty item. +You can use KSensrvPropIdDataRate as the property id +and ESensrvArrayPropertyInfo as the index to retrieve +the property item that contains this information.

                • +
               + +Create an instance +of TSensrvProperty. +TSensrvProperty property; +

              Each channel property is encapsulated by the TSensrvProperty class. +Therefore, the details of the retrieved property can be accessed using the +functions of the TSensrvProperty class.

               +               +Use the CSensrvChannel::GetPropertyL() function +to retrieve the property item for a particular property id. For example, to +check for the accuracy of a channel, pass the KSensrvPropIdChannelAccuracy as +a property id. +... + +CSensrvChannel* iSensorChannel; +.... +iSensorChannel->GetPropertyL( KSensrvPropIdChannelAccuracy, + KSensrvItemIndexNone, + property ); + +.... + You can retrieve all the properties associated with a particular +sensor channel using the CSensrvChannel::GetAllPropertiesL() function. + +               +
                +
              • End the session with the sensor channel using the CSensrvChannel::CloseChannel() function.
                • +
              • You can set the required channel properties. For details, see Setting +Channel Properties.
                • +
                             \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-83798F82-15FB-4EA6-9AD8-540616CBF6C4.dita --- a/Symbian3/SDK/Source/GUID-83798F82-15FB-4EA6-9AD8-540616CBF6C4.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-83798F82-15FB-4EA6-9AD8-540616CBF6C4.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,31 +1,31 @@ - - - - - -Control -pane with pop-up -

              In touch layout, the softkeys are placed inside the pop-up component to display -the functions closer to the context. Pop-up with softkeys is centered vertically -and horizontally in landscape orientation. In portrait orientation, the pop-up -is placed at the bottom of the screen. In case there is only one softkey available, -both button graphics are still displayed. In case there are no softkeys available, -the softkey area is not displayed.

              -

              Softkeys inside a pop-up have the same default functionality and touch -feedback as the normal control pane area defined in Control -pane section.

              - -Example images of pop-up components with two softkeys - - - -Examples images of pop-ups with one softkey - - + + + + + +Control +pane with pop-up +

              In touch layout, the softkeys are placed inside the pop-up component to display +the functions closer to the context. Pop-up with softkeys is centered vertically +and horizontally in landscape orientation. In portrait orientation, the pop-up +is placed at the bottom of the screen. In case there is only one softkey available, +both button graphics are still displayed. In case there are no softkeys available, +the softkey area is not displayed.

              +

              Softkeys inside a pop-up have the same default functionality and touch +feedback as the normal control pane area defined in Control +pane section.

              + +Example images of pop-up components with two softkeys + + + +Examples images of pop-ups with one softkey + +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8390D842-B8A3-5042-952D-73240DB30D6B.dita --- a/Symbian3/SDK/Source/GUID-8390D842-B8A3-5042-952D-73240DB30D6B.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-8390D842-B8A3-5042-952D-73240DB30D6B.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,161 +1,161 @@ - - - - - -Message -Server and Store Overview -

              This section provides an overview of the functionality and the architecture -of Message Server and Store.

              -
              Purpose

              The following services that are provided -by this component can be used by the client application:

                -

              • Storing -Messages

                • -

              • Handling -Client Requests

                • -

              • Caching

                • -

              • Searching -and Sorting Messages

                • -
              -
              Architecture

              Message type-dependent operations, -such as address handling, are called by client applications using client MTMs -and UI MTMs. These MTMs then access the appropriate Message Store and alter -it as required.

              The following figure shows the logical structure of -the Message Server. Dashed boxes indicate components that can be developed -by third-parties.

              - Logical structure of Messaging Middleware architecture - - - No lower-level communication components are shown, as the architecture -is designed to be independent of any particular communication protocol. Instead, -communication libraries are accessed as needed by Server MTMs. For example, -an SMTP MTM would use TCP/IP, while the SMS MTM would use the Telephony Server -(ETel).
              - -
              Application/App UI
              -

              This represents a message client application.

              -               - -
              User Interface MTM, Client-side MTM, UI Data MTM, Server-side MTM Bases
              -

              These are base classes required for implementing protocol-specific -MTM components. User Interface and UI Data MTMs handle user interface functionality -and resources. Client-side MTMs provide message data handling functions. Server-side -MTMs provide message transport functions.

              -               - -
              Concrete User Interface MTM, Concrete Client-side MTM, Concrete UI Data -MTM, Concrete Server-side MTM
              -

              These represent instances of MTM components written to implement a -particular messaging protocol.

              -               - -
              Message Server
              -

              The Message Server handles all requests to access or manipulate message -data. Where necessary, it passes requests to the protocol-specific message -transport components, the Server-side MTMs.

              -               - -
              Session
              -

              Sessions allow client-side components to issue requests to the Message -Server. There are a number of classes provided to clients that allow message -entries to be manipulated.

              -               -

              The msgs.dll library provides a client-side -session class called CMsvSession . Client applications -typically create an instance of this class on start-up. Instances of Client -MTMs, User Interface (UI) MTMs and high-level client library classes maintain -a reference to the client application’s session object, to make requests if -needed.

              Message client applications, Client MTMs and UI MTMs manipulate -entries through TMsvEntry and CMsvEntry classes. -The entry currently being operated on is called the context. A client application -can begin by setting the context to the root entry. By finding the children -of this initial entry, and then their children in turn, any entry can be found.

              Operations -such as creating, deleting, sorting and accessing body text, or changing an -index entry, which are independent of the message-type, are requested by client -applications and MTMs through CMvsEntry or CMsvServerEntry. -The Message Server may either perform such operations itself or delegate them -to a server MTM.

              -
              Description

              The Message Server is the core component -in the Messaging Middleware module. It accepts asynchronous requests from -clients through a kernel-maintained session. It performs the following functions:

                -

              • Controls access -to message data

                In response to client requests, the Message Server -delegates temporary, exclusive access to message data, so that more than one -client cannot edit the same message at the same time. It is the responsibility -of Message Server to keep the message data in workable order, and cope with -events such as failure recovery.

                • -

              • Delegates requests -to Server MTMs

                Message Server must identify requests, such as -sending a message that requires protocol-specific functionality, and load -the appropriate Server MTM.

                • -

              Message Store

              Message -Server provides persistent storage of messages and messaging account settings -by providing a Message Store. The Message Store contains message data in a -variable number of entries in a tree view, each of which is referenced by -a unique identifier. This concept is known as a dictionary -file store. Each entry in the tree can represent an email account, -folder of messages, message part and so on.

              Message Store is secured -in a protected data-caged area of Message Server. Message Server allows multiple -read-only and a single read-write access to a message in the Message Store -at given time. It also accepts copy and delete requests from clients trusted -with WriteUserData capability. When a copy or delete is requested, -the message server first flags itself as unavailable and then locks the files -before attempting to process them.

              Message settings are stored in -the Central Repository and attachment information is stored in the Message -Store. MTMs can create additional streams in the message store to hold MTM-specific -message data. Usually, at least one stream is devoted to non-generic header -information such as recipient information.

              When Message Server starts, -the Message Store is created unless there is already a Message Store present. -Message Server initially creates the Message Store with just a root entry -and then creates standard folders defined in the msgs.rsc resource -file. Finally the Message Server runs mailinit.exe to -customise of the Message Store. The behaviour of mailinit.exe is -defined by the UI family of the device, such as Series 60 or UIQ. However, -the typical behaviour is to load each of the UI MTMs and allow each to perform -any message type specific initialisation. For example, the SMS plug-in typically -creates a default service entry.

              -
              API summary

              The storage abstractions through which -client applications access the various types of storage are key to the Messaging -Middleware module.

                -

              • The CMsvEntry API -access and acts on a particular Message Server entry. The main functions of -this API are to provide means to:

                  -

                • access the various types -of storage associated with an entry

                  • -

                • discover and access -other entries that the entry owns (its children)

                  • -
                • -

              • CMsvServerEntry is -similar to CMsvEntry, but used only by Server MTMs.

                • -

              • TMsvEntry encapsulates -an index entry the Message Server index.

                • -

              • CMsvStore encapsulates -an entry’s Message -Store.

                • -

              • MMsvAttachmentManager class -is a pure virtual interface class that defines the APIs to be used for attachment -management in the Messaging Framework.

                • -
              -
              Typical uses
                -

              • Configuring the Message -Server ans Store

                • -

              • Writing MTMs

                • -

              • Searching and sorting -messages

                • -

              • Processing emails in -chunks

                • -
              -               -Messaging -Framework -Message Server -and Store Concepts -Message Server -and Store Tutorials + + + + + +Message +Server and Store Overview +

              This section provides an overview of the functionality and the architecture +of Message Server and Store.

              +
              Purpose

              The following services that are provided +by this component can be used by the client application:

                +

              • Storing +Messages

                • +

              • Handling +Client Requests

                • +

              • Caching

                • +

              • Searching +and Sorting Messages

                • +
              +
              Architecture

              Message type-dependent operations, +such as address handling, are called by client applications using client MTMs +and UI MTMs. These MTMs then access the appropriate Message Store and alter +it as required.

              The following figure shows the logical structure of +the Message Server. Dashed boxes indicate components that can be developed +by third-parties.

              + Logical structure of Messaging Middleware architecture + + + No lower-level communication components are shown, as the architecture +is designed to be independent of any particular communication protocol. Instead, +communication libraries are accessed as needed by Server MTMs. For example, +an SMTP MTM would use TCP/IP, while the SMS MTM would use the Telephony Server +(ETel).
              + +
              Application/App UI
              +

              This represents a message client application.

              +               + +
              User Interface MTM, Client-side MTM, UI Data MTM, Server-side MTM Bases
              +

              These are base classes required for implementing protocol-specific +MTM components. User Interface and UI Data MTMs handle user interface functionality +and resources. Client-side MTMs provide message data handling functions. Server-side +MTMs provide message transport functions.

              +               + +
              Concrete User Interface MTM, Concrete Client-side MTM, Concrete UI Data +MTM, Concrete Server-side MTM
              +

              These represent instances of MTM components written to implement a +particular messaging protocol.

              +               + +
              Message Server
              +

              The Message Server handles all requests to access or manipulate message +data. Where necessary, it passes requests to the protocol-specific message +transport components, the Server-side MTMs.

              +               + +
              Session
              +

              Sessions allow client-side components to issue requests to the Message +Server. There are a number of classes provided to clients that allow message +entries to be manipulated.

              +               +

              The msgs.dll library provides a client-side +session class called CMsvSession . Client applications +typically create an instance of this class on start-up. Instances of Client +MTMs, User Interface (UI) MTMs and high-level client library classes maintain +a reference to the client application’s session object, to make requests if +needed.

              Message client applications, Client MTMs and UI MTMs manipulate +entries through TMsvEntry and CMsvEntry classes. +The entry currently being operated on is called the context. A client application +can begin by setting the context to the root entry. By finding the children +of this initial entry, and then their children in turn, any entry can be found.

              Operations +such as creating, deleting, sorting and accessing body text, or changing an +index entry, which are independent of the message-type, are requested by client +applications and MTMs through CMvsEntry or CMsvServerEntry. +The Message Server may either perform such operations itself or delegate them +to a server MTM.

              +
              Description

              The Message Server is the core component +in the Messaging Middleware module. It accepts asynchronous requests from +clients through a kernel-maintained session. It performs the following functions:

                +

              • Controls access +to message data

                In response to client requests, the Message Server +delegates temporary, exclusive access to message data, so that more than one +client cannot edit the same message at the same time. It is the responsibility +of Message Server to keep the message data in workable order, and cope with +events such as failure recovery.

                • +

              • Delegates requests +to Server MTMs

                Message Server must identify requests, such as +sending a message that requires protocol-specific functionality, and load +the appropriate Server MTM.

                • +

              Message Store

              Message +Server provides persistent storage of messages and messaging account settings +by providing a Message Store. The Message Store contains message data in a +variable number of entries in a tree view, each of which is referenced by +a unique identifier. This concept is known as a dictionary +file store. Each entry in the tree can represent an email account, +folder of messages, message part and so on.

              Message Store is secured +in a protected data-caged area of Message Server. Message Server allows multiple +read-only and a single read-write access to a message in the Message Store +at given time. It also accepts copy and delete requests from clients trusted +with WriteUserData capability. When a copy or delete is requested, +the message server first flags itself as unavailable and then locks the files +before attempting to process them.

              Message settings are stored in +the Central Repository and attachment information is stored in the Message +Store. MTMs can create additional streams in the message store to hold MTM-specific +message data. Usually, at least one stream is devoted to non-generic header +information such as recipient information.

              When Message Server starts, +the Message Store is created unless there is already a Message Store present. +Message Server initially creates the Message Store with just a root entry +and then creates standard folders defined in the msgs.rsc resource +file. Finally the Message Server runs mailinit.exe to +customise of the Message Store. The behaviour of mailinit.exe is +defined by the UI family of the device, such as Series 60 or UIQ. However, +the typical behaviour is to load each of the UI MTMs and allow each to perform +any message type specific initialisation. For example, the SMS plug-in typically +creates a default service entry.

              +
              API summary

              The storage abstractions through which +client applications access the various types of storage are key to the Messaging +Middleware module.

                +

              • The CMsvEntry API +access and acts on a particular Message Server entry. The main functions of +this API are to provide means to:

                  +

                • access the various types +of storage associated with an entry

                  • +

                • discover and access +other entries that the entry owns (its children)

                  • +
                • +

              • CMsvServerEntry is +similar to CMsvEntry, but used only by Server MTMs.

                • +

              • TMsvEntry encapsulates +an index entry the Message Server index.

                • +

              • CMsvStore encapsulates +an entry’s Message +Store.

                • +

              • MMsvAttachmentManager class +is a pure virtual interface class that defines the APIs to be used for attachment +management in the Messaging Framework.

                • +
              +
              Typical uses
                +

              • Configuring the Message +Server ans Store

                • +

              • Writing MTMs

                • +

              • Searching and sorting +messages

                • +

              • Processing emails in +chunks

                • +
              +               +Messaging +Framework +Message Server +and Store Concepts +Message Server +and Store Tutorials               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-83A4D862-368E-5DCC-998E-90144BE18A22.dita --- a/Symbian3/SDK/Source/GUID-83A4D862-368E-5DCC-998E-90144BE18A22.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-83A4D862-368E-5DCC-998E-90144BE18A22.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,16 +1,16 @@ - - - - - -How to Override Default Authentication Handling

              SIP provides a feature to the SIP client to handle authentication handling for services such as registration and session establishment. By default, this authentication challenge handling is handled by the SIP server using the digest mechanism. This mechanism is used by profile plug-ins that implement nondefault SIP behaviour which is also known as extensible Service Provider (xSP).

              These components are used when a SIP client handles authentication challenges independently. When an authentication problem is reported use CSIPAuthorizationHeader and CSIPProxyAuthorizationHeader objects to manipulate the registration or session initiation request headers. Then re-register a profile or reinitiate a session using the updated headers.

              To enable a client to override default authentication handling mechanisms, it must inform the SIP server by disabling the built-in security mechanism of the SIP using the CSIP::SetSecurityHandlingL() function. The client uses CSIP::IsSecurityHandlingEnabled() function to determine what is handling the authentication challenges. This function returns ETrue if the built-in security mechanism of the SIP is used.

              When a SIP client handles authentication challenges independently, it uses CSIPAuthorizationHeader and CSIPProxyAuthorizationHeader objects to manipulate the registration or session initiation request headers when an authentication problem is reported. Re-registration of a profile or reinitiating a session is done using the updated headers.

              In the following illustration the client handles authentication challenges related to the profile registration. All authentication errors are then forwarded to the xSP profile agent plug-in. When an error is reported to the plug-in, it runs a proprietary authentication procedure and tries to re-register the profile.

              The following illustration shows the call flow of handling authentication challenges while registering a SIP profile:

              - Call flow for handling 401 challenges using xSP profile agent plug-in -

              In the following illustration the client handles authentication challenges related to the session initiation. All the authentication errors are then forwarded to the xSP provider. When an error is reported to the provider, it runs a proprietary authentication procedure and tries to reinitiate the session.

              The following illustration shows the call flow of handling authentication challenges while establishing a session:

              - Call flow for handling 401 challenges using xSP provider -
              See also

              How to use the SIP Client API

              \ No newline at end of file + + + + + +How to Override Default Authentication Handling

              SIP provides a feature to the SIP client to handle authentication handling for services such as registration and session establishment. By default, this authentication challenge handling is handled by the SIP server using the digest mechanism. This mechanism is used by profile plug-ins that implement nondefault SIP behaviour which is also known as extensible Service Provider (xSP).

              These components are used when a SIP client handles authentication challenges independently. When an authentication problem is reported use CSIPAuthorizationHeader and CSIPProxyAuthorizationHeader objects to manipulate the registration or session initiation request headers. Then re-register a profile or reinitiate a session using the updated headers.

              To enable a client to override default authentication handling mechanisms, it must inform the SIP server by disabling the built-in security mechanism of the SIP using the CSIP::SetSecurityHandlingL() function. The client uses CSIP::IsSecurityHandlingEnabled() function to determine what is handling the authentication challenges. This function returns ETrue if the built-in security mechanism of the SIP is used.

              When a SIP client handles authentication challenges independently, it uses CSIPAuthorizationHeader and CSIPProxyAuthorizationHeader objects to manipulate the registration or session initiation request headers when an authentication problem is reported. Re-registration of a profile or reinitiating a session is done using the updated headers.

              In the following illustration the client handles authentication challenges related to the profile registration. All authentication errors are then forwarded to the xSP profile agent plug-in. When an error is reported to the plug-in, it runs a proprietary authentication procedure and tries to re-register the profile.

              The following illustration shows the call flow of handling authentication challenges while registering a SIP profile:

              + Call flow for handling 401 challenges using xSP profile agent plug-in +

              In the following illustration the client handles authentication challenges related to the session initiation. All the authentication errors are then forwarded to the xSP provider. When an error is reported to the provider, it runs a proprietary authentication procedure and tries to reinitiate the session.

              The following illustration shows the call flow of handling authentication challenges while establishing a session:

              + Call flow for handling 401 challenges using xSP provider +
              See also

              How to use the SIP Client API

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-83BE15D8-511F-592D-A93B-C71BD6FB1B08.dita --- a/Symbian3/SDK/Source/GUID-83BE15D8-511F-592D-A93B-C71BD6FB1B08.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-83BE15D8-511F-592D-A93B-C71BD6FB1B08.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,47 +1,47 @@ - - - - - -What -are tablesThis topic describes the structure of a table. A table is an item -that can be stored in the Comms Database. -

              A table is a set of records. All records in a table are the same type. -A table is also a container and an element.

              -

              There are two types of table:

              -
                -

              • a table that has records -defined at system compile time - these records have named fields and are defined -by Symbian platform.

                • -

              • a table that consists -of records defined at run time - these records are user defined records - -they are not known to Symbian platform when Symbian platform is built.

                • -
              -
              Tables that have records defined at system compile - time

              A table that has records defined at system compile time -is represented by the templated class CMDBRecordSet <T>. -The template parameter defines the record type. The template parameter is -a Symbian platform defined record.

              You create a table -object on the heap. You use the new (Eleave) construction -to create this object.

              - -

              The CommsDat API implements the table as an array of records and -uses RPointerArray <T> as -the array. The CommsDat API implements RPointerArray<T> in -the base class CMDBRecordSetBase, because -this behaviour is common to all tables. Tools and applications can access -the array and can use the sort behaviour provided by RPointerArray<T> to -sort records.

              -
              Tables that have user defined records

              A table that -has user defined records is represented by the CMDBGenericRecord. -The class has the behaviour that allows it to represent a record and a set -of records. Internally, the class has an array that can contain the records.

              You -use the CommsDat::CCDRecordBase::RecordFactoryL() factory -function to create a CMDBGenericRecord object.

              + + + + + +What +are tablesThis topic describes the structure of a table. A table is an item +that can be stored in the Comms Database. +

              A table is a set of records. All records in a table are the same type. +A table is also a container and an element.

              +

              There are two types of table:

              +
                +

              • a table that has records +defined at system compile time - these records have named fields and are defined +by Symbian platform.

                • +

              • a table that consists +of records defined at run time - these records are user defined records - +they are not known to Symbian platform when Symbian platform is built.

                • +
              +
              Tables that have records defined at system compile + time

              A table that has records defined at system compile time +is represented by the templated class CMDBRecordSet <T>. +The template parameter defines the record type. The template parameter is +a Symbian platform defined record.

              You create a table +object on the heap. You use the new (Eleave) construction +to create this object.

              + +

              The CommsDat API implements the table as an array of records and +uses RPointerArray <T> as +the array. The CommsDat API implements RPointerArray<T> in +the base class CMDBRecordSetBase, because +this behaviour is common to all tables. Tools and applications can access +the array and can use the sort behaviour provided by RPointerArray<T> to +sort records.

              +
              Tables that have user defined records

              A table that +has user defined records is represented by the CMDBGenericRecord. +The class has the behaviour that allows it to represent a record and a set +of records. Internally, the class has an array that can contain the records.

              You +use the CommsDat::CCDRecordBase::RecordFactoryL() factory +function to create a CMDBGenericRecord object.

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-83DC4E21-72B3-459F-9AE8-41ED52BF219C-master.png Binary file Symbian3/SDK/Source/GUID-83DC4E21-72B3-459F-9AE8-41ED52BF219C-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-83DC4E21-72B3-459F-9AE8-41ED52BF219C_d0e65944_href.png Binary file Symbian3/SDK/Source/GUID-83DC4E21-72B3-459F-9AE8-41ED52BF219C_d0e65944_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-83DC4E21-72B3-459F-9AE8-41ED52BF219C_d0e71193_href.png Binary file Symbian3/SDK/Source/GUID-83DC4E21-72B3-459F-9AE8-41ED52BF219C_d0e71193_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-845F3021-E3ED-4676-916A-75740886DCBD.dita --- a/Symbian3/SDK/Source/GUID-845F3021-E3ED-4676-916A-75740886DCBD.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-845F3021-E3ED-4676-916A-75740886DCBD.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,80 +1,80 @@ - - - - - -Providing -a vertical list of selectable items -

              To provide a vertical list of selectable items using the Choice List API, -follow the steps below:

              -
                -

              1. Link the AVKON libraries -(avkon.lib and eikcoctl.lib) to the project -file of the application.

                2. -

              2. Provide an observer -class that realizes the McoeControlObserver interface.

                3. -

              3. Create an instance of -the class CAknChoiceList.

                4. -

              4. Add content to the created -choice list instance.

                5. -

              5. Show the choice list.

                6. -

              6. Receive information -from the choice list through the observer interface.

                7. -

              7. Delete the choice list.

                8. -
              -
              Indexing of -items in the choice list

              The client application is responsible for -keeping track of item indexes in the choice list. The choice list component -does not do this: it only returns the index of a list item.

              The choice -list items are indexed as follows:

                -

              • When the items are added to the choice list from e.g. an array, the -first item gets an index of 0.

                • -

              • The other items added from the array get indexes 1, 2, 3 and so forth -until the last item has received an index. Therefore, for example, in a list -of four items, the items have indexes 0 - 3.

                • -

              • If an item is added to the end of the list, it gets the next index -number based on the number of items already in the list. For example, adding -the fifth item in a four-item list results in that item having the index 4.

                • -

              • If items are added to the middle of the list, the indexes of the items -after the added items are shifted up accordingly. For example, if an item -is added as the fourth item in a six-item list, the old fourth, fifth, and -sixth items with indexes 3 - 5 get indexes 4 - 6.

                • -

              • If an items is removed from the list, the indexes of the subsequent -items in the list are shifted down accordingly. For example, if the second -item is removed, the old third item becomes the second item and therefore -gets an index of 1.

                • -
              -
              Use cases -Choice list API use cases - -

              To use a choice list in your application, implementing the following -use cases is mandatory:

                -

              • Creating the -choice list

                • -

              • Adding items -to the choice list

                • -

              • Getting user -selection from the choice list

                • -

              • Deleting the -choice list

                • -

              The following use cases are optional, allowing you to set additional -properties for your choice list:

                -

              • Showing the -choice list

                • -

              • Removing items -from the choice list

                • -

              • Setting the -item selected when the choice list is opened

                • -
              -
              Main implementation -files

              The implementation file for the Choice list API is aknchoicelist.h.

              -               -Choice list -API description + + + + + +Providing +a vertical list of selectable items +

              To provide a vertical list of selectable items using the Choice List API, +follow the steps below:

              +
                +

              1. Link the AVKON libraries +(avkon.lib and eikcoctl.lib) to the project +file of the application.

                2. +

              2. Provide an observer +class that realizes the McoeControlObserver interface.

                3. +

              3. Create an instance of +the class CAknChoiceList.

                4. +

              4. Add content to the created +choice list instance.

                5. +

              5. Show the choice list.

                6. +

              6. Receive information +from the choice list through the observer interface.

                7. +

              7. Delete the choice list.

                8. +
              +
              Indexing of +items in the choice list

              The client application is responsible for +keeping track of item indexes in the choice list. The choice list component +does not do this: it only returns the index of a list item.

              The choice +list items are indexed as follows:

                +

              • When the items are added to the choice list from e.g. an array, the +first item gets an index of 0.

                • +

              • The other items added from the array get indexes 1, 2, 3 and so forth +until the last item has received an index. Therefore, for example, in a list +of four items, the items have indexes 0 - 3.

                • +

              • If an item is added to the end of the list, it gets the next index +number based on the number of items already in the list. For example, adding +the fifth item in a four-item list results in that item having the index 4.

                • +

              • If items are added to the middle of the list, the indexes of the items +after the added items are shifted up accordingly. For example, if an item +is added as the fourth item in a six-item list, the old fourth, fifth, and +sixth items with indexes 3 - 5 get indexes 4 - 6.

                • +

              • If an items is removed from the list, the indexes of the subsequent +items in the list are shifted down accordingly. For example, if the second +item is removed, the old third item becomes the second item and therefore +gets an index of 1.

                • +
              +
              Use cases +Choice list API use cases + +

              To use a choice list in your application, implementing the following +use cases is mandatory:

                +

              • Creating the +choice list

                • +

              • Adding items +to the choice list

                • +

              • Getting user +selection from the choice list

                • +

              • Deleting the +choice list

                • +

              The following use cases are optional, allowing you to set additional +properties for your choice list:

                +

              • Showing the +choice list

                • +

              • Removing items +from the choice list

                • +

              • Setting the +item selected when the choice list is opened

                • +
              +
              Main implementation +files

              The implementation file for the Choice list API is aknchoicelist.h.

              +               +Choice list +API description               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-84897583-A06F-42EE-917D-DF908B095AFF-master.png Binary file Symbian3/SDK/Source/GUID-84897583-A06F-42EE-917D-DF908B095AFF-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-84897583-A06F-42EE-917D-DF908B095AFF_d0e316089_href.png Binary file Symbian3/SDK/Source/GUID-84897583-A06F-42EE-917D-DF908B095AFF_d0e316089_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-84B088C0-7013-4B6A-BA34-8F022E38E822_d0e68775_href.png Binary file Symbian3/SDK/Source/GUID-84B088C0-7013-4B6A-BA34-8F022E38E822_d0e68775_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-84C75561-E082-4EFF-89A7-901361612CCA_d0e61144_href.png Binary file Symbian3/SDK/Source/GUID-84C75561-E082-4EFF-89A7-901361612CCA_d0e61144_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-85058500-87C5-457A-9567-ECAB29708759.dita --- a/Symbian3/SDK/Source/GUID-85058500-87C5-457A-9567-ECAB29708759.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-85058500-87C5-457A-9567-ECAB29708759.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,85 +1,84 @@ - - - - - -Lists -in pop-up windowsVertical lists are used extensively in most applications as part -of the pop-up windows, to display the options available for a selected item. -

              For the information on the available list types in pop-ups, refer to List types section

              - - - -

              Design Guidelines : Lists do not have permanent highlight in touch. -For information on the list navigation, see Dragging -and flicking and Scrollbar.

              -

              Tactile: For information about the feedback of list navigation, see Dragging and flicking and Scrollbar. For pop-up -related tactile feedback, refer to Pop-ups.

              -Default touch -events for lists in pop-up windows - - - - - - -

              User action

               -

              State change

               -

              Feedback

               -               - - - -

              Touch down

               -

              No effect

               -

              Highlight is shown.

              Tactile: Basic list effect and audio -feedback are given with touch down event.

               -               - -

              Touch release

               -

              Item is activated.

               -

              Highlight disappears.

              Tactile: Basic list effect is provided -with touch release event.

               -               - -

              Touch down and hold on item

               -

              Inactive

               -

              Tactile: No effect

               -               - -

              Touch down and move inside pop-up

               -

              Refer to Dragging -and flicking events.

               -

              Tactile: Refer to Dragging -and flicking events.

               -               - -

              Touch down, move and touch release with speed

               -

              Refer to Dragging -and flicking events.

               -

              Tactile: Refer to Dragging -and flicking events.

               -               - -

              Touch down and move outside the pop-up without releasing touch

               -

              Refer to Dragging -and flicking events.

               -

              Tactile: Refer to Dragging -and flicking events.

               -               - -

              Touch down and release outside the pop-up

               -

              Inactive

              Pop-up stays open if the pop-up has softkeys. Refer -to Pop-ups for -mode details.

               -

              Tactile: No effect

               -               - - + + + + + +Lists +in pop-up windowsVertical lists are used extensively in most applications as part +of the pop-up windows, to display the options available for a selected item. + + + +

              Design Guidelines : Lists do not have permanent highlight in touch. +For information on the list navigation, see Dragging +and flicking and Scrollbar.

              +

              Tactile: For information about the feedback of list navigation, see Dragging and flicking and Scrollbar. For pop-up +related tactile feedback, refer to Pop-ups.

              +
              Default touch +events for lists in pop-up windows + + + + + + +

              User action

               +

              State change

               +

              Feedback

               +               + + + +

              Touch down

               +

              No effect

               +

              Highlight is shown.

              Tactile: Basic list effect and audio +feedback are given with touch down event.

               +               + +

              Touch release

               +

              Item is activated.

               +

              Highlight disappears.

              Tactile: Basic list effect is provided +with touch release event.

               +               + +

              Touch down and hold on item

               +

              Inactive

               +

              Tactile: No effect

               +               + +

              Touch down and move inside pop-up

               +

              Refer to Dragging +and flicking events.

               +

              Tactile: Refer to Dragging +and flicking events.

               +               + +

              Touch down, move and touch release with speed

               +

              Refer to Dragging +and flicking events.

               +

              Tactile: Refer to Dragging +and flicking events.

               +               + +

              Touch down and move outside the pop-up without releasing touch

               +

              Refer to Dragging +and flicking events.

               +

              Tactile: Refer to Dragging +and flicking events.

               +               + +

              Touch down and release outside the pop-up

               +

              Inactive

              Pop-up stays open if the pop-up has softkeys. Refer +to Pop-ups for +mode details.

               +

              Tactile: No effect

               +               + +
               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8526BBD8-CA70-4B3F-B91D-D70AF06440B2-master.png Binary file Symbian3/SDK/Source/GUID-8526BBD8-CA70-4B3F-B91D-D70AF06440B2-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8526BBD8-CA70-4B3F-B91D-D70AF06440B2_d0e55432_href.png Binary file Symbian3/SDK/Source/GUID-8526BBD8-CA70-4B3F-B91D-D70AF06440B2_d0e55432_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-85291DF3-C134-4231-938A-C20DD122AB7D_d0e11153_href.png Binary file Symbian3/SDK/Source/GUID-85291DF3-C134-4231-938A-C20DD122AB7D_d0e11153_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-85291DF3-C134-4231-938A-C20DD122AB7D_d0e12428_href.png Binary file Symbian3/SDK/Source/GUID-85291DF3-C134-4231-938A-C20DD122AB7D_d0e12428_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-857A523E-E660-5AFA-98B1-3A5440A8372F_d0e250294_href.jpg Binary file Symbian3/SDK/Source/GUID-857A523E-E660-5AFA-98B1-3A5440A8372F_d0e250294_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-857A523E-E660-5AFA-98B1-3A5440A8372F_d0e254026_href.jpg Binary file Symbian3/SDK/Source/GUID-857A523E-E660-5AFA-98B1-3A5440A8372F_d0e254026_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-858ABC77-053B-5C45-A8EB-08C68506B193.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-858ABC77-053B-5C45-A8EB-08C68506B193.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,30 @@ + + + + + +VectorSprite: drawing sprites +
              Description

              The VectorSprite example creates a simple animated sprite (a rotating line), and +creates the sprite's bitmaps by creating and drawing to off-screen +bitmaps within the application. No redraw events are caused by the +sprite.

              +
              Download

              Click on the following link to download the example: VectorSprite.zip

              Click: browse to view the example code.

              +
              Class Defined

              CSprite: Demonstrates +how to use class RWsSprite by setting up the sprite members to contain +bitmaps then appending them to the sprite. The bitmaps are off screen +bitmaps drawn to using a graphics context

              +
              Class Summary
                +

              • RWsSpriteBase: Abstract base class for sprites

                • +

              • RWsSprite: Sprite

                • +

              • TSpriteMember : Sprite member

                • +

              • CFbsBitmap : Font-bitmap server bitmap

                • +

              • CFbsBitmapDevice : FBS bitmap used as graphics device

                • +

              • CGraphicsContext : Graphics context for drawing

                • +
              +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-859CAA08-59C9-5FD3-98DE-6BDD0D6ED50B.dita --- a/Symbian3/SDK/Source/GUID-859CAA08-59C9-5FD3-98DE-6BDD0D6ED50B.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-859CAA08-59C9-5FD3-98DE-6BDD0D6ED50B.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,150 +1,150 @@ - - - - - -Graphics -Composition -

              Composition is the process of putting together the output elements from -various different sources to create the screen display that the end user sees -on the device.

              -

              Variant: ScreenPlay.

              -

              In a multi-tasking device many of the activities taking place simultaneously -generate output for display on the screen. Their output can include words, -pictures, video, games and the screen furniture (scroll bars, buttons, icons, -borders, tabs, menus, title bars) familiar to every computer user.

              -

              Many of these output elements can appear at the same time, either next -to each other or overlapping each other. They can be opaque, such that they -obscure anything behind, or semi-transparent such that the elements underneath -are partially visible.

              -

              The diagram below illustrates how the display that the viewer sees (looking -down from the top) is a two-dimensional representation composed from a series -of layers.

              - - The display is an orthogonal view of a series of layers. - - - -

              Composition requires:

              -
                -

              • Calculations based on -the size, position, visibility, transparency and ordering of the layers to -determine what will be displayed. This is a logic exercise referred -to as UI Composition.

                • -

              • Handling of image content, -which is a data processing exercise referred to as Image Composition.

                • -
              -

              For this reason the two are handled separately.

              -

              UI Composition

              -

              UI Composition is performed by the Window Server. Each application has -its own window group containing all of its child windows. The Window Server -keeps track of the windows' positions, sizes, visibilities, transparencies -and z-order and is able to establish which windows, and which bits of each -window, are visible. It ensures that each visible bit of window is kept up-to-date -by calling its application when necessary.

              -

              Image composition

              -

              Prior to the introduction of ScreenPlay the Window Server did rudimentary -composition in its main thread and rendered composited output to the screen -buffer using the GDI (Graphics Device Interface). To achieve high frame rates, -applications typically bypassed the Window Server using Direct Screen Access -(DSA) and animation DLLs.

              -

              In ScreenPlay sources -that generate complex graphical output render directly to graphics surfaces. -The Window Server delegates the composition of surfaces to a composition engine -that device creators can adapt to take advantage of graphics processing hardware.

              -

              Although the composition engine runs in the Window Server's process, it -is largely transparent to application developers and works quite differently. -Instead of using windows, it uses surfaces to store pixel data and elements -to manipulate size, position, z-order, visibility and transparency.

              -

              While an element is a simple lightweight object, and easy to manipulate, -a surface stores a large amount of data and its handling requires more consideration.

              -

              The diagram below is a simplistic representation of how applications create -output which is rendered, composited and displayed.

              - - Graphics Composition - - -

              In a device with graphics acceleration hardware (a Graphics Processing -Unit or GPU) there might, in addition to the memory managed by the CPU, be -additional memory managed by the GPU. Image data may therefore be considered -to have been software rendered (onto a surface in CPU memory) or hardware -rendered (onto a surface in hardware accelerated GPU memory). The following -diagram shows applications and other graphical data sources rendering to surfaces -in software and hardware.

              - - Hardware rendered graphics - the wrong way! - - -

              The diagram, however, represents a system with several problem areas that -would render it unsuitable for any practical implementation

              -
                -

              • In practice it is likely -that once data has been rendered to hardware-managed memory it is, to all -intents and purposes, unavailable to software: the CPU is unable to access -it sufficiently quickly. The dotted paths on the diagram above must therefore -be avoided.

                • -

              • Furthermore, GDI rendered -data (the UI) is typically 'stored' as redrawing instructions rather than -bitmapped pixel data—so rendering it to bitmaps before composition is likely -to use a lot of memory unnecessarily.

                • -
              -

              In ScreenPlay, the UI is therefore composed and rendered onto a single -surface before being composited with any other surfaces. This surface is termed -the UI surface and is displayed on a layer placed in front of all of -the others. In fact, the UI surface is created for the Window Server during -system start up and is then passed to the composition components as a 'special -case' surface for composition.

              -
              Combining Window Server and Composition

              The compositing -of surfaces according to their origin means that the physical composition -process behaves differently from the logical composition process that is based -on what the user and the UI are doing. Logically the windows in the UI and -memory rendered surfaces may be on layers that are interleaved yet the memory -rendered surfaces are physically composed behind.

              ScreenPlay addresses -this issue by associating 'external' surfaces with windows in the Window Server -using the RWindowBase::SetBackgroundSurface() method. This -means that the Window Server is able to include them in its logical composition -and make provision for them during data composition. A window with its background -set to a surface in this way becomes transparent in the UI rendered UI surface.

              In -most cases this is not apparent to the viewer. Surfaces that are physically -composed behind the UI appear in the correct position on the two-dimensional -display. The diagram below illustrates how Window Server-rendered UI content -and external surfaces are composited using the UI surface.

              - Hardware composition and the Flattened UI - -

              Although this method of composition is flexible and powerful, it -does have some limitations, particularly with respect to semi-transparent -hardware-accelerated surfaces.

              It is not possible, for example, to -include a semi-transparent surface in front of the UI surface. In such cases -the composition engine determines how the display is composed.

              Here -is a second version of the diagram at the top of the page showing how the -same composition might be achieved in practice. The UI menus, windows and -dialogs are composited by the Window Server onto a single surface. The light -green layer displays a hardware rendered surface so it is actually behind -the layer on which it appears.

              - The UI surface - -
              -
              Composition -Examples

              This illustrations below illustrate the use of hardware -accelerated surfaces and the UI surface

              - Video rendered to a hardware accelerated surface mapped -to a layer behind the UI surface - - - As above with a semi-transparent dialog on the UI surface - - -
              -               -The ScreenPlay -Architecture -Hardware -Acceleration - + + + + + +Graphics +Composition +

              Composition is the process of putting together the output elements from +various different sources to create the screen display that the end user sees +on the device.

              +

              Variant: ScreenPlay.

              +

              In a multi-tasking device many of the activities taking place simultaneously +generate output for display on the screen. Their output can include words, +pictures, video, games and the screen furniture (scroll bars, buttons, icons, +borders, tabs, menus, title bars) familiar to every computer user.

              +

              Many of these output elements can appear at the same time, either next +to each other or overlapping each other. They can be opaque, such that they +obscure anything behind, or semi-transparent such that the elements underneath +are partially visible.

              +

              The diagram below illustrates how the display that the viewer sees (looking +down from the top) is a two-dimensional representation composed from a series +of layers.

              + + The display is an orthogonal view of a series of layers. + + + +

              Composition requires:

              +
                +

              • Calculations based on +the size, position, visibility, transparency and ordering of the layers to +determine what will be displayed. This is a logic exercise referred +to as UI Composition.

                • +

              • Handling of image content, +which is a data processing exercise referred to as Image Composition.

                • +
              +

              For this reason the two are handled separately.

              +

              UI Composition

              +

              UI Composition is performed by the Window Server. Each application has +its own window group containing all of its child windows. The Window Server +keeps track of the windows' positions, sizes, visibilities, transparencies +and z-order and is able to establish which windows, and which bits of each +window, are visible. It ensures that each visible bit of window is kept up-to-date +by calling its application when necessary.

              +

              Image composition

              +

              Prior to the introduction of ScreenPlay the Window Server did rudimentary +composition in its main thread and rendered composited output to the screen +buffer using the GDI (Graphics Device Interface). To achieve high frame rates, +applications typically bypassed the Window Server using Direct Screen Access +(DSA) and animation DLLs.

              +

              In ScreenPlay sources +that generate complex graphical output render directly to graphics surfaces. +The Window Server delegates the composition of surfaces to a composition engine +that device creators can adapt to take advantage of graphics processing hardware.

              +

              Although the composition engine runs in the Window Server's process, it +is largely transparent to application developers and works quite differently. +Instead of using windows, it uses surfaces to store pixel data and elements +to manipulate size, position, z-order, visibility and transparency.

              +

              While an element is a simple lightweight object, and easy to manipulate, +a surface stores a large amount of data and its handling requires more consideration.

              +

              The diagram below is a simplistic representation of how applications create +output which is rendered, composited and displayed.

              + + Graphics Composition + + +

              In a device with graphics acceleration hardware (a Graphics Processing +Unit or GPU) there might, in addition to the memory managed by the CPU, be +additional memory managed by the GPU. Image data may therefore be considered +to have been software rendered (onto a surface in CPU memory) or hardware +rendered (onto a surface in hardware accelerated GPU memory). The following +diagram shows applications and other graphical data sources rendering to surfaces +in software and hardware.

              + + Hardware rendered graphics - the wrong way! + + +

              The diagram, however, represents a system with several problem areas that +would render it unsuitable for any practical implementation

              +
                +

              • In practice it is likely +that once data has been rendered to hardware-managed memory it is, to all +intents and purposes, unavailable to software: the CPU is unable to access +it sufficiently quickly. The dotted paths on the diagram above must therefore +be avoided.

                • +

              • Furthermore, GDI rendered +data (the UI) is typically 'stored' as redrawing instructions rather than +bitmapped pixel data—so rendering it to bitmaps before composition is likely +to use a lot of memory unnecessarily.

                • +
              +

              In ScreenPlay, the UI is therefore composed and rendered onto a single +surface before being composited with any other surfaces. This surface is termed +the UI surface and is displayed on a layer placed in front of all of +the others. In fact, the UI surface is created for the Window Server during +system start up and is then passed to the composition components as a 'special +case' surface for composition.

              +
              Combining Window Server and Composition

              The compositing +of surfaces according to their origin means that the physical composition +process behaves differently from the logical composition process that is based +on what the user and the UI are doing. Logically the windows in the UI and +memory rendered surfaces may be on layers that are interleaved yet the memory +rendered surfaces are physically composed behind.

              ScreenPlay addresses +this issue by associating 'external' surfaces with windows in the Window Server +using the RWindowBase::SetBackgroundSurface() method. This +means that the Window Server is able to include them in its logical composition +and make provision for them during data composition. A window with its background +set to a surface in this way becomes transparent in the UI rendered UI surface.

              In +most cases this is not apparent to the viewer. Surfaces that are physically +composed behind the UI appear in the correct position on the two-dimensional +display. The diagram below illustrates how Window Server-rendered UI content +and external surfaces are composited using the UI surface.

              + Hardware composition and the Flattened UI + +

              Although this method of composition is flexible and powerful, it +does have some limitations, particularly with respect to semi-transparent +hardware-accelerated surfaces.

              It is not possible, for example, to +include a semi-transparent surface in front of the UI surface. In such cases +the composition engine determines how the display is composed.

              Here +is a second version of the diagram at the top of the page showing how the +same composition might be achieved in practice. The UI menus, windows and +dialogs are composited by the Window Server onto a single surface. The light +green layer displays a hardware rendered surface so it is actually behind +the layer on which it appears.

              + The UI surface + +
              +
              Composition +Examples

              This illustrations below illustrate the use of hardware +accelerated surfaces and the UI surface

              + Video rendered to a hardware accelerated surface mapped +to a layer behind the UI surface + + + As above with a semi-transparent dialog on the UI surface + + +
              +               +The ScreenPlay +Architecture +Hardware +Acceleration +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-85CA1089-3F58-5E82-86A4-4674C893B25F.dita --- a/Symbian3/SDK/Source/GUID-85CA1089-3F58-5E82-86A4-4674C893B25F.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-85CA1089-3F58-5E82-86A4-4674C893B25F.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,47 +1,47 @@ - - - - - - Overview -

              The SIP Codec API provides functions to encode and decode SIP headers and -their fields. It converts SIP messages from the UTF-8 ASCII format to the -API implementations internal structure and from the API implementations internal -structure to the UTF-8 ASCII format. This implementation validates the SIP -message syntax according to the SIP BNF definition and supports serialization -and de-serialization of objects belonging to the SIP message structure.

              -

              This implementation is provided in a shared DLL and is run in the context -of the user. It creates class instances in the user heap area which means -the instances cannot be shared between different users.

              -
              Architectural -relationships

              The SIP Codec API does not require any interfaces.

              Capability -information

              There is no capability required when you use the SIP -Codec API. This API is valid for all platforms running Symbian OS version -9.1.

              Extending the API

              SIP Codec API cannot be extended.

              -
              Class structure

              The -logical type of the SIP Codec API is Library API. This interface contains -synchronous functions that do not block, but return immediately and it uses -only local objects.

              The following illustration shows the relationships -of the SIP Codec API classes.

              - Relationships of the SIP Codec classes - Part 1 - - - - Relationships of the SIP Codec classes - Part 2 - - -

              The SIP Codec API defines the functions required to create the SIP -headers of a SIP message. CSIPHeaderBase is the base class for all SIP headers. -A client creates a new instance of the CSIPXHeader class, where “X” is the -name of the header required, and sets the values of the header with the setter -functions of this class.

              -
              Memory used

              The -amount of memory used by every header object of the SIP Codec API is equivalent -to the memory used by the header as text (class + the size of SIP headers).

              + + + + + + Overview +

              The SIP Codec API provides functions to encode and decode SIP headers and +their fields. It converts SIP messages from the UTF-8 ASCII format to the +API implementations internal structure and from the API implementations internal +structure to the UTF-8 ASCII format. This implementation validates the SIP +message syntax according to the SIP BNF definition and supports serialization +and de-serialization of objects belonging to the SIP message structure.

              +

              This implementation is provided in a shared DLL and is run in the context +of the user. It creates class instances in the user heap area which means +the instances cannot be shared between different users.

              +
              Architectural +relationships

              The SIP Codec API does not require any interfaces.

              Capability +information

              There is no capability required when you use the SIP +Codec API. This API is valid for all platforms running Symbian OS version +9.1.

              Extending the API

              SIP Codec API cannot be extended.

              +
              Class structure

              The +logical type of the SIP Codec API is Library API. This interface contains +synchronous functions that do not block, but return immediately and it uses +only local objects.

              The following illustration shows the relationships +of the SIP Codec API classes.

              + Relationships of the SIP Codec classes - Part 1 + + + + Relationships of the SIP Codec classes - Part 2 + + +

              The SIP Codec API defines the functions required to create the SIP +headers of a SIP message. CSIPHeaderBase is the base class for all SIP headers. +A client creates a new instance of the CSIPXHeader class, where “X” is the +name of the header required, and sets the values of the header with the setter +functions of this class.

              +
              Memory used

              The +amount of memory used by every header object of the SIP Codec API is equivalent +to the memory used by the header as text (class + the size of SIP headers).

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-85D006FA-EDCB-4BB4-8FD9-91C658B80DE7.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-85D006FA-EDCB-4BB4-8FD9-91C658B80DE7.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,84 @@ + + + + + +Removed APIsAll the APIs removed from Symbian^3 are listed with changes +required for the existing applications to work on Symbian^3. +

              The following list summarizes the removed APIs:

              + + + + +APIs +Affected headers and libraries +Description + + + + + +CDMA Support +etelcdma.dll, etelcdmautils.dll, and cdmau.dll. +All APIs related to CDMA are removed. Device manufacturers +who want to have Symbian-based CDMA products, must have their own +CDMA implementation. + + +CFontStore::RemoveLinkedFont(), CFontStore::IsValidLinkedFontSpecification(), CBitmapFont::FontWithCharacter(), CBitmapFont::IsLinkedFont(), CBitmapFont::LinkedFontInformation(), CBitmapFont::NextFontClientSpace(), CLinkedFontInformation, CLinkedFontSpecification, CLinkedFontForCache, and COpenFontForCache. +openfont.h and fntstr.dll +All these linked font APIs have been removed. Remove all references +to these APIs and rebuild the applications. + + +Application Engines
                +

              • Word Engine (wngmodel.h, wngmodel.inl, and wngdoor.h)

                • +

              • Sheet Engine (shgapi.h, shgerr.h, shgpanic.h, shgcoord.h, shgtoken.h, shgfmlex.h, shgfmevl.h, and shgfmvwr.h)

                • +

              • Chart Engine (chtstd.h and chtstd.inl)

                • +

              • Text to Word Converter Engine

                • +

              • Data Model Engine

                • +
               +wpeng.dll, sheng.dll, chart.dll, and txtword.dll. +All these application engines are removed. Remove all references +to the relevant APIs and rebuild the applications. +               + +CCHFContentHandler, CCHFDataSupplier, CCHFTopParent, CCHFContentLoader, CCHFProxySessionObject, CCHFSession, CCHFDiscoveryService, CCHFEventMappingService, RAbstractEventArray, MCHFContentLoaderObserver, MCHFDataSupplierObserver, MCHFDiscoveryService, MCHFEventMappingService, and MCHFParent;CFileDataSupplier. +chf.dll, filedatasupplier.dll, and filedatasupplier_shared.dll. +All Content Handling Framework APIs are removed. Remove all +references to these APIs and rebuild the applications. + + +MContactBackupObserver +cntmodel.lib +This API has been removed. Remove implementations of this API +and rebuild applications. + + +CClkDateTimeViewand MClkModelObserver + +These APIs have been removed as they were deprecated in the +earlier platform releases. + + +CVibraControl, TVibraCtrlPanic, MVibraControlObserver, and VibraFactory. +VibraCtrl.DLL +This API has been removed as it was deprecated in earlier platform +release. Use the HWRM Vibra API instead. + + +Calendar Interim Utils API +CalenInterimUtils.h and CalenInterimUtils.lib +This API has been replaced with Calendar Interim Utils2 API +in Symbian^3. So replace all your references to CalenInterimUtils.h and CalenInterimUtils.lib with CalenInterimUtils2.h and CalenInterimUtils2.lib, and build the application +binaries. + + + +
               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-860DCACE-4C5A-508F-B94C-12336E96D1C7-master.png Binary file Symbian3/SDK/Source/GUID-860DCACE-4C5A-508F-B94C-12336E96D1C7-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-860DCACE-4C5A-508F-B94C-12336E96D1C7_d0e383173_href.png Binary file Symbian3/SDK/Source/GUID-860DCACE-4C5A-508F-B94C-12336E96D1C7_d0e383173_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8661A7E0-F19A-41F8-9062-FBFAE70CF658.dita --- a/Symbian3/SDK/Source/GUID-8661A7E0-F19A-41F8-9062-FBFAE70CF658.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-8661A7E0-F19A-41F8-9062-FBFAE70CF658.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,103 +1,105 @@ - - - - - -Tactile -feedback client APIThe Tactile feedback client API is used for producing tactile feedback -for different touch events. -

              The Tactile feedback client API is a library API that has been implemented -with a client-server technique. A major part of the processing is done on -the client side, and thus API calls don't necessarily generate a client-server -transaction immediately. Instead for example, changes to area registry are -buffered, and then transferred to server-side at once.

              -

              You can use tactile feedback in, for example, the following cases:

              -
                -
              • When the user starts to scroll with the scroll bar, user can feel and/or -hear when the scroll bar thumb has been caught.
                • -
              • When button is pressed, user can feel and/or hear the button being pressed.
                • -
              -

              The concept of logical feedback type is very important from this API's -point of view.

              -

              In practice it means that, for example, you should not try to use this -API for producing vibrator feedback only. Instead, logical feedback types -such as "basic" or "sensitive" are used on this level, and the actual physical -effect then depends on the settings and device configuration. This way the -feedback works in a unified way from the end user point of view in the whole -device.

              -

              For user experience -guidelines on tactile feedback, see Tactile -feedback.

              For information on using the API, see Providing -tactile feedback for touch events.

              For the Tactile feedback client -API classes and header files, see Classes and Definitions.

              -
              API class structure

              All -functionality of the Tactile feedback client API is provided in the class MTouchFeedback.

              -
              Constraints

              This -API is valid for all platforms running on Symbian OS v9.4 or later.

              -
              Error handling

              The -leave mechanism of Symbian environment is used to handle memory exhaustion. -The panic mechanism is not used.

              The table below presents possible -error conditions and responses to them.

              -Possible error situations when using Tactile Feedback Client API - - - -Error situation -Response - - - - -SetFeedbackArea returns KErrNoMemory in -case of an OOM situation. -This error can usually be ignored by the application. - - -SetFeedbackArea returns KErrArgument -The given CCoeControl pointer is a NULL pointer -or the control does not have any window associated with it (the feedback area -setting is attempted before SetContainerWindow has been called -on the control). - - -SetFeedbackArea returns KErrNotSupported. -The given logical feedback type or triggering event type is out of -range. - - -A tactile feedback enabled control is moved with CCoeControl::SetPosition, -but the feedback area is not moved. -The control must override the CCoeControl::PositionChanged function, -and update the feedback area there the same way as in the SizeChanged function. - - -Area registry updates not are effective fast enough. This might happen -in some applications which use very many frequently running active objects, -so that the CIdle object used by the implementation of this -API gets no change to run. -Use the FlushRegistryUpdates function for forcing -an update to the server side after doing all updates on the client side. - - -A control's feedback areas are not automatically disabled when the -control is dimmed. -CCoeControl::SetMopParent has not been called on the -control, and thus the object provider hierarchy is broken. - - - -
              -
              Memory overhead

              Using -direct feedback does not cause additional memory overhead.

              Area registry -based feedback consumes approximately 32 bytes for each feedback area.

              -
              Extensions -to the API

              New logical feedback types can be added in later releases. -Otherwise the Tactile feedback client API does not explicitly support any -kinds of extensions to it.

              + + + + + +Tactile +feedback client APIThe Tactile feedback client API is used for producing tactile feedback +for different touch events. +

              The Tactile feedback client API is a library API that has been implemented +with a client-server technique. A major part of the processing is done on +the client side, and thus API calls don't necessarily generate a client-server +transaction immediately. Instead for example, changes to area registry are +buffered, and then transferred to server-side at once.

              +

              You can use tactile feedback in, for example, the following cases:

              +
                +
              • When the user starts to scroll with the scroll bar, user can feel and/or +hear when the scroll bar thumb has been caught.
                • +
              • When button is pressed, user can feel and/or hear the button being pressed.
                • +
              +

              The concept of logical feedback type is very important from this API's +point of view.

              +

              In practice it means that, for example, you should not try to use this +API for producing vibrator feedback only. Instead, logical feedback types +such as "basic" or "sensitive" are used on this level, and the actual physical +effect then depends on the settings and device configuration. This way the +feedback works in a unified way from the end user point of view in the whole +device.

              +

              For user experience +guidelines on tactile feedback, see Tactile +feedback.

              For information on using the API, see Providing +tactile feedback for touch events.

              For the Tactile feedback client +API classes and header files, see Classes and Definitions.

              +
              API class structure

              All +functionality of the Tactile feedback client API is provided in the class MTouchFeedback.

              +
              Changes and release information

              The Tactile feedback +client API is an SDK API and first released in S60 5th Edition.

              +
              Constraints

              This +API is valid for all platforms running on Symbian OS v9.4 or later.

              +
              Error handling

              The +leave mechanism of Symbian environment is used to handle memory exhaustion. +The panic mechanism is not used.

              The table below presents possible +error conditions and responses to them.

              +Possible error situations when using Tactile Feedback Client API + + + +Error situation +Response + + + + +SetFeedbackArea returns KErrNoMemory in +case of an OOM situation. +This error can usually be ignored by the application. + + +SetFeedbackArea returns KErrArgument +The given CCoeControl pointer is a NULL pointer +or the control does not have any window associated with it (the feedback area +setting is attempted before SetContainerWindow has been called +on the control). + + +SetFeedbackArea returns KErrNotSupported. +The given logical feedback type or triggering event type is out of +range. + + +A tactile feedback enabled control is moved with CCoeControl::SetPosition, +but the feedback area is not moved. +The control must override the CCoeControl::PositionChanged function, +and update the feedback area there the same way as in the SizeChanged function. + + +Area registry updates not are effective fast enough. This might happen +in some applications which use very many frequently running active objects, +so that the CIdle object used by the implementation of this +API gets no change to run. +Use the FlushRegistryUpdates function for forcing +an update to the server side after doing all updates on the client side. + + +A control's feedback areas are not automatically disabled when the +control is dimmed. +CCoeControl::SetMopParent has not been called on the +control, and thus the object provider hierarchy is broken. + + + +
              +
              Memory overhead

              Using +direct feedback does not cause additional memory overhead.

              Area registry +based feedback consumes approximately 32 bytes for each feedback area.

              +
              Extensions +to the API

              New logical feedback types can be added in later releases. +Otherwise the Tactile feedback client API does not explicitly support any +kinds of extensions to it.

               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8675AC01-E2D8-425C-899F-12BE99345AA9.dita --- a/Symbian3/SDK/Source/GUID-8675AC01-E2D8-425C-899F-12BE99345AA9.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-8675AC01-E2D8-425C-899F-12BE99345AA9.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,163 +1,163 @@ - - - - - -C++ -and Machine ArchitectureThe C++ language, following its foundation in C, is close to the -machine architecture. This allows applications to be implemented efficiently, -but, especially for developers new to the language, presents some issues of -which you need to be aware. This topic reviews the basic language features -from this perspective, and discusses how the resulting issues are handled. -
              Arithmetic types

              An int is -usually implemented as the natural machine word size of the particular implementation. -This is 32 bits in most modern machines. It was 16 bits in older machines, -and in a few machines it may even be 64 bits.

              Similarly, a pointer -(a void*, for instance) is usually implemented as a machine -word but, in some machines with special architectures, a pointer may be more -complex.

              It is assumed that Symbian is implemented on a machine -with a 32-bit or greater machine word, and 32-bit pointers. The types TInt and TUint are typedefed onto the built-in int and unsigned int types, -and are guaranteed to be at least 32 bits.

              When you need a specific -size, regardless of implementation, use a sized type. Several of these are -available:

              - - - -

              TInt32, TUint32

              -

              32-bit signed and unsigned integer

              In each case, the -representation is a 32-bit machine word which, in the ARM architecture, must -be aligned to a four-byte boundary. The compiler ensures that this is always -the case.

               -               - -

              TInt8, TUint8, TText8

               -

              8-bit signed and unsigned integer, and 8-bit character

              In -each case, the representation is an 8-bit byte, which has no specific alignment -requirements.

              -               - -

              TInt16, TUint16, TText16

              -

              16-bit signed and unsigned integer, and 16-bit character

              In -each case, the representation is a 16-bit halfword, which should be aligned -to a two-byte boundary.

              -               - -

              TInt64, TUint64

              -

              64-bit signed and unsigned integer

              These are typedefed -to appropriate built-in types for the compiler being used (long long, and -unsigned long long for ARM RVCT).

              -               - -

              TReal, TReal64

              -

              Double-precision floating point, IEEE754 64-bit representation - This is the floating-point type recommended for general use.

              You -are recommended to perform operations in integer arithmetic if possible (for -instance, most GUI calculations), and to use floating-point only when the -problem demands it (for instance, a spreadsheet application).

              On -processors that have floating point hardware, the compiler generates host -instructions which use that hardware directly. On processors which don't have -a floating point unit, the compiler implements the calculations in software. -

              -               - -

              TReal32

              -

              32-bit floating point

              This is smaller and quicker, but -should only be used when space and/or time are at a true premium, as its precision -is unsatisfactory for many applications.

              -               - - -
              -
              Compound types

              Apart from classes, C++ inherits -from C various other types of compounding.

              A struct maps an area -of memory:

              struct TEg - { - TInt iInt; // offset 0, 4 bytes - TText8 iText; // offset 4, 1 byte - // 3 wasted bytes - TReal iReal; // offset 8, 8 bytes - } // total length = 16 bytes - -

              Structures are regarded as T types: that is they -may not own heap-allocated resources such as C type classes. -

              An array contains many built-ins or other types

              TInt a[32]; // 32 TInts, = 128 bytes -S b[3]; // 3 Ss, = 48 bytes

              The main disadvantage of using -C++ arrays is that there is no automatic checking of index values. For this -reason, and to support more complex containers, C++ has evolved the Standard -Template Library (STL). Symbian does not use STL, but provides its own range -of efficient container classes, for fixed, dynamic, and associative arrays. -For details, see Dynamic -Arrays.

              -
              Pointers

              A pointer is a memory address. If you can -take the address of an object, then you can refer to it by pointer:

              S* ps; // pointer to an S -ps=&s // take address of existing S -

              A pointer is a 32-bit machine word, and could point to anything.

              - -

              The specifier is placed next to the type rather than the name.

              There -is often a need to refer to memory as anything: for this, a void* pointer -is used in C++. In Symbian, a TAny* may be referred to instead. -A TAny* is a pointer to anything.

              -
              Strings

              In C++, the basic string is an array of -characters:

              char* hello="hello";

              This statement -does two things: firstly, it sets aside six bytes of memory containing the -characters 'h', 'e', 'l', 'l', 'o', '\0'. Secondly, it sets the pointer hello -to contain the address of the first of those bytes.

              - -

              Functions accessing the string rely on this address as its starting -point, and the terminating \0 to indicate its end. Functions -which manipulate the string must either deliberately not extend it, or must -have some cue as to the amount of memory reserved for the string (beyond the -trailing\0) so they know how much it can be extended. This -leads to an awkward programming style, and every C++ library provides a way -to manipulate strings more elegantly. The Symbian platform solution is descriptors: -these are introduced in Descriptors

              -
              Functions

              Functions are a piece of code which can -be called and executed from anywhere else in a program. The stack is used -to pass parameters and to contain local variables. The stack is often augmented -by machine registers, especially in a register-rich processor such as the -ARM, so that memory is often not used. But, conceptually, there is a stack, -and for the purposes of this explanation it is convenient to consider the -stack as if it were implemented entirely in memory.

              Parameters are -passed by copying or evaluating onto the called functions stack frame. It -is bad practice to pass large parameters, such as an entire struct, or, in -fact, anything beyond two machine words in size, because this involves excessive -copying. Instead, a pointer or a reference should be used to pass the address, -instead of the data itself.

              In a multi-tasking system such as Symbian, -each thread has its own stack, which is a pre-allocated area of memory. Each -function then allocates its own frame from the stack on entry, and de-allocates -it on exit. The advantage of the stack mechanism is that allocation and de-allocation -are very rapid indeed— just a couple of instructions. Also, the lifetime of -any variable on the stack is very well defined: it is the lifetime of its -owning function, or, in fact, its owning block, since functions may have blocks -within them.

              When a function returns, its stack memory is still there: -it is just not allocated. The stack memory will be re-used by the next function -that is called. A potential source of error is to allocate an object on a -functions stack frame, and then return a pointer to it:

              TEg* foo() - { - TEg s; - TEg* ps=&s - return ps; // !! error !! - } -

              This pointer will not be valid for long, because the memory -will be re-used when the next function is called. You should never allow this -to happen. This error is so obvious that a compiler will trap it. But it can -occur in more subtle forms:

              foo(CContainer* aContainer) - { - TEg s; - TEg* ps=&s - aContainer->iMember=ps; - } -

              These cannot be trapped so easily.

              -
              Heap

              Each thread also has a heap. You can allocate -and de-allocate objects on the heap at will, and refer to them by pointer. -The benefit of a heap is that the lifetime of an object is entirely within -your control. This power comes with responsibility: you must not forget to -de-allocate objects once you have finished with them, and you must not use -pointers to objects that have been de-allocated.

              + + + + + +C++ +and Machine ArchitectureThe C++ language, following its foundation in C, is close to the +machine architecture. This allows applications to be implemented efficiently, +but, especially for developers new to the language, presents some issues of +which you need to be aware. This topic reviews the basic language features +from this perspective, and discusses how the resulting issues are handled. +
              Arithmetic types

              An int is +usually implemented as the natural machine word size of the particular implementation. +This is 32 bits in most modern machines. It was 16 bits in older machines, +and in a few machines it may even be 64 bits.

              Similarly, a pointer +(a void*, for instance) is usually implemented as a machine +word but, in some machines with special architectures, a pointer may be more +complex.

              It is assumed that Symbian is implemented on a machine +with a 32-bit or greater machine word, and 32-bit pointers. The types TInt and TUint are typedefed onto the built-in int and unsigned int types, +and are guaranteed to be at least 32 bits.

              When you need a specific +size, regardless of implementation, use a sized type. Several of these are +available:

              + + + +

              TInt32, TUint32

              +

              32-bit signed and unsigned integer

              In each case, the +representation is a 32-bit machine word which, in the ARM architecture, must +be aligned to a four-byte boundary. The compiler ensures that this is always +the case.

               +               + +

              TInt8, TUint8, TText8

               +

              8-bit signed and unsigned integer, and 8-bit character

              In +each case, the representation is an 8-bit byte, which has no specific alignment +requirements.

              +               + +

              TInt16, TUint16, TText16

              +

              16-bit signed and unsigned integer, and 16-bit character

              In +each case, the representation is a 16-bit halfword, which should be aligned +to a two-byte boundary.

              +               + +

              TInt64, TUint64

              +

              64-bit signed and unsigned integer

              These are typedefed +to appropriate built-in types for the compiler being used (long long, and +unsigned long long for ARM RVCT).

              +               + +

              TReal, TReal64

              +

              Double-precision floating point, IEEE754 64-bit representation + This is the floating-point type recommended for general use.

              You +are recommended to perform operations in integer arithmetic if possible (for +instance, most GUI calculations), and to use floating-point only when the +problem demands it (for instance, a spreadsheet application).

              On +processors that have floating point hardware, the compiler generates host +instructions which use that hardware directly. On processors which don't have +a floating point unit, the compiler implements the calculations in software. +

              +               + +

              TReal32

              +

              32-bit floating point

              This is smaller and quicker, but +should only be used when space and/or time are at a true premium, as its precision +is unsatisfactory for many applications.

              +               + + +
              +
              Compound types

              Apart from classes, C++ inherits +from C various other types of compounding.

              A struct maps an area +of memory:

              struct TEg + { + TInt iInt; // offset 0, 4 bytes + TText8 iText; // offset 4, 1 byte + // 3 wasted bytes + TReal iReal; // offset 8, 8 bytes + } // total length = 16 bytes + +

              Structures are regarded as T types: that is they +may not own heap-allocated resources such as C type classes. +

              An array contains many built-ins or other types

              TInt a[32]; // 32 TInts, = 128 bytes +S b[3]; // 3 Ss, = 48 bytes

              The main disadvantage of using +C++ arrays is that there is no automatic checking of index values. For this +reason, and to support more complex containers, C++ has evolved the Standard +Template Library (STL). Symbian does not use STL, but provides its own range +of efficient container classes, for fixed, dynamic, and associative arrays. +For details, see Dynamic +Arrays.

              +
              Pointers

              A pointer is a memory address. If you can +take the address of an object, then you can refer to it by pointer:

              S* ps; // pointer to an S +ps=&s // take address of existing S +

              A pointer is a 32-bit machine word, and could point to anything.

              + +

              The specifier is placed next to the type rather than the name.

              There +is often a need to refer to memory as anything: for this, a void* pointer +is used in C++. In Symbian, a TAny* may be referred to instead. +A TAny* is a pointer to anything.

              +
              Strings

              In C++, the basic string is an array of +characters:

              char* hello="hello";

              This statement +does two things: firstly, it sets aside six bytes of memory containing the +characters 'h', 'e', 'l', 'l', 'o', '\0'. Secondly, it sets the pointer hello +to contain the address of the first of those bytes.

              + +

              Functions accessing the string rely on this address as its starting +point, and the terminating \0 to indicate its end. Functions +which manipulate the string must either deliberately not extend it, or must +have some cue as to the amount of memory reserved for the string (beyond the +trailing\0) so they know how much it can be extended. This +leads to an awkward programming style, and every C++ library provides a way +to manipulate strings more elegantly. The Symbian platform solution is descriptors: +these are introduced in Descriptors

              +
              Functions

              Functions are a piece of code which can +be called and executed from anywhere else in a program. The stack is used +to pass parameters and to contain local variables. The stack is often augmented +by machine registers, especially in a register-rich processor such as the +ARM, so that memory is often not used. But, conceptually, there is a stack, +and for the purposes of this explanation it is convenient to consider the +stack as if it were implemented entirely in memory.

              Parameters are +passed by copying or evaluating onto the called functions stack frame. It +is bad practice to pass large parameters, such as an entire struct, or, in +fact, anything beyond two machine words in size, because this involves excessive +copying. Instead, a pointer or a reference should be used to pass the address, +instead of the data itself.

              In a multi-tasking system such as Symbian, +each thread has its own stack, which is a pre-allocated area of memory. Each +function then allocates its own frame from the stack on entry, and de-allocates +it on exit. The advantage of the stack mechanism is that allocation and de-allocation +are very rapid indeed— just a couple of instructions. Also, the lifetime of +any variable on the stack is very well defined: it is the lifetime of its +owning function, or, in fact, its owning block, since functions may have blocks +within them.

              When a function returns, its stack memory is still there: +it is just not allocated. The stack memory will be re-used by the next function +that is called. A potential source of error is to allocate an object on a +functions stack frame, and then return a pointer to it:

              TEg* foo() + { + TEg s; + TEg* ps=&s + return ps; // !! error !! + } +

              This pointer will not be valid for long, because the memory +will be re-used when the next function is called. You should never allow this +to happen. This error is so obvious that a compiler will trap it. But it can +occur in more subtle forms:

              foo(CContainer* aContainer) + { + TEg s; + TEg* ps=&s + aContainer->iMember=ps; + } +

              These cannot be trapped so easily.

              +
              Heap

              Each thread also has a heap. You can allocate +and de-allocate objects on the heap at will, and refer to them by pointer. +The benefit of a heap is that the lifetime of an object is entirely within +your control. This power comes with responsibility: you must not forget to +de-allocate objects once you have finished with them, and you must not use +pointers to objects that have been de-allocated.

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-868C1A38-3CD0-4082-8106-DC3EE1F815D8.dita --- a/Symbian3/SDK/Source/GUID-868C1A38-3CD0-4082-8106-DC3EE1F815D8.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-868C1A38-3CD0-4082-8106-DC3EE1F815D8.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,54 +1,59 @@ - - - - - -System -events -

              System events are enumerated in TApaSystemEvent, -which is defined in the apgtask.h. You must override CCoeAppUI::HandleSystemEventL() to -handle these events, which should be done in the UI controller. The default -implementation is empty. The possible events are as follows:

              -enum TApaSystemEvent - { - EApaSystemEventShutdown = 1, - EApaSystemEventBackupStarting, - EApaSystemEventBackupComplete, - EApaSystemEventBroughtToForeground - }; - -

              The following is a code example of system event handling:

              -void CExampleAppUI::HandleSystemEvent( const TWsEvent& aEvent ) - { - switch( *( TApaSystemEvent* )( aEvent.EventData() ) ) - { - case EApaSystemEventBackupStarting: - { - // Handle backup starting - //... - break; - } - case EApaSystemEventBackupComplete: - { - // Handle backup complete - //... - break; - } - case EApaSystemEventShutdown: - { - // Handle shutdown - //... - break; - } - } - // Call the base class implementation - CAknAppUi::HandleSystemEvent( aEvent ); - } - + + + + + +System +events +

              System events are enumerated in TApaSystemEvent, +which is defined in the apgtask.h. You must override CCoeAppUI::HandleSystemEventL() to +handle these events, which should be done in the UI controller. The default +implementation is empty. The possible events are as follows:

              +enum TApaSystemEvent + { + EApaSystemEventShutdown = 1, + EApaSystemEventBackupStarting, + EApaSystemEventBackupComplete, + EApaSystemEventBroughtToForeground + }; + +

              The following is a code example of system event handling:

              +void CExampleAppUI::HandleSystemEvent( const TWsEvent& aEvent ) + { + switch( *( TApaSystemEvent* )( aEvent.EventData() ) ) + { + case EApaSystemEventBackupStarting: + { + // Handle backup starting + //... + break; + } + case EApaSystemEventBackupComplete: + { + // Handle backup complete + //... + break; + } + case EApaSystemEventShutdown: + { + // Handle shutdown + //... + break; + } + default: + { + break; + } + + } + // Call the base class implementation + CAknAppUi::HandleSystemEvent( aEvent ); + } +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-86AADA3E-B77C-45CC-B523-785B75BAA5AA.dita --- a/Symbian3/SDK/Source/GUID-86AADA3E-B77C-45CC-B523-785B75BAA5AA.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-86AADA3E-B77C-45CC-B523-785B75BAA5AA.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,41 +1,41 @@ - - - - - -Menu -

              Mobile device users can use the Menu to access applications. Pressing the -Home / Menu key opens the Menu, where the user may browse and select an application. -The Menu was previously called Application Shell and the Home / Menu -key was called Applications key. In addition to direct access to applications, -related applications can be collected in folders.

              -

              Applications are presented as a grid of items by default. User can select -a customized version of the Menu layout, such as a list. The recommended grid -layout is 3 x 4 (portrait) or 4 x 3 (landscape), that is 12 icons. Pressing -the Selection key opens an application and closes the Menu.

              - -Menu with a 3 x 4 grid in portrait (left) and 4 x 3 grid in landscape -(right) - - -

              For more details on the landscape orientation, see Symbian -UI with rotation.

              -
              ShortcutsWhen -the Menu is opened, numeric keys 1-9 can be used as shortcuts to select an -application. The keys are mapped directly to the nine icons in Menu’s initial -view, so that the Numeric key 1 corresponds to the top-left application and -the Numeric key 9 to the bottom-right one.
              -
              Customizing -Menu

              The user can organize the order of applications, create folders -and move applications into folders within the Menu. The folders created in -a Menu are customizable (the user can add and remove folders) and can have -unlimited sub-folders to allow a hierarchically organized structures. The -customizing functions are available in the Options menu. -In addition, the layout of the Menu can also be customized.

              + + + + + +Menu +

              Mobile device users can use the Menu to access applications. Pressing the +Home / Menu key opens the Menu, where the user may browse and select an application. +The Menu was previously called Application Shell and the Home / Menu +key was called Applications key. In addition to direct access to applications, +related applications can be collected in folders.

              +

              Applications are presented as a grid of items by default. User can select +a customized version of the Menu layout, such as a list. The default grid +layout is 3 x 4 (portrait) or 4 x 3 (landscape), that is 12 icons. Pressing +the Selection key opens an application and closes the Menu.

              + +Menu with a 3 x 4 grid in portrait (left) and 4 x 3 grid in landscape +(right) + + +

              For more details on the landscape orientation, see Symbian +UI with rotation.

              +
              ShortcutsWhen +the Menu is opened, numeric keys 1-9 can be used as shortcuts to select an +application. The keys are mapped directly to the nine icons in Menu’s initial +view, so that the Numeric key 1 corresponds to the top-left application and +the Numeric key 9 to the bottom-right one.
              +
              Customizing +Menu

              The user can organize the order of applications, create folders +and move applications into folders within the Menu. The folders created in +a Menu are customizable (the user can add and remove folders) and can have +unlimited sub-folders to allow a hierarchically organized structures. The +customizing functions are available in the Options menu. In addition, +the layout of the Menu can also be customized.

               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-873186CE-9723-558F-9C7E-0CEE607F076C_d0e429248_href.png Binary file Symbian3/SDK/Source/GUID-873186CE-9723-558F-9C7E-0CEE607F076C_d0e429248_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-873186CE-9723-558F-9C7E-0CEE607F076C_d0e429410_href.png Binary file Symbian3/SDK/Source/GUID-873186CE-9723-558F-9C7E-0CEE607F076C_d0e429410_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-875D74D3-5663-42E3-A4B9-294F82FF5486.dita --- a/Symbian3/SDK/Source/GUID-875D74D3-5663-42E3-A4B9-294F82FF5486.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-875D74D3-5663-42E3-A4B9-294F82FF5486.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,70 +1,82 @@ - - - - - -Confirmation -note -

              Confirmation notes inform the user about a successfully completed operation. -They have a short duration and a subtle tone (they should not be used after -every kind of successful action).

              - -Confirmation note - - -
              Guidelines -for using confirmation notes

              Use a confirmation note when:

                -

              • The effect of the operation cannot be seen directly by some -other means. For example, Message sent.

                • -

              • There is some relevant information to be communicated by it. -For example, Last call duration.

                • -

              Confirmation notes should not be used after every completed operation, -as this would easily start to annoy users. Confirmation notes should not be -used when:

                -

              • There is already another dialogue in the procedure, for example Do -you want to remove this message? Y/N.

                • -

              • A progress indication is visible during the procedure.

                -
                • -

              • The user can see the result of the operation when it is performed. -For example, when adding or removing objects in a list.

                • -

              • A setting has been changed. The new value of the setting is -visible in the setting item.

                • -

              • The operation can be considered minor or so frequent that -a note would be annoying. For example, Copy-Paste actions.

                • -
              -
              Using -confirmation notes in C++ applications

              You can create either a basic -confirmation note that is displayed only when your application is in the foreground -or a global note that stays displayed even if the application launching the -note is not in the foreground. The related APIs are the Notes -API (for basic notes) and the Notifiers API (for global notes).

              To use a confirmation -note with the default icon, text, sound, and duration, create an instance -of the note class CAknConfirmationNote. For implementation information, see Creating a waiting confirmation (basic) note.

              To -create a global confirmation note, use the class CAknGlobalNote in the Notes API. For implementation information, see Using global notes and Using global notes with user interaction.

              For -basic notes, you can change the icon or text displayed in the note, use a -different kind of sound, or change the note duration using the setter methods -in the class CAknNoteDialog: SetIconL(), SetTextL(), SetTone(), and SetTimeout().

              For information on customizing global notes, see Enhancing global notes. You can change the graphic, animation, -tone, and softkeys using the methods in the class CAknGlobalNote: SetGraphic(), SetAnimation(), SetTone(), and SetSoftkeys().

              - - - -               -Information -note -Warning note - -Error note - -Permanent -note -Wait note - -Progress -note + + + + + +Confirmation +note +

              Confirmation notes inform the user about a successfully completed operation. +They have a short duration and a subtle tone (they should not be used after +every kind of successful action).

              + +Confirmation note + + +
              Guidelines +for using confirmation notes

              Use a confirmation note when:

                +

              • The effect of the operation cannot be seen directly by some +other means. For example, Message sent.

                • +

              • There is some relevant information to be communicated by it. +For example, Last call duration.

                • +

              Confirmation notes should not be used after every completed operation, +as this would easily start to annoy users. Confirmation notes should not be +used when:

                +

              • There is already another dialogue in the procedure, for example Do +you want to remove this message? Y/N.

                • +

              • A progress indication is visible during the procedure.

                +
                • +

              • The user can see the result of the operation when it is performed. +For example, when adding or removing objects in a list.

                • +

              • A setting has been changed. The new value of the setting is +visible in the setting item.

                • +

              • The operation can be considered minor or so frequent that +a note would be annoying. For example, Copy-Paste actions.

                • +
              +
              Using +confirmation notes in applications

              You can create either a basic +confirmation note that is displayed only when your application is in the foreground +or a global note that stays displayed even if the application launching the +note is not in the foreground. The related APIs are the Notes +API (for basic notes) and the Notifiers API (for global notes).

              To use a confirmation +note with the default icon, text, sound, and duration, create an instance +of the note class CAknConfirmationNote. For implementation +information, see Creating a waiting confirmation (basic) note.

              To +create a global confirmation note, use the class CAknGlobalNote in +the Notes API. For implementation information, see Using global notes and Using global notes with user interaction.

              For basic +notes, you can change the icon or text displayed in the note, use a different +kind of sound, or change the note duration using the setter methods in the +class CAknNoteDialog:

                +

              • CAknNoteDialog::SetIconL()

                • +

              • CAknNoteDialog::SetTextL()

                • +

              • CAknNoteDialog::SetTone()

                • +

              • CAknNoteDialog::SetTimeout()

                • +

              For information on customizing global notes, see Enhancing global notes. You can change the graphic, animation, +tone, and softkeys using the methods in the class CAknGlobalNote:

                +

              • CAknGlobalNote::SetGraphic()

                • +

              • CAknGlobalNote::SetAnimation()

                • +

              • CAknGlobalNote::SetTone()

                • +

              • CAknGlobalNote::SetSoftkeys()

                • +

              + + + +               +Information +note +Warning note + +Error note + +Permanent +note +Wait note + +Progress +note               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8761F82E-5DC4-5BD5-A422-2EC45A92925B_d0e383456_href.png Binary file Symbian3/SDK/Source/GUID-8761F82E-5DC4-5BD5-A422-2EC45A92925B_d0e383456_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8761F82E-5DC4-5BD5-A422-2EC45A92925B_d0e388502_href.png Binary file Symbian3/SDK/Source/GUID-8761F82E-5DC4-5BD5-A422-2EC45A92925B_d0e388502_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-87BEA6F9-B236-50CF-9DB3-36234A6EB797.dita --- a/Symbian3/SDK/Source/GUID-87BEA6F9-B236-50CF-9DB3-36234A6EB797.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,13 +0,0 @@ - - - - - -System GUI -Framework example codeThis describes the example code for the System GUI Framework module. \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-87DB3E71-AAE1-57B6-BC79-CBAF8382614A-GENID-1-8-1-3-1-1-7-1-4-1.dita --- a/Symbian3/SDK/Source/GUID-87DB3E71-AAE1-57B6-BC79-CBAF8382614A-GENID-1-8-1-3-1-1-7-1-4-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,12 +0,0 @@ - - - - - -Multiple Screens Overview
              Purpose

              Multiple screens allow an application to be displayed on more than one screen simultaneously, and also to react to a change in the active screen whilst the application is running. Prior to the implementation of this feature, applications could only display on one screen during its lifetime.

              When an application creates a view it will be allowed to specify which screen that view will be displayed on. The view will be fixed to that screen, but the application can then create another view on a different screen. If the characteristics (for example, size or colour depth) of the screens are similar, the view on the second screen could just be a second instance of the original view.

              Some typical uses for taking advantage of multiple screens could be:

              • A clamshell device with a screen on the inside and one on the outside. The user is working on an application on one screen. The device is opened or closed and the application switches itself to the other screen.

              • A clamshell device with two screens one on each side of the inside. An application shows part of its data on each screen.

              • A phone application which displays itself on all screens when the user is not using them for other purposes.

              Architectural Relationships

              Component Changes

              The CONE component (which provides the control environment) has been extended to support multiple screens.iCoeEnv->ScreenDevice( screennumber ) will return a pointer to the requested screen.

              WSERV has also been extended to support multiple screens. Specifically, RWindowGroup::ConstructL() has been overloaded so that a screen device that is associated with a screen can be passed as a parameter during the construction of a window group.

              Description

              Finding out information about a screen

              The class RWsSession can be used to query WSERV about the window groups on a particular screen and the number of screens on the device.

              The class CWsScreenDevice can be used to query the physical characteristics of the screen, and set the parameters of the corresponding logical screen associated with it.

              The class RWindowGroup is the client side handle to the server side window group.

              Both CWsScreenDevice and RWindowGroup are needed as a pair to draw on a screen.

              The Cone component maintains the array of screen devices and window group pairs through its RWsSession::WsSession() method. The screen number is used to index this array in order to retrieve a particular window group and its corresponding screen device. This array can be queried in order to find out information such as:

              • the window group with the current keyboard focus

              • the window group with focus on a particular screen

              • the maximum colour and display mode on a particular screen

              • the list of colour modes for a particular screen

              Creating a control on a particular screen

              A control is associated with a window and a particular window group. A window group is associated with a screen device, which in turn is associated with a screen. To create a control on a particular screen, retrieve an appropriate window group on that screen and use it as the parameter in the control’s ConstructL(). The window for that control will then be created on that screen

              Graphics Context

              The class CWindowGc provides the interface for the application’s window graphics context and can be activated on any window in the application. This means that it can be used on any screen on the phone

              Window Group Focus Policy

              There are two focus policies supported by WSERV. The default focus policy is that it is only the focused window group on the focused screen that receives focus gained and focus lost events. The new policy is that any window group can receive focus gained and lost events and can be switched on by defining the keyword MULTIFOCUSPOLICY in the wsini.ini file.

              Limitations

              Pointer Events

              The first screen created is also the primary screen in the system. It is important to note that only the primary screen can respond to pointer events. This is due to the fact that the kernel supports only one screen digitiser.

              For information about further limitations specifically related to the legacy nature of Cone, please see How To Multiple Screens.

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-87DB3E71-AAE1-57B6-BC79-CBAF8382614A-GENID-1-8-1-6-1-1-4-1-6-1-4-1.dita --- a/Symbian3/SDK/Source/GUID-87DB3E71-AAE1-57B6-BC79-CBAF8382614A-GENID-1-8-1-6-1-1-4-1-6-1-4-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,12 +0,0 @@ - - - - - -Multiple Screens Overview
              Purpose

              Multiple screens allow an application to be displayed on more than one screen simultaneously, and also to react to a change in the active screen whilst the application is running. Prior to the implementation of this feature, applications could only display on one screen during its lifetime.

              When an application creates a view it will be allowed to specify which screen that view will be displayed on. The view will be fixed to that screen, but the application can then create another view on a different screen. If the characteristics (for example, size or colour depth) of the screens are similar, the view on the second screen could just be a second instance of the original view.

              Some typical uses for taking advantage of multiple screens could be:

              • A clamshell device with a screen on the inside and one on the outside. The user is working on an application on one screen. The device is opened or closed and the application switches itself to the other screen.

              • A clamshell device with two screens one on each side of the inside. An application shows part of its data on each screen.

              • A phone application which displays itself on all screens when the user is not using them for other purposes.

              Architectural Relationships

              Component Changes

              The CONE component (which provides the control environment) has been extended to support multiple screens.iCoeEnv->ScreenDevice( screennumber ) will return a pointer to the requested screen.

              WSERV has also been extended to support multiple screens. Specifically, RWindowGroup::ConstructL() has been overloaded so that a screen device that is associated with a screen can be passed as a parameter during the construction of a window group.

              Description

              Finding out information about a screen

              The class RWsSession can be used to query WSERV about the window groups on a particular screen and the number of screens on the device.

              The class CWsScreenDevice can be used to query the physical characteristics of the screen, and set the parameters of the corresponding logical screen associated with it.

              The class RWindowGroup is the client side handle to the server side window group.

              Both CWsScreenDevice and RWindowGroup are needed as a pair to draw on a screen.

              The Cone component maintains the array of screen devices and window group pairs through its RWsSession::WsSession() method. The screen number is used to index this array in order to retrieve a particular window group and its corresponding screen device. This array can be queried in order to find out information such as:

              • the window group with the current keyboard focus

              • the window group with focus on a particular screen

              • the maximum colour and display mode on a particular screen

              • the list of colour modes for a particular screen

              Creating a control on a particular screen

              A control is associated with a window and a particular window group. A window group is associated with a screen device, which in turn is associated with a screen. To create a control on a particular screen, retrieve an appropriate window group on that screen and use it as the parameter in the control’s ConstructL(). The window for that control will then be created on that screen

              Graphics Context

              The class CWindowGc provides the interface for the application’s window graphics context and can be activated on any window in the application. This means that it can be used on any screen on the phone

              Window Group Focus Policy

              There are two focus policies supported by WSERV. The default focus policy is that it is only the focused window group on the focused screen that receives focus gained and focus lost events. The new policy is that any window group can receive focus gained and lost events and can be switched on by defining the keyword MULTIFOCUSPOLICY in the wsini.ini file.

              Limitations

              Pointer Events

              The first screen created is also the primary screen in the system. It is important to note that only the primary screen can respond to pointer events. This is due to the fact that the kernel supports only one screen digitiser.

              For information about further limitations specifically related to the legacy nature of Cone, please see How To Multiple Screens.

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-87DB3E71-AAE1-57B6-BC79-CBAF8382614A.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-87DB3E71-AAE1-57B6-BC79-CBAF8382614A.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,12 @@ + + + + + +Multiple Screens Overview
              Purpose

              Multiple screens allow an application to be displayed on more than one screen simultaneously, and also to react to a change in the active screen whilst the application is running. Prior to the implementation of this feature, applications could only display on one screen during its lifetime.

              When an application creates a view it will be allowed to specify which screen that view will be displayed on. The view will be fixed to that screen, but the application can then create another view on a different screen. If the characteristics (for example, size or colour depth) of the screens are similar, the view on the second screen could just be a second instance of the original view.

              Some typical uses for taking advantage of multiple screens could be:

              • A clamshell device with a screen on the inside and one on the outside. The user is working on an application on one screen. The device is opened or closed and the application switches itself to the other screen.

              • A clamshell device with two screens one on each side of the inside. An application shows part of its data on each screen.

              • A phone application which displays itself on all screens when the user is not using them for other purposes.

              Architectural Relationships

              Component Changes

              The CONE component (which provides the control environment) has been extended to support multiple screens.iCoeEnv->ScreenDevice( screennumber ) will return a pointer to the requested screen.

              WSERV has also been extended to support multiple screens. Specifically, RWindowGroup::ConstructL() has been overloaded so that a screen device that is associated with a screen can be passed as a parameter during the construction of a window group.

              Description

              Finding out information about a screen

              The class RWsSession can be used to query WSERV about the window groups on a particular screen and the number of screens on the device.

              The class CWsScreenDevice can be used to query the physical characteristics of the screen, and set the parameters of the corresponding logical screen associated with it.

              The class RWindowGroup is the client side handle to the server side window group.

              Both CWsScreenDevice and RWindowGroup are needed as a pair to draw on a screen.

              The Cone component maintains the array of screen devices and window group pairs through its RWsSession::WsSession() method. The screen number is used to index this array in order to retrieve a particular window group and its corresponding screen device. This array can be queried in order to find out information such as:

              • the window group with the current keyboard focus

              • the window group with focus on a particular screen

              • the maximum colour and display mode on a particular screen

              • the list of colour modes for a particular screen

              Creating a control on a particular screen

              A control is associated with a window and a particular window group. A window group is associated with a screen device, which in turn is associated with a screen. To create a control on a particular screen, retrieve an appropriate window group on that screen and use it as the parameter in the control’s ConstructL(). The window for that control will then be created on that screen

              Graphics Context

              The class CWindowGc provides the interface for the application’s window graphics context and can be activated on any window in the application. This means that it can be used on any screen on the phone

              Window Group Focus Policy

              There are two focus policies supported by WSERV. The default focus policy is that it is only the focused window group on the focused screen that receives focus gained and focus lost events. The new policy is that any window group can receive focus gained and lost events and can be switched on by defining the keyword MULTIFOCUSPOLICY in the wsini.ini file.

              Limitations

              Pointer Events

              The first screen created is also the primary screen in the system. It is important to note that only the primary screen can respond to pointer events. This is due to the fact that the kernel supports only one screen digitiser.

              For information about further limitations specifically related to the legacy nature of Cone, please see How To Multiple Screens.

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-881C353C-6482-4DFE-9D43-CFB80DEB77A5_d0e4619_href.png Binary file Symbian3/SDK/Source/GUID-881C353C-6482-4DFE-9D43-CFB80DEB77A5_d0e4619_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-881C353C-6482-4DFE-9D43-CFB80DEB77A5_d0e5894_href.png Binary file Symbian3/SDK/Source/GUID-881C353C-6482-4DFE-9D43-CFB80DEB77A5_d0e5894_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8862E271-ABA4-5A25-8990-C0B3931E370D_d0e406639_href.png Binary file Symbian3/SDK/Source/GUID-8862E271-ABA4-5A25-8990-C0B3931E370D_d0e406639_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8862E271-ABA4-5A25-8990-C0B3931E370D_d0e406801_href.png Binary file Symbian3/SDK/Source/GUID-8862E271-ABA4-5A25-8990-C0B3931E370D_d0e406801_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-89185EBD-223F-5F52-B1CA-9F9692F7D21F_d0e190349_href.png Binary file Symbian3/SDK/Source/GUID-89185EBD-223F-5F52-B1CA-9F9692F7D21F_d0e190349_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-89185EBD-223F-5F52-B1CA-9F9692F7D21F_d0e195357_href.png Binary file Symbian3/SDK/Source/GUID-89185EBD-223F-5F52-B1CA-9F9692F7D21F_d0e195357_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-894AB487-C127-532D-852B-37CB0DEA1440.dita --- a/Symbian3/SDK/Source/GUID-894AB487-C127-532D-852B-37CB0DEA1440.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-894AB487-C127-532D-852B-37CB0DEA1440.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,101 +1,166 @@ - - - - - -Symbian-Specific -BehaviorThis topic provides information about the points that the EGL specification -explicitly states are platform-specific. This information is aimed at both -users and implementers of EGL on the Symbian platform. -
              Symbian windows

              EGL -window surfaces are tied to Symbian windows. To create an on-screen rendering -surface, a Window Server window with attributes corresponding to the desired EGLConfig must -be created first. The RWindow class is a handle to a server-side -window that can be displayed and drawn to, and whose redraws are performed -by the application.

              Threading. Because of the limitations of -the Window Server API, clients must create and use an EGL window surface -in the thread in which its RWindow was created. This means -that the following are not supported and will lead to undefined behavior:

                -

              • Creating an EGL window surface in thread B using an RWindow that -was created in thread A.

                • -

              • Using an EGL window surface in thread B when that EGL window -surface and its RWindow were created in thread A.

                • -

              For example, in the second scenario, EGL in thread B may fail -when it attempts to get the window size from the RWindow in -thread A.

              Buffer handling. EGL window surfaces have two -buffers, known as the front and back buffers. This means that the client application -can draw to the back buffer, while the front buffer is being composed to the -screen. The client must call eglSwapBuffers() to post the -back buffer to the screen.

              EGL 1.4 introduces a preserve buffer feature. -When this is supported by the implementation, the content of the buffer can -be preserved from one frame to the next. This means that the client can provide -incremental drawing operations rather than the entire drawing operations for -each frame. When the implementation supports this feature, it is usually off -by default. This means that legacy applications that do not expect -this feature are not slowed down by the unnecessary copying of the buffer -contents.

              Window resizing. A window can be resized using one -of the Window Server or UI Framework APIs, such as RWindow::SetExtent() or CCoeControl::SetExtent(). -When these APIs are called on a window that is bound to an EGL window surface, -the EGL implementation is expected to handle the situation by adjusting its -internal buffers. Applications need not do anything specific with regard to -EGL APIs. Depending on the type of application, APIs may want to adjust their -rendering operations—for example, clip or scale the contents.

              EGL -handles the resize in the next call to eglSwapBuffers() by -creating a new surface for the resized window. If the preserve buffer option -is in use, this function also copies across all the pixels from the old surface -that overlap the new surface, although the exact details depend on the implementation. -A client application may therefore need to provide extra drawing operations, -for example, if the window is made larger.

              Screen rotation. -There is no specific EGL handling for screen rotation—instead screen rotation -is handled in the same way as a change of screen resolution. Applications -can detect screen rotation by listening to the Window Server event EEventScreenDeviceChanged. -However, applications do not normally use the Window Server API directly, -because they are built on top of the UI Framework layer. This layer provides -a different mechanism to notify applications using—for example, CCoeAppUi::HandleScreenDeviceChangedL().

              When -one of the these events is detected, the application may need to resize its -windows and update its content accordingly. If the application wants to accept -the system rotation, it does not need to rotate its content. However, some -applications may want to maintain a fixed physical orientation. They would -then need to rotate the window content in order to counteract the physical -rotation.

              -
              Symbian pixmap -types

              An EGL implementation can support the CFbsBitmap pointer -as an EGLNativePixmapType. This means that it is possible -to create an EGLSurface to render to a CFbsBitmap.

              CFbsBitmap bitmaps -are managed by the Font -and Bitmap Server. The format is internal to Symbian, but the Image -Converter API can be used to convert them to standard formats. The CFbsBitmap type -has limitations with regard to hardware acceleration.

              -
              Display handling

              Most -EGL calls include an EGLDisplay parameter. The EGL specification -describes this as "the abstract display on which graphics are drawn". On some -systems, this corresponds to a physical screen. However, the details are platform -specific and on Symbian systems, it does not correspond to a physical -screen. When working on the Symbian platform, it is generally more useful -to think of an EGLDisplay as the EGL session.

              On -Symbian systems, you usually use a single EGLDisplay. You -get this by a call to eglGetDisplay() and passing EGL_DEFAULT_DISPLAY as -the <display id> parameter.

              The physical screen -on which the content is displayed is determined by the window's parent window -group. In Symbian, every window (RWindow) has a parent -window group (RWindowGroup), as shown in the following -diagram. When you create a window group, you can specify the screen on which -it is to be shown.

              -Each window has a parent window group which is associated with a screen - -

              When you create a window surface in EGL using eglCreateWindowSurface, -you pass in the RWindow as an argument. The window surface -is then displayed on the screen associated with that window's parent window -group. Currently a window can exist on only one screen.

              -               -EGL Interface -Component -EGL Collection -Overview + + + + + +Symbian-Specific BehaviorThis topic provides information about the points that the +EGL specification explicitly states are platform-specific. This information +is aimed at both users and implementers of EGL on the Symbian platform. +
              ScreenPlay +(NGA)

              Applications can find out whether ScreenPlay (also +known as the New Graphics Architecture or NGA) is supported on the +device at runtime.

              To do this, call eglQueryString(display, +EGL_EXTENSIONS) and search for the string EGL_SYMBIAN_COMPOSITION within the string returned. If EGL_SYMBIAN_COMPOSITION is present, it means that ScreenPlay is supported. For further information, +see EGL Functions +with Symbian-Specific Behavior.

              By checking for the presence +of the EGL_SYMBIAN_COMPOSITION string, you can create +applications that can work on both ScreenPlay devices and those with +the non-ScreenPlay architecture.

              +
              Symbian +windows

              EGL window surfaces are on-screen rendering surfaces +that are tied to Symbian windows. The RWindow class +is a client-side handle to a Symbian Window Server window. You must +create the RWindow before creating the EGL window +surface for on-screen rendering.

              Because the EGL window surface +is implemented differently depending on whether ScreenPlay is in use, +there are some differences in how you create an EGL window surface:

                +

              • In ScreenPlay, the pixel format of the EGL window surface is +determined entirely by the EGL config passed to eglCreateWindowSurface() and not by the properties of the RWindow.

                • +

              • On a non-ScreenPlay device, the display mode of the RWindow must match the buffer size of the EGL window surface. +You can call RWindowBase::DisplayMode() const to +retrieve the window’s display mode and use it to determine the buffer +size when retrieving the EGL config to pass to eglCreateWindowSurface().

                • +

              Threading. Because of the limitations of the Window +Server API, clients must create and use an EGL window surface +in the thread in which its RWindow was created. This +means that the following are not supported and will lead to +undefined behavior:

                +

              • Creating an EGL window surface in thread B using an RWindow that was created in thread A.

                • +

              • Using an EGL window surface in thread B when that EGL +window surface and its RWindow were created in thread A.

                • +

              For example, in the second scenario, EGL in thread B will fail (with a WSERV panic) when it attempts to get the window +size from the RWindow in thread A.

              Buffer handling. By default EGL window surfaces have multiple +buffers, which means that the client can draw to a back buffer, while +the front buffer is being composed to the screen. The client must +call eglSwapBuffers() to post the back buffer to +the screen.

              EGL 1.4 introduces a preserve buffer feature, which +enables the content of the front buffer to be preserved from one frame +to the next. This means that the client can provide incremental drawing +operations rather than the entire drawing operations for each frame. +This feature is usually off by default. This means that legacy applications +that do not expect this feature are not slowed down by the unnecessary +copying of the buffer contents.

              Window resizing. The +size of an application’s view can be changed by a variety of external +events, such as a UI layout switch, a change in the size of the status +pane or the rotation of the screen. An application can also resize +a window directly, such as through a call to RWindow::SetExtent(), CCoeControl::SetExtent() or CCoeControl::SetExtentToWholeScreen().

              When there is a change in the size of a window that is bound +to an EGL window surface, the application must take appropriate action +in its CCoeControl::SizeChanged() or CCoeControl::HandleResourceChange() implementation. The action depends on the nature of the application +but might include clipping or scaling the contents to fit the resized +window.

              On the Symbian platform, EGL handles the window resize +in the next call to eglSwapBuffers(), which resizes +the surface to match the new window size. If the preserve buffer option +is in use, this function also copies across all the pixels from the +old surface that overlap the new surface, although the exact details +depend on the implementation.

              If the surface resize fails, eglSwapBuffers() returns EGL_FALSE and +an EGL_BAD_ALLOC error is raised. This may mean that +the implementation does not support the resizing of a surface or that +there is not enough memory available (on a platform with GPU, this +would be GPU rather than system memory). Applications must always +monitor whether eglSwapBuffers() fails after a +window resize. When it does fail, the application should do the following:

                +

              1. Call eglDestroySurface() to destroy the current EGL window surface.

                2. +

              2. Call eglCreateWindowSurface() to recreate the EGL window surface.

                3. +

              This may cause a noticeable flicker and so should be done +only when necessary.

              Screen rotation. There is no specific +EGL handling for screen rotation—instead screen rotation is handled +in the same way as a change of screen resolution. An application typically +handles changes in screen resolution and rotation in its CCoeAppUi::HandleScreenDeviceChangedL() or CCoeControl::HandleResourceChange(TInt) implementation. When there is a change in screen rotation, the application +may need to resize its windows and update the content accordingly.

              The EGL implementation updates the surface size on the next call +to eglSwapBuffers(). However, the interim frames +appear in the new orientation, and so an application may want to adjust +the contents to minimize flicker. If the application wants to accept +the system rotation, it does not need to rotate its content. However, +some applications may require a fixed physical orientation. These +need to rotate the window content in order to counteract the physical +rotation.

              Sometimes a screen rotation simply results in the +swapping of the window’s width and height dimensions—for example, +when the application is running in full screen mode and the device +is rotated from portrait to landscape or vice versa. This is guaranteed +to succeed on all Symbian EGL implementations.

              In other situations +the screen rotation must be treated like a window resize and the application +must monitor whether eglSwapBuffers() succeeds and +take appropriate action if it fails, as described above. For example, +if the application is not in full screen mode, rotating the device +from portrait to landscape may not result in the swapping of the width +and height of the window.

              UI content. Applications that +want to make use of the ScreenPlay ability to place semi-transparent CWindowGc rendering above the EGL window surface should +check whether ScreenPlay is supported on the device as described above.

              On ScreenPlay devices, you can combine CWindowGc drawing and OpenVG/OpenGL ES drawing in the same window, provided +the CWindowGc content is drawn using a semi-transparent +pen or brush color or bitmap. It is also possible to create semi-transparent CWindowGc drawing in another Symbian window placed over +the EGL window. To do this, make the Symbian window semi-transparent +by calling RWindow::SetTransparencyAlphaChannel(). Transparent +Windows has more detail on implementing semi-transparent windows.

              On non-ScreenPlay devices, you need to place the CWindowGc drawing in an opaque child window over the EGL window surface or +implement the UI by using OpenVG/OpenGL ES drawing that is directed +to the EGL window surface itself.

              Window lifetime. Clients +must maintain the RWindow associated with the EGL +window surface for the lifetime of that window surface, provided they +follow the good practice guidelines of unbinding the EGL window surface +from the current context before destroying it. If these guidelines +are not followed, it may be necessary to maintain the RWindow for the entire duration of EGL usage within the client application.

              For example, the following pseudocode demonstrates good practice. +The RWindow must be valid until eglDestroySurface() is called:

              // Unbind the window surface from the current context. +eglMakeCurrent(display, EGL_NO_SURFACE, EGL_NO_SURFACE, EGL_NO_CONTEXT); + +// Destroy the window surface. +eglDestroySurface(display, surface); + +... + +eglTerminate(display)

              When the application does not +follow this good practice and destroys the surface before unbinding +it from the current context, the RWindow must be +valid for longer. For example in the following pseudocode, RWindow must be valid until after eglMakeCurrent() is called:

              eglDestroySurface(display, surface); +eglMakeCurrent(display, EGL_NO_SURFACE, EGL_NO_SURFACE, EGL_NO_CONTEXT); + +... + +eglTerminate(display)

              If eglMakeCurrent() is not called with a null surface and null context at all, the RWindow must be valid until eglTerminate() is called.

              +
              Symbian +pixmap types

              An EGL implementation can support the CFbsBitmap pointer as an EGLNativePixmapType. This means that it is possible to create an EGLSurface to render to a CFbsBitmap. However, it is not +guaranteed to be supported on all EGL implementations.

              +
              Display +handling

              Most EGL calls include an EGLDisplay parameter. The EGL specification describes this as "the abstract +display on which graphics are drawn". On some systems, this corresponds +to a physical screen. However, the details are platform specific and +on Symbian systems, it does not correspond to a physical screen. +When working on the Symbian platform, it is generally more useful +to think of an EGLDisplay as the EGL session.

              On Symbian systems, you usually use a single EGLDisplay. You get this by a call to eglGetDisplay() and +passing EGL_DEFAULT_DISPLAY as the <display +id> parameter.

              The physical screen on which the content +is displayed is determined by the window's parent window group. In +Symbian, every window (RWindow) has a parent window +group (RWindowGroup), as shown in the following +diagram. When you create a window group, you can specify the screen +on which it is to be shown.

              +Each window has a parent window group which is associated with +a screen + +

              When you create a window surface in EGL using eglCreateWindowSurface, you pass in the RWindow as an argument. The window +surface is then displayed on the screen associated with that window's +parent window group. Currently a window can exist on only one screen.

              +               +EGL +Interface Component +EGL +Collection Overview +Coverflow: +using ScreenPlay +Drawing +with CWindowGc               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8983A095-3F5A-5262-8920-8A13ADD045DC_d0e220940_href.png Binary file Symbian3/SDK/Source/GUID-8983A095-3F5A-5262-8920-8A13ADD045DC_d0e220940_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8983A095-3F5A-5262-8920-8A13ADD045DC_d0e224677_href.png Binary file Symbian3/SDK/Source/GUID-8983A095-3F5A-5262-8920-8A13ADD045DC_d0e224677_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-89C5B56D-0846-4D32-94E5-CEF8BFA47D4E.dita --- a/Symbian3/SDK/Source/GUID-89C5B56D-0846-4D32-94E5-CEF8BFA47D4E.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-89C5B56D-0846-4D32-94E5-CEF8BFA47D4E.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,42 +1,42 @@ - - - - - -Migrating -from C Standard Library (ESTLIB) to P.I.P.S.If you are using ESTLIB, it is recommended that you migrate to -P.I.P.S. available from Symbian^1, as P.I.P.S. is much more POSIX compliant -and feature-rich. -

              P.I.P.S. -is supported from Symbian^1 onwards on ROM. ESTLIB applications -can be ported to use P.I.P.S., by keeping the base source as it is while making -changes to the MMP files and rebuilding the code.

               -

              To migrate -from C Standard Library (ESTLIB) to P.I.P.S., perform the following steps:

              -               - - -

              Replace the LIBRARY entry in the .MMP file -from estlib.lib to libc.lib libm.lib libpthread.lib.

               -               - -

              Replace the LIBRARY entry in the .MMP file -from ecrt0.lib to libcrt0.lib.

               -               - -

              Replace the SYSTEMINCLUDE path from \epoc32\include\libc to \epoc32\include\stdapis.

               -

              Important: If any non-POSIX worked around code (written -to satisfy POSIX-deviated ESTLIB return codes) is present in your existing -application, you will also need to modify it to make them POSIX complaint.

               -               -               -

              Note: For -more information about using P.I.P.S. on Symbian platform, see Open -Environment Core (P.I.P.S.).

              + + + + + +Migrating +from C Standard Library (ESTLIB) to P.I.P.S.If you are using ESTLIB, it is recommended that you migrate to +P.I.P.S. available from Symbian^1, as P.I.P.S. is much more POSIX compliant +and feature-rich. +

              P.I.P.S. +is supported from Symbian^1 onwards on ROM. ESTLIB applications +can be ported to use P.I.P.S., by keeping the base source as it is while making +changes to the MMP files and rebuilding the code.

               +

              To migrate +from C Standard Library (ESTLIB) to P.I.P.S., perform the following steps:

              +               + + +

              Replace the LIBRARY entry in the .MMP file +from estlib.lib to libc.lib libm.lib libpthread.lib.

               +               + +

              Replace the LIBRARY entry in the .MMP file +from ecrt0.lib to libcrt0.lib.

               +               + +

              Replace the SYSTEMINCLUDE path from \epoc32\include\libc to \epoc32\include\stdapis.

               +

              Important: If any non-POSIX worked around code (written +to satisfy POSIX-deviated ESTLIB return codes) is present in your existing +application, you will also need to modify it to make them POSIX complaint.

               +               +               +

              Note: For +more information about using P.I.P.S. on Symbian platform, see Open +Environment Core (P.I.P.S.).

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-89D8ECA6-23C3-5573-8DC6-10F7FF7B491F.dita --- a/Symbian3/SDK/Source/GUID-89D8ECA6-23C3-5573-8DC6-10F7FF7B491F.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-89D8ECA6-23C3-5573-8DC6-10F7FF7B491F.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,25 +1,25 @@ - - - - - -Types of Email

              This section describes the types of email that Messaging Middleware supports and the structure of email messages.

              The following are the types of email that are supported. The diagrams represent the structure of the message entries in the Message Server.

              Plain text messages

              Non-MIME emails are the simplest type of mail message and contain only a plain text message body.

              - Plain text messages -
              UUEncoded messages

              To allow for binary files to be ‘attached’ to non-MIME emails, it is possible to UUEncode the binary data and include it as text within the message. A typical message would consist of some text, followed by the UUEncoded data, followed by more text and UUEncoded data.

              - UUEncoded messages -
              Multipart messages

              The multipart messages are the most popular form of modern emails. Multipart messages contain a sequence of body parts which can in turn contain additional nested body parts. The simplest example would be a text message with a single binary attachment. Binary data is typically encoded using BASE64 encoding.

              - Multipart messages -
              HTML text messages

              HTML text messages contain an HTML representation of the message body text (complete with all text formatting) and a corresponding plain text version. The email client can then decide which to display to the user based in its capabilities.

              - HTML text messages -
              HTML messages with attachments

              As with HTML text messages, these contain plain and HTML versions of the body text, as well as additional body parts containing potentially encoded attachment data.

              - HTML messages with attachments -
              HTML messages with embedded message

              Messages can contain embedded messages within their body parts. This example shows a message with parts consisting of plain text, an attachment, and an embedded message. The embedded message in turn contains an attachment as well a plain and html versions of the body text.

              - HTML messages with embedded message -
              Storage of email parts

              The majority of the message data is stored within a single file. This contain separate streams for header information, MIME headers, attachment information and the rich text store. If the message contained attachments, a corresponding folder exists that stores each attachment as a separate decoded file.

              Message Server and Store Message Type Module IMAP4 + + + + + +Types of Email

              This section describes the types of email that Messaging Middleware supports and the structure of email messages.

              The following are the types of email that are supported. The diagrams represent the structure of the message entries in the Message Server.

              Plain text messages

              Non-MIME emails are the simplest type of mail message and contain only a plain text message body.

              + Plain text messages +
              UUEncoded messages

              To allow for binary files to be ‘attached’ to non-MIME emails, it is possible to UUEncode the binary data and include it as text within the message. A typical message would consist of some text, followed by the UUEncoded data, followed by more text and UUEncoded data.

              + UUEncoded messages +
              Multipart messages

              The multipart messages are the most popular form of modern emails. Multipart messages contain a sequence of body parts which can in turn contain additional nested body parts. The simplest example would be a text message with a single binary attachment. Binary data is typically encoded using BASE64 encoding.

              + Multipart messages +
              HTML text messages

              HTML text messages contain an HTML representation of the message body text (complete with all text formatting) and a corresponding plain text version. The email client can then decide which to display to the user based in its capabilities.

              + HTML text messages +
              HTML messages with attachments

              As with HTML text messages, these contain plain and HTML versions of the body text, as well as additional body parts containing potentially encoded attachment data.

              + HTML messages with attachments +
              HTML messages with embedded message

              Messages can contain embedded messages within their body parts. This example shows a message with parts consisting of plain text, an attachment, and an embedded message. The embedded message in turn contains an attachment as well a plain and html versions of the body text.

              + HTML messages with embedded message +
              Storage of email parts

              The majority of the message data is stored within a single file. This contain separate streams for header information, MIME headers, attachment information and the rich text store. If the message contained attachments, a corresponding folder exists that stores each attachment as a separate decoded file.

              Message Server and Store Message Type Module IMAP4 MTM POP3 MTM SMTP MTM               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8A5054C9-7556-5153-8CEE-FA8E5F4155AE.dita --- a/Symbian3/SDK/Source/GUID-8A5054C9-7556-5153-8CEE-FA8E5F4155AE.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-8A5054C9-7556-5153-8CEE-FA8E5F4155AE.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,99 +1,99 @@ - - - - - -How -to Create an Explicitly Bound SocketThis topic describes how create an explicitly bound socket. -

              Start the network interface connection with RConnection::Start() to -create an explicitly bound socket.

              Creating an explicitly bound -socket

              Explicitly bound sockets can be created in two ways:

              - -Open a socket and bind the socket to a network interface connection. -
                -

              • Call RSocket::Open() and pass an RConnection.

                RConnection binds -to an interface corresponding to the RConnection.

                -In the following example code, if iConn corresponds to a -WiFi RConnection then, after a calling RSocket::Open() the -socket is explicitly bound to WiFi.

                iRecvSock.Open( ss, KAfInet, KSockStream, KProtocolInetTcp, iConn );
                • -
               -               -Open a socket and bind the socket to an IP address of the network -interface connection. -
                -

              • Call RSocket::Bind() and bind the socket to an -IP address of the network interface connection.

                RSocket::Bind() binds -the socket to a unique IP address of the network interface connection.

                -The following example code shows how to open a socket and bind the socket -to a unique IP address of the WiFi connection.

                // open an implicit socket -TInt err = iRecvSock.Open( iSs, KAfInet, KSockDatagram, KProtocolInetUdp); -User::LeaveIfError( err ); -// This IP address maps to WiFi in the ced.cfg file -_LIT(KRasAddr,"192.168.220.4"); -const TInt KPort = 7000; -TInetAddr addr; -err = addr.Input( KRasAddr ); -User::LeaveIfError( err ); -addr.SetPort( KPort ); -// Now the socket is explicitly bound to WiFi -err = iRecvSock.Bind( addr ); -RDebug::Print( _L("testapp: ETH Bind() = %d"), err ); -User::LeaveIfError( err ); -
                • -

              The following code block shows an extract from the ced.cfg file. -

              -## -[LANService] -ADD_SECTION -# COMMDB_ID = 1 -Name=Ethernet -IfNetworks=ip -IpNetMask=255.0.0.0 -IpGateway=0.0.0.0 -IpAddrFromServer=FALSE -IpAddr=192.168.1.1 -IpDNSAddrFromServer=FALSE -ConfigDaemonManagerName=NetCfgExtnDhcp -ConfigDaemonName=!DhcpServ -FIELD_COUNT=9 -END_ADD - -ADD_SECTION -# COMMDB_ID = 2 -Name=Ethernet WiFi -IfNetworks=ip -IpNetMask=255.0.0.0 -IpGateway=0.0.0.0 -IpAddrFromServer=FALSE --// This IP address maps to WiFi -IpAddr=192.168.220.4 -IpDNSAddrFromServer=FALSE -IpNameServer1=194.72.6.51 -IpNameServer2=194.72.6.52 -ConfigDaemonManagerName=NetCfgExtnDhcp -ConfigDaemonName=!DhcpServ -LanServiceExtensionTableName=WLANServiceExtensionTable -LanServiceExtensionTableRecordId=4 -FIELD_COUNT=13 -END_ADD -               -               -               -

              The socket is explicitly bound to the specific IP address of the -network interface connection.

              -Explicit binding example

              Client A creates a socket -with explicit binding using the specified interface connection.

              sock1 = RSocket.Open(srv,conn);

              ESock -creates the socket within the default connection and subconnection.

              - -               -

              A socket can also be opened over a sub-connection using RSubConnection. -When the socket is opened, a new Service Access Point (SAP) is created for -the socket in ESock. The SAP is used to handle inbound -and outbound data.

              + + + + + +How +to Create an Explicitly Bound SocketThis topic describes how create an explicitly bound socket. +

              Start the network interface connection with RConnection::Start() to +create an explicitly bound socket.

              Creating an explicitly bound +socket

              Explicitly bound sockets can be created in two ways:

              + +Open a socket and bind the socket to a network interface connection. +
                +

              • Call RSocket::Open() and pass an RConnection.

                RConnection binds +to an interface corresponding to the RConnection.

                +In the following example code, if iConn corresponds to a +WiFi RConnection then, after a calling RSocket::Open() the +socket is explicitly bound to WiFi.

                iRecvSock.Open( ss, KAfInet, KSockStream, KProtocolInetTcp, iConn );
                • +
               +               +Open a socket and bind the socket to an IP address of the network +interface connection. +
                +

              • Call RSocket::Bind() and bind the socket to an +IP address of the network interface connection.

                RSocket::Bind() binds +the socket to a unique IP address of the network interface connection.

                +The following example code shows how to open a socket and bind the socket +to a unique IP address of the WiFi connection.

                // open an implicit socket +TInt err = iRecvSock.Open( iSs, KAfInet, KSockDatagram, KProtocolInetUdp); +User::LeaveIfError( err ); +// This IP address maps to WiFi in the ced.cfg file +_LIT(KRasAddr,"192.168.220.4"); +const TInt KPort = 7000; +TInetAddr addr; +err = addr.Input( KRasAddr ); +User::LeaveIfError( err ); +addr.SetPort( KPort ); +// Now the socket is explicitly bound to WiFi +err = iRecvSock.Bind( addr ); +RDebug::Print( _L("testapp: ETH Bind() = %d"), err ); +User::LeaveIfError( err ); +
                • +

              The following code block shows an extract from the ced.cfg file. +

              +## +[LANService] +ADD_SECTION +# COMMDB_ID = 1 +Name=Ethernet +IfNetworks=ip +IpNetMask=255.0.0.0 +IpGateway=0.0.0.0 +IpAddrFromServer=FALSE +IpAddr=192.168.1.1 +IpDNSAddrFromServer=FALSE +ConfigDaemonManagerName=NetCfgExtnDhcp +ConfigDaemonName=!DhcpServ +FIELD_COUNT=9 +END_ADD + +ADD_SECTION +# COMMDB_ID = 2 +Name=Ethernet WiFi +IfNetworks=ip +IpNetMask=255.0.0.0 +IpGateway=0.0.0.0 +IpAddrFromServer=FALSE +-// This IP address maps to WiFi +IpAddr=192.168.220.4 +IpDNSAddrFromServer=FALSE +IpNameServer1=194.72.6.51 +IpNameServer2=194.72.6.52 +ConfigDaemonManagerName=NetCfgExtnDhcp +ConfigDaemonName=!DhcpServ +LanServiceExtensionTableName=WLANServiceExtensionTable +LanServiceExtensionTableRecordId=4 +FIELD_COUNT=13 +END_ADD +               +               +               +

              The socket is explicitly bound to the specific IP address of the +network interface connection.

              +Explicit binding example

              Client A creates a socket +with explicit binding using the specified interface connection.

              sock1 = RSocket.Open(srv,conn);

              ESock +creates the socket within the default connection and subconnection.

              + +               +

              A socket can also be opened over a sub-connection using RSubConnection. +When the socket is opened, a new Service Access Point (SAP) is created for +the socket in ESock. The SAP is used to handle inbound +and outbound data.

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8A7B837D-4069-5364-A596-686EEBAE351D.dita --- a/Symbian3/SDK/Source/GUID-8A7B837D-4069-5364-A596-686EEBAE351D.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-8A7B837D-4069-5364-A596-686EEBAE351D.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,16 +1,16 @@ - - - - - -Plug-In Framework Overview

              The Plug-in (ECom) framework is a generic framework that provides a single mechanism to register and discover plug-ins and load an appropriate plug-in.

              Purpose

              In early versions of Symbian platform, plug-ins were provided by polymorphic interface DLLs. All the frameworks within the Symbian platform that needed to use plug-ins had to provide their own mechanisms for the clients to discover and instantiate the implementations. This resulted in duplication of functionality.

              The Plug-In framework is intended to provide a common and system-wide mechanism for instantiating a dynamically determined component.

              Three distinct users of the plug-in framework are:

              • Framework or Application designers

                These users need to understand interface definition design and platform security implications.

              • Plug-in writers

                These users need to understand interface implementation, DLL creation and platform security implementation issue.

              • Plug-in users

                These users need to understand that the plug-in framework helps in selecting the plug-in but sometimes may need to specify which implementation the framework should choose.

              Required background

              Run-time Binding: This is called dynamic binding or late binding. The linking of a routine or object is performed during runtime based on the requirements.

              DLL (Dynamic Link Library): Is a piece of code (a library) that is linked to a program at runtime rather than during the build process. The code inside a DLL can be shared by several clients at the same time without being duplicated in the mobile memory.

              In addition , the user should be aware of the Platform Security Considerations of the plug-in framework architecture.

              Key concepts and terms
              Plug-in

              In computing, a plug-in(extension) consists of a computer program that interacts with a host application(a web browser or an email client) to provide a very specific function on demand.

              Applications support plugins to:

              • Enable third-party developers to create capabilities to extend an application.

              • Reduce the size of an application.

              • Separate source code from an application.

              Plug-in System

              A client wishes to access a plug-in. The plug-in details are known only at run-time. The general characteristics of the plug-in are defined in an interface. Multiple variants of the plug-in can co-exist.

              The four clearly-defined roles of a plug-in system are:

              • The Client that wishes to access services.

              • The Interface Definition that defines how to request services.

              • The Interface Implementation/Plug-in that provides the required processing.

              • The Framework that provides the clients with the required access to the implementations.

              The relationships can be represented as follows:

              - Plug-in relationships -

              The instantiation mechanism is responsible for providing the services that identify, and load the correct implementation at run-time.

              Interface

              Is an abstraction that an entity provides of itself to the outside. This separates the methods of external communication from internal operation. It allows internal modification and this modification does not affect the outside entities interaction with the interface. An interface can provide multiple abstractions.

              Interface API / Interface Definition

              Is a template for an interface implementation.

              Interface Client/Client

              Is an application that uses the interface definition.

              Interface Implementation Collection

              Is a collection of interface implementations/plug-ins.

              Registry

              Is a collection of plug-ins registered with the framework.

              Architecture

              The plug-in framework employs the client server architecture. The client session is a singleton per process thread.

              - Plug-in framework architecture -

              The functional components of the plug-in framework are:

              • The Client /Interface Client that invokes the available services via the interface definition.

              • The Server / Framework controls access to a registry of available implementations that is used for interface implementation resolution and loading.

                The server facilitates:

                • Addition and removal of interface implementations.

                  The addition, removal or modifications to an implementation is notified to the server. The server updates the changes in the registry.

                • Search/Access mechanisms.

                  The registry data is maintained as a hierarchical arrangement of implementations. The complete data is scanned and matching interface implementation list is produced as a result of search.

                • Resolution mechanisms.

                  The best fit implementation from the resultant search is identified.

                • Load control.

                  Controls access to a single instance of the available implementations. The implementation identification information is used to load the appropriate collection.

              APIs API Description

              REComSession

              Resolves, instantiates, and destroys interface class implementations requested by the plug-in framework clients.

              Typical uses

              The plug-in framework allows:

              • Framework developers to write interface definitions and extend interfaces.

              • Plug-in writer to implement the interfaces.

              • Plug-in user to use the interfaces.

              Framework Developer Tutorials Plug-in Writer's Tutorials Plug-in User's Tutorials               \ No newline at end of file + + + + + +Plug-In Framework Overview

              The Plug-in (ECom) framework is a generic framework that provides a single mechanism to register and discover plug-ins and load an appropriate plug-in.

              Purpose

              In early versions of Symbian platform, plug-ins were provided by polymorphic interface DLLs. All the frameworks within the Symbian platform that needed to use plug-ins had to provide their own mechanisms for the clients to discover and instantiate the implementations. This resulted in duplication of functionality.

              The Plug-In framework is intended to provide a common and system-wide mechanism for instantiating a dynamically determined component.

              Three distinct users of the plug-in framework are:

              • Framework or Application designers

                These users need to understand interface definition design and platform security implications.

              • Plug-in writers

                These users need to understand interface implementation, DLL creation and platform security implementation issue.

              • Plug-in users

                These users need to understand that the plug-in framework helps in selecting the plug-in but sometimes may need to specify which implementation the framework should choose.

              Required background

              Run-time Binding: This is called dynamic binding or late binding. The linking of a routine or object is performed during runtime based on the requirements.

              DLL (Dynamic Link Library): Is a piece of code (a library) that is linked to a program at runtime rather than during the build process. The code inside a DLL can be shared by several clients at the same time without being duplicated in the mobile memory.

              In addition , the user should be aware of the Platform Security Considerations of the plug-in framework architecture.

              Key concepts and terms
              Plug-in

              In computing, a plug-in(extension) consists of a computer program that interacts with a host application(a web browser or an email client) to provide a very specific function on demand.

              Applications support plugins to:

              • Enable third-party developers to create capabilities to extend an application.

              • Reduce the size of an application.

              • Separate source code from an application.

              Plug-in System

              A client wishes to access a plug-in. The plug-in details are known only at run-time. The general characteristics of the plug-in are defined in an interface. Multiple variants of the plug-in can co-exist.

              The four clearly-defined roles of a plug-in system are:

              • The Client that wishes to access services.

              • The Interface Definition that defines how to request services.

              • The Interface Implementation/Plug-in that provides the required processing.

              • The Framework that provides the clients with the required access to the implementations.

              The relationships can be represented as follows:

              + Plug-in relationships +

              The instantiation mechanism is responsible for providing the services that identify, and load the correct implementation at run-time.

              Interface

              Is an abstraction that an entity provides of itself to the outside. This separates the methods of external communication from internal operation. It allows internal modification and this modification does not affect the outside entities interaction with the interface. An interface can provide multiple abstractions.

              Interface API / Interface Definition

              Is a template for an interface implementation.

              Interface Client/Client

              Is an application that uses the interface definition.

              Interface Implementation Collection

              Is a collection of interface implementations/plug-ins.

              Registry

              Is a collection of plug-ins registered with the framework.

              Architecture

              The plug-in framework employs the client server architecture. The client session is a singleton per process thread.

              + Plug-in framework architecture +

              The functional components of the plug-in framework are:

              • The Client /Interface Client that invokes the available services via the interface definition.

              • The Server / Framework controls access to a registry of available implementations that is used for interface implementation resolution and loading.

                The server facilitates:

                • Addition and removal of interface implementations.

                  The addition, removal or modifications to an implementation is notified to the server. The server updates the changes in the registry.

                • Search/Access mechanisms.

                  The registry data is maintained as a hierarchical arrangement of implementations. The complete data is scanned and matching interface implementation list is produced as a result of search.

                • Resolution mechanisms.

                  The best fit implementation from the resultant search is identified.

                • Load control.

                  Controls access to a single instance of the available implementations. The implementation identification information is used to load the appropriate collection.

              APIs API Description

              REComSession

              Resolves, instantiates, and destroys interface class implementations requested by the plug-in framework clients.

              Typical uses

              The plug-in framework allows:

              • Framework developers to write interface definitions and extend interfaces.

              • Plug-in writer to implement the interfaces.

              • Plug-in user to use the interfaces.

              Framework Developer Tutorials Plug-in Writer's Tutorials Plug-in User's Tutorials               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8AB9527A-1C7E-5D3A-9AB2-A3FA1F5A2D5B.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-8AB9527A-1C7E-5D3A-9AB2-A3FA1F5A2D5B.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,675 @@ + + + + + +UIDs +
              Symmetric cipher +algorithm UIDs + + + +UID +Description +Value +RFC standard + + + + +

              KDesUid

              +

              DES (Data Encryption Standard) algorithm

              +

              0x10283179

              +

              RFC +2406

              +               + +

              K3DesUid

              +

              3DES (Triple Data Encryption Standard) algorithm

              +

              0x1028317a

              +

              RFC +2405

              RFC +2420

              +               + +

              KRc2Uid

              +

              RC2 algorithm

              +

              0x1028317b

              +

              RFC +2268

              +               + +

              KArc4Uid

              +

              ARC4 ('alleged' RC4) algorithm (strong random number generator)

              +

              0x1028317c

              +

              RFC +2144

              +               + +

              KAesUid

              +

              AES (Advanced Encryption Standard)

              +

              0x1028317d

              +

              RFC +3268

              +               + +

              KMisty1Uid

              +

              Misty1 algorithm

              +

              0x102831be

              +

              RFC +2994

              +               + +

              KMisty2Uid

              +

              Misty2 algorithm

              +

              0x102831bf

              + +               + +

              KKasumiUid

              +

              Kasumi algorithm

              +

              0x102831c0

              +

              RFC +3711

              +               + + +

              The symmetric cipher algorithm UIDs are used by the following +CryptoSPI APIs:

                +

              • CSymmetricCipherFactory::CreateSymmetricCipherL()

                • +

              • CRuleSelector::CreateSymmetricCipherL()

                • +

              • CCryptoPluginEntry::CreateSymmetricCipherL()

                • +

              • CAsymmetricCipherFactory::CreateAsymmetricCipherL()

                • +

              • CRuleSelector::CreateAsymmetricCipherL()

                • +

              • CCryptoPluginEntry::CreateAsymmetricCipherL()

                • +
              +
              Asymmetric +cipher algorithm UIDs + + + +UID +Description +Value +RFC standard + + + + +

              KRsaCipherUid

              +

              RSA

              +

              0x1028317e

              +

              RFC +2437: PKCS #1: RSA Cryptography Specifications Version 2.0

              RFC 2313 - PKCS +#1: RSA Encryption Version 1.5

              +               + + +

              The asymmetric cipher algorithm UIDs are used by the following + CryptoSPI APIs:

                +

              • CAsymmetricCipherFactory::CreateAsymmetricCipherL()

                • +

              • CRuleSelector::CreateAsymmetricCipherL()

                • +

              • CCryptoPluginEntry::CreateAsymmetricCipherL()

                • +

              • CAsymmetricCipherFactory::CreateAsyncAsymmetricCipherL()

                • +

              • CRuleSelector::CreateAsyncAsymmetricCipherL()

                • +
              +
              Signer algorithm +UIDs + + + +UID +Description +Value +RFC standard + + + + +

              KRsaSignerUid

              +

              RSA Signer algorithm

              +

              0x1028317f

              +

              RFC +4853

              +               + +

              KDsaSignerUid

              +

              DSA Signer algorithm

              +

              0x10283180

              +

              RFC +3279

              +               + + +

              The signer algorithm UIDs are used by the following CryptoSPI +APIs:

                +

              • CSignatureFactory::CreateSignerL()

                • +

              • CRuleSelector::CreateSignerL()

                • +

              • CSignatureFactory::CreateAsyncSignerL()

                • +

              • CRuleSelector::CreateAsyncSignerL()

                • +
              +
              Verifier algorithm +UIDs + + + +UID +Description +Value +RFC standard + + + + +

              KRsaVerifierUid

              +

              RSA Verifier algorithm

              +

              0x10283181

              +

              RFC +4853

              +               + +

              KDsaVerifierUid

              +

              DSA Verifier algorithm

              +

              0x10283182

              +

              RFC +3279

              +               + + +

              The verifier algorithm UIDs are used by the following CryptoSPI +APIs:

                +

              • CSignatureFactory::CreateVerifierL()

                • +

              • MPluginSelector::CreateVerifierL()

                • +

              • CSignatureFactory::CreateAsyncVerifierL()

                • +

              • CRuleSelector::CreateAsyncVerifierL()

                • +
              +
              Key Agreement +algorithm UIDs + + + +UID +Description +Value +RFC standard + + + + +

              KDHAgreementUid

              +

              Diffie-Hellman Key Agreement algorithm

              +

              0x10283183

              +

              RFC +2631

              +               + + +

              The Key Agreement algorithm UIDs are used by the following CryptoSPI +APIs:

                +

              • CKeyAgreementFactory::CreateKeyAgreementL()

                • +

              • CRuleSelector::CreateKeyAgreementL()

                • +

              • CCryptoPluginEntry::CreateKeyAgreementL()

                • +

              • CKeyAgreementFactory::CreateAsyncKeyAgreementL()

                • +

              • CRuleSelector::CreateAsyncKeyAgreementL()

                • +
              +
              Key Pair Generator +algorithm UIDs + + + +UID +Description +Value +RFC standard + + + + +

              KDHKeyPairGeneratorUid

              +

              DH Key Pair Generator algorithm

              +

              0x10283184

              +

              RFC +2539

              +               + +

              KRSAKeyPairGeneratorUid

              +

              RSA Key Pair Generator algorithm

              +

              0x10283185

              +

              RFC +4055

              +               + +

              KDSAKeyPairGeneratorUid

              +

              DSA Key Pair Generator algorithm

              +

              0x10283186

              + +               + + +

              The Key Pair Generator algorithm UIDs are used by the following +CryptoSPI APIs:

                +

              • CKeyPairGeneratorFactory::CreateAsyncKeyPairGeneratorL()

                • +

              • CRuleSelector::CreateAsyncKeyPairGeneratorL()

                • +
              +
              Padding modes + + + +UID +Description +Value + + + + +

              KPaddingModeNoneUid

              +

              Padding Mode None Uid

              +

              0x10283188

              +               + +

              KPaddingModeSSLv3Uid

              +

              SSLv3 Padding Mode Uid

              +

              0x10283189

              +               + +

              KPaddingModePKCS7Uid

              +

              PKCS7 Padding Mode Uid

              +

              0x1028318a

              +               + +

              KPaddingModePkcs1_v1_5_EncryptionUid

              +

              Pkcs1 v1.5 Encryption Padding mode Uid

              +

              0x1028318b

              +               + +

              KPaddingModePkcs1_v1_5_SignatureUid

              +

              Pkcs1 v1.5 Signature Padding mode Uid

              +

              0x1028318c

              +               + + +

              The padding modes are used by the following CryptoSPI APIs:

                +

              • CAsymmetricCipherFactory::CreateAsymmetricCipherL()

                • +

              • CAsymmetricCipherFactory::CreateAsyncAsymmetricCipherL()

                • +
              +
              Cryptography +modes + + + +UID +Description +Value + + + + +

              KCryptoModeEncryptUid

              +

              Crypto Encrypt Mode Uid

              +

              0x1028318d

              +               + +

              KCryptoModeDecryptUid

              +

              Crypto Decrypt Mode Uid

              +

              0x1028318e

              +               + +

              KCryptoModeNoneUid

              +

              Crypto None Mode Uid

              +

              0x1028318f

              +               + + +

              The cryptography modes are used by the following CryptoSPI APIs:

                +

              • CAsymmetricCipherFactory::CreateAsymmetricCipherL()

                • +

              • CAsymmetricCipherFactory::CreateAsyncAsymmetricCipherL()

                • +
              +
              Hash algorithm UIDs + + + +UID +Description +Value +RFC standard + + + + +

              KMd2Uid

              +

              MD2, Message-Digest Algorithm

              +

              0x10283173

              +

              RFC +1319

              +               + +

              KMd4Uid

              +

              MD4, Message-Digest Algorithm (Output: 128 bit message digest)

              +

              0x2000B341

              +

              RFC +1320

              +               + +

              KMd5Uid

              +

              MD5 ,Message-Digest Algorithm (output:128-bit "fingerprint" or "message +digest)

              +

              0x10283174

              +

              RFC +1321

              +               + +

              KSha1Uid

              +

              Secure Hash Algorithm(output: 160-bit message digest)

              +

              0x10283175

              +

              FIPS +180-1 and RFC +3174

              +               + +

              KSha224Uid

              +

              Sha224 algorithm

              +

              0x2000E258

              +

              FIPS 180-2 (with change notice), RFC3874 and FIPS 180-3

              +               + +

              KSha256Uid

              +

              Sha256 algorithm

              +

              0x2000E259

              +

              FIPS 180-2 and RFC 4634

              +               + +

              KSha384Uid

              +

              Sha384 algorithm

              +

              0x2000E25A

              +

              FIPS 180-2 and RFC 4634

              +               + +

              KSha512Uid

              +

              Sha512 algorithm

              +

              0x2000E25B

              +

              FIPS 180-2 and RFC 4634

              +               + + +

              The hash algorithm UIDs are used by the following APIs:

                +

              • CryptoSpi::CHashFactory::CreateHashL()

                • +

              • CryptoSpi::CRuleSelector::CreateHashL()

                • +

              • CryptoSpi::CCryptoPluginEntry::CreateHashL()

                • +

              • CryptoSpi::CHashFactory::CreateAsyncHashL()

                • +

              • CryptoSpi::CRuleSelector::CreateAsyncHashL()

                • +
              +
              Random algorithm UIDs + + + +UID +Description +Value + + + + +

              KRandomUid

              +

              Random algorithm UID

              +

              0x10283178

              +               + + +

              The random algorithm UIDs are used by the following APIs:

                +

              • CryptoSpi::CRandomFactory::CreateRandomL()

                • +

              • CryptoSpi::CRuleSelector::CreateRandomL()

                • +

              • CryptoSpi::CRandomFactory::CreateAsyncRandomL()

                • +

              • CryptoSpi::CRuleSelector::CreateAsyncRandomL()

                • +
              +
              Symmetric key algorithm UIDs + + + +UID +Description +Value + + + + +

              KDesUid

              +

              Des algorithm UID

              +

              0x10283179

              +               + +

              K3DesUid

              +

              3Des algorithm UID

              +

              0x1028317a

              +               + +

              KRc2Uid

              +

              RC2 algorithm UID

              +

              0x1028317b

              +               + +

              KArc4Uid

              +

              ARC4 algorithm UID

              +

              0x1028317c

              +               + +

              KAesUid

              +

              AES algorithm UID

              +

              0x1028317d

              +               + +

              KMisty1Uid

              +

              Misty1 algorithm UID

              +

              0x102831be

              +               + +

              KMisty2Uid

              +

              Misty2 algorithm UID

              +

              0x102831bf

              +               + +

              KKasumiUid

              +

              Kasumi algorithm UID

              +

              0x102831c0

              +               + + +

              The symmetric key algorithm UIDs are used by the following API:

                +

              • CryptoSpi::CSymmetricCipher::CSymmetricCipher()

                • +
              +
              Asymmetric key algorithm UIDs + + + +UID +Description +Value + + + + +

              KRsaCipherUid

              +

              RSA Cipher algorithm UID

              +

              0x1028317e

              +               + +

              KRsaSignerUid

              +

              RSA Signer algorithm UID

              +

              0x1028317f

              +               + +

              KRsaVerifierUid

              +

              RSA Verifier algorithm UID

              +

              0x10283181

              +               + +

              KRSAKeyPairGeneratorUid

              +

              RSA Key Pair Generator algorithm UID

              +

              0x10283185

              +               + +

              KDsaSignerUid

              +

              DSA Signer algorithm UID

              +

              0x10283180

              +               + +

              KDsaVerifierUid

              +

              DSA Verifier algorithm UID

              +

              0x10283182

              +               + +

              KDSAKeyPairGeneratorUid

              +

              DSA Key Pair Generator algorithm UID

              +

              0x10283186

              +               + +

              KDHAgreementUid

              +

              DH Agreement algorithm UID

              +

              0x10283183

              +               + +

              KDHKeyPairGeneratorUid

              +

              DH Key Pair Generator algorithm UID

              +

              0x10283184

              +               + +

              KEccCipherUid

              +

              ECC Key Cipher algorithm UID

              +

              0x20024482

              +               + +

              KEccSignerUid

              +

              ECC Key Signer algorithm UID

              +

              0x20024483

              +               + +

              KEccVerifierUid

              +

              ECC Key Verifier algorithm UID

              +

              0x20024486

              +               + +

              KEccKeyPairGeneratorUid

              +

              ECC Key Pair Generator algorithm UID

              +

              0x20024487

              +               + + +

              Note: The ECC key UIDs are enabled only if the macros SYMBIAN_ENABLE_SDP_ECC and SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT are enabled.

              The asymmetric key algorithm UIDs are used by the following +API:

                +

              • CryptoSpi::CAsymmetricCipher::CAsymmetricCipher()

                • +
              +
              Other UIDs + + + +UID +Description +Value + + + + +

              KPassedHandleToKeyUid

              +

              Use this UID as CKey key parameter, +whenever the CryptoSPI user has just the handle and not the actual key. The +CryptoSPI plug-in searches for this ID and invokes the appropriate APIs for +providing access to the key.

              Note: This UID is enabled only +if the SYMBIAN_ENABLE_SDP_WMDRM_SUPPORT macro is enabled.

              +

              0x20025161

              +               + + +

              Example usage of KPassedHandleToKeyUid

              The following +sequence of steps explains the use of KPassedHandleToKeyUid in +the key parameter, which, along with the key property creates a CKey object. +This CKey object is one of the parameters +in the creation of a signer object, which can be used for performing signing +operations.

                +

              1. Define the key property.

                Create +a CCryptoParams object for the key parameter. Add the key +handle and KPassedHandleToKeyUid to the CCryptoParams object +by using CCryptoParams::AddL().

                2. +

              2. Create a CKey object +by passing instance of the key property and the CCryptoParams object +containing KPassedHandleToKeyUid.

                3. +

              3. Create a signer object +by using the CKey object as one of the +parameters. This signer object can be used for performing signing operations.

                4. +

              The following code snippet demonstrates the use of KPassedHandleToKeyUid:

              +. +. +. +// Define the key property +TKeyProperty keyProperty; +keyProperty.iAlgorithmUid = KRsaSignerUid; + +// Create the key parameter object +CCryptoParams* keyParameters = CCryptoParams::NewLC(); + +// iHandle is of type TCTTokenObjectHandle. It contains handle to the key +keyParameters->AddL(iHandle.iObjectId, KPassedHandleToKeyUid); + +// Create a CKey object +CKey* newKey = CKey::NewL(keyProperty, *keyParameters); + +// Create a signer plug-in object +CSigner * implsig = NULL; + +// Create the signer object +CSignatureFactory::CreateSignerL(implsig, KRsaSignerUid, *newKey, KPaddingModePkcs1_v1_5_SignatureUid, NULL); +. +. +. +
              +
              Operation modes + + + +UID +Description +Value + + + + +

              KOperationModeNoneUid

              +

              None Mode UID

              +

              0x10283190

              +               + +

              KOperationModeECBUid

              +

              ECB Mode UID

              +

              0x10283191

              +               + +

              KOperationModeCBCUid

              +

              CBC Mode UID

              +

              0x10283192

              +               + +

              KOperationModeOFBUid

              +

              OFB Mode UID

              +

              0x10283193

              +               + +

              KOperationModeCFBUid

              +

              CFB Mode UID

              +

              0x10283194

              +               + +

              KOperationModeCTRUid

              +

              CTR Mode UID

              +

              0x10283195

              +               + + +

              The operation modes are used by the following APIs:

                +

              • CryptoSpi::CHashFactory::CreateHashL()

                • +

              • CryptoSpi::CHashFactory::CreateAsyncHashL()

                • +
              +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8AEE1966-D348-41BB-8513-61C379945DB8-master.png Binary file Symbian3/SDK/Source/GUID-8AEE1966-D348-41BB-8513-61C379945DB8-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8AEE1966-D348-41BB-8513-61C379945DB8_d0e52168_href.png Binary file Symbian3/SDK/Source/GUID-8AEE1966-D348-41BB-8513-61C379945DB8_d0e52168_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8AEE1966-D348-41BB-8513-61C379945DB8_d0e74508_href.png Binary file Symbian3/SDK/Source/GUID-8AEE1966-D348-41BB-8513-61C379945DB8_d0e74508_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8AF21373-E51E-5B9D-ACC1-243752C9BB5B_d0e357317_href.png Binary file Symbian3/SDK/Source/GUID-8AF21373-E51E-5B9D-ACC1-243752C9BB5B_d0e357317_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8AF21373-E51E-5B9D-ACC1-243752C9BB5B_d0e363397_href.png Binary file Symbian3/SDK/Source/GUID-8AF21373-E51E-5B9D-ACC1-243752C9BB5B_d0e363397_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8B137691-7C9E-4085-BFFE-4CFE4A64A091.dita --- a/Symbian3/SDK/Source/GUID-8B137691-7C9E-4085-BFFE-4CFE4A64A091.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-8B137691-7C9E-4085-BFFE-4CFE4A64A091.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,50 +1,42 @@ - - - - - -Control -pane -

              The Control pane occupies the bottom part of the screen and displays the -labels associated with the softkeys.

              - -Control pane - - -

              Normal touch down and release functionality applies to the softkeys in -control pane. Activation is performed on touch release. However, activation -can be cancelled by dragging the touch from the softkey area and performing -a touch release.

              -

              The Control pane is also active during Options -menus, queries, -and other states using pop-up -windows, although it does not itself reside in a pop-up window.

              -

              The actual physical softkeys should be positioned directly beneath the -screen so that the association between the keys and their respective labels -is evident. Note, however, that the middle label refers to the Selection key -(see Labeling the Selection -key for further details).

              -
              Using -the control pane in C++ applications

              The APIs to use for the control -pane are the Buttons API for the softkeys and the Options menu API for the menus.

              For implementation -information on using the softkeys, see Using the Buttons API. For implementation information -on the menus, see Using the Options menu API.

              The Symbian -platform uses Control Button Area (CBA) resources to set the options in the -control pane above the softkeys. CBA resources map the text that appears above -the softkeys in the control pane with commands that are collected by the event -loop of the application framework and delivered to your application for command handling.

              When -a mobile device user selects an Options softkey, the application framework -displays the Options menu based upon the definitions in the menu bar's resources.

              The -Symbian platform uses MENU_BAR resources to create the Options menu, when -a mobile device user selects the Options softkey. The options that appear -above the softkeys are determined by CBA resources. The MENU_BAR resources -map the text that appears in the Options menu with commands that are collected -by the event loop of the application framework and delivered to your application -for command handling.

              + + + + + +Control +pane +

              The control pane occupies the bottom part of the screen and displays the +labels associated with the softkeys.

              + +Control pane + + + In landscape orientation, a part of the status pane (the clock and +indicator pane) is inside the control pane. +

              Normal touch down and release functionality applies to the softkeys in +control pane. Activation is performed on touch release. However, activation +can be cancelled by dragging the touch from the softkey area and performing +a touch release.

              +

              The actual physical softkeys should be positioned directly beneath the +screen so that the association between the keys and their respective labels +is evident. Note, however, that the middle label refers to the Selection key +(see Labeling the Selection +key for further details).

              +
              Using +the control pane in applications

              The APIs to use for the control +pane are the Buttons API for the softkeys and the Options menu API for the menus.

              For implementation +information on using the softkeys, see Using the Buttons API. For implementation information +on the menus, see Using the Options menu API.

              The Symbian platform +uses MENU_BAR resources to create the Options menu, when a mobile device user +selects the Options softkey. The options that appear above the +softkeys are determined by CBA resources. The MENU_BAR resources map the text +that appears in the Options menu with commands that are collected by the event +loop of the application framework and delivered to your application for command +handling.

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8B1C7778-0C6D-5DEE-90FD-3B016EC0E3CE_d0e355357_href.png Binary file Symbian3/SDK/Source/GUID-8B1C7778-0C6D-5DEE-90FD-3B016EC0E3CE_d0e355357_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8B1C7778-0C6D-5DEE-90FD-3B016EC0E3CE_d0e361437_href.png Binary file Symbian3/SDK/Source/GUID-8B1C7778-0C6D-5DEE-90FD-3B016EC0E3CE_d0e361437_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8B37A2C7-B4DB-5826-B6C2-3C21012EF9EA_d0e15221_href.png Binary file Symbian3/SDK/Source/GUID-8B37A2C7-B4DB-5826-B6C2-3C21012EF9EA_d0e15221_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8B37A2C7-B4DB-5826-B6C2-3C21012EF9EA_d0e45567_href.png Binary file Symbian3/SDK/Source/GUID-8B37A2C7-B4DB-5826-B6C2-3C21012EF9EA_d0e45567_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8B37A2C7-B4DB-5826-B6C2-3C21012EF9EA_d0e51123_href.png Binary file Symbian3/SDK/Source/GUID-8B37A2C7-B4DB-5826-B6C2-3C21012EF9EA_d0e51123_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8B4CC1A0-1A39-4AF0-826B-8DDB9A837A27.dita --- a/Symbian3/SDK/Source/GUID-8B4CC1A0-1A39-4AF0-826B-8DDB9A837A27.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-8B4CC1A0-1A39-4AF0-826B-8DDB9A837A27.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,158 +1,158 @@ - - - - - -Sensors -Framework OverviewThe Sensors Framework consists of a sensor server and channel based -client APIs for supporting an extensible set of sensor hardware. The sensor -server defines a plug-in interface for adding sensor plug-ins for any type -of sensor hardware. The channel APIs enable client applications to interact -with the sensor hardware. -
              Key Concepts -and Terms
              - -
              Sensor Channel
              -

              The sensor channel forms a medium of interaction between the sensor -hardware and client applications.

              The data from one physical sensor -can be mapped to several channels. For example, the Sensor System handling -an acceleration sensor can provide raw data on one channel and preprocessed -tap events on another.

              -               - -
              Channel Properties
              -

              Channel properties contain properties of a specific channel, such as -data rate, availability, connection type and so on.

              -               - -
              Data item
              -

              A data item is a discrete data package that contains sensor data or -an event parsed from sensor data and related values, such as timestamp. Each -channel provides a single type of data item only.

              -               - -
              Channel condition
              -

              A value-operator pair targeting a single value inside a data item, -indicated by an index. A condition is met when the channel data value in comparison -with the condition value using condition operator is true. The conditions -are gathered in condition sets.

              There are two condition types: single -limit conditions and range conditions. Range conditions are formed from two -separate conditions, representing the lower and upper limits of the range.

              -               - -
              Channel Condition Set
              -

              A set of channel conditions. Following are the two types of condition -sets:

                -

              • AND condition set: An AND condition is met only if a data value satisfies -all conditions in the set.

                • -

              • OR condition: An OR condition is met if a data value satisfies even -one single condition in the set.

                • -

              -               -
              -
              Description

              The -sensor server provides a plug-in interface (Sensor Definitions APIs) that -enables platform developers to create sensor plug-ins for required sensors -hardware. The sensor plug-ins enable the interaction between a client application -and the sensor hardware through sensor channels. The Sensor Channel APIs provides -access to each sensor channel.

              One physical sensor can -provide several different types of data. For example, the physical magnetometer -can provide data for the Magnetometer channel and the Magnetic North channel. -Each sensor channel has its own sensor channel data definition in the Sensor -Definitions APIs that defines the format of the data package supplied by the -sensor channel. The data definition can also define properties for each data -item in the data package.

              The sensor server facilitates the transfer -of data from one sensor hardware to multiple clients simultaneously. It also -resolves any contention between client applications for opening channels or -configuring a sensor device.

              -
              APIs - - - - -API -Description - - - - -CSensrvChannelFinder -The channel finder provides functions to search and find sensor channels -that are supported by the Symbian device. - - -CSensrvChannel -The sensor channel provides functions to open and control a sensor -channel. - - -CSensrvChannelCondition -The sensor channel provides functions for notifying when a specific -condition is met. - - - -CSensrvChannelConditionSet -The sensor channel condition set provides functions for adding one -or more channel conditions to a condition set. - - -MSensrvChannelListener -The sensor channel listener is a callback interface that tracks for -new channels installed on the Symbian device. - - -MSensrvChannelConditionListener -The sensor channel condition listener is a callback interface that -notifies the clients when a condition-set is satisfied. - - -MSensrvDataListener -The sensor data listener is a callback interface that notifies the -clients when the sensor data is available. - - -MSensrvPropertyListener -The sensor property listener is a callback interface that notifies -the client when a channel property changes. - - - -
              - -

              A physical sensor can supply data to several sensor channels (CSensrvChannel) -. A sensor channel provides data to an application in a channel-specific data -format (for example, TSensrvXyzData) through a callback to the MSensrvDataListener::DataReceived() interface. A -sensor channel has a single channel info item (TSensrvChannelInfo) that describes the channel in general. A sensor channel has multiple -property items (TSensrvProperty) -that describe the channel in more detail. Each property item is referenced -by a property id and an index.

              -
              Typical Uses

              Using -the sensor channel APIs, you can perform the following operations:

                -

              • List all the sensor channels that are available for a particular sensor -type. For details, see Querying -for Sensor Channels

                • -

              • Receive and control periodic sensor data.

                For details, see Receiving Data from Sensors
                • -

              • Configure sensor channels.

                For details, see Retrieving -Channel Properties and Setting -Channel Properties
                • -

              • Receive notifications about sensor channel additions and removal. For -details, see Receiving -Notifications about Channel Changes

                • -

              • Configure a sensor channel to support conditional listening. This means -that you can configure it to notify you when the data on the channel matches -some particular values, or exceeds specified boundaries. For details, see Receiving Channel Data based -on Conditions.

                • -

              -               -Using Sensor -Channels APIs -Compensating -Sensor Data for Display Orientation + + + + + +Sensors +Framework OverviewThe Sensors Framework consists of a sensor server and channel based +client APIs for supporting an extensible set of sensor hardware. The sensor +server defines a plug-in interface for adding sensor plug-ins for any type +of sensor hardware. The channel APIs enable client applications to interact +with the sensor hardware. +
              Key Concepts +and Terms
              + +
              Sensor Channel
              +

              The sensor channel forms a medium of interaction between the sensor +hardware and client applications.

              The data from one physical sensor +can be mapped to several channels. For example, the Sensor System handling +an acceleration sensor can provide raw data on one channel and preprocessed +tap events on another.

              +               + +
              Channel Properties
              +

              Channel properties contain properties of a specific channel, such as +data rate, availability, connection type and so on.

              +               + +
              Data item
              +

              A data item is a discrete data package that contains sensor data or +an event parsed from sensor data and related values, such as timestamp. Each +channel provides a single type of data item only.

              +               + +
              Channel condition
              +

              A value-operator pair targeting a single value inside a data item, +indicated by an index. A condition is met when the channel data value in comparison +with the condition value using condition operator is true. The conditions +are gathered in condition sets.

              There are two condition types: single +limit conditions and range conditions. Range conditions are formed from two +separate conditions, representing the lower and upper limits of the range.

              +               + +
              Channel Condition Set
              +

              A set of channel conditions. Following are the two types of condition +sets:

                +

              • AND condition set: An AND condition is met only if a data value satisfies +all conditions in the set.

                • +

              • OR condition: An OR condition is met if a data value satisfies even +one single condition in the set.

                • +

              +               +
              +
              Description

              The +sensor server provides a plug-in interface (Sensor Definitions APIs) that +enables platform developers to create sensor plug-ins for required sensors +hardware. The sensor plug-ins enable the interaction between a client application +and the sensor hardware through sensor channels. The Sensor Channel APIs provides +access to each sensor channel.

              One physical sensor can +provide several different types of data. For example, the physical magnetometer +can provide data for the Magnetometer channel and the Magnetic North channel. +Each sensor channel has its own sensor channel data definition in the Sensor +Definitions APIs that defines the format of the data package supplied by the +sensor channel. The data definition can also define properties for each data +item in the data package.

              The sensor server facilitates the transfer +of data from one sensor hardware to multiple clients simultaneously. It also +resolves any contention between client applications for opening channels or +configuring a sensor device.

              +
              APIs + + + + +API +Description + + + + +CSensrvChannelFinder +The channel finder provides functions to search and find sensor channels +that are supported by the Symbian device. + + +CSensrvChannel +The sensor channel provides functions to open and control a sensor +channel. + + +CSensrvChannelCondition +The sensor channel provides functions for notifying when a specific +condition is met. + + + +CSensrvChannelConditionSet +The sensor channel condition set provides functions for adding one +or more channel conditions to a condition set. + + +MSensrvChannelListener +The sensor channel listener is a callback interface that tracks for +new channels installed on the Symbian device. + + +MSensrvChannelConditionListener +The sensor channel condition listener is a callback interface that +notifies the clients when a condition-set is satisfied. + + +MSensrvDataListener +The sensor data listener is a callback interface that notifies the +clients when the sensor data is available. + + +MSensrvPropertyListener +The sensor property listener is a callback interface that notifies +the client when a channel property changes. + + + +
              + +

              A physical sensor can supply data to several sensor channels (CSensrvChannel) +. A sensor channel provides data to an application in a channel-specific data +format (for example, TSensrvXyzData) through a callback to the MSensrvDataListener::DataReceived() interface. A +sensor channel has a single channel info item (TSensrvChannelInfo) that describes the channel in general. A sensor channel has multiple +property items (TSensrvProperty) +that describe the channel in more detail. Each property item is referenced +by a property id and an index.

              +
              Typical Uses

              Using +the sensor channel APIs, you can perform the following operations:

                +

              • List all the sensor channels that are available for a particular sensor +type. For details, see Querying +for Sensor Channels

                • +

              • Receive and control periodic sensor data.

                For details, see Receiving Data from Sensors
                • +

              • Configure sensor channels.

                For details, see Retrieving +Channel Properties and Setting +Channel Properties
                • +

              • Receive notifications about sensor channel additions and removal. For +details, see Receiving +Notifications about Channel Changes

                • +

              • Configure a sensor channel to support conditional listening. This means +that you can configure it to notify you when the data on the channel matches +some particular values, or exceeds specified boundaries. For details, see Receiving Channel Data based +on Conditions.

                • +

              +               +Using Sensor +Channels APIs +Compensating +Sensor Data for Display Orientation               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8BA0D643-5ED1-4DC4-82EC-C8AA392DCBC4-master.png Binary file Symbian3/SDK/Source/GUID-8BA0D643-5ED1-4DC4-82EC-C8AA392DCBC4-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8BA0D643-5ED1-4DC4-82EC-C8AA392DCBC4_d0e36995_href.png Binary file Symbian3/SDK/Source/GUID-8BA0D643-5ED1-4DC4-82EC-C8AA392DCBC4_d0e36995_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8BA0D643-5ED1-4DC4-82EC-C8AA392DCBC4_d0e42562_href.png Binary file Symbian3/SDK/Source/GUID-8BA0D643-5ED1-4DC4-82EC-C8AA392DCBC4_d0e42562_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8BA0D643-5ED1-4DC4-82EC-C8AA392DCBC4_d0e57289_href.png Binary file Symbian3/SDK/Source/GUID-8BA0D643-5ED1-4DC4-82EC-C8AA392DCBC4_d0e57289_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8BA0D643-5ED1-4DC4-82EC-C8AA392DCBC4_d0e60154_href.png Binary file Symbian3/SDK/Source/GUID-8BA0D643-5ED1-4DC4-82EC-C8AA392DCBC4_d0e60154_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8BA0D643-5ED1-4DC4-82EC-C8AA392DCBC4_d0e60783_href.png Binary file Symbian3/SDK/Source/GUID-8BA0D643-5ED1-4DC4-82EC-C8AA392DCBC4_d0e60783_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8BA0D643-5ED1-4DC4-82EC-C8AA392DCBC4_d0e61412_href.png Binary file Symbian3/SDK/Source/GUID-8BA0D643-5ED1-4DC4-82EC-C8AA392DCBC4_d0e61412_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8BA0D643-5ED1-4DC4-82EC-C8AA392DCBC4_d0e65577_href.png Binary file Symbian3/SDK/Source/GUID-8BA0D643-5ED1-4DC4-82EC-C8AA392DCBC4_d0e65577_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8BA0D643-5ED1-4DC4-82EC-C8AA392DCBC4_d0e68958_href.png Binary file Symbian3/SDK/Source/GUID-8BA0D643-5ED1-4DC4-82EC-C8AA392DCBC4_d0e68958_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8BA0D643-5ED1-4DC4-82EC-C8AA392DCBC4_d0e74100_href.png Binary file Symbian3/SDK/Source/GUID-8BA0D643-5ED1-4DC4-82EC-C8AA392DCBC4_d0e74100_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8C134C72-0552-59FE-AA19-F72250A8A947.dita --- a/Symbian3/SDK/Source/GUID-8C134C72-0552-59FE-AA19-F72250A8A947.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-8C134C72-0552-59FE-AA19-F72250A8A947.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,32 +1,37 @@ - - - - - -CustomControls: -custom control example -

              Note: This example only works properly with Techview and there -is no guarantee that it will work with other interfaces.

              -
              Description

              CustomControls demonstrates -customised simple and compound UI Control Framework control classes. Compound -controls are used as on-screen containers for other controls, either simple -or compound. The custom controls are subclasses of the class CCoeControl, -with implementations of its virtual functions for construction, drawing, and -accepting user input.

              Note that the CustomControls example -has dependencies on GUI components that may not be present on all SDKs.

              -
              Download

              Click on the following link to download -the example: CustomControls.zip

              Click: browse to view the example code.

              -
              Usage

              When the application starts, it displays -two smiling faces (smiley) controls. The mood of the smileys can be changed -by selecting a smiley using the left/right keys or pointer, and pressing space/clicking. -A dialog containing the smiley controls can be started from the application’s -menu.

              -
              Class Summary

              CCoeControl

              MCoeControlObserver

              CEikDialog

              CEikAppUi

              CEikDocument

              CEikApplication -

              + + + + + +CustomControls: custom control example +

              Note: This example only works properly with Techview and +there is no guarantee that it will work with other interfaces.

              +
              Description

              CustomControls demonstrates customised +simple and compound UI Control Framework control classes. Compound +controls are used as on-screen containers for other controls, either +simple or compound. The custom controls are subclasses of the class CCoeControl, with implementations of its virtual functions +for construction, drawing, and accepting user input.

              Note +that the CustomControls example has dependencies +on GUI components that may not be present on all SDKs.

              +
              Download

              Click on the following link to download the example: CustomControls.zip

              Click: browse to view the example code.

              +
              Usage

              When the application starts, it displays two smiling faces (smiley) +controls. The mood of the smileys can be changed by selecting a smiley +using the left/right keys or pointer, and pressing space/clicking. +A dialog containing the smiley controls can be started from the application’s +menu.

              +
              Class +Summary
                +

              • CCoeControl

                • +

              • MCoeControlObserver

                • +

              • CEikDialog

                • +

              • CEikAppUi

                • +

              • CEikDocument

                • +

              • CEikApplication

                • +
               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8C5A65E6-D753-472F-B885-FD0409589036.dita --- a/Symbian3/SDK/Source/GUID-8C5A65E6-D753-472F-B885-FD0409589036.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-8C5A65E6-D753-472F-B885-FD0409589036.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,117 +1,117 @@ - - - - - -HTTP -Whole Message Filter Example -

              The following diagram illustrates the class relationship between the MHTTPDataOptimiser interface -and the RHTTPSession class:

              - - Class relationship between MHTTPDataOptimiser and - RHTTPSession - - -

              For more information about MHTTPTransactionCallback, -see A simple HTTP Client -session.

              -

              The following code segment illustrates how to define the header file required -for implementing the HTTP Whole Message Filter APIs:

              -#include <http.h> - -class CMyHTTPClient: public CBase, - public MHTTPTransactionCallback, - public MHttpDataOptimiser -{ -public: // methods from MHTTPTransactionCallback - virtual void MHFRunL(RHTTPTransaction aTransaction, const THTTPEvent& aEvent); - virtual TInt MHFRunError(TInt aError, RHTTPTransaction aTransaction, const THTTPEvent& aEvent); - -public: // methods from MHttpDataOptimiser - virtual void EncodeL (const TDesC8& aHttpData, HBufC8*& aEncodedData); - virtual void DecodeL (const TDesC8& aData, HBufC8*& aHttpData, TBool& aTransFail); -}; -

              The following code segment illustrates how HTTP Whole Message Filter APIs -can be used to enable support for Web Acceleration:

              -#include "CMyHTTPClient.h" - -// CMyHTTPClient.cpp -// -// defines CMyHTTPClient class: CMyHTTPClient -// Literals used in the file -_LIT8(KHttpAuthenticationUrl, "http://remix.kwed.org"); - - -void CMyHTTPClient::CreateTransactionL() - { - TUriParser8 up; - up.Parse(KHttpAuthenticationUrl); - - RHTTPSession session; - RHTTPTransaction trans; - - // Open the HTTP session - session.OpenL(); - CleanupClosePushL(session); - - RStringPool strP = session.StringPool(); - - //To enable MHTTPDataOptimiser for transaction - - // Open a GET transaction, specifying this object as the request body data supplier - trans = session.OpenTransactionL(up, *this, strP.StringF(HTTP::EGET,RHTTPSession::GetTable())); - CleanupClosePushL(trans); - trans.SetupHttpDataOptimiser(*this); - - trans.SubmitL(); - CleanupStack::PopAndDestroy(&trans); - CActiveScheduler::Start(); - - CleanupStack::PopAndDestroy(&session); //Closes the session - - } - -TInt CMyHTTPClient::MHFRunError(TInt aError, RHTTPTransaction aTransaction, const THTTPEvent& aEvent) - { - // Handle Error appropriately - } - -void CMyHTTPClient::MHFRunL(RHTTPTransaction aTransaction, const THTTPEvent& aEvent) - { - // Handle events from the framework. - switch (aEvent.iStatus) - { - case KErrHttpOptimiserFailsTrans: - { - INFO_PRINTF1(_L("Cancelling/Failing Transaction\n")); - aTransaction.Fail(THTTPFilterHandle::EProtocolHandler); - } break; - - } - return; - //The following statement is used to eliminate leavescan errors - User::Leave(KErrGeneral); - } - -void CMyHTTPClient::EncodeL (const TDesC8& aHttpData, HBufC8* &aEncodedData) - { - //Provide your own custom encoding implementation - } - -void CMyHTTPClient::DecodeL (const TDesC8& aData, HBufC8*& aHttpData, TBool& aTransFail) - { - //Provide your own custom decoding implementation - } -

              This code enables the MHTTPDataOptimiser for a transaction -by using RHTTPTransaction::SetupHTTPDataOptimiser() and also -illustrates where custom encoding and decoding mechanisms are implemented.

              -

              Note: Alternatively, in this code, you can use the following code -segment to enable MHTTPDataOptimiser for a particular session.

              -

              session.SetupHttpDataOptimiser(*this);

              + + + + + +HTTP +Whole Message Filter Example +

              The following diagram illustrates the class relationship between the MHTTPDataOptimiser interface +and the RHTTPSession class:

              + + Class relationship between MHTTPDataOptimiser and + RHTTPSession + + +

              For more information about MHTTPTransactionCallback, +see A simple HTTP Client +session.

              +

              The following code segment illustrates how to define the header file required +for implementing the HTTP Whole Message Filter APIs:

              +#include <http.h> + +class CMyHTTPClient: public CBase, + public MHTTPTransactionCallback, + public MHttpDataOptimiser +{ +public: // methods from MHTTPTransactionCallback + virtual void MHFRunL(RHTTPTransaction aTransaction, const THTTPEvent& aEvent); + virtual TInt MHFRunError(TInt aError, RHTTPTransaction aTransaction, const THTTPEvent& aEvent); + +public: // methods from MHttpDataOptimiser + virtual void EncodeL (const TDesC8& aHttpData, HBufC8*& aEncodedData); + virtual void DecodeL (const TDesC8& aData, HBufC8*& aHttpData, TBool& aTransFail); +}; +

              The following code segment illustrates how HTTP Whole Message Filter APIs +can be used to enable support for Web Acceleration:

              +#include "CMyHTTPClient.h" + +// CMyHTTPClient.cpp +// +// defines CMyHTTPClient class: CMyHTTPClient +// Literals used in the file +_LIT8(KHttpAuthenticationUrl, "http://remix.kwed.org"); + + +void CMyHTTPClient::CreateTransactionL() + { + TUriParser8 up; + up.Parse(KHttpAuthenticationUrl); + + RHTTPSession session; + RHTTPTransaction trans; + + // Open the HTTP session + session.OpenL(); + CleanupClosePushL(session); + + RStringPool strP = session.StringPool(); + + //To enable MHTTPDataOptimiser for transaction + + // Open a GET transaction, specifying this object as the request body data supplier + trans = session.OpenTransactionL(up, *this, strP.StringF(HTTP::EGET,RHTTPSession::GetTable())); + CleanupClosePushL(trans); + trans.SetupHttpDataOptimiser(*this); + + trans.SubmitL(); + CleanupStack::PopAndDestroy(&trans); + CActiveScheduler::Start(); + + CleanupStack::PopAndDestroy(&session); //Closes the session + + } + +TInt CMyHTTPClient::MHFRunError(TInt aError, RHTTPTransaction aTransaction, const THTTPEvent& aEvent) + { + // Handle Error appropriately + } + +void CMyHTTPClient::MHFRunL(RHTTPTransaction aTransaction, const THTTPEvent& aEvent) + { + // Handle events from the framework. + switch (aEvent.iStatus) + { + case KErrHttpOptimiserFailsTrans: + { + INFO_PRINTF1(_L("Cancelling/Failing Transaction\n")); + aTransaction.Fail(THTTPFilterHandle::EProtocolHandler); + } break; + + } + return; + //The following statement is used to eliminate leavescan errors + User::Leave(KErrGeneral); + } + +void CMyHTTPClient::EncodeL (const TDesC8& aHttpData, HBufC8* &aEncodedData) + { + //Provide your own custom encoding implementation + } + +void CMyHTTPClient::DecodeL (const TDesC8& aData, HBufC8*& aHttpData, TBool& aTransFail) + { + //Provide your own custom decoding implementation + } +

              This code enables the MHTTPDataOptimiser for a transaction +by using RHTTPTransaction::SetupHTTPDataOptimiser() and also +illustrates where custom encoding and decoding mechanisms are implemented.

              +

              Note: Alternatively, in this code, you can use the following code +segment to enable MHTTPDataOptimiser for a particular session.

              +

              session.SetupHttpDataOptimiser(*this);

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8C8D6B06-E794-4269-B4DF-D2BE4DDB9E8B_d0e38310_href.png Binary file Symbian3/SDK/Source/GUID-8C8D6B06-E794-4269-B4DF-D2BE4DDB9E8B_d0e38310_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8C8D6B06-E794-4269-B4DF-D2BE4DDB9E8B_d0e43877_href.png Binary file Symbian3/SDK/Source/GUID-8C8D6B06-E794-4269-B4DF-D2BE4DDB9E8B_d0e43877_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8CCA308A-5302-4D95-8E60-DA75D8B6DC41-master.png Binary file Symbian3/SDK/Source/GUID-8CCA308A-5302-4D95-8E60-DA75D8B6DC41-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8CCA308A-5302-4D95-8E60-DA75D8B6DC41_d0e51707_href.png Binary file Symbian3/SDK/Source/GUID-8CCA308A-5302-4D95-8E60-DA75D8B6DC41_d0e51707_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8CCA308A-5302-4D95-8E60-DA75D8B6DC41_d0e57262_href.png Binary file Symbian3/SDK/Source/GUID-8CCA308A-5302-4D95-8E60-DA75D8B6DC41_d0e57262_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8CCA308A-5302-4D95-8E60-DA75D8B6DC41_d0e57411_href.png Binary file Symbian3/SDK/Source/GUID-8CCA308A-5302-4D95-8E60-DA75D8B6DC41_d0e57411_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8CCA308A-5302-4D95-8E60-DA75D8B6DC41_d0e61778_href.png Binary file Symbian3/SDK/Source/GUID-8CCA308A-5302-4D95-8E60-DA75D8B6DC41_d0e61778_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8CCA308A-5302-4D95-8E60-DA75D8B6DC41_d0e68938_href.png Binary file Symbian3/SDK/Source/GUID-8CCA308A-5302-4D95-8E60-DA75D8B6DC41_d0e68938_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8CCA308A-5302-4D95-8E60-DA75D8B6DC41_d0e74080_href.png Binary file Symbian3/SDK/Source/GUID-8CCA308A-5302-4D95-8E60-DA75D8B6DC41_d0e74080_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8CF0C00C-0FDF-517E-96FB-84F718237F61_d0e252803_href.jpg Binary file Symbian3/SDK/Source/GUID-8CF0C00C-0FDF-517E-96FB-84F718237F61_d0e252803_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8CF0C00C-0FDF-517E-96FB-84F718237F61_d0e256511_href.jpg Binary file Symbian3/SDK/Source/GUID-8CF0C00C-0FDF-517E-96FB-84F718237F61_d0e256511_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8D046AD9-1D28-52AE-8B69-2CBF6441F733_d0e190606_href.png Binary file Symbian3/SDK/Source/GUID-8D046AD9-1D28-52AE-8B69-2CBF6441F733_d0e190606_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8D046AD9-1D28-52AE-8B69-2CBF6441F733_d0e195614_href.png Binary file Symbian3/SDK/Source/GUID-8D046AD9-1D28-52AE-8B69-2CBF6441F733_d0e195614_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8D130FC5-3AB8-5C70-A9D2-C753957E729F.dita --- a/Symbian3/SDK/Source/GUID-8D130FC5-3AB8-5C70-A9D2-C753957E729F.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-8D130FC5-3AB8-5C70-A9D2-C753957E729F.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,22 +1,21 @@ - - - - - -S60 -Platform: DBMS ExampleThis is an example of database manipulation using the DBMS. -
              Description

              The -DBMS (Database Management System) example application demonstrates the usage -of DBMS APIs. The example includes a bookstore database engine and a simple -Avkon GUI for testing the engine. The example has been tested to support S60 -5th Edition and touch UI. Main classes: RDbStoreDatabase, RFs. For more details, -look into this link : DBMS Example

              -
              Download

              Download -the example: DBMS.zip

              View the source code: browse.

              + + + + + +DBMS +ExampleThis is an example of database manipulation using the DBMS. +
              Description

              The +DBMS (Database Management System) example application demonstrates the usage +of DBMS APIs. The example includes a bookstore database engine and a simple +Avkon GUI for testing the engine.

              +
              Download

              Download +the example: DBMS.zip

              View the source code: browse.

              +
              Class Summary

              RDbStoreDatabase

              RFs

               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8D4AD37E-6B96-5B82-8313-F88D97531DEC.dita --- a/Symbian3/SDK/Source/GUID-8D4AD37E-6B96-5B82-8313-F88D97531DEC.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-8D4AD37E-6B96-5B82-8313-F88D97531DEC.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,55 +1,55 @@ - - - - - -Types -of packageDescribes the three types of package descriptors. -

              Three types of package are available:

              -
                -

              • a packaged modifiable -buffer descriptor

                • -

              • a packaged non-modifiable -pointer descriptor

                • -

              • a packaged modifiable -pointer descriptor

                • -
              -
              Packaged modifiable buffer descriptor

              This is an -object of type TPckgBuf and is a modifiable buffer descriptor. -The class is templated; the template parameter defines the type of object -that this descriptor can contain.

              For example, a package descriptor -of type TPckgBuf<TExample> is a modifiable buffer descriptor -that only contains objects of type TExample.

              The package -class also allows functions to be called on the contained class.

              - -
              -
              Packaged non-modifiable pointer descriptor

              This -is an object of type TPckgC and is a non-modifiable pointer -descriptor. The class is templated; the template parameter defines the type -of object that this descriptor can represent.

              For example, a package -descriptor of type TPckgC<TExample> is a non- modifiable -pointer descriptor that only represents objects of type TExample.

              The -package class also allows functions to be called on the contained class.

              - -
              -
              Packaged modifiable pointer descriptor

              This is -an object of type TPckg and is a modifiable pointer descriptor. -The class is templated; the template parameter defines the type of object -that this descriptor can represent.

              For example, a package descriptor -of type TPckg<TExample> is a modifiable pointer descriptor -that only represents objects of type TExample.

              The -package class also allows functions to be called on the contained class.

              - -
              -
              See also

              TBuf

              TPtrC

              TPtr

              -               - -Descriptor concepts - + + + + + +Types +of packageDescribes the three types of package descriptors. +

              Three types of package are available:

              +
                +

              • a packaged modifiable +buffer descriptor

                • +

              • a packaged non-modifiable +pointer descriptor

                • +

              • a packaged modifiable +pointer descriptor

                • +
              +
              Packaged modifiable buffer descriptor

              This is an +object of type TPckgBuf and is a modifiable buffer descriptor. +The class is templated; the template parameter defines the type of object +that this descriptor can contain.

              For example, a package descriptor +of type TPckgBuf<TExample> is a modifiable buffer descriptor +that only contains objects of type TExample.

              The package +class also allows functions to be called on the contained class.

              + +
              +
              Packaged non-modifiable pointer descriptor

              This +is an object of type TPckgC and is a non-modifiable pointer +descriptor. The class is templated; the template parameter defines the type +of object that this descriptor can represent.

              For example, a package +descriptor of type TPckgC<TExample> is a non- modifiable +pointer descriptor that only represents objects of type TExample.

              The +package class also allows functions to be called on the contained class.

              + +
              +
              Packaged modifiable pointer descriptor

              This is +an object of type TPckg and is a modifiable pointer descriptor. +The class is templated; the template parameter defines the type of object +that this descriptor can represent.

              For example, a package descriptor +of type TPckg<TExample> is a modifiable pointer descriptor +that only represents objects of type TExample.

              The +package class also allows functions to be called on the contained class.

              + +
              +
              See also

              TBuf

              TPtrC

              TPtr

              +               + +Descriptor concepts +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8D51B706-6941-5043-B435-1CAFBAE5A8F2_d0e396870_href.jpg Binary file Symbian3/SDK/Source/GUID-8D51B706-6941-5043-B435-1CAFBAE5A8F2_d0e396870_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8D51B706-6941-5043-B435-1CAFBAE5A8F2_d0e397032_href.jpg Binary file Symbian3/SDK/Source/GUID-8D51B706-6941-5043-B435-1CAFBAE5A8F2_d0e397032_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8D5FFAE9-7E8A-5144-B0CC-B56A34D42A3F_d0e220696_href.png Binary file Symbian3/SDK/Source/GUID-8D5FFAE9-7E8A-5144-B0CC-B56A34D42A3F_d0e220696_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8D5FFAE9-7E8A-5144-B0CC-B56A34D42A3F_d0e224433_href.png Binary file Symbian3/SDK/Source/GUID-8D5FFAE9-7E8A-5144-B0CC-B56A34D42A3F_d0e224433_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8D7AEB5A-9A88-5B6D-B6B0-7126A56AA495.dita --- a/Symbian3/SDK/Source/GUID-8D7AEB5A-9A88-5B6D-B6B0-7126A56AA495.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-8D7AEB5A-9A88-5B6D-B6B0-7126A56AA495.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,213 +1,213 @@ - - - - - -Versit -Overview -

              This topic describes the Versit component, which can be used to import -and export contact and calendar information.

              -
              Purpose

              The -Versit component provides a set of classes that can be used by application -or system developers, to import and export data formatted according to a set -of standards initially prescribed by the Versit consortium.

              The plain-text -formatted data can be included in emails, saved to disk or transferred from -one application to another using streams. Two specifications have been published, -one for the transmission of contact information and the other for the transmission -of calendaring information in the form of vCards and vCalendars.

              Although -the information contained in vCard is different from that contained in vCalendar, -the basic formatting of the information follows the same style.

              -
              Required background

              Some -knowledge of vCard and vCalendar specifications, which are documented on the -Internet Mail Consortium's website at http://www.imc.org.

              -
              Key concepts

              In -this component a vCard or vCalendar is referred to as an entity. An entity -has an array of properties. Entities can be nested, making them sub-entities.

              The -component has the following key concepts:

              - -
              Parser
              -

              The parser converts the vCard and vCal data into a format understandable -by the current system and vice-a-versa. The vCard and vCal are common standards -used for exchanging contact and calendar data across different systems such -as handheld devices, PDA and so on. Each handheld device or PDA store and -interpret these kind of personal information in their own way. A parser reads -and writes properties and sub-entities for an entity. The base class for parsers -is provided by CVersitParser which provides the basic functionality -for both vCard and vCal.

              The CVersitParser class -is extended to provide separate implementations for vCard, vCal and their -sub-entities such as vEvent, vTodo and so on. The following are few such classes:

                -

              • CParserVCard is -a vCard parser that converts between a vCard entities, stored in a stream -using the format standard set by the Internet Mail Consortium, and a vCard -entities stored on a Symbian phone.

                • -

              • CParserVCal is -a vCalendar parser that converts between a vCalendar entities stored in a -stream, and vCalender entities stored on a Symbian phone.

                • -

              • CParserVCalEntity is -a parser for vCalendar sub-entities such as, events and to-do lists.

                • -

              The CVersitParser class provides support for vCard -version 2.1 and vCalendar version 1.0 by default. But this class is not compatible -with higher versions of vCard, and these compatibility issues are addressed -in MVersitPlugIn abstract class. An implementation of MVersitPlugIn class -along with a derived class of CParserVCard can extend the -parser support to vCard versions above 2.1.

              -               - -
              Property
              -

              A property consists of a property name, a property value and optionally -one or more property parameters. They have the general form:

              Property Name (; Parameter Name(= Parameter Value))* : Property Value

              where -items in brackets are optional and * indicates that the item may be repeated.

              For -example,

              TEL; HOME; ENCODING=QUOTED-PRINTABLE; CHARSET=US-ASCII : 01234 567890

              Here, TEL is the property name, HOME, ENCODING and CHARSET are property -parameter names and QUOTED-PRINTABLE and US-ASCII are property parameter values. -The component following the colon is the property value.

              The property -interface is provided by CParserProperty.

              -               - -
              Property parameter
              -

              A property parameter describes an aspect of a property. A property -may have multiple aspects. In the above example the TEL property has several -aspects (parameters), such as HOME, ENCODING and CHARSET with their associated -values QUOTED-PRINTABLE and US-ASCII.

              The property parameter interface -is provided by CParserParam.

              -               - -
              Property value
              -

              A property value may be of any type, such as date/time, integer, string -etc.

              A number of classes are provided to support any type of data -as a property value, these classes are derived from CParserPropertyValue.

              -               - -
              Observer
              -

              The versit parser observer can find out the version of the entity being -parsed, which is the version number of the vCard/vCalendar. Then the behaviour -of the parser is adjusted according to the version number detected. The observer -is implemented as a pure virtual plug-in class MVersitObserver, -for use in conjunction with MVersitPlugIn class.

              The -implementor of MVersitObserver class can respond to new parser -creation by setting MVersitPlugIn as the parser, and itself -as the observer to parse the embedded sub-entity.

              -               -
              -
              Architectural -relationships

              Any application or system intending to import or -export vCards or vCalendars can use this component. At present, it is used -by Contacts Model and Calendar components -to support import and export of contact and calendar information.

              The -Versit libraries export a set of utility classes that allow clients to parse -and generate data formatted according to the specifications first published -by the Versit consortium (The specifications are now owned by the IMC).

              In -broad terms, the Versit API allows clients to:

                -

              • Internalise Versit formatted -data into container classes.

                • -

              • Externalise contact -and calendar data.

                • -

              • Derive a custom Versit -parser from the base classes.

                • -

              • Perform various utility -functions (searching, modifying etc.) on the data.

                • -

              It delivers four files:

                -

              • Versit.dll - defines -the client API common to all versit parser.

                • -

              • VCard.dll - implements -a vCard v2.1 parser & generator.

                • -

              • VCal.dll - implements -a vCalendar 1.0 parser & generator.

                • -

              • RVERSIT.MDL - implements -a Recognizer which recognises Versit vCalendar and vCard files and reports -their file type. This is according to the standard Symbian file recognizer -pattern. For more information about recognizers, refer to Using -MIME.

                • -

              Internal Relationships

              The Versit libraries are designed -to provide a self contained set of tools. As such, they have no internal dependencies -with other App-Services components. The diagram below gives an abstract illustration -of the internal dependencies of the Versit components themselves.

              - Abstraction of Versit deliverables - -

              As the diagram above illustrates, it is possible to make use of -the Versit.dll library on its own. If vCard or vCalendar support is required -then the Versit library must be included as both vCard.dll and vCal.dll depend -on it.

              It is also possible for users to develop their own Versit parsers -using the base classes provided in Versit.dll and not include the vCard and -vCalendar libraries.

              External Relationships

              It is possible for any third party -code to make use of the Versit libraries. The only Symbian components that -have a dependency on Versit are the App-Engines. The application engines provide -API’s which allow their users to import and export Versit formatted data.

              The -mechanism used to allow these operations differs depending on the application -engine and the documentation associated to each should be referred to for -more detail. The two application engines that make use of Versit are the Contacts Model and Calendar components.

              -
              API summary - Relationship between different classes of the Versit -component - - - - - -Class Name -Description - - - - -

              CVersitParser

              -

              This is a generic parser class which provides functions implementing -behaviour common to both vCalendar and vCard parsers.

              -               - -

              CParserVCard

              -

              This is a vCard parser class derived from CVersitParser. -It implements additional functionality needed to parse vCards, other than -the generic functionality inherited from CVersitParser.

              -               - -

              CParserVCal

              -

              This is a vCalendar parser class derived from CVersitParser. -It also implements additional functionality needed to parse vCalendar, other -than the generic functionality inherited from CVersitParser.

              -               - -

              CParserVCalEntity

              -

              This is a parser for vCalendar sub-entities. A vCalendar sub-entity -is a vEvent or vToDo contained in a vCalendar. vEvents and vToDos are derived -from CRecurrenceParser, which provides recurrence functionality.

              -               - -

              CParserProperty

              -

              This is a property class used to store properties of vCard and vCalendar, -and also sub-entities of vCalendar such as vEvent and vToDo. Each property -has a name, an optional value and one or more optional parameters.

              -               - - -
              -
              Typical uses

              The -Versit component can be used by any application which needs to import or export -vCards or vCalendars. The following are the typical use cases for this API.

              Importing contact and calendar data

              Any application can import -contact and/or calendar data using this API. To import contact or calendar -data from an external source, the client has to make use of appropriate parsers. -That is, vCard parser to import contact data, and vCalendar parser to import -calendar data. For more information, refer to How -to Import Contact and Calendar Data.

              Exporting contact and calendar data

              Any application can export -contact and/or calendar data using this API. To export contact or calendar -data to an external source, clients have to make use of appropriate parsers. -That is, vCard parser to export contact data, and vCalendar parser to export -calendar data. For more information, refer to How -to Export Contact and Calendar Data.

              Creating a custom Versit parser

              Apart from the typical vCard -and vCalendar parsers, custom versit parser can be implemented using the CVersitParser class -as the base class. These kind of parsers are needed, when the functionality -provided by CVersitParser, CParserVCard and CParserVCal classes -are not sufficient.

              Using various utility functions

              In addition to the normal -import and export functionality, the client applications can use these APIs -for character set conversions and to parse character strings using the VersitUtils class.

              -               -Contacts -Model Overview -Calendar -Overview + + + + + +Versit +Overview +

              This topic describes the Versit component, which can be used to import +and export contact and calendar information.

              +
              Purpose

              The +Versit component provides a set of classes that can be used by application +or system developers, to import and export data formatted according to a set +of standards initially prescribed by the Versit consortium.

              The plain-text +formatted data can be included in emails, saved to disk or transferred from +one application to another using streams. Two specifications have been published, +one for the transmission of contact information and the other for the transmission +of calendaring information in the form of vCards and vCalendars.

              Although +the information contained in vCard is different from that contained in vCalendar, +the basic formatting of the information follows the same style.

              +
              Required background

              Some +knowledge of vCard and vCalendar specifications, which are documented on the +Internet Mail Consortium's website at http://www.imc.org.

              +
              Key concepts

              In +this component a vCard or vCalendar is referred to as an entity. An entity +has an array of properties. Entities can be nested, making them sub-entities.

              The +component has the following key concepts:

              + +
              Parser
              +

              The parser converts the vCard and vCal data into a format understandable +by the current system and vice-a-versa. The vCard and vCal are common standards +used for exchanging contact and calendar data across different systems such +as handheld devices, PDA and so on. Each handheld device or PDA store and +interpret these kind of personal information in their own way. A parser reads +and writes properties and sub-entities for an entity. The base class for parsers +is provided by CVersitParser which provides the basic functionality +for both vCard and vCal.

              The CVersitParser class +is extended to provide separate implementations for vCard, vCal and their +sub-entities such as vEvent, vTodo and so on. The following are few such classes:

                +

              • CParserVCard is +a vCard parser that converts between a vCard entities, stored in a stream +using the format standard set by the Internet Mail Consortium, and a vCard +entities stored on a Symbian phone.

                • +

              • CParserVCal is +a vCalendar parser that converts between a vCalendar entities stored in a +stream, and vCalender entities stored on a Symbian phone.

                • +

              • CParserVCalEntity is +a parser for vCalendar sub-entities such as, events and to-do lists.

                • +

              The CVersitParser class provides support for vCard +version 2.1 and vCalendar version 1.0 by default. But this class is not compatible +with higher versions of vCard, and these compatibility issues are addressed +in MVersitPlugIn abstract class. An implementation of MVersitPlugIn class +along with a derived class of CParserVCard can extend the +parser support to vCard versions above 2.1.

              +               + +
              Property
              +

              A property consists of a property name, a property value and optionally +one or more property parameters. They have the general form:

              Property Name (; Parameter Name(= Parameter Value))* : Property Value

              where +items in brackets are optional and * indicates that the item may be repeated.

              For +example,

              TEL; HOME; ENCODING=QUOTED-PRINTABLE; CHARSET=US-ASCII : 01234 567890

              Here, TEL is the property name, HOME, ENCODING and CHARSET are property +parameter names and QUOTED-PRINTABLE and US-ASCII are property parameter values. +The component following the colon is the property value.

              The property +interface is provided by CParserProperty.

              +               + +
              Property parameter
              +

              A property parameter describes an aspect of a property. A property +may have multiple aspects. In the above example the TEL property has several +aspects (parameters), such as HOME, ENCODING and CHARSET with their associated +values QUOTED-PRINTABLE and US-ASCII.

              The property parameter interface +is provided by CParserParam.

              +               + +
              Property value
              +

              A property value may be of any type, such as date/time, integer, string +etc.

              A number of classes are provided to support any type of data +as a property value, these classes are derived from CParserPropertyValue.

              +               + +
              Observer
              +

              The versit parser observer can find out the version of the entity being +parsed, which is the version number of the vCard/vCalendar. Then the behaviour +of the parser is adjusted according to the version number detected. The observer +is implemented as a pure virtual plug-in class MVersitObserver, +for use in conjunction with MVersitPlugIn class.

              The +implementor of MVersitObserver class can respond to new parser +creation by setting MVersitPlugIn as the parser, and itself +as the observer to parse the embedded sub-entity.

              +               +
              +
              Architectural +relationships

              Any application or system intending to import or +export vCards or vCalendars can use this component. At present, it is used +by Contacts Model and Calendar components +to support import and export of contact and calendar information.

              The +Versit libraries export a set of utility classes that allow clients to parse +and generate data formatted according to the specifications first published +by the Versit consortium (The specifications are now owned by the IMC).

              In +broad terms, the Versit API allows clients to:

                +

              • Internalise Versit formatted +data into container classes.

                • +

              • Externalise contact +and calendar data.

                • +

              • Derive a custom Versit +parser from the base classes.

                • +

              • Perform various utility +functions (searching, modifying etc.) on the data.

                • +

              It delivers four files:

                +

              • Versit.dll - defines +the client API common to all versit parser.

                • +

              • VCard.dll - implements +a vCard v2.1 parser & generator.

                • +

              • VCal.dll - implements +a vCalendar 1.0 parser & generator.

                • +

              • RVERSIT.MDL - implements +a Recognizer which recognises Versit vCalendar and vCard files and reports +their file type. This is according to the standard Symbian file recognizer +pattern. For more information about recognizers, refer to Using +MIME.

                • +

              Internal Relationships

              The Versit libraries are designed +to provide a self contained set of tools. As such, they have no internal dependencies +with other App-Services components. The diagram below gives an abstract illustration +of the internal dependencies of the Versit components themselves.

              + Abstraction of Versit deliverables + +

              As the diagram above illustrates, it is possible to make use of +the Versit.dll library on its own. If vCard or vCalendar support is required +then the Versit library must be included as both vCard.dll and vCal.dll depend +on it.

              It is also possible for users to develop their own Versit parsers +using the base classes provided in Versit.dll and not include the vCard and +vCalendar libraries.

              External Relationships

              It is possible for any third party +code to make use of the Versit libraries. The only Symbian components that +have a dependency on Versit are the App-Engines. The application engines provide +API’s which allow their users to import and export Versit formatted data.

              The +mechanism used to allow these operations differs depending on the application +engine and the documentation associated to each should be referred to for +more detail. The two application engines that make use of Versit are the Contacts Model and Calendar components.

              +
              API summary + Relationship between different classes of the Versit +component + + + + + +Class Name +Description + + + + +

              CVersitParser

              +

              This is a generic parser class which provides functions implementing +behaviour common to both vCalendar and vCard parsers.

              +               + +

              CParserVCard

              +

              This is a vCard parser class derived from CVersitParser. +It implements additional functionality needed to parse vCards, other than +the generic functionality inherited from CVersitParser.

              +               + +

              CParserVCal

              +

              This is a vCalendar parser class derived from CVersitParser. +It also implements additional functionality needed to parse vCalendar, other +than the generic functionality inherited from CVersitParser.

              +               + +

              CParserVCalEntity

              +

              This is a parser for vCalendar sub-entities. A vCalendar sub-entity +is a vEvent or vToDo contained in a vCalendar. vEvents and vToDos are derived +from CRecurrenceParser, which provides recurrence functionality.

              +               + +

              CParserProperty

              +

              This is a property class used to store properties of vCard and vCalendar, +and also sub-entities of vCalendar such as vEvent and vToDo. Each property +has a name, an optional value and one or more optional parameters.

              +               + + +
              +
              Typical uses

              The +Versit component can be used by any application which needs to import or export +vCards or vCalendars. The following are the typical use cases for this API.

              Importing contact and calendar data

              Any application can import +contact and/or calendar data using this API. To import contact or calendar +data from an external source, the client has to make use of appropriate parsers. +That is, vCard parser to import contact data, and vCalendar parser to import +calendar data. For more information, refer to How +to Import Contact and Calendar Data.

              Exporting contact and calendar data

              Any application can export +contact and/or calendar data using this API. To export contact or calendar +data to an external source, clients have to make use of appropriate parsers. +That is, vCard parser to export contact data, and vCalendar parser to export +calendar data. For more information, refer to How +to Export Contact and Calendar Data.

              Creating a custom Versit parser

              Apart from the typical vCard +and vCalendar parsers, custom versit parser can be implemented using the CVersitParser class +as the base class. These kind of parsers are needed, when the functionality +provided by CVersitParser, CParserVCard and CParserVCal classes +are not sufficient.

              Using various utility functions

              In addition to the normal +import and export functionality, the client applications can use these APIs +for character set conversions and to parse character strings using the VersitUtils class.

              +               +Contacts +Model Overview +Calendar +Overview               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8D8202BB-1070-5EE2-85C0-E37AABA67340-GENID-1-8-1-18-1-1-4-1-9-1.dita --- a/Symbian3/SDK/Source/GUID-8D8202BB-1070-5EE2-85C0-E37AABA67340-GENID-1-8-1-18-1-1-4-1-9-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,28 +0,0 @@ - - - - - -MmfExCodec: -Multimedia Framework codec plug-in example -
              Description

              MmfExCodec demonstrates -how to implement a codec plug-in for the Multimedia Framework. A codec converts -media data in one encoding into another encoding. The example converts audio -data encoded with PCM8 into PCM16.

              The program is an ECom plug-in -that implements the codec interface CMMFCodec by the class CMMFExPcm8Pcm16Codec. -When a client or media format requires a PCM8 to PCM16 codec, the Multimedia -Framework will instantiate a CMMFExPcm8Pcm16Codec object, -and call its ProcessL() member function to convert data supplied -a source buffer. As converting PCM8 into PCM16 only requires expanding each -byte in the source buffer into two bytes in the destination buffer, CMMFExPcm8Pcm16Codec::ProcessL() is -not very complex.

              -
              Download

              Click -on the following link to download the example: MmfExCodec.zip file

              Click: browse to view the example code.

              -
              Class summary

              CMMFCodec CMMFDataBuffer

              -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8D8202BB-1070-5EE2-85C0-E37AABA67340-GENID-1-8-1-18-1-1-5-1-7-1-6-1-5-1.dita --- a/Symbian3/SDK/Source/GUID-8D8202BB-1070-5EE2-85C0-E37AABA67340-GENID-1-8-1-18-1-1-5-1-7-1-6-1-5-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,28 +0,0 @@ - - - - - -MmfExCodec: -Multimedia Framework codec plug-in example -
              Description

              MmfExCodec demonstrates -how to implement a codec plug-in for the Multimedia Framework. A codec converts -media data in one encoding into another encoding. The example converts audio -data encoded with PCM8 into PCM16.

              The program is an ECom plug-in -that implements the codec interface CMMFCodec by the class CMMFExPcm8Pcm16Codec. -When a client or media format requires a PCM8 to PCM16 codec, the Multimedia -Framework will instantiate a CMMFExPcm8Pcm16Codec object, -and call its ProcessL() member function to convert data supplied -a source buffer. As converting PCM8 into PCM16 only requires expanding each -byte in the source buffer into two bytes in the destination buffer, CMMFExPcm8Pcm16Codec::ProcessL() is -not very complex.

              -
              Download

              Click -on the following link to download the example: MmfExCodec.zip file

              Click: browse to view the example code.

              -
              Class summary

              CMMFCodec CMMFDataBuffer

              -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8D8202BB-1070-5EE2-85C0-E37AABA67340.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-8D8202BB-1070-5EE2-85C0-E37AABA67340.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,28 @@ + + + + + +MmfExCodec: +Multimedia Framework codec plug-in example +
              Description

              MmfExCodec demonstrates +how to implement a codec plug-in for the Multimedia Framework. A codec converts +media data in one encoding into another encoding. The example converts audio +data encoded with PCM8 into PCM16.

              The program is an ECom plug-in +that implements the codec interface CMMFCodec by the class CMMFExPcm8Pcm16Codec. +When a client or media format requires a PCM8 to PCM16 codec, the Multimedia +Framework will instantiate a CMMFExPcm8Pcm16Codec object, +and call its ProcessL() member function to convert data supplied +a source buffer. As converting PCM8 into PCM16 only requires expanding each +byte in the source buffer into two bytes in the destination buffer, CMMFExPcm8Pcm16Codec::ProcessL() is +not very complex.

              +
              Download

              Click +on the following link to download the example: MmfExCodec.zip file

              Click: browse to view the example code.

              +
              Class summary

              CMMFCodec CMMFDataBuffer

              +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8D9FE811-3F8A-5C2A-B76A-5C0248179590_d0e336582_href.jpg Binary file Symbian3/SDK/Source/GUID-8D9FE811-3F8A-5C2A-B76A-5C0248179590_d0e336582_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8D9FE811-3F8A-5C2A-B76A-5C0248179590_d0e342779_href.jpg Binary file Symbian3/SDK/Source/GUID-8D9FE811-3F8A-5C2A-B76A-5C0248179590_d0e342779_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8DB1C618-597C-560C-95A2-C0AB2CEBB027.dita --- a/Symbian3/SDK/Source/GUID-8DB1C618-597C-560C-95A2-C0AB2CEBB027.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-8DB1C618-597C-560C-95A2-C0AB2CEBB027.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,16 +1,140 @@ - - - - - -Redraw DrawingThis topic provides background information about redraw drawing and tips for updating old code to comply with the recommendation that all drawing is migrated to redraw drawing.

              Variant: Both (ScreenPlay and non-ScreenPlay). Target audience: Application developers.

              About Redraw Drawing

              Symbian recommends that all CWindowGc drawing is redraw drawing, which means that it takes place between RWindow::BeginRedraw() and RWindow::EndRedraw() calls. The UI Control Framework (CONE) automatically takes care of this for you if you use the CCoeControl::DrawNow() and CCoeControl::DrawDeferred() methods.

              For example, suppose an application wants to write the text "Hello!" to a window and then add a red diagonal line below it (A in following diagram). When this is performed as redraw drawing, the application calculates the bounding rectangles of the "Hello!" text and the red line (B). For each one, the application passes the rectangle to RWindow::BeginRedraw(const - TRect&), then calls the draw commands and afterwards calls RWindow::EndRedraw().

              This has the advantage that the Window Server knows that the area of the window that has the "Hello!" text is not affected by the drawing of the red line. There are also advantages when some or all of the window needs to be repainted. For example, suppose another window (such as an OK dialog box) appears above the window (as shown in C). When the dialog box is closed, the Window Server repaints the screen behind the dialog box. Because in this example the OK dialog box was entirely within the red line's bounding rectangle, the Window Server simply replays that rectangle's drawing operations (D). This is more efficient than repainting the whole window.

              However, in earlier versions of Symbian you could, for example, draw the red line without bracketing it within BeginRedraw() and EndRedraw() calls. This is called non-redraw drawing. In ScreenPlay, each non-redraw drawing operation triggers the Window Server to invalidate the entire window. This means that the client application must then perform a full window redraw, as shown in the next diagram.

              - Non-redraw drawing sequence -

              This is less efficient than the Window Server replaying the draw operations for the affected area.

              Symbian recommends that all drawing is now performed as redraw drawing. Typically this involves dividing the window up into rectangular areas that represent different aspects of the user interface—for example, as shown in the following diagram. If anything spoils the screen, the Window Server then only needs to redraw the corresponding portions of the user interface.

              In earlier versions of Symbian, before the introduction of the CCoeControl::DrawNow(TRect&) overload, developers sometimes used non-redraw drawing to update a small part of a control. This technique has often been used for virtual keyboards and calendar controls. This type of use case is now particularly unsuited to non-redraw drawing because in ScreenPlay each non-redraw drawing command triggers a server-initiated client redraw of the entire window. This can be very slow if the window requires many drawing operations to redraw the scene.

              Symbian recommends that all non-redraw drawing is changed to redraw drawing. Sometimes this causes some subtle changes in behavior, as explained below.

              Restrictions

              1. You must supply only drawing operations between the BeginRedraw() and EndRedraw() calls. For example, you must not change the window extent between a BeginRedraw() and EndRedraw() call.

              2. You must not call any functions that can leave between the BeginRedraw() and EndRedraw() calls. This is because drawing operations must never leave.

              Note: A redrawer's RunL() function must never perform any non-redraw drawing. See Server-Initiated vs. Application-Initiated Redrawing for more information.

              Tips for migrating old code

              Migrating non-redraw drawing to redraw drawing means that you must enclose all drawing operations between RWindow::BeginRedraw() and RWindow::EndRedraw() calls or migrate it to use the CCoeControl::DrawNow() and CCoeControl::DrawDeferred() methods. The main points to note are provided below under separate subheadings.

              Performance

              You can improve performance by passing the smallest possible bounding rectangle to the RWindow::BeginRedraw() and CCoeControl::DrawNow() methods. If this still results in poor performance, because, for example, there is a large amount of incremental screen updating, the recommended solution in ScreenPlay is to render to a surface.

              Delay of execution

              After you migrate non-redraw drawing to redraw drawing, the execution of the drawing operations is deferred compared to previously. This means that if the arguments of the drawing operations result in a panic, the panic also appears later than before.

              CRemoteGc usage

              Device creators can use CRemoteGc to create a data buffer containing a series of drawing operations. These can then be executed to display the drawing on the screen by using CCommandBuffer::Play().

              For example, consider a weather program that has one sub-system responsible for deciding the drawing operations that comprise a weather symbol and another sub-system that places weather symbols at different locations on the screen. Here we potentially have a Cloud symbol buffer created once and played many times.

              The points to note are:

              • Any BeginRedraw() and EndRedraw() commands that are placed into the CRemoteGc buffer are not transferred to the target window when the buffer is played

              • You must bracket any call to CCommandBuffer::Play() within BeginRedraw() and EndRedraw() calls.

              It may be puzzling to understand why any BeginRedraw() and EndRedraw() commands would be placed in the CRemoteGc buffer at all. This facility is to allow the commands already in the CRemoteGc buffer to be replaced with new drawing operations. In the weather example, it might be done to allow a "7o Celsius" label to partially occlude a cloud graphic placed earlier into the CRemoteGc buffer.

              Configuring the emulator to panic clients that ignore the - convention

              In both ScreenPlay and the non-ScreenPlay variant, you can configure the TechView emulator to panic clients that ignore the convention (described above) that all drawing operations are performed as redraw drawing.

              To enable this feature, add the following line to the epoc32/data/epoc.ini file:

              debug_wserv_exe_EnforceRedrawCallingConvention 1

              This feature is disabled if you do not specify this parameter or if you set it to zero, like this:

              debug_wserv_exe_EnforceRedrawCallingConvention 0

              The feature takes effect in debug emulator (WINSCW) builds only—it never affects ARM builds.

              When a Window Server panic code 79 (EWservPanicWindowBeginRedrawNotCalled) then occurs, it means that a non-redraw drawing operation has occurred.

              However, the Window Server buffers client requests. This means that the drawing that is at fault may have been issued by the client some time earlier. It is therefore helpful to enable autoflushing, because this removes the buffering between the client issuing the drawing operations and the Window Server processing them. This makes it easier to identify the drawing operation that is at fault.

              There are three ways to enable autoflushing:

              1. To enable autoflushing globally across all clients, define __AUTO_FLUSH in client/client.h and re-compile the Window Server code.

              2. To enable autoflushing in your client-side code only, call RWsSession::SetAutoFlush(ETrue).

              3. To enable autoflushing on an ad hoc basis in the TechView emulator, press Ctrl-Alt-Shift-F.

              Graphics and Drawing The UI Control Framework (CONE)               \ No newline at end of file + + + + + +Redraw DrawingThis topic provides background information about redraw +drawing and tips for updating old code to comply with the recommendation +that all drawing is migrated to redraw drawing. +

              Variant: Both (ScreenPlay and non-ScreenPlay). Target +audience: Application developers.

              +
              About +Redraw Drawing

              Symbian recommends that all CWindowGc drawing is redraw drawing, which means that it takes place +between RWindow::BeginRedraw() and RWindow::EndRedraw() calls. The +UI Control Framework (CONE) automatically takes care of this +for you if you use the CCoeControl::DrawNow(const TRect &)const and CCoeControl::DrawDeferred()const methods.

              For example, suppose an application wants to write the text "Hello!" +to a window and then add a red diagonal line below it (A in following +diagram). When this is performed as redraw drawing, the application +calculates the bounding rectangles of the "Hello!" text and the red +line (B). For each one, the application passes the rectangle to RWindow::BeginRedraw(const TRect &), then calls the +draw commands and afterwards calls RWindow::EndRedraw().

              + +

              This has the advantage that the Window Server knows that +the area of the window that has the "Hello!" text is not affected +by the drawing of the red line. There are also advantages when some +or all of the window needs to be repainted. For example, suppose another +window (such as an OK dialog box) appears above the window (as shown +in C). When the dialog box is closed, the Window Server repaints the +screen behind the dialog box. Because in this example the OK dialog +box was entirely within the red line's bounding rectangle, the Window +Server simply replays that rectangle's drawing operations (D). This +is more efficient than repainting the whole window.

              However, +in earlier versions of Symbian you could, for example, draw the red +line without bracketing it within BeginRedraw() and EndRedraw() calls. This is called non-redraw drawing. In ScreenPlay, each non-redraw drawing operation triggers the Window +Server to invalidate the entire window. This means that the client +application must then perform a full window redraw, as shown in the +next diagram.

              + Non-redraw drawing sequence + +

              This is less efficient than the Window Server replaying +the draw operations for the affected area.

              Symbian recommends +that all drawing is now performed as redraw drawing. Typically this +involves dividing the window up into rectangular areas that represent +different aspects of the user interface—for example, as shown in the +following diagram. If anything spoils the screen, the Window Server +then only needs to redraw the corresponding portions of the user interface.

              + +

              In earlier versions of Symbian, before the introduction +of the CCoeControl::DrawNow(const TRect &)const overload, developers sometimes used non-redraw drawing to update +a small part of a control. This technique has often been used for +virtual keyboards and calendar controls. This type of use case is +now particularly unsuited to non-redraw drawing because in ScreenPlay +each non-redraw drawing command triggers a server-initiated client +redraw of the entire window. This can be very slow if the window requires +many drawing operations to redraw the scene.

              Symbian recommends +that all non-redraw drawing is changed to redraw drawing. Migrating +non-redraw drawing to redraw drawing means that you must enclose all +drawing operations between RWindow::BeginRedraw() and RWindow::EndRedraw() calls or migrate it +to use the CCoeControl::DrawNow() and CCoeControl::DrawDeferred() methods. Sometimes this causes +some subtle changes in behavior, as explained in the Notes below.

              +
              Restrictions
                +

              1. You must supply only drawing operations between the BeginRedraw() and EndRedraw() calls. For example, you must not +change the window extent between a BeginRedraw() and EndRedraw() call.

                2. +

              2. For opaque windows, +you must define pixel content for the entire area being redrawn. +For example, when calling CCoeControl::DrawNow(const TRect +&)const, you must supply drawing operations for the +entire rectangle passed to the function. Similarly when calling the CCoeControl::DrawNow()const overload, you must supply drawing +operations for the entire window. However, this is not necessary for +transparent windows.

                3. +

              3. You must not call any functions that can leave between the BeginRedraw() and EndRedraw() calls. This is because drawing +operations must never leave.

                4. +

              Note: A redrawer's RunL() function must never perform any non-redraw drawing. See Server-Initiated +vs. Application-Initiated Redrawing for more information.

              +
              Notes

              Performance

              You can improve performance by passing +the smallest possible bounding rectangle to the RWindow::BeginRedraw() and CCoeControl::DrawNow() methods. If this still +results in poor performance, because, for example, there is a large +amount of incremental screen updating, the recommended solution in +ScreenPlay is to render to a surface.

              High frequency rendering

              It is possible for a client to provide batches of redraw +drawing (that is, drawing bracketed in BeginRedraw() and EndRedraw() calls) for the same region of a +window faster than they can be displayed on the screen. +When this happens, the Window Server may discard the drawing commands +in one or more of the earlier batches of redraw drawing and simply +draw the pixels defined in a later redraw batch to the screen. This +can result in missing frames, but is only likely to be noticeable +in an application like a game that performs high-frequency rendering.

              The solution is to call RWsSession::Finish() after each EndRedraw() call. This slows the client +so that it does not generate pixel content faster than the Window +Server can display it on the screen.

              To summarize: When you +want to ensure that every single frame is shown on the screen, call Finish() after each EndRedraw() call.

              Delay of execution

              After you migrate non-redraw +drawing to redraw drawing, the execution of the drawing operations +is deferred compared to previously. This means that if the arguments +of the drawing operations result in a panic, the panic also appears +later than before.

              CRemoteGc usage

              Device +creators can use CRemoteGc to create a data buffer +containing a series of drawing operations. These can then be executed +to display the drawing on the screen by using CCommandBuffer::Play().

              For example, consider a weather program that has one sub-system +responsible for deciding the drawing operations that comprise a weather +symbol and another sub-system that places weather symbols at different +locations on the screen. Here we potentially have a Cloud symbol buffer +created once and played many times.

              The points to note are:

                +

              • Any BeginRedraw() and EndRedraw() commands +that are placed into the CRemoteGc buffer are not transferred to the target window when the buffer is played

                • +

              • You must bracket any call to CCommandBuffer::Play() within BeginRedraw() and EndRedraw() calls.

                • +

              It may be puzzling to understand why any BeginRedraw() and EndRedraw() commands would be placed in the CRemoteGc buffer at all. This facility is to allow the commands +already in the CRemoteGc buffer to be replaced with +new drawing operations. In the weather example, it might be done to +allow a "7o Celsius" label to partially occlude a cloud +graphic placed earlier into the CRemoteGc buffer.

              +
              Configuring +the emulator to panic clients that ignore the convention

              In both ScreenPlay and the non-ScreenPlay variant, you can configure +the TechView emulator to panic clients that ignore the convention +(described above) that all drawing operations are performed as redraw +drawing.

              To enable this feature, add the following line to +the epoc32/data/epoc.ini file:

              debug_wserv_exe_EnforceRedrawCallingConvention 1

              This feature is disabled if you do not specify this parameter +or if you set it to zero, like this:

              debug_wserv_exe_EnforceRedrawCallingConvention 0

              The feature takes effect in debug emulator (WINSCW) builds only—it +never affects ARM builds.

              When a Window Server panic code +79 (EWservPanicWindowBeginRedrawNotCalled) then occurs, +it means that a non-redraw drawing operation has occurred.

              However, the Window Server buffers client requests. This means that +the drawing that is at fault may have been issued by the client some +time earlier. It is therefore helpful to enable autoflushing, because this removes the buffering between the client issuing the +drawing operations and the Window Server processing them. This makes +it easier to identify the drawing operation that is at fault.

              There are three ways to enable autoflushing:

                +

              1. To enable autoflushing +globally across all clients, define __AUTO_FLUSH in client/client.h and re-compile the Window Server code.

                2. +

              2. To enable autoflushing +in your client-side code only, call RWsSession::SetAutoFlush(ETrue).

                3. +

              3. To enable autoflushing +on an ad hoc basis in the TechView emulator, press Ctrl-Alt-Shift-F.

                4. +
              +               +Graphics +and Drawing +The +UI Control Framework (CONE) +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8E158109-AE22-5216-90E8-63A4BD4CC90B.dita --- a/Symbian3/SDK/Source/GUID-8E158109-AE22-5216-90E8-63A4BD4CC90B.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-8E158109-AE22-5216-90E8-63A4BD4CC90B.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,107 +1,107 @@ - - - - - - Opening -a Socket Server connection: TutorialThis tutorial describes how an application can open and manage -a connection to the Socket Server. Other Socket Server tutorials build upon -this tutorial. The Socket Server is also known as ESock. -
              Connecting to the Socket Server

              The RSocketServ class -provides the Connect() function to create a session to -the socket server.

              -
              Procedure

              The steps to connect and then close a -session with the Socket Server are:

                -

              • Call one of the RSocketServ::Connect() functions. -

                • -

              • Perform socket operations

                • -

              • Call Close to end the session with the Socket Server -

                • -
              -
              ExampleRSocketServ ss; - -// Connect to ESOCK -ss.Connect(); - -// Perform operations on the socket server -... - -// Close the connection -ss.Close(); -
              -
              Further considerations

              The RSocketServ::Connect() function -allows optional extra information to be sent to the Socket Server to change -the performance of the connection. Two optional parameters are available: -

                -

              1. Message Slots - If the client application expects to keep -a large number of requests open at the same time, then the client application -can increase the message slots available to the connection.

                2. -

              2. Protocol Preference - If the client application will use the -connection to interact with only one protocol, then this protocol should -be specified. The Socket Server uses the preferred protocol to improve the -efficiency of the messages between the client application and the protocol

                3. -
              -

              The RSocketServ connection -allows a number of sub-connections that -offer more functionality. The sub-connections available are:

                -

              • RConnection

                • -

              • RSubConnection

                • -

              • RSocket

                • -

              • RHostResolver

                • -

              • RNetDatabase

                • -

              The purpose of each of these sub-connections is described in the -.

              Procedure

              The -procedure to attach any of these sub-connections is:

                -

              1. Create or use an existing RSocketServ session.

                2. -

              2. Call the Open() function -on the object for the sub-connection class. Pass into the Open() function -a reference to the RSocketServ session.

                3. -

              3. Perform sub-connection -operations

                4. -

              4. Call Close to -end the sub-session

                5. -

              Example 1: Socket (RSocket)

              RSocketServ ss; -RSocket sock; - -// Connect to the Sockets Server -ss.Connect(); - -// open a socket -sock.Open(ss); - -// Perform operations on the socket -... - -// Close the socket connection -sock.Close(); -

              Example 2: Connection Management -(RConnection)

              RSocketServ ss; -RConnection conn; - -// Connect to the Sockets Server -ss.Connect(); - -// Open the Connection Management sub-connection -conn.Open(ss); - -// Perform operations on the connection -... - -// Close the sub-connection and connection -ss.Close(); -

              This example shows that you do not need to close sub-connections -explicitly. If you close the RSocketServ connection, the Comms Framework closes -all attached sub-connections.

              -               -How to - Start and Close a Management Plane session: Tutorial - -Socket Server -Reference + + + + + + Opening +a Socket Server connection: TutorialThis tutorial describes how an application can open and manage +a connection to the Socket Server. Other Socket Server tutorials build upon +this tutorial. The Socket Server is also known as ESock. +
              Connecting to the Socket Server

              The RSocketServ class +provides the Connect() function to create a session to +the socket server.

              +
              Procedure

              The steps to connect and then close a +session with the Socket Server are:

                +

              • Call one of the RSocketServ::Connect() functions. +

                • +

              • Perform socket operations

                • +

              • Call Close to end the session with the Socket Server +

                • +
              +
              ExampleRSocketServ ss; + +// Connect to ESOCK +ss.Connect(); + +// Perform operations on the socket server +... + +// Close the connection +ss.Close(); +
              +
              Further considerations

              The RSocketServ::Connect() function +allows optional extra information to be sent to the Socket Server to change +the performance of the connection. Two optional parameters are available: +

                +

              1. Message Slots - If the client application expects to keep +a large number of requests open at the same time, then the client application +can increase the message slots available to the connection.

                2. +

              2. Protocol Preference - If the client application will use the +connection to interact with only one protocol, then this protocol should +be specified. The Socket Server uses the preferred protocol to improve the +efficiency of the messages between the client application and the protocol

                3. +
              +

              The RSocketServ connection +allows a number of sub-connections that +offer more functionality. The sub-connections available are:

                +

              • RConnection

                • +

              • RSubConnection

                • +

              • RSocket

                • +

              • RHostResolver

                • +

              • RNetDatabase

                • +

              The purpose of each of these sub-connections is described in the +.

              Procedure

              The +procedure to attach any of these sub-connections is:

                +

              1. Create or use an existing RSocketServ session.

                2. +

              2. Call the Open() function +on the object for the sub-connection class. Pass into the Open() function +a reference to the RSocketServ session.

                3. +

              3. Perform sub-connection +operations

                4. +

              4. Call Close to +end the sub-session

                5. +

              Example 1: Socket (RSocket)

              RSocketServ ss; +RSocket sock; + +// Connect to the Sockets Server +ss.Connect(); + +// open a socket +sock.Open(ss); + +// Perform operations on the socket +... + +// Close the socket connection +sock.Close(); +

              Example 2: Connection Management +(RConnection)

              RSocketServ ss; +RConnection conn; + +// Connect to the Sockets Server +ss.Connect(); + +// Open the Connection Management sub-connection +conn.Open(ss); + +// Perform operations on the connection +... + +// Close the sub-connection and connection +ss.Close(); +

              This example shows that you do not need to close sub-connections +explicitly. If you close the RSocketServ connection, the Comms Framework closes +all attached sub-connections.

              +               +How to + Start and Close a Management Plane session: Tutorial + +Socket Server +Reference               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8E2303E9-DB60-5F38-A4D4-8BF8F7A1EF9F_d0e304490_href.jpg Binary file Symbian3/SDK/Source/GUID-8E2303E9-DB60-5F38-A4D4-8BF8F7A1EF9F_d0e304490_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8E2303E9-DB60-5F38-A4D4-8BF8F7A1EF9F_d0e310505_href.jpg Binary file Symbian3/SDK/Source/GUID-8E2303E9-DB60-5F38-A4D4-8BF8F7A1EF9F_d0e310505_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8E322085-07E7-542C-B0FD-54431F7B4BB7_d0e272075_href.jpg Binary file Symbian3/SDK/Source/GUID-8E322085-07E7-542C-B0FD-54431F7B4BB7_d0e272075_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8E322085-07E7-542C-B0FD-54431F7B4BB7_d0e275756_href.jpg Binary file Symbian3/SDK/Source/GUID-8E322085-07E7-542C-B0FD-54431F7B4BB7_d0e275756_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8E3F3745-7875-51A2-BDA1-AA537C7B220E_d0e393399_href.png Binary file Symbian3/SDK/Source/GUID-8E3F3745-7875-51A2-BDA1-AA537C7B220E_d0e393399_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8E3F3745-7875-51A2-BDA1-AA537C7B220E_d0e393561_href.png Binary file Symbian3/SDK/Source/GUID-8E3F3745-7875-51A2-BDA1-AA537C7B220E_d0e393561_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8E6FD3FD-64C8-51E0-AFE7-76DC5AB6A254_d0e110788_href.png Binary file Symbian3/SDK/Source/GUID-8E6FD3FD-64C8-51E0-AFE7-76DC5AB6A254_d0e110788_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8E6FD3FD-64C8-51E0-AFE7-76DC5AB6A254_d0e117326_href.png Binary file Symbian3/SDK/Source/GUID-8E6FD3FD-64C8-51E0-AFE7-76DC5AB6A254_d0e117326_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8E759F53-8DA7-5AA3-B004-7D989CCF8755_d0e123728_href.jpg Binary file Symbian3/SDK/Source/GUID-8E759F53-8DA7-5AA3-B004-7D989CCF8755_d0e123728_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8E759F53-8DA7-5AA3-B004-7D989CCF8755_d0e130266_href.jpg Binary file Symbian3/SDK/Source/GUID-8E759F53-8DA7-5AA3-B004-7D989CCF8755_d0e130266_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8E794D5A-9C83-54EB-AD5A-6A74BB155223.dita --- a/Symbian3/SDK/Source/GUID-8E794D5A-9C83-54EB-AD5A-6A74BB155223.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-8E794D5A-9C83-54EB-AD5A-6A74BB155223.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,226 +1,226 @@ - - - - - -JPEG -Image Transform Extension Guide -

              This document introduces you to the JPEG image transform extensions.

              -
              Purpose

              The -Image Transform framework supports standard extensions for advanced JPEG functions.

              The -functions are,

                -

              • Orientation (Rotation and Mirror over horizontal and vertical Axis)

                • -

              • Overlay

                • -

              • Squeeze

                • -
              -
              Orientation

              The -COrientationTransformExtension extension to CImageTransform allows you to -rotate in steps of 90 degrees or to mirror a JPEG file either from file or -memory.

              When you require an Image Transform plugin which supports -the Orientation extension, call CImageTransform::SetTransformationsL() or CImageTransform::EOrientation(). -The client must get the COrientationTransformExtension extension and use this -to set up the required transformation:

              - -IMPORT_C void COrientationTransformExtension::SetOrientationL(TOrientation aOrientation); - -

              The orientation changes supported by the COrientationTransformExtension are,

                -

              • 90 degree clockwise

                • -

              • 180 degree clockwise

                • -

              • 270 degree clockwise

                • -

              • mirroring over the vertical -axis

                • -

              • mirroring over the horizontal -axis

                • -

              • transpose over the main -diagonal

                • -

              • transpose over the minor -diagonal.

                • -

              In the example function below a JPEG image is rotated by 90 degrees:

              - - // Create the image transform - CImageTransform* imageTransform = CImageTransform::NewL(iFs); - CleanupStack::PushL(imageTransform); - - // Setup the image transform - imageTransform->SetSourceFilenameL(aSrcFileName); - imageTransform->SetDestFilenameL(aDestFileName); - imageTransform->SetTransformationsL(CImageTransform::EOrientation); - imageTransform->SetupL(); - - // Get the extension plugin supporting orientation - TUid lRotateUid = {KUidOrientationTransformExtension }; - TInt err = KErrNone; - COrientationTransformExtension* lRotateExt = static_cast<COrientationTransformExtension*> - (imageTransform->Extension(lRotateUid, err)); - - // Check here whether the plugin supports this extension or not set the orientation on - // the plugin - lRotateExt->SetOrientationL(COrientationTransformExtension::ERotation90DegreesClockwise); - - // Perform the transformation - imageTransform->Transform(aStatus); - - // CImageTransform::Transform() is an asynchronous function - // and the result of the transformation would be known in the - // RunL() function of the active object associated with the aStatus - -

              The image rotation can be performed in the compressed domain -allowing a transformation of the image. Benefits of speed and memory usage -can be obtained dependent on the implementation of the plugin.

              -
              Overlay

              COverlayTransformExtension extension -to Image Transform framework allows lossless overlay or blend of images. Examples -of the use of COverlayTransformExtension include adding -timestamp or place-stamp, some text or inserting a company logo. The images -below show an example of overlay functionality:

              - -

              The image overlay transformation can, depending on its implementation, -be very fast eliminating the need to decode the whole image making it very -useful, for example a camera application. The types of image that can be overlaid -onto the main JPEG image can be discovered through the extension. It is also -possible to overlay a CFbsBitmap. If you need transparency, -then you have to choose an image format supporting a transparency channel -such as PNG.

              When you require an Image Transform plugin which supports -the Overlay extension, call CImageTransform::SetTransformationsL() or CImageTransform::EOverlay(). -The client must get the COverlayTransformExtension extension and use this -to set up the required transformation. The client can control the desired -position for overlay, and the transparency for image. The example below show -the successful setup for COverlayTransformExtension with -the JPEG image overlaid by an image at (0,0) position co-ordinates:

              - - // Create the image transform - CImageTransform* imageTransform = CImageTransform::NewL(iFs); - CleanupStack::PushL(imageTransform); - - // Setup the image transform - imageTransform->SetSourceFilenameL(aSrcFileName); - imageTransform->SetDestFilenameL(aDestFileName); - imageTransform->SetTransformationsL(CImageTransform::EOverlay); - imageTransform->SetupL(); - - // Get the extension plugin supporting overlay - TUid lOverlayUid = {KUidOverlayTransformExtension }; - TInt err = KErrNone; - COverlayTransformExtension * lOverlayExt = static_cast< COverlayTransformExtension *> - (imageTransform->Extension(lOverlayUid, err)); - - // Check here whether the plugin supports this extension or not Set the position on - // the plugin - lOverlayExt->Position(TPoint(0,0)); - - // Set the overlay file and its type - lOverlayExt->SetOverlayFileL(aOverlayFileName, KImageTypeJPGUid); - - // Perform the transformation - imageTransform->Transform(aStatus); - - // CImageTransform::Transform() is an asynchronous function - // and the result of the transformation would be known in the - // RunL() function of the active object associated with the aStatus - -
              -
              Squeeze

              The CSqueezeTransformExtension() extension -to the Image Transform framework allows,

                -

              • Auto-resize

                • -

              • Squeeze.

                • -

              A auto-resize adjusts the image size and encoding quality to achieve -a desired file size. If the file size requirement has not been met, then you -can use squeeze to compress the image even further. The JPEG squeeze module -is a convenient tool when creating MMS.

              When you require an Image -Transform plugin which supports the Squeeze extension, call CImageTransform::SetTransformationsL() or CImageTransform::ESqueeze().

              Squeezing an image can be accomplished through:

              - -IMPORT_C void CSqueezeTransformExtension::SetDestSizeInBytes(TUint aMaxDestDataSize ) ; - -

              Or

              - IMPORT_C void SetAdvancedSqueezeModeL(TAdvancedSqueezeParams* aSqueezeAutoResizeParams ) ; -

              In the latter case can be made through the use of TAdvancedSqueezeParams::TAutoResizeAction. -The enumeration to do auto resize are,

                -

              • - EAutoResizeActionPreserveSourceEncodingQuality for preserving -the source encoding quality while shrinking the width and height of the image

                • -

              • EAutoResizeActionPrioritizeLargeImageSize for -preserving the maxImageSize while lowering the encoding quality

                • -

              • EAutoResizeActionResizePrioritizeHighEncodingQuality for -preserving the highest possible encoding quality while shrinking the width -and height of the image

                • -

              • EAutoResizeActionMiddleCourse for -simultaneously lower the encoding quality and shrink the width and height -of the image.

                • -

              These settings are used by the auto resize to determine size and -encoding quality for the new image file.

              The JPEG squeeze enblaes -images to be set to a enblaes pre-defined size. This is useful if storage -size is critical or if there are limitations when sending images i.e. MMS -file size. The dimensions of the image are preserved; the JPEG compression -ratio being changed to maintain the image size.

              Note: The -JPEG squeeze functionality must be used with care. Drastically decreasing -file size will result in poor image quality.

              In the below example, -the JPEG image is squeezed to get a file size less than the specified maxium -size:

              - - // Create the image transform - CImageTransform* imageTransform = CImageTransform::NewL(iFs); - CleanupStack::PushL(imageTransform); - // Setup the image transform - imageTransform->SetSourceFilenameL(aSrcFileName); - imageTransform->SetDestFilenameL(aDestFileName); - imageTransform->SetTransformationsL(CImageTransform::ESqueeze); - imageTransform->SetupL(); - // Get the extension plugin supporting squeeze - TUid lSqueezeUid = {KUidSqueezeTransformExtension }; - TInt err = KErrNone; - CSqueezeTransformExtension * lSqueezeExt = static_cast< CSqueezeTransformExtension*> -(imageTransform->Extension(lSqueezeUid, err)); - // Check here whether the plugin supports this extension or not - // Set the max dest size in bytes - lSqueezeExt-> SetDestSizeInBytes(aMaxSizeInBytes); - // Perform the transformation - imageTransform->Transform(aStatus); - // CImageTransform::Transform() is an asynchronous function - // and the result of the transformation would be known in the - // RunL() function of the active object associated with the aStatus - -

              The example code below show how the JPEG squeeze image is -used to make an image fulfill the MMS ‘Image Rich’ class constraints, i.e. -file size less than 100k bytes and image size no more than 640*480 pixels.

              - - // Create the image transform - CImageTransform* imageTransform = CImageTransform::NewL(iFs); - CleanupStack::PushL(imageTransform); - // Setup the image transform - imageTransform->SetSourceFilenameL(aSrcFileName); - imageTransform->SetDestFilenameL(aDestFileName); - imageTransform->SetTransformationsL(CImageTransform::ESqueeze); - imageTransform->SetupL(); - // Get the extension plugin supporting squeeze - TUid lSqueezeUid = {KUidSqueezeTransformExtension }; - TInt err = KErrNone; - CSqueezeTransformExtension * lSqueezeExt = static_cast< CSqueezeTransformExtension*> -(imageTransform->Extension(lSqueezeUid, err)); - TInt res = KErrNone; - TInt newSize = 0; - TAdvancedSqueezeParams info ; - - // MMS Image Rich - info.iMaxDestSizeInBytes = 100000; - info.iMaxImageSize.iWidth = 640; - info.iMaxImageSize.iHeight = 480; - info.iMinImageSize. iWidth = 160; - info.iMinImageSize. iHeight = 120; - info.iResizeAction = EAutoResizeActionPrioritizeLargeImageSize; - info.iMinEncodingQuality = 0.5f; - info.iSamplingUid = KUidSamplingColor420; - lSqueezeExt->SetAdvancedSqueezeModeL(&info); - // Perform the transformation - imageTransform->Transform(aStatus); - // CImageTransform::Transform() is an asynchronous function - // and the result of the transformation would be known in the - // RunL() function of the active object associated with the aStatus - -
              - + + + + + +JPEG +Image Transform Extension Guide +

              This document introduces you to the JPEG image transform extensions.

              +
              Purpose

              The +Image Transform framework supports standard extensions for advanced JPEG functions.

              The +functions are,

                +

              • Orientation (Rotation and Mirror over horizontal and vertical Axis)

                • +

              • Overlay

                • +

              • Squeeze

                • +
              +
              Orientation

              The +COrientationTransformExtension extension to CImageTransform allows you to +rotate in steps of 90 degrees or to mirror a JPEG file either from file or +memory.

              When you require an Image Transform plugin which supports +the Orientation extension, call CImageTransform::SetTransformationsL() or CImageTransform::EOrientation(). +The client must get the COrientationTransformExtension extension and use this +to set up the required transformation:

              + +IMPORT_C void COrientationTransformExtension::SetOrientationL(TOrientation aOrientation); + +

              The orientation changes supported by the COrientationTransformExtension are,

                +

              • 90 degree clockwise

                • +

              • 180 degree clockwise

                • +

              • 270 degree clockwise

                • +

              • mirroring over the vertical +axis

                • +

              • mirroring over the horizontal +axis

                • +

              • transpose over the main +diagonal

                • +

              • transpose over the minor +diagonal.

                • +

              In the example function below a JPEG image is rotated by 90 degrees:

              + + // Create the image transform + CImageTransform* imageTransform = CImageTransform::NewL(iFs); + CleanupStack::PushL(imageTransform); + + // Setup the image transform + imageTransform->SetSourceFilenameL(aSrcFileName); + imageTransform->SetDestFilenameL(aDestFileName); + imageTransform->SetTransformationsL(CImageTransform::EOrientation); + imageTransform->SetupL(); + + // Get the extension plugin supporting orientation + TUid lRotateUid = {KUidOrientationTransformExtension }; + TInt err = KErrNone; + COrientationTransformExtension* lRotateExt = static_cast<COrientationTransformExtension*> + (imageTransform->Extension(lRotateUid, err)); + + // Check here whether the plugin supports this extension or not set the orientation on + // the plugin + lRotateExt->SetOrientationL(COrientationTransformExtension::ERotation90DegreesClockwise); + + // Perform the transformation + imageTransform->Transform(aStatus); + + // CImageTransform::Transform() is an asynchronous function + // and the result of the transformation would be known in the + // RunL() function of the active object associated with the aStatus + +

              The image rotation can be performed in the compressed domain +allowing a transformation of the image. Benefits of speed and memory usage +can be obtained dependent on the implementation of the plugin.

              +
              Overlay

              COverlayTransformExtension extension +to Image Transform framework allows lossless overlay or blend of images. Examples +of the use of COverlayTransformExtension include adding +timestamp or place-stamp, some text or inserting a company logo. The images +below show an example of overlay functionality:

              + +

              The image overlay transformation can, depending on its implementation, +be very fast eliminating the need to decode the whole image making it very +useful, for example a camera application. The types of image that can be overlaid +onto the main JPEG image can be discovered through the extension. It is also +possible to overlay a CFbsBitmap. If you need transparency, +then you have to choose an image format supporting a transparency channel +such as PNG.

              When you require an Image Transform plugin which supports +the Overlay extension, call CImageTransform::SetTransformationsL() or CImageTransform::EOverlay(). +The client must get the COverlayTransformExtension extension and use this +to set up the required transformation. The client can control the desired +position for overlay, and the transparency for image. The example below show +the successful setup for COverlayTransformExtension with +the JPEG image overlaid by an image at (0,0) position co-ordinates:

              + + // Create the image transform + CImageTransform* imageTransform = CImageTransform::NewL(iFs); + CleanupStack::PushL(imageTransform); + + // Setup the image transform + imageTransform->SetSourceFilenameL(aSrcFileName); + imageTransform->SetDestFilenameL(aDestFileName); + imageTransform->SetTransformationsL(CImageTransform::EOverlay); + imageTransform->SetupL(); + + // Get the extension plugin supporting overlay + TUid lOverlayUid = {KUidOverlayTransformExtension }; + TInt err = KErrNone; + COverlayTransformExtension * lOverlayExt = static_cast< COverlayTransformExtension *> + (imageTransform->Extension(lOverlayUid, err)); + + // Check here whether the plugin supports this extension or not Set the position on + // the plugin + lOverlayExt->Position(TPoint(0,0)); + + // Set the overlay file and its type + lOverlayExt->SetOverlayFileL(aOverlayFileName, KImageTypeJPGUid); + + // Perform the transformation + imageTransform->Transform(aStatus); + + // CImageTransform::Transform() is an asynchronous function + // and the result of the transformation would be known in the + // RunL() function of the active object associated with the aStatus + +
              +
              Squeeze

              The CSqueezeTransformExtension() extension +to the Image Transform framework allows,

                +

              • Auto-resize

                • +

              • Squeeze.

                • +

              A auto-resize adjusts the image size and encoding quality to achieve +a desired file size. If the file size requirement has not been met, then you +can use squeeze to compress the image even further. The JPEG squeeze module +is a convenient tool when creating MMS.

              When you require an Image +Transform plugin which supports the Squeeze extension, call CImageTransform::SetTransformationsL() or CImageTransform::ESqueeze().

              Squeezing an image can be accomplished through:

              + +IMPORT_C void CSqueezeTransformExtension::SetDestSizeInBytes(TUint aMaxDestDataSize ) ; + +

              Or

              + IMPORT_C void SetAdvancedSqueezeModeL(TAdvancedSqueezeParams* aSqueezeAutoResizeParams ) ; +

              In the latter case can be made through the use of TAdvancedSqueezeParams::TAutoResizeAction. +The enumeration to do auto resize are,

                +

              • + EAutoResizeActionPreserveSourceEncodingQuality for preserving +the source encoding quality while shrinking the width and height of the image

                • +

              • EAutoResizeActionPrioritizeLargeImageSize for +preserving the maxImageSize while lowering the encoding quality

                • +

              • EAutoResizeActionResizePrioritizeHighEncodingQuality for +preserving the highest possible encoding quality while shrinking the width +and height of the image

                • +

              • EAutoResizeActionMiddleCourse for +simultaneously lower the encoding quality and shrink the width and height +of the image.

                • +

              These settings are used by the auto resize to determine size and +encoding quality for the new image file.

              The JPEG squeeze enblaes +images to be set to a enblaes pre-defined size. This is useful if storage +size is critical or if there are limitations when sending images i.e. MMS +file size. The dimensions of the image are preserved; the JPEG compression +ratio being changed to maintain the image size.

              Note: The +JPEG squeeze functionality must be used with care. Drastically decreasing +file size will result in poor image quality.

              In the below example, +the JPEG image is squeezed to get a file size less than the specified maxium +size:

              + + // Create the image transform + CImageTransform* imageTransform = CImageTransform::NewL(iFs); + CleanupStack::PushL(imageTransform); + // Setup the image transform + imageTransform->SetSourceFilenameL(aSrcFileName); + imageTransform->SetDestFilenameL(aDestFileName); + imageTransform->SetTransformationsL(CImageTransform::ESqueeze); + imageTransform->SetupL(); + // Get the extension plugin supporting squeeze + TUid lSqueezeUid = {KUidSqueezeTransformExtension }; + TInt err = KErrNone; + CSqueezeTransformExtension * lSqueezeExt = static_cast< CSqueezeTransformExtension*> +(imageTransform->Extension(lSqueezeUid, err)); + // Check here whether the plugin supports this extension or not + // Set the max dest size in bytes + lSqueezeExt-> SetDestSizeInBytes(aMaxSizeInBytes); + // Perform the transformation + imageTransform->Transform(aStatus); + // CImageTransform::Transform() is an asynchronous function + // and the result of the transformation would be known in the + // RunL() function of the active object associated with the aStatus + +

              The example code below show how the JPEG squeeze image is +used to make an image fulfill the MMS ‘Image Rich’ class constraints, i.e. +file size less than 100k bytes and image size no more than 640*480 pixels.

              + + // Create the image transform + CImageTransform* imageTransform = CImageTransform::NewL(iFs); + CleanupStack::PushL(imageTransform); + // Setup the image transform + imageTransform->SetSourceFilenameL(aSrcFileName); + imageTransform->SetDestFilenameL(aDestFileName); + imageTransform->SetTransformationsL(CImageTransform::ESqueeze); + imageTransform->SetupL(); + // Get the extension plugin supporting squeeze + TUid lSqueezeUid = {KUidSqueezeTransformExtension }; + TInt err = KErrNone; + CSqueezeTransformExtension * lSqueezeExt = static_cast< CSqueezeTransformExtension*> +(imageTransform->Extension(lSqueezeUid, err)); + TInt res = KErrNone; + TInt newSize = 0; + TAdvancedSqueezeParams info ; + + // MMS Image Rich + info.iMaxDestSizeInBytes = 100000; + info.iMaxImageSize.iWidth = 640; + info.iMaxImageSize.iHeight = 480; + info.iMinImageSize. iWidth = 160; + info.iMinImageSize. iHeight = 120; + info.iResizeAction = EAutoResizeActionPrioritizeLargeImageSize; + info.iMinEncodingQuality = 0.5f; + info.iSamplingUid = KUidSamplingColor420; + lSqueezeExt->SetAdvancedSqueezeModeL(&info); + // Perform the transformation + imageTransform->Transform(aStatus); + // CImageTransform::Transform() is an asynchronous function + // and the result of the transformation would be known in the + // RunL() function of the active object associated with the aStatus + +
              +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8E8F1999-4DE0-5CA0-9656-C54127FDB3D4_d0e337751_href.png Binary file Symbian3/SDK/Source/GUID-8E8F1999-4DE0-5CA0-9656-C54127FDB3D4_d0e337751_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8E8F1999-4DE0-5CA0-9656-C54127FDB3D4_d0e343948_href.png Binary file Symbian3/SDK/Source/GUID-8E8F1999-4DE0-5CA0-9656-C54127FDB3D4_d0e343948_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8E907968-E6F8-5792-9B04-664971762FFF_d0e230483_href.png Binary file Symbian3/SDK/Source/GUID-8E907968-E6F8-5792-9B04-664971762FFF_d0e230483_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8E907968-E6F8-5792-9B04-664971762FFF_d0e234220_href.png Binary file Symbian3/SDK/Source/GUID-8E907968-E6F8-5792-9B04-664971762FFF_d0e234220_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8E995178-F3F2-4391-B99D-7A3451880F53-master.png Binary file Symbian3/SDK/Source/GUID-8E995178-F3F2-4391-B99D-7A3451880F53-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8E995178-F3F2-4391-B99D-7A3451880F53_d0e52050_href.png Binary file Symbian3/SDK/Source/GUID-8E995178-F3F2-4391-B99D-7A3451880F53_d0e52050_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8E995178-F3F2-4391-B99D-7A3451880F53_d0e75139_href.png Binary file Symbian3/SDK/Source/GUID-8E995178-F3F2-4391-B99D-7A3451880F53_d0e75139_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8EAF5A96-EB48-4A58-82D7-0583A22A51D0.dita --- a/Symbian3/SDK/Source/GUID-8EAF5A96-EB48-4A58-82D7-0583A22A51D0.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,33 +0,0 @@ - - - - - -Information -pop-up -

              Information pop-up notes are used to provide additional information to -the user, most typically regarding a focused item. Although the Information -pop-up can be used in various applications and components, it should not be -used too frequently as constantly appearing and disappearing notes may disturb -smooth user experience.

              -

              The Information pop-up does not have focus, its content cannot be scrolled, -and the control always remains in the main pane. The maximum number of rows -in the Information pop-up is four. In a typical case, the pop-up emerges one -second after the user has taken the focus on an item but has not made any -further actions. The pop-up is timed so that it (typically) remains visible -for ten seconds or until some event interrupts it. Time-outs are application-specific -and variation is possible.

              - -Information pop-up related to the focused day - - -
              Using -information pop-ups in C++ applications

              The API to use for the information -pop-up is the Info pop-up API.

              -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8ECEF376-CB27-52FC-A9DD-933ACC24FDDC_d0e307907_href.png Binary file Symbian3/SDK/Source/GUID-8ECEF376-CB27-52FC-A9DD-933ACC24FDDC_d0e307907_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8ECEF376-CB27-52FC-A9DD-933ACC24FDDC_d0e314301_href.png Binary file Symbian3/SDK/Source/GUID-8ECEF376-CB27-52FC-A9DD-933ACC24FDDC_d0e314301_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8EE8E38C-7CA1-5F1B-86D0-1A0B03AAC5F2_d0e149865_href.png Binary file Symbian3/SDK/Source/GUID-8EE8E38C-7CA1-5F1B-86D0-1A0B03AAC5F2_d0e149865_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8EE8E38C-7CA1-5F1B-86D0-1A0B03AAC5F2_d0e156386_href.png Binary file Symbian3/SDK/Source/GUID-8EE8E38C-7CA1-5F1B-86D0-1A0B03AAC5F2_d0e156386_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8EF8CDD3-9FFE-5C39-8303-67A661C67F6B_d0e337871_href.jpg Binary file Symbian3/SDK/Source/GUID-8EF8CDD3-9FFE-5C39-8303-67A661C67F6B_d0e337871_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8EF8CDD3-9FFE-5C39-8303-67A661C67F6B_d0e344068_href.jpg Binary file Symbian3/SDK/Source/GUID-8EF8CDD3-9FFE-5C39-8303-67A661C67F6B_d0e344068_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8F04D882-B846-4A0D-B858-15FDA85758FA.dita --- a/Symbian3/SDK/Source/GUID-8F04D882-B846-4A0D-B858-15FDA85758FA.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-8F04D882-B846-4A0D-B858-15FDA85758FA.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,46 +1,46 @@ - - - - - -Displaying -commands in a context menu -

              To use a stylus pop-up menu in your application, implement the following -use cases:

              -
                -

              • Creating stylus -pop-up menu

                • -

              • Handling stylus -pop-up menu events and commands

                • -

              • Handling user -command selection

                • -

              • Showing and -hiding stylus pop-up menu

                • -

              • Adding and removing -menu items

                • -
              -

              We need to provide more clarity -on the required order of implementing the use cases and clarify whether there -are alternative approaches for achieving the same results.

              -

              The following use cases are optional, allowing you to set additional properties -for your stylus pop-up menu:

              -
                -

              • Setting stylus -pop-up menu position

                • -

              • Hiding and showing -stylus pop-up menu items

                • -
              -
              Implementation file

              The implementation file for -the Stylus pop-up menu API is aknstyluspopupmenu.h.

              -               -Stylus pop-up -menu API description -Look and -feel guidelines for the stylus pop-up menu + + + + + +Displaying +commands in a stylus pop-up menu +

              To use a stylus pop-up menu in your application, implement the following +use cases:

              +
                +

              • Creating stylus +pop-up menu

                • +

              • Handling stylus +pop-up menu events and commands

                • +

              • Handling user +command selection

                • +

              • Showing and +hiding stylus pop-up menu

                • +

              • Adding and removing +menu items

                • +
              +

              We need to provide more clarity +on the required order of implementing the use cases and clarify whether there +are alternative approaches for achieving the same results.

              +

              The following use cases are optional, allowing you to set additional properties +for your stylus pop-up menu:

              +
                +

              • Setting stylus +pop-up menu position

                • +

              • Hiding and showing +stylus pop-up menu items

                • +
              +
              Implementation +file

              The implementation file for the Stylus pop-up menu API is aknstyluspopupmenu.h.

              +               +Stylus pop-up +menu API description +Look and +feel guidelines for the stylus pop-up menu               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8F1567B4-6957-5B93-9499-35489AD610F5.dita --- a/Symbian3/SDK/Source/GUID-8F1567B4-6957-5B93-9499-35489AD610F5.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-8F1567B4-6957-5B93-9499-35489AD610F5.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,121 +1,121 @@ - - - - - -ChunksChunks map RAM or memory-mapped I/O devices into contiguous virtual -addresses. -

              A chunk consists of a reserved region and a committed region. -The reserved region is the contiguous set of virtual addresses accessible -to running code. The committed region is the region in which RAM (or memory-mapped -I/O) is actually mapped. The size of a chunk is dynamically alterable, allowing -the committed region to vary in size from zero up to the reserved region size, -in integer multiples of the processor page size. This allows processes to -obtain more memory on demand. Generally the committed region starts at the -bottom of the reserved region.

              -

              A chunk also has a maximum size, which is defined when the chunk is created. -The reserved region can be smaller than this maximum size, but it can also -be made bigger by reallocating it. The reserved region cannot be made bigger -than the maximum size.

              -

              The size of the reserved region of a chunk is always an integer multiple -of the virtual address range of a single entry in the processor page directory -(PDE size). This means that the reserved region of a chunk is mapped by a -number of consecutive page directory entries (PDEs). Any given PDE maps part -of the reserved region of at most one chunk.

              -

              Symbian platform has a number of chunk types, but for user side code, the -chunks of interest are User chunks and Shared chunks.

              -

              A chunk is a kernel side entity, and like all other kernel side entities, -it is accessed from the user side using a handle, an instance of the RChunk class. -The concept of local and global also applies to chunks.

              -
                -

              • User chunks

                • -

              • Shared chunks

                • -

              • Local and global chunks

                • -
              -
              User chunks

              On -systems with an MMU, Symbian platform provides three types of user chunks. -Each type is characterised by having a different subset of the reserved address -range containing committed memory:

                -

              • Normal chunks

                • -

              • Double-ended chunks

                • -

              • Disconnected chunks

                • -

              Normal chunks

              These -chunks have a committed region consisting of a single contiguous range starting -at the chunk's base address and a size that is a multiple of the MMU page -size. The following diagram is an example of this kind of chunk:

              -Normal chunks - -

              Double-ended chunks

              These -chunks have a committed region consisting of a single contiguous range starting -at arbitrary lower and upper endpoints within the reserved region. The only -condition is that the lower and upper endpoints must be a multiple of the -MMU page size. Both the bottom and top of the committed region can be altered -dynamically. The following diagram shows an example of this kind of chunk:

              -Double-ended chunks - -

              Disconnected chunks

              These -chunks have a committed region consisting of an arbitrary set of MMU pages -within the reserved region. Each page-sized address range within the reserved -region starting on a page boundary can be committed independently. The following -diagram shows an example of this kind of chunk:

              -Disconnected chunks - -
              -
              Shared chunks

              A -shared chunk is a mechanism that allows kernel-side code to share memory buffers -safely with user-side code. By kernel-side code, we usually mean device driver -code.

              The main points to note about shared chunks are:

                -

              • They can only be created -and destroyed by device drivers. It is typical behaviour for user-side code, -which in this context we refer to as the client of the device driver, to pass -a request to the device driver to open a handle to a shared chunk. This causes -the device driver to open a handle to the chunk and return the handle value to -the client. Successful handle creation also causes the chunk's memory to be -mapped into the address space of the process to which the client's thread -belongs. Note, however, that it is the driver that dictates exactly when the -chunk itself is created, and when memory is committed. The precise protocol -depends on the design of the driver; you need to refer to that driver's documentation -for programming guidance.

                • -

              • Like all kernel side -objects, a shared chunk is reference counted. This means that it remains in -existence for as long as the reference count is greater than zero. Once all -opened references to the shared chunk have been closed, regardless -of whether the references are user-side, or kernel-side, then it is destroyed.

                • -

              • User-side code that -has gained access to a shared chunk from one device driver can pass this to -a second device driver. The second device driver must open the chunk -before it can be used.

                • -

              • More than one user side -application can access the data in a shared chunk. A handle to a shared chunk -can be passed from one process to another process using standard handle passing -mechanisms. In practice, handles would be passed in a client-server context, -either from client to server or from server to client using inter-process -communication (IPC).

                • -

              • Processes that share -data inside a chunk should communicate the location of that data as an offset -from the start of the chunk, and not as an absolute address. The shared -chunk may appear at different addresses within the address spaces of different -user processes.

                • -
              -
              Local and global -chunks

              Local chunks

              A chunk is local when it is private to the process -creating it and is not intended for access by other user processes.

              A -local chunk cannot be mapped into any other process and is, therefore, used -for memory that does not need to be shared.

              A local chunk does not -have a name.

              Global chunks

              A chunk is global if it is intended to be accessed -by other processes.

              Global chunks have names that can be used to identify -the chunk to another process wishing to access it. A process can open a global -chunk by name; this maps the chunk into that process's address space, allowing -direct access and enabling the sharing of data between processes.

              If -the name of the global chunk to be opened is known, use RChunk::OpenGlobal(). -If a part of the name is known, use the RChunk::Open() variant -that takes a TFindChunk.

              A process can only access -an unnamed global chunk if it is passed a handle to that chunk from another -process. See RChunk::Open().

              + + + + + +ChunksChunks map RAM or memory-mapped I/O devices into contiguous virtual +addresses. +

              A chunk consists of a reserved region and a committed region. +The reserved region is the contiguous set of virtual addresses accessible +to running code. The committed region is the region in which RAM (or memory-mapped +I/O) is actually mapped. The size of a chunk is dynamically alterable, allowing +the committed region to vary in size from zero up to the reserved region size, +in integer multiples of the processor page size. This allows processes to +obtain more memory on demand. Generally the committed region starts at the +bottom of the reserved region.

              +

              A chunk also has a maximum size, which is defined when the chunk is created. +The reserved region can be smaller than this maximum size, but it can also +be made bigger by reallocating it. The reserved region cannot be made bigger +than the maximum size.

              +

              The size of the reserved region of a chunk is always an integer multiple +of the virtual address range of a single entry in the processor page directory +(PDE size). This means that the reserved region of a chunk is mapped by a +number of consecutive page directory entries (PDEs). Any given PDE maps part +of the reserved region of at most one chunk.

              +

              Symbian platform has a number of chunk types, but for user side code, the +chunks of interest are User chunks and Shared chunks.

              +

              A chunk is a kernel side entity, and like all other kernel side entities, +it is accessed from the user side using a handle, an instance of the RChunk class. +The concept of local and global also applies to chunks.

              +
                +

              • User chunks

                • +

              • Shared chunks

                • +

              • Local and global chunks

                • +
              +
              User chunks

              On +systems with an MMU, Symbian platform provides three types of user chunks. +Each type is characterised by having a different subset of the reserved address +range containing committed memory:

                +

              • Normal chunks

                • +

              • Double-ended chunks

                • +

              • Disconnected chunks

                • +

              Normal chunks

              These +chunks have a committed region consisting of a single contiguous range starting +at the chunk's base address and a size that is a multiple of the MMU page +size. The following diagram is an example of this kind of chunk:

              +Normal chunks + +

              Double-ended chunks

              These +chunks have a committed region consisting of a single contiguous range starting +at arbitrary lower and upper endpoints within the reserved region. The only +condition is that the lower and upper endpoints must be a multiple of the +MMU page size. Both the bottom and top of the committed region can be altered +dynamically. The following diagram shows an example of this kind of chunk:

              +Double-ended chunks + +

              Disconnected chunks

              These +chunks have a committed region consisting of an arbitrary set of MMU pages +within the reserved region. Each page-sized address range within the reserved +region starting on a page boundary can be committed independently. The following +diagram shows an example of this kind of chunk:

              +Disconnected chunks + +
              +
              Shared chunks

              A +shared chunk is a mechanism that allows kernel-side code to share memory buffers +safely with user-side code. By kernel-side code, we usually mean device driver +code.

              The main points to note about shared chunks are:

                +

              • They can only be created +and destroyed by device drivers. It is typical behaviour for user-side code, +which in this context we refer to as the client of the device driver, to pass +a request to the device driver to open a handle to a shared chunk. This causes +the device driver to open a handle to the chunk and return the handle value to +the client. Successful handle creation also causes the chunk's memory to be +mapped into the address space of the process to which the client's thread +belongs. Note, however, that it is the driver that dictates exactly when the +chunk itself is created, and when memory is committed. The precise protocol +depends on the design of the driver; you need to refer to that driver's documentation +for programming guidance.

                • +

              • Like all kernel side +objects, a shared chunk is reference counted. This means that it remains in +existence for as long as the reference count is greater than zero. Once all +opened references to the shared chunk have been closed, regardless +of whether the references are user-side, or kernel-side, then it is destroyed.

                • +

              • User-side code that +has gained access to a shared chunk from one device driver can pass this to +a second device driver. The second device driver must open the chunk +before it can be used.

                • +

              • More than one user side +application can access the data in a shared chunk. A handle to a shared chunk +can be passed from one process to another process using standard handle passing +mechanisms. In practice, handles would be passed in a client-server context, +either from client to server or from server to client using inter-process +communication (IPC).

                • +

              • Processes that share +data inside a chunk should communicate the location of that data as an offset +from the start of the chunk, and not as an absolute address. The shared +chunk may appear at different addresses within the address spaces of different +user processes.

                • +
              +
              Local and global +chunks

              Local chunks

              A chunk is local when it is private to the process +creating it and is not intended for access by other user processes.

              A +local chunk cannot be mapped into any other process and is, therefore, used +for memory that does not need to be shared.

              A local chunk does not +have a name.

              Global chunks

              A chunk is global if it is intended to be accessed +by other processes.

              Global chunks have names that can be used to identify +the chunk to another process wishing to access it. A process can open a global +chunk by name; this maps the chunk into that process's address space, allowing +direct access and enabling the sharing of data between processes.

              If +the name of the global chunk to be opened is known, use RChunk::OpenGlobal(). +If a part of the name is known, use the RChunk::Open() variant +that takes a TFindChunk.

              A process can only access +an unnamed global chunk if it is passed a handle to that chunk from another +process. See RChunk::Open().

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8F19C257-9A41-5D38-BC8A-285D0EB16E1B_d0e402513_href.png Binary file Symbian3/SDK/Source/GUID-8F19C257-9A41-5D38-BC8A-285D0EB16E1B_d0e402513_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8F19C257-9A41-5D38-BC8A-285D0EB16E1B_d0e402675_href.png Binary file Symbian3/SDK/Source/GUID-8F19C257-9A41-5D38-BC8A-285D0EB16E1B_d0e402675_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8F29E5C9-0EEA-569C-ADB2-82FD61D87378_d0e323093_href.jpg Binary file Symbian3/SDK/Source/GUID-8F29E5C9-0EEA-569C-ADB2-82FD61D87378_d0e323093_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8F29E5C9-0EEA-569C-ADB2-82FD61D87378_d0e329250_href.jpg Binary file Symbian3/SDK/Source/GUID-8F29E5C9-0EEA-569C-ADB2-82FD61D87378_d0e329250_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8F4C626F-3490-50BC-A97F-FD1972FFF65B_d0e193631_href.png Binary file Symbian3/SDK/Source/GUID-8F4C626F-3490-50BC-A97F-FD1972FFF65B_d0e193631_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8F4C626F-3490-50BC-A97F-FD1972FFF65B_d0e198639_href.png Binary file Symbian3/SDK/Source/GUID-8F4C626F-3490-50BC-A97F-FD1972FFF65B_d0e198639_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8F6F6C2C-C00E-4412-A880-5EEBF7270265.dita --- a/Symbian3/SDK/Source/GUID-8F6F6C2C-C00E-4412-A880-5EEBF7270265.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-8F6F6C2C-C00E-4412-A880-5EEBF7270265.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,124 +1,120 @@ - - - - - -Generic -button -

              Button is a generic component, which may have touch down and release and/or -touch down and hold functionality. Touch down and hold can be interpreted -as touch down and hold or key repeat. Generic buttons can be placed, for example, -inside the toolbar.

              -

              The generic button can have the following properties:

                -

              • ON/OFF button - it can be used for active/inactive type of functions -such as Loudspeaker or Font italics.

                • -

              • Mode toggle button - can be used for switching between several -modes as in Flash.

                • -

              • Command button - it offers direct action (functions/view access) -such as Send or New contact with a button press feedback.

                • -

              -

              Buttons can have the following states:

                -

              • Unavailable / dimmed when button function is not available

                • -

              • Available and not pressed with or without focus when the button -is active but has not been pressed

                • -

              • Latched down with or without focus, for example, in case where -there are many different text formatting options ON at the same time. In multiple -mode buttons, user can switch between the different ’selected’ modes by touching -the multiple mode button again. States change after touch release and current -mode’s function is executed. Button states loop when the user touches those -again

                • -

              • Pressed with or without focus - This state indicates to the -user that touch down has activated the button

                • -

              -Default touch -events for generic button - - - - -

              User action

               -

              State change

               -

              Feedback

               -               - - - -

              Touch down

               -

              Button pressed effect. On down event application specific functionality.

               -

              Graphical indication and possible tooltip

              Tactile: Basic -button effect and audio feedback is provided with touch down.

               -               - -

              Touch release

               -

              Activates the button, launches other view or event.

              Button -is latched down or set to available and non-pressed.

               -

              Switches between down look and non-pressed look of the button.

              When -the toolbar button launches another view or event, the button does not appear -latched down.

              Tactile: Basic button effect is provided with touch release. -No audio feedback is provided.

               -               - -

              Touch down on a multiple mode button

               -

              Button is pressed.

               -

              Tactile: Basic button effect and audio feedback is provided with -touch down.

               -               - -

              Touch release on a multiple mode button

               -

              Current mode’s function is executed.

              User can switch between -different modes by touching the multiple mode button again. State changes -after touch release and current mode’s functions are executed. Button states -loop when the user touches those again.

               -

              Tactile: Basic button effect given with touch release. No audio -feedback given.

               -               - -

              Touch down and hold (also known as long tap)

               -

              Activates the button functionality, assigned for the touch down -and hold event.

              Application specific

               -

              Tactile: Basic button effect and audio feedback is provided with -touch down event.

               -               - -

              Touch down and hold (also known as key repeat

               -

              May or may not have key repeat functionality

              Application specific

               -

              Tactile: Basic button effect is provide with touch down. In case -of key repeat, sensitive button effect is provided.

               -               - -

              Touch down and move out from the button and releasing

               -

              If the drag moves outside the container, button functionality is -canceled with release event.

               -

              Tactile: Basic button effect and audio feedback with touch down -is provided. No feedback with release.

               -               - -

              Touch down and move out from the button and then back before up -event

               -

              As in touch down and release.

               -

              Tactile: Basic button effect and audio feedback is provided with -touch down. If release activates a function, then basic button effect is also -provided with touch release. No audio feedback with touch release.

               -               - -

              Touch down and move out from a button to another button and then -releasing

               -

              If the drag goes outside the container, button functionality is -canceled with release event and does not activate the other button.

               -

              Tactile: Basic button effect and audio feedback with touch down. -No feedback with release.

               -               - - -
              -
              Using generic -buttons in C++ applicationsThe API to use for creating the generic -button component is the Generic -Button API.
              + + + + + +Generic +button +

              Button is a generic component, which may have touch down and release and/or +touch down and hold functionality. Touch down and hold can be interpreted +as touch down and hold or key repeat. Generic buttons can be placed, for example, +inside the toolbar.

              +

              The generic button can have properties such as ON/OFF button, Mode toggle +button and Command button. For more details, see Toolbar:

              + + + +

              Buttons can have the following states:

                +

              • Unavailable / dimmed when button function is not available

                • +

              • Available and not pressed with or without focus when the button +is active but has not been pressed

                • +

              • Latched down with or without focus, for example, in case where +there are many different text formatting options ON at the same time. In multiple +mode buttons, user can switch between the different ’selected’ modes by touching +the multiple mode button again. States change after touch release and current +mode’s function is executed. Button states loop when the user touches those +again

                • +

              • Pressed with or without focus - This state indicates to the +user that touch down has activated the button

                • +

              +Default touch +events for generic button + + + +

              User action

               +

              State change

               +

              Feedback

               +               + + + +

              Touch down

               +

              Button pressed effect. On down event application specific functionality.

               +

              Graphical indication and possible tooltip

              Tactile: Basic +button effect and audio feedback is provided with touch down.

               +               + +

              Touch release

               +

              Activates the button, launches another view or event.

              Button +is latched down or set to available and non-pressed.

               +

              Switches between down look and non-pressed look of the button.

              When +the toolbar button launches another view or event, the button does not appear +latched down.

              Tactile: Basic button effect is provided with touch release. +No audio feedback is provided.

               +               + +

              Touch down on a multiple mode button.

               +

              Button is pressed.

               +

              Tactile: Basic button effect and audio feedback is provided with +touch down.

               +               + +

              Touch release on a multiple mode button.

               +

              Current mode’s function is executed.

              User can switch between +different modes by touching the multiple mode button again. State changes +after touch release and current mode’s functions are executed. Button states +loop when the user touches those again.

               +

              Tactile: Basic button effect given with touch release. No audio +feedback given.

               +               + +

              Touch down and hold (also known as long tap).

               +

              Activates the button functionality, assigned for the touch down +and hold event.

              Application specific.

               +

              Tactile: Basic button effect and audio feedback is provided with +touch down event.

               +               + +

              Touch down and hold (also known as key repeat).

               +

              May or may not have key repeat functionality

              Application specific.

               +

              Tactile: Basic button effect is provide with touch down. In case +of key repeat, sensitive button effect is provided.

               +               + +

              Touch down and move out from the button and releasing.

               +

              If the drag moves outside the container, button functionality is +canceled with release event.

               +

              Tactile: Basic button effect and audio feedback with touch down +is provided. No feedback with release.

               +               + +

              Touch down and move out from the button and then back before up +event.

               +

              As in touch down and release.

               +

              Tactile: Basic button effect and audio feedback is provided with +touch down. If release activates a function, then basic button effect is also +provided with touch release. No audio feedback with touch release.

               +               + +

              Touch down and move out from a button to another button and then +releasing.

               +

              If the drag goes outside the container, button functionality is +canceled with release event and does not activate the another button.

               +

              Tactile: Basic button effect and audio feedback with touch down. +No feedback with release.

               +               + + +
              +
              Using generic +buttons in applicationsThe API to use for creating the generic button +component is the Generic +Button API.
              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-8F8E3814-7ED6-4218-BEEF-741AE0E9366F.dita --- a/Symbian3/SDK/Source/GUID-8F8E3814-7ED6-4218-BEEF-741AE0E9366F.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-8F8E3814-7ED6-4218-BEEF-741AE0E9366F.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,58 +1,58 @@ - - - - - -Changing -the PriorityThis section describes how an application (internal or third-party) -can change its priority by using OOM Monitor APIs. -

              An application -which is processing a task in the background can change its priority at runtime -to protect itself from being closed by the OOM Monitor. For example:

                -

              • Music Player playing music in the background

                • -

              • Download Manager downloading a file in the background

                • -

              If an application is processing a task for the user in the background, -the application is said to be Busy and the OOM Monitor must -not close a Busy application. An application can declare -itself to be Busy using ROomMonitorSession::SetOomPriority(EOomPriorityBusy) method. -When the application finishes its background job and becomes idle, it should -change its priority to Normal.

               - -Create an OOM Monitor -session -ROomMonitorSession ioomMonitorSession; -CleanUpClosePushL(ioomMonitorSession); -User::LeaveIfError(ioomMonitorSession.Connect()); - - -Set the priority -for the application to Busy before performing the background -task -iOomMonitorSession.SetOomPriority(ROomMonitorSession::EOomPriorityBusy); -DoCriticalBackgroundProcessingL(); - - -Set the priority -for the application to Normal after the task is completed. -iOomMonitorSession.SetOomPriority(ROomMonitorSession::EOomPriorityNormal); - - -Close the session. -iOomMonitorSession.Close(); - - - -               -OOM Monitor -Priority -OOM Monitor -Overview -OOM Monitor -Reference + + + + + +Changing +the PriorityThis section describes how an application (internal or third-party) +can change its priority by using OOM Monitor APIs. +

              An application +which is processing a task in the background can change its priority at runtime +to protect itself from being closed by the OOM Monitor. For example:

                +

              • Music Player playing music in the background

                • +

              • Download Manager downloading a file in the background

                • +

              If an application is processing a task for the user in the background, +the application is said to be Busy and the OOM Monitor must +not close a Busy application. An application can declare +itself to be Busy using ROomMonitorSession::SetOomPriority(EOomPriorityBusy) method. +When the application finishes its background job and becomes idle, it should +change its priority to Normal.

               + +Create an OOM Monitor +session +ROomMonitorSession ioomMonitorSession; +CleanUpClosePushL(ioomMonitorSession); +User::LeaveIfError(ioomMonitorSession.Connect()); + + +Set the priority +for the application to Busy before performing the background +task +iOomMonitorSession.SetOomPriority(ROomMonitorSession::EOomPriorityBusy); +DoCriticalBackgroundProcessingL(); + + +Set the priority +for the application to Normal after the task is completed. +iOomMonitorSession.SetOomPriority(ROomMonitorSession::EOomPriorityNormal); + + +Close the session. +iOomMonitorSession.Close(); + + + +               +OOM Monitor +Priority +OOM Monitor +Overview +OOM Monitor +Reference               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-90076A13-E062-5A7B-BB0F-168F7C8A96DD_d0e76273_href.png Binary file Symbian3/SDK/Source/GUID-90076A13-E062-5A7B-BB0F-168F7C8A96DD_d0e76273_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-90076A13-E062-5A7B-BB0F-168F7C8A96DD_d0e82985_href.png Binary file Symbian3/SDK/Source/GUID-90076A13-E062-5A7B-BB0F-168F7C8A96DD_d0e82985_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9014ED9B-B0A0-5C95-9C5B-7D2F658C757F.dita --- a/Symbian3/SDK/Source/GUID-9014ED9B-B0A0-5C95-9C5B-7D2F658C757F.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,33 +0,0 @@ - - - - - -Accessing and Power Control of CameraThis tutorial describes how to access camera and control its power settings using Ecam APIs:
              Purpose

              The purpose of the tutorial is to explain you how to use Ecam APIs to access and control power settings of a camera on a phone.

              Required Background

              The Onboard Camera Overview introduces the camera utilities.

              Camera is implemented as Ecom plug-ins, the Ecom plug-in implements CCamera interface defined in ECam.h. When you need to create a new camera object, the Ecam library requests a camera plug-in from the ECOM framework.

              Introduction

              Ecam is a component of the Symbian platform Multimedia subsystem that represents the Onboard Camera API. Licensees may provide customised implementation for snapshots, histogram and image processing depending on the camera mode in which it is operated.

              Using Camera

              The following tasks will be covered in this tutorial:

              • Accessing the Camera

              • Power Control

              Accessing the Camera

              The high level steps to access specific camera connected to the device are shown here:

              1. Make sure that you configure the initial settings and use CCamera::CamerasAvailable() method to get the number of cameras available for usage.

                TInt numCameras = CCamera::CamerasAvailable(); -if (numCameras <= 0) - { - INFO_PRINTF2(_L("Error %d returned"), numCameras); - return EFail; - } -INFO_PRINTF2(_L("Available cameras %d returned"), numCameras); -return EPass; -

              2. Create a new camera object using CCamera::New2L() API.

                CCamera* camera = NULL; -MCameraObserver2* observer2L; //exists beforehand - -camera = CCamera::New2L(*observer2, 0, 0); -

              3. Use Ccamera::NewDuplicate2L, if collaborative clients wants to share the same camera device. This makes sure that the client can receive unrecognised enum, UIDs and so on.

                Note: This is true if New2L method instead of NewL and NewDuplicate2L method is instead of over NewDuplicateL method.

                CCamera* sharingCamera = NULL; -sharingCamera = CCamera::NewDuplicate2L(*observer2, 0);

              4. Use CCamera::Reserve, an asynchronous method to gain exclusive access to a particular camera.

                Even if a camera object is created successfully based on specified camera index, the client cannot use it, if it is not reserved.

                • The CCamera::Reserve call will be unsuccessful if a higher priority client is already using the camera and MCameraObserver2::HandleEvent call back will return an error.

                • Event UID KUidECamEventCameraNoLongerReserved notifies that a high priority client has gained control over another client.

              5. Use HandleEvent() method to notify the client that the call is unsuccessful and the camera is not available. This can be due to completion of a call to Reserve(), a call to PowerOn() or a notification that the client has lost control of the camera.

                This provides a reference to a TECAMEvent with uid KUidECamEventReserveComplete and error as KErrNone.

                void HandleEvent(const TECAMEvent& aEvent); -void TDummyObserver::HandleEvent(const TECAMEvent& /*aEvent*/) - { - return; - }

              6. Use CCamera::Release() method to de-initialize and withdraw the client's access to the camera such that other clients might use it.

              Note: Clients should not use the legacy call-back interface MCameraObserver which is still supported.

              Power Control

              The high level steps to control the power settings of the camera are shown here:

              1. Use PowerOn(), an asynchronous method, to switch on the camera, when the client gains exclusive access for the given camera.

                When power on is complete, client receives notification through MCameraObserver2::HandleEvent callback with uid KUidECamEventPowerOnComplete and the appropriate error code. If the camera is not successfully reserved, PowerOn will fail.

              2. The callback interface is notified when power on is complete via MCameraObserver2::HandleEvent() notification. The event used is KUidECamEventPowerOnComplete.

                void CCamMyPlugin::PowerOn() - { - }

              3. Once the processing is complete, use PowerOff(), a synchronous method to switch off the camera power.

                void CCamMyPlugin::PowerOff() - { - }
              Miscellaneous

              This section details miscellaneous camera access and control APIsl.

              Reserve Status Retrieval

              Licensees need to implement MSecureIdPlugin (ecaminfoplugin.h) to retrieve the secure ID of the process where serialized part of the ECam implementation runs, such as Ecam server.

              Clients can retrieve the reservation status of a particular camera prior to creating an instance of the Ccamera class. This saves time, if the client is denied control to reserve the camera after creating an instance of theCcamera class. Client needs to subscribe for receiving the reserve status by calling static method TreservedInfo::SubscribeReserveInfoL() and this provides a reference to CcameraStatusWatch.

              Symbian must provide implementation of CCameraStatusWatch class. Clients can use this to asynchronously receive the reserve status of a camera index through MReserveObserver. Client must implement MReserveObserver to handle the notifications of Reserve status and take appropriate steps accordingly. Note: If the client needs to unsubscribe, it must make sure to delete the CcameraStatusWatch object.

              Get the reserve status of the camera using ReserveStatus API. This can be used, when a low priority client interrupts a high priority client in a phone supporting multiple cameras.

              Camera Preset Support Capturing Image Capturing Video               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9022E900-2BDD-5B64-9802-4EBA5BFEB4B2_d0e111104_href.png Binary file Symbian3/SDK/Source/GUID-9022E900-2BDD-5B64-9802-4EBA5BFEB4B2_d0e111104_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9022E900-2BDD-5B64-9802-4EBA5BFEB4B2_d0e117642_href.png Binary file Symbian3/SDK/Source/GUID-9022E900-2BDD-5B64-9802-4EBA5BFEB4B2_d0e117642_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9045FC43-162E-52B8-ABE2-5EC1EC88BD99_d0e196262_href.png Binary file Symbian3/SDK/Source/GUID-9045FC43-162E-52B8-ABE2-5EC1EC88BD99_d0e196262_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9045FC43-162E-52B8-ABE2-5EC1EC88BD99_d0e201270_href.png Binary file Symbian3/SDK/Source/GUID-9045FC43-162E-52B8-ABE2-5EC1EC88BD99_d0e201270_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-90644B52-69D7-595C-95E3-D6F7A30C060D.dita --- a/Symbian3/SDK/Source/GUID-90644B52-69D7-595C-95E3-D6F7A30C060D.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-90644B52-69D7-595C-95E3-D6F7A30C060D.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,212 +1,212 @@ - - - - - -Font -and Text Services Collection OverviewA font is a set of characters of matching size (height) and appearance. -In order to be displayed each character must ultimately be drawn as a series -of pixels (a bitmap). Symbian can store fonts in bitmap or vector form. A -vector font (for example, an OpenType font) must be converted to bitmaps (or -rasterized) before it can be drawn. Symbian caches and shares bitmaps for -performance and memory efficiency. -
                -

              • Application developers can -use Font and Text Services for selecting fonts for displaying text according -to various criteria (size and typeface).

                • -

              • Device creators can -add fonts and font rasterizers. Fonts can be included in the ROM or installed -on user drives.

                • -
              -
              Concepts and -terms
              - -
              Points, twips and pixels
              -

              Points (1/72th inch) and twips (a twentieth of a point) are absolute -measurements of distance and specify device-independent size. Pixel sizes -are only relevant for a specific graphics device. Each graphics device (screen -or printer) must provide a mechanism for converting between pixels and twips.

              -               - -
              Font
              -

              A named set of characters of matching size (height) and font style (normal, -bold, italic, underline). Times Roman 14 point bold is an example of -a font.

              -               - -
              Typeface
              -

              A group of fonts with similar appearance. The typeface does not include -the size or font style. Times is an example of a typeface. Typefaces -are sometimes referred to as font families.

              Typefaces are grouped -generically as mono-spaced, variable width, serif, sans-serif and symbol. -This allows the grouping of typefaces that have similar characteristics, so -that an alternative font can be selected when an exact match is not found. -This means that applications can display text relatively accurately when a -specific font is not available.

              -               - -
              OpenType font
              -

              A font that is stored as vector data, which can be rasterized to any -pixel size. OpenType fonts are sometimes simply called open fonts. -An open font can only be used with a corresponding font rasterizer. The Font and Bitmap Server caches -rasterized fonts into bitmap form.

              OpenType is an open source vector -font format, which is similar to TrueType. Like TrueType fonts, OpenType fonts -can contain font hinting information. However the font rasterizer's use of -the font hinting information in OpenType fonts is restricted by a software -patent.

              -               - -
              Character
              -

              A single element (such as a letter, number, ligature, symbol or punctuation -mark) of written language. Each character has a unique number (its Unicode code point).

              -               - -
              Glyph
              -

              A graphical representation of a character in a specific font. The mapping -between a character and a glyph is not always direct. For example, a character -may be represented by different glyphs, depending on the context.

              -               - -
              Font metrics
              -

              Measurements (such as maximum height) that are common to all of the -characters in a font.

              -               - -
              Character metrics
              -

              Measurements (such as character width) that apply to an individual -character within a font.

              -               - -
              Bitmap font
              -

              A font stored as bitmap glyphs. The size of a font is described in -pixels. However, the actual size is dependent on the pixel size of the graphics -device.

              -               - -
              Rasterizing
              -

              The process of converting drawing instructions into bitmap data. Fonts -provided in vector form (OpenType fonts) must be rasterized into fixed size -fonts before they can be used.

              -               - -
              Linked font
              -

              A virtual font or typeface created from characters from other fonts. -The component fonts must be open fonts or other linked fonts. Linked fonts -are typically used where a preferred font does not contain all of the characters -in the character set. One of the typefaces in a linked font must be designated -as the principal typeface from which any unspecified default metrics or characters -are used.

              -               - -
              Contextual shaping
              -

              In some scripts some characters are drawn differently depending on -the adjacent characters. This means that different glyphs are used to represent -a particular character in different contexts. Contextual shaping is the selection -of the appropriate glyph from several glyphs that represent a particular character -depending on the context.

              In Latin scripts, contextual shaping is -normally used only when simulating handwriting. For example, the glyph used -for the letter p might depend on whether the letter is at the start, -middle or end of a word, as shown in the following diagram. For example, when -it is in the middle of the word, it might have a "tail" on both sides to join -it to the letters that appear before and after.

              - Figure 1: Handwriting simulation might use different -glyphs for the letter p depending on its position in a word - - -

              Contextual shaping is an essential feature of some scripts, including -Arabic and many Indian and East Asian scripts, such as Devanagari, Kannada, -Telugu, Tamil, Bengali, Malayalam and Gurmukhi. For this reason, support for -contextual shaping is sometimes referred to as Brahmic support.

              -               - -
              Text shaper
              -

              A plug-in that performs the contextual shaping for scripts that require -this feature. Text shapers are font and language specific.

              -               - -
              System font
              -

              A default font that is used when no font is specified.

              -               -
              -
              Architectural relationships

              The Font and Text Services -components are closely integrated with the Font and Bitmap Server, GDI, BitGDI -and Window Server components in the Graphics -package. Font size is only meaningful in the context of the current -graphics device and its pixel size. Open fonts must be rasterized in the context -of the current graphics device. The diagram below shows how BitGDI implements -Graphics Devices and Contexts.

              - Figure 2: The Graphics Device and Context Architecture. - -

              Note that the names of the BitGDI classes begin with CFbs.

              - -

              Applications access font services through the Font -and Bitmap Server (FBSERV) which caches font bitmaps in a shared heap. -The Font and Bitmap Server ensures that there is only ever a single instance -of a particular glyph bitmap in memory. However, eXecute In Place (XIP) ROM-based -bitmaps (including fonts) are used in place and are not copied into the heap.

              Use -of the Font and Bitmap Server is transparent to clients of the Window Server. -The Window Server client session (RWsSession) automatically -creates an RFbsSession and stores it in thread local storage -(TLS). The Font and Bitmap Server provides two client-side classes for fonts: CFbsFont and CFbsTypefaceStore. These find and use the session in TLS automatically. Clients of the Window -Server are therefore automatically clients of the Font and Bitmap Server and -need perform no explicit session management.

              Classes representing -fonts, such as CFbsFont (on the client side) and CBitmapFont (on -the server side), are derived from the abstract class CFont.

              The Font Store lives in -the Font and Bitmap -Server and contains all of the fonts on the device and the font rasterizers -required to render them. The Font Store loads font files when the phone starts -up. It scans all of the drives on the device so that new fonts can be installed -from user drives. Font files can be loaded by the Font Store while the phone -is running. However, font rasterizers can only be installed by restarting -the phone. If a new font requires a font rasterizer to be installed, the phone -must be restarted before the font can be used.

              Open font rasterizers -are implemented as ECOM plug-ins. An open font file (represented by COpenFontFile) -can contain one or more open fonts in proprietary vector format. A corresponding -font rasterizer plug-in (COpenFontRasterizer) must convert -the vector data into bitmaps that the Font and Bitmap Server can cache and -access using the CBitmapFont and COpenFont APIs. -Applications use rasterized open fonts by using CFbsFont in -exactly the same way as native bitmap fonts. The open font framework means -that Symbian can support any font in any format. There is a performance impact -associated with open fonts, however, as they must be rasterized.

              Text -shapers (CShaper) are used for contextual scripts, which -require their glyphs to be modified according to the adjacent characters. -Text shapers are font and language specific.

              -
              Components

              The Font and Text Services collection -is made up of the following components:

                -

              • Font -Store. This manages font matching, ownership and rasterizing.

                • -

              • FreeType -Font Rasterizer. This open source plug-in rasterizes OpenType fonts. -More information can be found at www.freetype.org. -This rasterizer is normally loaded by default.

                • -

              • ICU -Layout Engine Component. A plug-in that performs contextual shaping -for specific scripts that require this feature. When a function, such as CFbsBitGc::DrawText() draws -text in one of these scripts, internally a text shaper is used to convert -the string of characters into the appropriate series of glyphs.

                • -

              • Reference -Fonts. This provides a collection of reference font files including -bitmap and OpenType fonts. By default the Symbian platform supports the DejaVu -OpenType typeface (which includes variable-width, monospaced, serif and sans -serif fonts) and legacy Calculator and Agenda symbols (which are bitmap fonts).

                • -

              Note: The iType -Font Rasterizer is an OpenType font rasterizer from MonoType Imaging®. -This provides additional features compared to the FreeType font rasterizer, -such as four color blending, which is required for outline and shadow fonts. -This component is not provided by the Symbian Foundation because it belongs -to Monotype. However, the Symbian platform has test cases for the four color -blending that the iType Font Rasterizer provides. These test cases can be -used by device creators who obtain this font rasterizer from MonoType.

              -               -Font and -Bitmap Server Component Overview - Font Store -Component Overview + + + + + +Font +and Text Services Collection OverviewA font is a set of characters of matching size (height) and appearance. +In order to be displayed each character must ultimately be drawn as a series +of pixels (a bitmap). Symbian can store fonts in bitmap or vector form. A +vector font (for example, an OpenType font) must be converted to bitmaps (or +rasterized) before it can be drawn. Symbian caches and shares bitmaps for +performance and memory efficiency. +
                +

              • Application developers can +use Font and Text Services for selecting fonts for displaying text according +to various criteria (size and typeface).

                • +

              • Device creators can +add fonts and font rasterizers. Fonts can be included in the ROM or installed +on user drives.

                • +
              +
              Concepts and +terms
              + +
              Points, twips and pixels
              +

              Points (1/72th inch) and twips (a twentieth of a point) are absolute +measurements of distance and specify device-independent size. Pixel sizes +are only relevant for a specific graphics device. Each graphics device (screen +or printer) must provide a mechanism for converting between pixels and twips.

              +               + +
              Font
              +

              A named set of characters of matching size (height) and font style (normal, +bold, italic, underline). Times Roman 14 point bold is an example of +a font.

              +               + +
              Typeface
              +

              A group of fonts with similar appearance. The typeface does not include +the size or font style. Times is an example of a typeface. Typefaces +are sometimes referred to as font families.

              Typefaces are grouped +generically as mono-spaced, variable width, serif, sans-serif and symbol. +This allows the grouping of typefaces that have similar characteristics, so +that an alternative font can be selected when an exact match is not found. +This means that applications can display text relatively accurately when a +specific font is not available.

              +               + +
              OpenType font
              +

              A font that is stored as vector data, which can be rasterized to any +pixel size. OpenType fonts are sometimes simply called open fonts. +An open font can only be used with a corresponding font rasterizer. The Font and Bitmap Server caches +rasterized fonts into bitmap form.

              OpenType is an open source vector +font format, which is similar to TrueType. Like TrueType fonts, OpenType fonts +can contain font hinting information. However the font rasterizer's use of +the font hinting information in OpenType fonts is restricted by a software +patent.

              +               + +
              Character
              +

              A single element (such as a letter, number, ligature, symbol or punctuation +mark) of written language. Each character has a unique number (its Unicode code point).

              +               + +
              Glyph
              +

              A graphical representation of a character in a specific font. The mapping +between a character and a glyph is not always direct. For example, a character +may be represented by different glyphs, depending on the context.

              +               + +
              Font metrics
              +

              Measurements (such as maximum height) that are common to all of the +characters in a font.

              +               + +
              Character metrics
              +

              Measurements (such as character width) that apply to an individual +character within a font.

              +               + +
              Bitmap font
              +

              A font stored as bitmap glyphs. The size of a font is described in +pixels. However, the actual size is dependent on the pixel size of the graphics +device.

              +               + +
              Rasterizing
              +

              The process of converting drawing instructions into bitmap data. Fonts +provided in vector form (OpenType fonts) must be rasterized into fixed size +fonts before they can be used.

              +               + +
              Linked font
              +

              A virtual font or typeface created from characters from other fonts. +The component fonts must be open fonts or other linked fonts. Linked fonts +are typically used where a preferred font does not contain all of the characters +in the character set. One of the typefaces in a linked font must be designated +as the principal typeface from which any unspecified default metrics or characters +are used.

              +               + +
              Contextual shaping
              +

              In some scripts some characters are drawn differently depending on +the adjacent characters. This means that different glyphs are used to represent +a particular character in different contexts. Contextual shaping is the selection +of the appropriate glyph from several glyphs that represent a particular character +depending on the context.

              In Latin scripts, contextual shaping is +normally used only when simulating handwriting. For example, the glyph used +for the letter p might depend on whether the letter is at the start, +middle or end of a word, as shown in the following diagram. For example, when +it is in the middle of the word, it might have a "tail" on both sides to join +it to the letters that appear before and after.

              + Figure 1: Handwriting simulation might use different +glyphs for the letter p depending on its position in a word + + +

              Contextual shaping is an essential feature of some scripts, including +Arabic and many Indian and East Asian scripts, such as Devanagari, Kannada, +Telugu, Tamil, Bengali, Malayalam and Gurmukhi. For this reason, support for +contextual shaping is sometimes referred to as Brahmic support.

              +               + +
              Text shaper
              +

              A plug-in that performs the contextual shaping for scripts that require +this feature. Text shapers are font and language specific.

              +               + +
              System font
              +

              A default font that is used when no font is specified.

              +               +
              +
              Architectural relationships

              The Font and Text Services +components are closely integrated with the Font and Bitmap Server, GDI, BitGDI +and Window Server components in the Graphics +package. Font size is only meaningful in the context of the current +graphics device and its pixel size. Open fonts must be rasterized in the context +of the current graphics device. The diagram below shows how BitGDI implements +Graphics Devices and Contexts.

              + Figure 2: The Graphics Device and Context Architecture. + +

              Note that the names of the BitGDI classes begin with CFbs.

              + +

              Applications access font services through the Font +and Bitmap Server (FBSERV) which caches font bitmaps in a shared heap. +The Font and Bitmap Server ensures that there is only ever a single instance +of a particular glyph bitmap in memory. However, eXecute In Place (XIP) ROM-based +bitmaps (including fonts) are used in place and are not copied into the heap.

              Use +of the Font and Bitmap Server is transparent to clients of the Window Server. +The Window Server client session (RWsSession) automatically +creates an RFbsSession and stores it in thread local storage +(TLS). The Font and Bitmap Server provides two client-side classes for fonts: CFbsFont and CFbsTypefaceStore. These find and use the session in TLS automatically. Clients of the Window +Server are therefore automatically clients of the Font and Bitmap Server and +need perform no explicit session management.

              Classes representing +fonts, such as CFbsFont (on the client side) and CBitmapFont (on +the server side), are derived from the abstract class CFont.

              The Font Store lives in +the Font and Bitmap +Server and contains all of the fonts on the device and the font rasterizers +required to render them. The Font Store loads font files when the phone starts +up. It scans all of the drives on the device so that new fonts can be installed +from user drives. Font files can be loaded by the Font Store while the phone +is running. However, font rasterizers can only be installed by restarting +the phone. If a new font requires a font rasterizer to be installed, the phone +must be restarted before the font can be used.

              Open font rasterizers +are implemented as ECOM plug-ins. An open font file (represented by COpenFontFile) +can contain one or more open fonts in proprietary vector format. A corresponding +font rasterizer plug-in (COpenFontRasterizer) must convert +the vector data into bitmaps that the Font and Bitmap Server can cache and +access using the CBitmapFont and COpenFont APIs. +Applications use rasterized open fonts by using CFbsFont in +exactly the same way as native bitmap fonts. The open font framework means +that Symbian can support any font in any format. There is a performance impact +associated with open fonts, however, as they must be rasterized.

              Text +shapers (CShaper) are used for contextual scripts, which +require their glyphs to be modified according to the adjacent characters. +Text shapers are font and language specific.

              +
              Components

              The Font and Text Services collection +is made up of the following components:

                +

              • Font +Store. This manages font matching, ownership and rasterizing.

                • +

              • FreeType +Font Rasterizer. This open source plug-in rasterizes OpenType fonts. +More information can be found at www.freetype.org. +This rasterizer is normally loaded by default.

                • +

              • ICU +Layout Engine Component. A plug-in that performs contextual shaping +for specific scripts that require this feature. When a function, such as CFbsBitGc::DrawText() draws +text in one of these scripts, internally a text shaper is used to convert +the string of characters into the appropriate series of glyphs.

                • +

              • Reference +Fonts. This provides a collection of reference font files including +bitmap and OpenType fonts. By default the Symbian platform supports the DejaVu +OpenType typeface (which includes variable-width, monospaced, serif and sans +serif fonts) and legacy Calculator and Agenda symbols (which are bitmap fonts).

                • +

              Note: The iType +Font Rasterizer is an OpenType font rasterizer from MonoType Imaging®. +This provides additional features compared to the FreeType font rasterizer, +such as four color blending, which is required for outline and shadow fonts. +This component is not provided by the Symbian Foundation because it belongs +to Monotype. However, the Symbian platform has test cases for the four color +blending that the iType Font Rasterizer provides. These test cases can be +used by device creators who obtain this font rasterizer from MonoType.

              +               +Font and +Bitmap Server Component Overview + Font Store +Component Overview               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-90B58A30-8BE8-48E8-ADB2-57E8A0AD8376.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-90B58A30-8BE8-48E8-ADB2-57E8A0AD8376.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,13 @@ + + + + + +HDMIThis section describes HDMI functionality within the Multimedia +subsystem. \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-90B593E2-F38B-5B38-9367-E2BF344A2834_d0e413239_href.png Binary file Symbian3/SDK/Source/GUID-90B593E2-F38B-5B38-9367-E2BF344A2834_d0e413239_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-90B593E2-F38B-5B38-9367-E2BF344A2834_d0e413401_href.png Binary file Symbian3/SDK/Source/GUID-90B593E2-F38B-5B38-9367-E2BF344A2834_d0e413401_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-90DF40EF-7D3F-551D-9957-A3756317A254.dita --- a/Symbian3/SDK/Source/GUID-90DF40EF-7D3F-551D-9957-A3756317A254.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-90DF40EF-7D3F-551D-9957-A3756317A254.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,101 +1,101 @@ - - - - - -OCSP -Overview -

              Online Certificate Status Protocol (OCSP) is an internet protocol that -determines whether a given certificate or -a list of certificates has been revoked, and therefore, determines whether -the certificate can be trusted. The protocol is defined in RFC2560.

              -

              On the Symbian platform, Secure -Software Install (SWI) uses OCSP to verify whether a certificate associated -with an application to be installed has been revoked. For details of how SWI -uses OCSP revocation check, see OCSP -SWI Integration.

              -
              OCSP request and response

              OCSP primarily consists -of two parts: a request and a response, each specified in the Abstract Syntax -Notation One - Distinguished Encoding Rules (ASN.1 -DER) format. A client application that wants -to get information on the revocation status of a certificate, forms an OCSP -request and sends this to an OCSP server. In its simplest form, an OCSP request -consists of one or more identifiers for the certificates whose status is in -question. The request is sent to the OCSP server identified by a Uniform Resource -Identifier (URI). The URI is specified either in the Authority Information -Access (AIA) extension of the certificate whose revocation status is to be -checked, or as a global URI with the OCSP client. AIA is defined in RFC2459.

              The -OCSP server maintains information about the revocation of certificates. The -server replies to the client with a signed OCSP response, mentioning the revocation -status for each certificate. A response being signed with a key pair is trusted -as authoritative by the client. Alternatively, a server can also return an -error code as response (refer to RFC2560 for details of the various OCSP errors). OCSP -is transport-neutral with the URI of the server indicating the required transport -mechanism. Currently, only Hypertext Transfer Protocol (HTTP) is supported.

              The -client, in turn, verifies whether the response is valid and is from a trusted -entity.

              -
              OCSP client-server interaction

              The server to which -the request for revocation check is sent may not actually be the server which -is authoritative to answer the request, but may act as a proxy to the destination -server. For information on the server to which the request actually gets routed, -the client includes a serviceLocator extension (containing the URI) -in the OCSP request.

              There may be a serviceLocator extension -for each certificate in the request. Therefore, it is syntactically possible -for the request to be split into multiple parts, with each part routed to -a different OCSP responder (the server that actually responds to the OCSP -request). The intermediate server collates the individual responses into one -and returns this to the client. This response is signed only by the intermediate -server. In such a situation, the client must trust this intermediate server.

              Three -scenarios are associated with the routing of OCSP requests to the appropriate -responder through intermediate servers. They are as follows:

                -

              • Single OCSP responder

                One -OCSP server contains the revocation information for all the certificates to -be checked. One request containing all the certificates is sent to the responder -(in this case, the OCSP server), which replies with a single response. The -following figure illustrates the interaction between the OCSP client and a -single destination responder.

                - -
                • -

              • Multiple OCSP responders -using an intermediate OCSP server

                Multiple OCSP responders use -an intermediate OCSP server to route requests to the appropriate destination -responders. One request is sent to the intermediate server, which sends multiple -individual requests to the destination responders. The responses are collated, -and one response is sent back to the client. The following figure shows the -interaction between an OCSP client and multiple destination responders by -using an intermediate responder.

                - -
                • -

              • Multiple OCSP responders -without an intermediate server

                The client does the work of sending -each request to the appropriate responder. The client collates the responses -received. The following figure shows the interaction between the client and -multiple destination responders.

                - -
                • -

              The choice of the correct method of interaction between the client -and the responders depends on the nature of the Public Key Infrastructure -(PKI) and the availability of OCSP responders for routing requests as intermediates.

              -
              Revocation check results

              If the response sent by -the OCSP server passes all the validation, the application that sends the -OCSP request determines the outcome by applying the following rules to the -certificate statuses in the response:

                -

              • If any certificate is -revoked, the result is Revoked

                • -

              • If all certificates -are valid, the result is Good

                • -

              • Otherwise, the result -is Unknown.

                • -

              Note: A certificate status of Good does not indicate -that the certificate may be trusted. It merely indicates that the certificate -has not been revoked. The normal validation of that certificate (or the certificate chain in -which it lies) must still be performed.

              -               -OCSP SWI -Integration + + + + + +OCSP +Overview +

              Online Certificate Status Protocol (OCSP) is an internet protocol that +determines whether a given certificate or +a list of certificates has been revoked, and therefore, determines whether +the certificate can be trusted. The protocol is defined in RFC2560.

              +

              On the Symbian platform, Secure +Software Install (SWI) uses OCSP to verify whether a certificate associated +with an application to be installed has been revoked. For details of how SWI +uses OCSP revocation check, see OCSP +SWI Integration.

              +
              OCSP request and response

              OCSP primarily consists +of two parts: a request and a response, each specified in the Abstract Syntax +Notation One - Distinguished Encoding Rules (ASN.1 -DER) format. A client application that wants +to get information on the revocation status of a certificate, forms an OCSP +request and sends this to an OCSP server. In its simplest form, an OCSP request +consists of one or more identifiers for the certificates whose status is in +question. The request is sent to the OCSP server identified by a Uniform Resource +Identifier (URI). The URI is specified either in the Authority Information +Access (AIA) extension of the certificate whose revocation status is to be +checked, or as a global URI with the OCSP client. AIA is defined in RFC2459.

              The +OCSP server maintains information about the revocation of certificates. The +server replies to the client with a signed OCSP response, mentioning the revocation +status for each certificate. A response being signed with a key pair is trusted +as authoritative by the client. Alternatively, a server can also return an +error code as response (refer to RFC2560 for details of the various OCSP errors). OCSP +is transport-neutral with the URI of the server indicating the required transport +mechanism. Currently, only Hypertext Transfer Protocol (HTTP) is supported.

              The +client, in turn, verifies whether the response is valid and is from a trusted +entity.

              +
              OCSP client-server interaction

              The server to which +the request for revocation check is sent may not actually be the server which +is authoritative to answer the request, but may act as a proxy to the destination +server. For information on the server to which the request actually gets routed, +the client includes a serviceLocator extension (containing the URI) +in the OCSP request.

              There may be a serviceLocator extension +for each certificate in the request. Therefore, it is syntactically possible +for the request to be split into multiple parts, with each part routed to +a different OCSP responder (the server that actually responds to the OCSP +request). The intermediate server collates the individual responses into one +and returns this to the client. This response is signed only by the intermediate +server. In such a situation, the client must trust this intermediate server.

              Three +scenarios are associated with the routing of OCSP requests to the appropriate +responder through intermediate servers. They are as follows:

                +

              • Single OCSP responder

                One +OCSP server contains the revocation information for all the certificates to +be checked. One request containing all the certificates is sent to the responder +(in this case, the OCSP server), which replies with a single response. The +following figure illustrates the interaction between the OCSP client and a +single destination responder.

                + +
                • +

              • Multiple OCSP responders +using an intermediate OCSP server

                Multiple OCSP responders use +an intermediate OCSP server to route requests to the appropriate destination +responders. One request is sent to the intermediate server, which sends multiple +individual requests to the destination responders. The responses are collated, +and one response is sent back to the client. The following figure shows the +interaction between an OCSP client and multiple destination responders by +using an intermediate responder.

                + +
                • +

              • Multiple OCSP responders +without an intermediate server

                The client does the work of sending +each request to the appropriate responder. The client collates the responses +received. The following figure shows the interaction between the client and +multiple destination responders.

                + +
                • +

              The choice of the correct method of interaction between the client +and the responders depends on the nature of the Public Key Infrastructure +(PKI) and the availability of OCSP responders for routing requests as intermediates.

              +
              Revocation check results

              If the response sent by +the OCSP server passes all the validation, the application that sends the +OCSP request determines the outcome by applying the following rules to the +certificate statuses in the response:

                +

              • If any certificate is +revoked, the result is Revoked

                • +

              • If all certificates +are valid, the result is Good

                • +

              • Otherwise, the result +is Unknown.

                • +

              Note: A certificate status of Good does not indicate +that the certificate may be trusted. It merely indicates that the certificate +has not been revoked. The normal validation of that certificate (or the certificate chain in +which it lies) must still be performed.

              +               +OCSP SWI +Integration               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-91224821-8094-59ED-A100-4174193A25EE_d0e264846_href.png Binary file Symbian3/SDK/Source/GUID-91224821-8094-59ED-A100-4174193A25EE_d0e264846_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-91224821-8094-59ED-A100-4174193A25EE_d0e268554_href.png Binary file Symbian3/SDK/Source/GUID-91224821-8094-59ED-A100-4174193A25EE_d0e268554_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9126A296-0301-4077-A183-3D703F77C548.dita --- a/Symbian3/SDK/Source/GUID-9126A296-0301-4077-A183-3D703F77C548.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-9126A296-0301-4077-A183-3D703F77C548.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,90 +1,90 @@ - - - - - -Multi-Touch -Support in the Emulator OverviewThis topic provides an overview of multi-touch support in the emulator. -Two mice are used to provide two independent pointer positions. The emulator -responds to the mice’s individual button-clicks, moves, and mouse wheel scrolls -as if two human fingers are moving, touching or hovering over the screen. -

              The emulator can be extended to support more than two mice or other pointer -devices.

              -

              Variant: ScreenPlay. Target -audience: Application developers.

              -

              The following figure shows two Windows pointers on the emulator screen, -each representing a mouse device. The ordinal integer (starting from 0) beside -each pointer is the unique device identifier. The position of each mouse on -the screen is represented by the X and Y coordinates. The pressure (a positive -value) and proximity (a negative value) information captured by the mouse -wheel is represented by the Z coordinate. Notice that the status bar shows -the identifier and the dynamic X, Y and Z values of each pointer.

              - -Two pointers are displayed in the emulator - - -

              The delivery of pointer events from the emulator driver to the Window Server -is the same in the multi-touch environment as in the single pointer environment. -This means the raw events for a mouse move, button click and mouse wheel movement -are delivered to the Window Server as usual. Each mouse has a unique device -identifier, which makes it possible to ascertain which mouse the events relate -to. The raw events for each individual mouse include the following:

              -
                -

              • TRawEvent::EPointerMove indicates a mouse move or -a mouse wheel movement event.

                • -

              • TRawEvent::EButton1Down indicates that the left mouse -button is pressed down.

                • -

              • TRawEvent::EButton1Up indicates that the left mouse -button is released.

                • -

              • TRawEvent::EPointerOutOfRange indicates that the proximity -of a mouse is out of range. This means that the Z coordinate value of the -mouse has reached HALData::EPointer3DMaxProximity.

                • -
              -
              Pressure -and proximity emulation

              The Z coordinate value is used to represent -the pressure and proximity to the screen. In the emulator, the Z value is -captured and tuned by the mouse wheel movement.

                -

              • Z < 0 indicates the proximity of the device from the screen.

                • -

              • Z > 0 indicates pressure.

                • -

              See Advanced -Pointer Overview for more information about pressure and proximity.

              The -mouse wheel combines the features of a wheel and a mouse button. The wheel -has discrete, evenly spaced notches. Rotating the wheel backwards or forwards -has the effect of changing the pressure or proximity.

                -

              • When the mouse wheel is rotated, a device-specific message is sent -to the emulator window that has focus as each notch is encountered.

                • -

              • The Z coordinate is initiated as 0. Then when the wheel is moved forward, -the Z value enters the pressure range and increases by one pressure step. -When the wheel is moved backward, the Z value enters the proximity range and -decreases by one proximity step.

                The pressure or proximity step can -be customized in the epoc.ini file. See Enabling -Multi-Touch in the Emulator Tutorial for more information.

                • -

              • When the Z value is in the pressure range (Z > 0), moving the wheel -forward by one notch increases Z by one pressure step. Moving the wheel backward -by one notch decreases Z by one pressure step, until Z returns to 0.

                • -

              • When the Z value is in the proximity range (Z < 0), moving the wheel -backward by one notch decreases Z by one proximity step. Moving the wheel -forward by one notch increases Z by one proximity step, until Z returns to -0.

                • -

              • There are limits to the values of the Z coordinate. This -means that the Symbian emulator does not allow Z to exceed the upper boundary HALData::EPointer3DMaxPressure (a -positive value) and lower boundary HALData::EPointer3DMaxProximity (a -negative value). If Z is at the lower boundary, when the mouse wheel is moved -backward next time, Z does not change. A new Out of Range pointer -event is generated and sent to the Window Server. Similarly when Z is at the -upper boundary, Z does not change when the mouse wheel is moved forward.

                • -

              • When the mouse button down or up event (TRawEvent::EButton1Down or TRawEvent::EButton1Up) -is generated, Z is reset to 0.

                • -
              -               -Advanced -Pointers -Enabling -Multi-Touch in the Emulator Tutorial + + + + + +Multi-Touch +Support in the Emulator OverviewThis topic provides an overview of multi-touch support in the emulator. +Two mice are used to provide two independent pointer positions. The emulator +responds to the mice’s individual button-clicks, moves, and mouse wheel scrolls +as if two human fingers are moving, touching or hovering over the screen. +

              The emulator can be extended to support more than two mice or other pointer +devices.

              +

              Variant: ScreenPlay. Target +audience: Application developers.

              +

              The following figure shows two Windows pointers on the emulator screen, +each representing a mouse device. The ordinal integer (starting from 0) beside +each pointer is the unique device identifier. The position of each mouse on +the screen is represented by the X and Y coordinates. The pressure (a positive +value) and proximity (a negative value) information captured by the mouse +wheel is represented by the Z coordinate. Notice that the status bar shows +the identifier and the dynamic X, Y and Z values of each pointer.

              + +Two pointers are displayed in the emulator + + +

              The delivery of pointer events from the emulator driver to the Window Server +is the same in the multi-touch environment as in the single pointer environment. +This means the raw events for a mouse move, button click and mouse wheel movement +are delivered to the Window Server as usual. Each mouse has a unique device +identifier, which makes it possible to ascertain which mouse the events relate +to. The raw events for each individual mouse include the following:

              +
                +

              • TRawEvent::EPointerMove indicates a mouse move or +a mouse wheel movement event.

                • +

              • TRawEvent::EButton1Down indicates that the left mouse +button is pressed down.

                • +

              • TRawEvent::EButton1Up indicates that the left mouse +button is released.

                • +

              • TRawEvent::EPointerOutOfRange indicates that the proximity +of a mouse is out of range. This means that the Z coordinate value of the +mouse has reached HALData::EPointer3DMaxProximity.

                • +
              +
              Pressure +and proximity emulation

              The Z coordinate value is used to represent +the pressure and proximity to the screen. In the emulator, the Z value is +captured and tuned by the mouse wheel movement.

                +

              • Z < 0 indicates the proximity of the device from the screen.

                • +

              • Z > 0 indicates pressure.

                • +

              See Advanced +Pointer Overview for more information about pressure and proximity.

              The +mouse wheel combines the features of a wheel and a mouse button. The wheel +has discrete, evenly spaced notches. Rotating the wheel backwards or forwards +has the effect of changing the pressure or proximity.

                +

              • When the mouse wheel is rotated, a device-specific message is sent +to the emulator window that has focus as each notch is encountered.

                • +

              • The Z coordinate is initiated as 0. Then when the wheel is moved forward, +the Z value enters the pressure range and increases by one pressure step. +When the wheel is moved backward, the Z value enters the proximity range and +decreases by one proximity step.

                The pressure or proximity step can +be customized in the epoc.ini file. See Enabling +Multi-Touch in the Emulator Tutorial for more information.

                • +

              • When the Z value is in the pressure range (Z > 0), moving the wheel +forward by one notch increases Z by one pressure step. Moving the wheel backward +by one notch decreases Z by one pressure step, until Z returns to 0.

                • +

              • When the Z value is in the proximity range (Z < 0), moving the wheel +backward by one notch decreases Z by one proximity step. Moving the wheel +forward by one notch increases Z by one proximity step, until Z returns to +0.

                • +

              • There are limits to the values of the Z coordinate. This +means that the Symbian emulator does not allow Z to exceed the upper boundary HALData::EPointer3DMaxPressure (a +positive value) and lower boundary HALData::EPointer3DMaxProximity (a +negative value). If Z is at the lower boundary, when the mouse wheel is moved +backward next time, Z does not change. A new Out of Range pointer +event is generated and sent to the Window Server. Similarly when Z is at the +upper boundary, Z does not change when the mouse wheel is moved forward.

                • +

              • When the mouse button down or up event (TRawEvent::EButton1Down or TRawEvent::EButton1Up) +is generated, Z is reset to 0.

                • +
              +               +Advanced +Pointers +Enabling +Multi-Touch in the Emulator Tutorial               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9169062F-3B6D-544C-847C-BA859DAB33B9.dita --- a/Symbian3/SDK/Source/GUID-9169062F-3B6D-544C-847C-BA859DAB33B9.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-9169062F-3B6D-544C-847C-BA859DAB33B9.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,92 +1,92 @@ - - - - - -Sessions -and requestsDescribes communication between the client and the server in the -client-server framework. -

              Communication between client and server is represented by a session; -this is initiated by the client. A client thread may have several sessions -with a server. A session can also be shared by all the client threads in a -process, if supported by the server, and also by all threads across all processes, -again if supported by the server.

              -

              Sessions are maintained by the Kernel and the important points are:

              -
                -

              • The client has an RSessionBase handle -to the session.

                • -

              • The server uses a CSession2 -derived -class to represent the session.

                • -

              • A session may be sharable -between the threads in the client process, between all threads across all -processes, or it can be restricted to the thread connecting to the server.

                • -
              -

              If a call to the client interface requires a service from the server, the -client interface must set up and send a message. The message has a 32-bit -operation code to identify the request, and up to four 32-bit parameters. -The message is encapsulated within a TIpcArgs object. The -process can be summarised as follows:

              -
                -

              • The client sends the -message to the server using RSessionBase::SendReceive(). -This call eventually returns with the completion code.

                • -

              • The Kernel packages -the operation code and parameters and delivers an RMessage2 to -the server.

                • -

              • The server delivers -the message to the appropriate CSession2 object, which deals -with the request. The request is handled by CSession2::ServiceL(). -This is defined as pure virtual in CSession2, and is implemented -by the class derived from CSession2. When the session has -finished dealing with the request, it calls RMessage2::Complete() to -indicate that the service has been performed and to return a 32-bit result -to the client - this is returned from the SendReceive().

                • -
              -

              The client-server framework also supports the sending of requests asynchronously -to the server.

              -

              The following diagram illustrates this:

              - - -

              Sending messages asynchronously to the server

              -               -

              A server can support multiple connections from a client in a number of -distinct ways:

              -
                -

              • The client may have -a number of concurrent sessions with a particular server.

                • -

              • Each session is independent -of any other within the client thread; Connect() must be -called to initialise each new connection.

                • -

              • The client may create -a number of subsessions within a single session.

                • -

              • Each client subsession corresponds -to a subsession object in the server. The client subsession contains -a handle to this subsession object. All communication is via the owning session; -the handle is used to match up corresponding client subsessions and subsession -objects.

                • -

              • Subsessions use fewer -Kernel resources than sessions, although they are slightly more complex to -use.

                • -
              -

              A server can support the creation of sharable sessions allowing either -all the threads in a client process to share a single session, or allowing -all threads across all processes to share a single session. The important -points are:

              -
                -

              • The server must support -the sharing of sessions.

                • -

              • The connecting thread -can make the session sharable after creation, or it can create the session -as sharable.

                • -

              • Up to 255 threads can -be concurrently attached to a session.

                • -
              -
              See also

              Subsessions -within a session

              + + + + + +Sessions +and requestsDescribes communication between the client and the server in the +client-server framework. +

              Communication between client and server is represented by a session; +this is initiated by the client. A client thread may have several sessions +with a server. A session can also be shared by all the client threads in a +process, if supported by the server, and also by all threads across all processes, +again if supported by the server.

              +

              Sessions are maintained by the Kernel and the important points are:

              +
                +

              • The client has an RSessionBase handle +to the session.

                • +

              • The server uses a CSession2 -derived +class to represent the session.

                • +

              • A session may be sharable +between the threads in the client process, between all threads across all +processes, or it can be restricted to the thread connecting to the server.

                • +
              +

              If a call to the client interface requires a service from the server, the +client interface must set up and send a message. The message has a 32-bit +operation code to identify the request, and up to four 32-bit parameters. +The message is encapsulated within a TIpcArgs object. The +process can be summarised as follows:

              +
                +

              • The client sends the +message to the server using RSessionBase::SendReceive(). +This call eventually returns with the completion code.

                • +

              • The Kernel packages +the operation code and parameters and delivers an RMessage2 to +the server.

                • +

              • The server delivers +the message to the appropriate CSession2 object, which deals +with the request. The request is handled by CSession2::ServiceL(). +This is defined as pure virtual in CSession2, and is implemented +by the class derived from CSession2. When the session has +finished dealing with the request, it calls RMessage2::Complete() to +indicate that the service has been performed and to return a 32-bit result +to the client - this is returned from the SendReceive().

                • +
              +

              The client-server framework also supports the sending of requests asynchronously +to the server.

              +

              The following diagram illustrates this:

              + + +

              Sending messages asynchronously to the server

              +               +

              A server can support multiple connections from a client in a number of +distinct ways:

              +
                +

              • The client may have +a number of concurrent sessions with a particular server.

                • +

              • Each session is independent +of any other within the client thread; Connect() must be +called to initialise each new connection.

                • +

              • The client may create +a number of subsessions within a single session.

                • +

              • Each client subsession corresponds +to a subsession object in the server. The client subsession contains +a handle to this subsession object. All communication is via the owning session; +the handle is used to match up corresponding client subsessions and subsession +objects.

                • +

              • Subsessions use fewer +Kernel resources than sessions, although they are slightly more complex to +use.

                • +
              +

              A server can support the creation of sharable sessions allowing either +all the threads in a client process to share a single session, or allowing +all threads across all processes to share a single session. The important +points are:

              +
                +

              • The server must support +the sharing of sessions.

                • +

              • The connecting thread +can make the session sharable after creation, or it can create the session +as sharable.

                • +

              • Up to 255 threads can +be concurrently attached to a session.

                • +
              +
              See also

              Subsessions +within a session

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-917790B7-A71D-511C-AFAB-BB46EFD046C6_d0e144644_href.jpg Binary file Symbian3/SDK/Source/GUID-917790B7-A71D-511C-AFAB-BB46EFD046C6_d0e144644_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-917790B7-A71D-511C-AFAB-BB46EFD046C6_d0e151178_href.jpg Binary file Symbian3/SDK/Source/GUID-917790B7-A71D-511C-AFAB-BB46EFD046C6_d0e151178_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-92018B6B-3CBB-434D-9E61-F271C67E98E3.dita --- a/Symbian3/SDK/Source/GUID-92018B6B-3CBB-434D-9E61-F271C67E98E3.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-92018B6B-3CBB-434D-9E61-F271C67E98E3.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,37 +1,39 @@ - - - - - -Touch -UI utilities APIThe Touch UI utilities API is used for detecting long-tap events -and showing an animation for them. -

              A long tap, also called a touch down and hold event, means that the user -holds the stylus down on the screen at the same point for a long time.

              - -Long-tap event used for opening a stylus pop-up menu - - -

              The Touch UI utilities API can be used in all GUI applications. It is a -library API that provides an interface for constructing and using the long-tap -detector component.

              -

              For user experience guidelines on the long-tap component, see Touch -down and hold.

              -

              For the Touch UI utilities API classes and header files, see Classes and -Definitions.

              -

              For implementation information, see Receiving -long tap events.

              -
              Error handling

              The -leave mechanism of the Symbian platform environment is used for handling memory -exhaustion.

              -
              Constraints

              This -API is valid for all touch enabled Symbian platforms.

              -
              Emulator support

              This -API is fully supported in the WINS/WINSCW emulator environment.

              + + + + + +Touch +UI utilities APIThe Touch UI utilities API is used for detecting long-tap events +and showing an animation for them. +

              A long tap, also called a touch down and hold event, means that the user +holds the stylus down on the screen at the same point for a long time.

              + +Long-tap event used for opening a stylus pop-up menu + + +

              The Touch UI utilities API can be used in all GUI applications. It is a +library API that provides an interface for constructing and using the long-tap +detector component.

              +

              For user experience guidelines on the long-tap component, see Touch +down and hold.

              +

              For the Touch UI utilities API classes and header files, see Classes and +Definitions.

              +

              For implementation information, see Receiving +long tap events.

              +
              Error handling

              The +leave mechanism of the Symbian platform environment is used for handling memory +exhaustion.

              +
              Changes and release information

              The Touch UI utilities +API is an SDK API and first released in S60 5th Edition.

              +
              Constraints

              This +API is valid for all touch enabled Symbian platforms.

              +
              Emulator support

              This +API is fully supported in the WINS/WINSCW emulator environment.

               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-92067BE3-40F0-4652-A882-FFDE2816C9BD_d0e71873_href.png Binary file Symbian3/SDK/Source/GUID-92067BE3-40F0-4652-A882-FFDE2816C9BD_d0e71873_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-92067BE3-40F0-4652-A882-FFDE2816C9BD_d0e77022_href.png Binary file Symbian3/SDK/Source/GUID-92067BE3-40F0-4652-A882-FFDE2816C9BD_d0e77022_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-924576EE-A016-4689-8B63-E8176063E1E6-master.png Binary file Symbian3/SDK/Source/GUID-924576EE-A016-4689-8B63-E8176063E1E6-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-924576EE-A016-4689-8B63-E8176063E1E6_d0e67660_href.png Binary file Symbian3/SDK/Source/GUID-924576EE-A016-4689-8B63-E8176063E1E6_d0e67660_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-924576EE-A016-4689-8B63-E8176063E1E6_d0e72782_href.png Binary file Symbian3/SDK/Source/GUID-924576EE-A016-4689-8B63-E8176063E1E6_d0e72782_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-924E26D6-8B9D-5C76-AF61-7C5514BB3D78_d0e215705_href.png Binary file Symbian3/SDK/Source/GUID-924E26D6-8B9D-5C76-AF61-7C5514BB3D78_d0e215705_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-924E26D6-8B9D-5C76-AF61-7C5514BB3D78_d0e219442_href.png Binary file Symbian3/SDK/Source/GUID-924E26D6-8B9D-5C76-AF61-7C5514BB3D78_d0e219442_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-92966ADC-17CF-5411-A829-1201C182B59F.dita --- a/Symbian3/SDK/Source/GUID-92966ADC-17CF-5411-A829-1201C182B59F.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-92966ADC-17CF-5411-A829-1201C182B59F.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,129 +1,149 @@ - - - - - -ETel3rdParty: -Using the Telephony Independent Software Vendor (ISV) API -

              This set of seven example applications demonstrate the use of the Telephony -ISV API provided by the CTelephony public interface to -the phone’s telephony system. This interface enables developers to access -common mobile telephony services, such as finding phone information, dialling -and answering voice calls.

              -

              Each example demonstrates a different set of mobile telephony services, -and is stored in a subdirectory of ETel3rdPartyExample. -These subdirectories are explained in the description section.

              -
              Download

              Click on the following link to download -the example: ETel3rdParty.zip

              Click browse to view the example code.

              -
              Description

              AutoDTMFDialler

              This -example performs the following operations:

                -

              • Retrieves the line status -using the CTelephony::GetLineStatus() function.

                • -

              • Retrieves the call status -using the CTelephony::GetCallStatus() function

                • -

              • Retrieves the current -network registration status using the CTelephony::GetNetworkRegistrationStatus() function

                • -

              • Retrieves the current -flight mode status using the CTelephony::GetFlightMode() function.

                • -

              • Initiates a call using -the CTelephony::DialNewCall() function

                • -

              • Transmits DTMF tones -across all the current active voice calls one after the other using the CTelephony::SendDTMFTones() function

                • -

              • Disconnects a call using -the CTelephony::Hangup() function.

                • -

              Configs

              This example directory contains the config.txt and -the TelephonyISVAppConfig.cfg files, which are required -to configure the SIM TSY to run the application. For more information, see -the Configuring -the Simulator TSY section.

              IncomingCalls

              This -example answers incoming calls using the CTelephony::AnswerIncomingCall() function. -It also retrieves information about the call using the CTelephony::GetCallInfo() function. -It uses a test plug-in named Simulator TSY (SIMTSY) which simulates telephony -functions like phonebook, voicecall, SMS etc.

              NetworkInformation

              This -example retrieves the over-the-air network information about the currently -registered mobile network using the CTelephony::GetCurrentNetworkInfo() function -and also requests notification of changes to this information using the CTelephony::NotifyChange() function.

              OutgoingCalls

              This uses a test plug-in named Simulator TSY (SIMTSY) which simulates -telephony functions like phonebook, voicecall, SMS etc. This example performs -the following operations:

                -

              • Initiates a call using -the CTelephony::DialNewCall() function.

                • -

              • Places a call on hold -using the CTelephony::Hold() function.

                • -

              • Swaps between calls -using the CTelephony::Swap() function.

                • -

              • Resumes a call on hold -using the CTelephony::Resume() function.

                • -

              • Retrieves the status -of ICC locks using the CTelephony::GetLockInfo() function.

                • -

              • Retrieves ICC-stored -information about the (preferred) name of the currently registered mobile -network using the CTelephony::GetCurrentNetworkName() function -and the network name using the CTelephony::GetOperatorName() function.

                • -

              • Retrieves the -dynamic call capabilities for the calls that was dialled or answered using -the CTelephony::GetCallDynamicCaps() function.

                • -

              PhoneId

              This example retrieves information about a -phone, such as the manufacturer name, serial number, phone and SIM card number -using the CTelephony::GetPhoneId() function, and current -subscriber information using the CTelephony::GetSubscriberId() function. -It then prints this information to the console.

              PhoneMonitoring

              This -example performs the following operations:

                -

              • Retrieves the status -and charge level of the phone battery using the CTelephony::GetBatteryInfo() function.

                • -

              • Indicates whether a -phone battery is being charged using the CTelephony::GetIndicator() function.

                • -

              • Retrieves the current -signal strength of the phone using the CTelephony::GetSignalStrength() function.

                • -

              • Retrieves the current -flight mode status using the CTelephony::GetFlightMode() function.

                • -

              Shared

              This example directory contains the shared -files to be used by other directories for synchronous and asynchronous operations.

              SuppleServices

              This -example retrieves the current status of the following services:

                -

              • call barring services -using the CTelephony::GetCallBarringStatus() function,

                • -

              • call forwarding services -using the CTelephony::GetCallForwardingStatus() function,

                • -

              • call waiting services -using the CTelephony::GetCallWaitingStatus() function,

                • -

              • call identity services -using the CTelephony::GetIdentityServiceStatus() function.

                • -
              -
              Class summary

              The principal class used in this -example is CTelephony.

              -
              Configuring -the simulator TSY

              To run the application you must configure the -Simulator TSY. To do this, install the configuration files by performing the -following steps:

                -

              1. Copy the config.txt file -and the TelephonyISVAppConfig.cfg file into the \epoc32\winscw\c\ directory -of the phone.

                2. -

              2. From the command prompt, -go to the source root directory.

                3. -

              3. Change directory to \epoc32\release\winscw\udeb and -run the following command:

                ced c:\TelephonyISVAppConfig.cfg

                4. -

              4. Check the ced.log file -to ensure that the configuration file has been read successfully.

                5. -
              -
              Building and -running

              The -Symbian build process describes how to build an application.

              The ETel3rdPartyExample builds -the following executables in the standard location (\epoc32\release\winscw\<build_variant> for -CodeWarrior):

                -

              • phoneid.exe

                • -

              • phonemonitor.exe

                • -

              • networkinformation.exe

                • -

              • suppleservices.exe

                • -

              • outgoingcalls.exe

                • -

              • autodtmf.exe

                • -

              • incomingcalls.exe

                • -

              Each executable must be run separately.

              Note: Set -the StartUpMode mode to 1 in the \epoc32\data\epoc.ini file -to start the emulator in text shell mode as the applications use a console -based interface.

              + + + + + +ETel3rdParty: Using the Telephony Independent Software Vendor +(ISV) API +

              This set of seven example applications demonstrate the use of the +Telephony ISV API provided by the CTelephony public +interface to the phone’s telephony system. This interface enables +developers to access common mobile telephony services, such as finding +phone information, dialling and answering voice calls.

              +

              Each example demonstrates a different set of mobile telephony services, +and is stored in a subdirectory of ETel3rdPartyExample. These subdirectories are explained in the description section.

              +
              Download

              Click on the following link to download the example: ETel3rdParty.zip

              Click browse to view the example code.

              +
              Description

              AutoDTMFDialler

              This example performs the following +operations:

                +

              • Retrieves the +line status using the CTelephony::GetLineStatus(const TPhoneLine& +, TDes8&) function.

                • +

              • Retrieves the +call status using the CTelephony::GetCallStatus(const TCallId& +, TDes8&) function

                • +

              • Retrieves the +current network registration status using the CTelephony::GetNetworkRegistrationStatus(TRequestStatus& +, TDes8&) function

                • +

              • Retrieves the +current flight mode status using the CTelephony::GetFlightMode(TRequestStatus& +, TDes8&) function.

                • +

              • Initiates a +call using the CTelephony::DialNewCall(TRequestStatus& +, TDes8& , const TTelNumber& , TCallId& , const TPhoneLine) function

                • +

              • Transmits DTMF +tones across all the current active voice calls one after the other +using the CTelephony::SendDTMFTones(TRequestStatus& , +const TDesC&) function

                • +

              • Disconnects +a call using the CTelephony::Hangup(TRequestStatus& , +const TCallId&) function.

                • +

              Configs

              This example directory contains the config.txt and the TelephonyISVAppConfig.cfg files, which are required to configure the SIM TSY to run the application. +For more information, see the Configuring the Simulator TSY section.

              IncomingCalls

              This example answers incoming calls using the CTelephony::AnswerIncomingCall(TRequestStatus& +, TCallId& , const TPhoneLine) function. It also retrieves +information about the call using the CTelephony::GetCallInfo(TDes8& +, TDes8& , TDes8&) function. It uses a test plug-in +named Simulator TSY (SIMTSY) which simulates telephony functions like +phonebook, voicecall, SMS etc.

              NetworkInformation

              This example retrieves the over-the-air network information about +the currently registered mobile network using the CTelephony::GetCurrentNetworkInfo(TRequestStatus& +, TDes8&) function and also requests notification of +changes to this information using the CTelephony::NotifyChange(TRequestStatus& +, const TNotificationEvent& , TDes8&) function.

              OutgoingCalls

              This uses a test plug-in named Simulator +TSY (SIMTSY) which simulates telephony functions like phonebook, voicecall, +SMS etc. This example performs the following operations:

                +

              • Initiates a +call using the CTelephony::DialNewCall(TRequestStatus& +, TDes8& , const TTelNumber& , TCallId& , const TPhoneLine) function.

                • +

              • Places a call +on hold using the CTelephony::Hold(TRequestStatus& , +const TCallId&) function.

                • +

              • Swaps between +calls using the CTelephony::Swap(TRequestStatus& , const +TCallId& , const TCallId&) function.

                • +

              • Resumes a call +on hold using the CTelephony::Resume(TRequestStatus& +, const TCallId&) function.

                • +

              • Retrieves the +status of ICC locks using the CTelephony::GetLockInfo(TRequestStatus& +, const TIccLock& , TDes8&) function.

                • +

              • Retrieves ICC-stored +information about the (preferred) name of the currently registered +mobile network using the CTelephony::GetCurrentNetworkName(TRequestStatus& +, TDes8& ) function and the network name using the CTelephony::GetOperatorName(TRequestStatus& , TDes8&) function.

                • +

              • Retrieves +the dynamic call capabilities for the calls that was dialled or answered +using the CTelephony::GetCallDynamicCaps(const TCallId&, +TDes8&) function.

                • +

              PhoneId

              This example retrieves information +about a phone, such as the manufacturer name, serial number, phone +and SIM card number using the CTelephony::GetPhoneId(TRequestStatus& +, TDes8&) function, and current subscriber information +using the CTelephony::GetSubscriberId(TRequestStatus& +, TDes8&) function. It then prints this information +to the console.

              PhoneMonitoring

              This example +performs the following operations:

                +

              • Retrieves the +status and charge level of the phone battery using the CTelephony::GetBatteryInfo(TRequestStatus& +, TDes8&) function.

                • +

              • Indicates whether +a phone battery is being charged using the CTelephony::GetIndicator(TRequestStatus& +, TDes8&) function.

                • +

              • Retrieves the +current signal strength of the phone using the CTelephony::GetSignalStrength(TRequestStatus& +, TDes8&) function.

                • +

              • Retrieves the +current flight mode status using the CTelephony::GetFlightMode(TRequestStatus& +, TDes8&) function.

                • +

              Shared

              This example directory contains the +shared files to be used by other directories for synchronous and asynchronous +operations.

              SuppleServices

              This example retrieves +the current status of the following services:

                +

              • call barring +services using the CTelephony::GetCallBarringStatus(TRequestStatus& +, const TCallBarringCondition , TDes8& , const TServiceGroup) function,

                • +

              • call forwarding +services using the CTelephony::GetCallForwardingStatus(TRequestStatus& +, const TCallForwardingCondition , TDes8& , const TServiceGroup) function,

                • +

              • call waiting +services using the CTelephony::GetCallWaitingStatus(TRequestStatus& +, TDes8& , const TServiceGroup) function,

                • +

              • call identity +services using the CTelephony::GetIdentityServiceStatus(TRequestStatus& +, const TIdentityService& , TDes8&) function.

                • +
              +
              Class +summary

              The principal class used in this example is CTelephony.

              +
              Configuring +the simulator TSY

              To run the application you must configure +the Simulator TSY. To do this, install the configuration files by +performing the following steps:

                +

              1. Copy the config.txt file and the TelephonyISVAppConfig.cfg file into the \epoc32\winscw\c\ directory of +the phone.

                2. +

              2. From the command +prompt, go to the source root directory.

                3. +

              3. Change directory +to \epoc32\release\winscw\udeb and run the following +command:

                ced c:\TelephonyISVAppConfig.cfg

                4. +

              4. Check the ced.log file to ensure that the configuration file has +been read successfully.

                5. +
              +
              Building +and running

              The Symbian build +process describes how to build an application.

              The ETel3rdPartyExample builds the following executables in +the standard location (\epoc32\release\winscw\<build_variant> for CodeWarrior):

                +

              • phoneid.exe

                • +

              • phonemonitor.exe

                • +

              • networkinformation.exe

                • +

              • suppleservices.exe

                • +

              • outgoingcalls.exe

                • +

              • autodtmf.exe

                • +

              • incomingcalls.exe

                • +

              Each executable must be run separately.

              Note: Set the StartUpMode mode to 1 in +the \epoc32\data\epoc.ini file to start the emulator +in text shell mode as the applications use a console based interface.

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-92AD13DF-216A-4B5A-9C6D-5FA50BB0D692.dita --- a/Symbian3/SDK/Source/GUID-92AD13DF-216A-4B5A-9C6D-5FA50BB0D692.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-92AD13DF-216A-4B5A-9C6D-5FA50BB0D692.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,90 +1,90 @@ - - - - - -Sensor -Data Compensator OverviewThe Sensor Data Compensator provides APIs to correct sensor data, -based on device or display orientation. That is, using the APIs, the coordinate -system can be adjusted appropriately to get correct sensor axis data in relation -to the Symbian device user's current display orientation. -
              Description -

              The sensor channel APIs retrieve coordinate information and angle -data from different sensors when a display or device orientation change is -detected. The data is bound to the device form factor and hardware configuration -using device based coordinate system. Using the data, the sensor data compensator -APIs can adjust the coordinate system to match the changed system characteristics. -This procedure is called sensor data compensation.

              For example, if -a display orientation change (as illustrated in the following figure) is detected, -the accelerometer sensor provides axis data using the device base coordinate -system. To convert the axis data to match the current display orientation, -sensor data compensator APIs can be used. The data compensator APIs enable -you to adjust the coordinate system to match the changed system characteristics.

              -Example to illustrate adjustment of the coordinate system due to device -orientation change - -

              To convert the sensor data to the compensated values, the adjustment -values (for example, interchanged x-axis with y-axis) for each device state -that the compensation is applied to, must be configured and taken as an input -for calculations.

              -Correcting the coordinate system of a Symbian device -The figure depicts the correction of coordinate system in the Symbian -device - -

              The following example explains how the sensor data compensation works, -by illustrating the behavior of maps application of the Symbian device when -the keyboard is in opened and closed state.

              - - - -Symbian device position -Symbian device movement -Application behavior - - - - -The keyboard is closed and the display is upward and parallel with -the table surface -The Symbian device spins around the z-axis -The compass needle points to the north and the map does not move on -the screen. - - -The keyboard is opened and the display is upward and parallel with -the table surface -The Symbian device spins around the z-axis -The compass needle points to the north and the map is always in the -north-south direction on the screen. - - - -
              -
              APIs - - - -API -Description - - - - -CSensorDataCompensator -The sensor data compensator class provides functions to -compensate sensor data. - - - -
              -
              Typical Uses
                -

              • Compensating -Sensor Data

                • -
              + + + + + +Sensor +Data Compensator OverviewThe Sensor Data Compensator provides APIs to correct sensor data, +based on device or display orientation. That is, using the APIs, the coordinate +system can be adjusted appropriately to get correct sensor axis data in relation +to the Symbian device user's current display orientation. +
              Description +

              The sensor channel APIs retrieve coordinate information and angle +data from different sensors when a display or device orientation change is +detected. The data is bound to the device form factor and hardware configuration +using device based coordinate system. Using the data, the sensor data compensator +APIs can adjust the coordinate system to match the changed system characteristics. +This procedure is called sensor data compensation.

              For example, if +a display orientation change (as illustrated in the following figure) is detected, +the accelerometer sensor provides axis data using the device base coordinate +system. To convert the axis data to match the current display orientation, +sensor data compensator APIs can be used. The data compensator APIs enable +you to adjust the coordinate system to match the changed system characteristics.

              +Example to illustrate adjustment of the coordinate system due to device +orientation change + +

              To convert the sensor data to the compensated values, the adjustment +values (for example, interchanged x-axis with y-axis) for each device state +that the compensation is applied to, must be configured and taken as an input +for calculations.

              +Correcting the coordinate system of a Symbian device +The figure depicts the correction of coordinate system in the Symbian +device + +

              The following example explains how the sensor data compensation works, +by illustrating the behavior of maps application of the Symbian device when +the keyboard is in opened and closed state.

              + + + +Symbian device position +Symbian device movement +Application behavior + + + + +The keyboard is closed and the display is upward and parallel with +the table surface +The Symbian device spins around the z-axis +The compass needle points to the north and the map does not move on +the screen. + + +The keyboard is opened and the display is upward and parallel with +the table surface +The Symbian device spins around the z-axis +The compass needle points to the north and the map is always in the +north-south direction on the screen. + + + +
              +
              APIs + + + +API +Description + + + + +CSensorDataCompensator +The sensor data compensator class provides functions to +compensate sensor data. + + + +
              +
              Typical Uses
                +

              • Compensating +Sensor Data

                • +
               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-92DF40DF-3C7C-5052-A78A-A47B8A455C32.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-92DF40DF-3C7C-5052-A78A-A47B8A455C32.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,12 @@ + + + + + +About the Window server example code

              These examples show how to use the Window Server Client-Side API. Note that these examples create windows directly rather than going through the UI Control Framework, as standard applications would do.

              The source files for the examples can be found under: examples\Graphics\WS\. The following files are common to several of them:

              • AppHolder.cpp provides the standard GUI application framework classes. The only command handling provided is a menu with a Close command.

              • Base.cpp provides base classes that use the window server. CWsClient handles the connection to the window server: it is an active object that issues a request for window server events, and handles them in its RunL(). CWindow encapsulates a basic window.

              • project-name .cpp provides most of the code specific to a particular example. Typically, they sub-class CWsClient and CWindow.

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-930F1E88-2A03-4BD1-AA2A-3A0128A844BD.dita --- a/Symbian3/SDK/Source/GUID-930F1E88-2A03-4BD1-AA2A-3A0128A844BD.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-930F1E88-2A03-4BD1-AA2A-3A0128A844BD.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,58 +1,58 @@ - - - - - -Enabling -Multi-Touch in the Emulator TutorialThis topic describes how to configure the Symbian emulator to enable -a multi-touch environment. -

              Variant: ScreenPlay. Target -audience: Application developers.

              -

              This topic builds on Multi-Touch -Support in the Emulator Overview.

              -
              Configuring -the emulator

              Make sure that two or more mice are plugged in and -detected on the Windows PC on which the emulator will run. The number of -detected mice can be from two up to the maximum number defined in the HAL HALData::EPointerMaxPointers attribute.

                -

              1. Add the following lines -to the \epoc32\data\epoc.ini file. These lines enable -ScreenPlay and multi-touch.

                SYMBIAN_BASE_USE_GCE ON -EnableMultiTouch ON
                2. -

              2. Specify the MultiTouchProximityStep and MultiTouchPressureStep values in the \epoc32\data\epoc.ini file to define -the proximity and pressure steps.

                MultiTouchProximityStep 10 -MultiTouchPressureStep 200 -

                If the above two options are not defined in the epoc.ini file, -the default proximity and pressure steps are taken from the following HAL -attributes.

                HALData::EPointer3DProximityStep -HALData::EPointer3DPressureStep
                3. -

              Result: Launch the emulator to verify that the mice are detected -and displayed inside the application window area. When you move a mouse or -scroll the mouse wheel, its X, Y and Z values are reflected in the status -bar.

              -
              Enabling -and disabling multi-touch

              Multi-touch is only required by UI applications. -Therefore, multi-touch is enabled inside the orange rectangular area shown -on the following diagram. Inside the area two Windows pointers are displayed. -The one numbered zero is the system pointer and the other is used only for -multi-touch purposes. The first mouse to report events to the emulator is -automatically taken as the primary mouse, which owns the Windows system pointer.

              -Multi-touch area - -

              System pointer. Once the system pointer moves outside multi-touch -area, multi-touch is temporarily disabled and standard emulator pointer behavior -is resumed. This means that only one Windows system pointer is displayed and -it is controlled by both mice.

              Non-system pointer. If the -non-system pointer moves out of the multi-touch area, the pointer just disappears -from the screen. Disabling multi-touch is then not necessary because the system -pointer behaves normally inside the multi-touch area. Moving the non-system -pointer back into the area makes it reappear on the screen.

              -               -Multi-Touch -Support in the Emulator Overview + + + + + +Enabling +Multi-Touch in the Emulator TutorialThis topic describes how to configure the Symbian emulator to enable +a multi-touch environment. +

              Variant: ScreenPlay. Target +audience: Application developers.

              +

              This topic builds on Multi-Touch +Support in the Emulator Overview.

              +
              Configuring +the emulator

              Make sure that two or more mice are plugged in and +detected on the Windows PC on which the emulator will run. The number of +detected mice can be from two up to the maximum number defined in the HAL HALData::EPointerMaxPointers attribute.

                +

              1. Add the following lines +to the \epoc32\data\epoc.ini file. These lines enable +ScreenPlay and multi-touch.

                SYMBIAN_BASE_USE_GCE ON +EnableMultiTouch ON
                2. +

              2. Specify the MultiTouchProximityStep and MultiTouchPressureStep values in the \epoc32\data\epoc.ini file to define +the proximity and pressure steps.

                MultiTouchProximityStep 10 +MultiTouchPressureStep 200 +

                If the above two options are not defined in the epoc.ini file, +the default proximity and pressure steps are taken from the following HAL +attributes.

                HALData::EPointer3DProximityStep +HALData::EPointer3DPressureStep
                3. +

              Result: Launch the emulator to verify that the mice are detected +and displayed inside the application window area. When you move a mouse or +scroll the mouse wheel, its X, Y and Z values are reflected in the status +bar.

              +
              Enabling +and disabling multi-touch

              Multi-touch is only required by UI applications. +Therefore, multi-touch is enabled inside the orange rectangular area shown +on the following diagram. Inside the area two Windows pointers are displayed. +The one numbered zero is the system pointer and the other is used only for +multi-touch purposes. The first mouse to report events to the emulator is +automatically taken as the primary mouse, which owns the Windows system pointer.

              +Multi-touch area + +

              System pointer. Once the system pointer moves outside multi-touch +area, multi-touch is temporarily disabled and standard emulator pointer behavior +is resumed. This means that only one Windows system pointer is displayed and +it is controlled by both mice.

              Non-system pointer. If the +non-system pointer moves out of the multi-touch area, the pointer just disappears +from the screen. Disabling multi-touch is then not necessary because the system +pointer behaves normally inside the multi-touch area. Moving the non-system +pointer back into the area makes it reappear on the screen.

              +               +Multi-Touch +Support in the Emulator Overview               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-935057C9-8FA9-5B41-A36C-03A825C51B32_d0e214529_href.png Binary file Symbian3/SDK/Source/GUID-935057C9-8FA9-5B41-A36C-03A825C51B32_d0e214529_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-935057C9-8FA9-5B41-A36C-03A825C51B32_d0e218266_href.png Binary file Symbian3/SDK/Source/GUID-935057C9-8FA9-5B41-A36C-03A825C51B32_d0e218266_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-93678518-1FBD-521D-807A-63DA2E33551F_d0e176542_href.png Binary file Symbian3/SDK/Source/GUID-93678518-1FBD-521D-807A-63DA2E33551F_d0e176542_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-93678518-1FBD-521D-807A-63DA2E33551F_d0e183136_href.png Binary file Symbian3/SDK/Source/GUID-93678518-1FBD-521D-807A-63DA2E33551F_d0e183136_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-937C3D70-2DCC-5084-AC87-3B1E5865A827.dita --- a/Symbian3/SDK/Source/GUID-937C3D70-2DCC-5084-AC87-3B1E5865A827.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-937C3D70-2DCC-5084-AC87-3B1E5865A827.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,14 +1,14 @@ - - - - - -Active Backup Client Overview

              The Active Backup Client enables Symbian Developers to write backup and restore software with complete control of which data is backed up and restored.

              The backup client application is often referred to as the data owner as it owns the data. The data owner is automatically invoked to prepare and supply the data to the Backup Engine at backup time. Similarly, the data is automatically supplied back to the data owner on restore.

              Required Background

              Before you start, you must understand the following architecture and concepts:

              • Symbian backup and restore architecture

              • Backup and restore modes (active, passive and proxy).

              Key concepts and terms

              Data owner

              A Symbian process that owns the data to be backed up or restored is a data owner. It can be an application or a server.

              Initiator/Responder

              There are two roles in MTP exchanges, an initiator and a responder. An initiator is the device which initiates requests and operations to the connected responder. A responder is the device which passively responds the requests and operations. Symbian MTP is implemented as a responder role only. A host PC or a portable device on a Symbian device is usually an initiator.

              Architecture

              The following flowchart shows how the Active Backup Client (data owner application) works with other components for data backup and restore. The components provided by Symbian are in green. The components that a device vendor must implement are in blue.

              - Active Backup Client -

              • The Backup Server communicates directly with the backup and restore initiator, for example a host PC.

                The Backup Server receives a request from a host PC for a backup or restore operation. It then calls the Backup Engine using the Backup Engine Client API (conn::CSBEClient) for lists of data sets. It also transfers data during a backup or a restore.

                Note: The Symbian platform includes a backup server which a device vendor may replace.

              • The Backup Engine component contains the logic related to the data backup and restore. It signals the start or completion of a backup or restore to all data owners.

                Note: This component runs in a separate process which allows the Backup Server to operate synchronously and asynchronously.

              • An active Data Owner Application responds to signals from the Backup Engine. It releases resources in case of file lock or data confliction. It must define a conn::CActiveBackupClient instance to connect to the Backup Engine and must provide a pointer to an conn::MActiveBackupDataClient implementation. The conn::MActiveBackupDataClient implementation prepares and transfers data to the Backup Engine for a backup and restore.

              APIs

              The Active Backup Client includes the following APIs:

              API Description

              conn::CActiveBackupClient

              Establishes a connection to the Backup Engine for the data owing process.

              conn::MActiveBackupDataClient

              The data owner application must implement this interface to provide the data to the Backup Engine. It is passed to the conn::CActiveBackupClient constructor.

              Typical uses

              The Active Backup Client can be used to prepare and transfer data for the Backup Engine to do a backup and restore.

              Writing an Active Backup Client Tutorial               \ No newline at end of file + + + + + +Active Backup Client Overview

              The Active Backup Client enables Symbian Developers to write backup and restore software with complete control of which data is backed up and restored.

              The backup client application is often referred to as the data owner as it owns the data. The data owner is automatically invoked to prepare and supply the data to the Backup Engine at backup time. Similarly, the data is automatically supplied back to the data owner on restore.

              Required Background

              Before you start, you must understand the following architecture and concepts:

              • Symbian backup and restore architecture

              • Backup and restore modes (active, passive and proxy).

              Key concepts and terms

              Data owner

              A Symbian process that owns the data to be backed up or restored is a data owner. It can be an application or a server.

              Initiator/Responder

              There are two roles in MTP exchanges, an initiator and a responder. An initiator is the device which initiates requests and operations to the connected responder. A responder is the device which passively responds the requests and operations. Symbian MTP is implemented as a responder role only. A host PC or a portable device on a Symbian device is usually an initiator.

              Architecture

              The following flowchart shows how the Active Backup Client (data owner application) works with other components for data backup and restore. The components provided by Symbian are in green. The components that a device vendor must implement are in blue.

              + Active Backup Client +

              • The Backup Server communicates directly with the backup and restore initiator, for example a host PC.

                The Backup Server receives a request from a host PC for a backup or restore operation. It then calls the Backup Engine using the Backup Engine Client API (conn::CSBEClient) for lists of data sets. It also transfers data during a backup or a restore.

                Note: The Symbian platform includes a backup server which a device vendor may replace.

              • The Backup Engine component contains the logic related to the data backup and restore. It signals the start or completion of a backup or restore to all data owners.

                Note: This component runs in a separate process which allows the Backup Server to operate synchronously and asynchronously.

              • An active Data Owner Application responds to signals from the Backup Engine. It releases resources in case of file lock or data confliction. It must define a conn::CActiveBackupClient instance to connect to the Backup Engine and must provide a pointer to an conn::MActiveBackupDataClient implementation. The conn::MActiveBackupDataClient implementation prepares and transfers data to the Backup Engine for a backup and restore.

              APIs

              The Active Backup Client includes the following APIs:

              API Description

              conn::CActiveBackupClient

              Establishes a connection to the Backup Engine for the data owing process.

              conn::MActiveBackupDataClient

              The data owner application must implement this interface to provide the data to the Backup Engine. It is passed to the conn::CActiveBackupClient constructor.

              Typical uses

              The Active Backup Client can be used to prepare and transfer data for the Backup Engine to do a backup and restore.

              Writing an Active Backup Client Tutorial               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-938C0EB5-D0B3-502E-87A9-7C626642AE4B_d0e270526_href.jpg Binary file Symbian3/SDK/Source/GUID-938C0EB5-D0B3-502E-87A9-7C626642AE4B_d0e270526_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-938C0EB5-D0B3-502E-87A9-7C626642AE4B_d0e274234_href.jpg Binary file Symbian3/SDK/Source/GUID-938C0EB5-D0B3-502E-87A9-7C626642AE4B_d0e274234_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-93A4CD14-A3CD-57B2-BF32-57EF38F59ECF_d0e202480_href.png Binary file Symbian3/SDK/Source/GUID-93A4CD14-A3CD-57B2-BF32-57EF38F59ECF_d0e202480_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-93A4CD14-A3CD-57B2-BF32-57EF38F59ECF_d0e207488_href.png Binary file Symbian3/SDK/Source/GUID-93A4CD14-A3CD-57B2-BF32-57EF38F59ECF_d0e207488_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-93EFC9E4-8779-415D-ABEB-2AC9991996DD.dita --- a/Symbian3/SDK/Source/GUID-93EFC9E4-8779-415D-ABEB-2AC9991996DD.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-93EFC9E4-8779-415D-ABEB-2AC9991996DD.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,53 +1,59 @@ - - - - - -Wait -note -

              Wait notes contain a wait graphic of indefinite duration. They are used -during operations that take a long time when it is not possible to estimate -the duration of the operation. Whenever possible, the user should be able -to stop the operation. For this, a softkey labeled for example,Cancel is -provided.

              - -Wait note - - -
              - Using wait notes in C++ applications

              You can create -either a basic wait note that is displayed only when your application is in -the foreground or a global note that stays displayed even if the application -launching the note is not in the foreground. The related APIs are the Notes API (for basic notes) and the Notifiers API (for global notes).

              Wait notes are -predefined notes that cannot be used just by instantiating a simple note class. -These notes' lifetime is based on a background process, and client code has -to provide an interface to retrieve this information. For implementation information, -see Creating a wait note.

              To create a global wait note, -use the class CAknGlobalNote in -the Notifiers API. For implementation information, see Using global notes and Using global notes with user interaction.

              For basic -notes, you can change the icon or text displayed in the note, use a different -kind of sound, or change the note duration using the setter methods in the -class CAknNoteDialog: SetIconL(), SetTextL(), SetTone(), and SetTimeout().

              For information on customizing -global notes, see Enhancing global notes. You can change the graphic, animation, -tone, and softkeys using the methods in the class CAknGlobalNote: SetGraphic(), SetAnimation(), SetTone(), and SetSoftkeys.

              - -               -Confirmation -note -Information -note -Warning note - -Error note - -Permanent -note -Progress -note + + + + + +Wait note +

              Wait notes contain a wait graphic of indefinite duration. They are used +during operations that take a long time when it is not possible to estimate +the duration of the operation. Whenever possible, the user should be able +to stop the operation. For this, a softkey labeled for example,Cancel is +provided.

              + +Wait note + + +
              + Using wait notes in applications

              You can create +either a basic wait note that is displayed only when your application is in +the foreground or a global note that stays displayed even if the application +launching the note is not in the foreground. The related APIs are the Notes API (for basic notes) and the Notifiers API (for global notes).

              Wait notes are +predefined notes that cannot be used just by instantiating a simple note class. +These notes' lifetime is based on a background process, and client code has +to provide an interface to retrieve this information. For implementation information, +see Creating a wait note.

              To create a global wait note, +use the CAknGlobalNote class in the Notifiers API. For implementation information, see Using global notes and Using global notes with user interaction.

              For basic +notes, you can change the icon or text displayed in the note, use a different +kind of sound, or change the note duration using the setter methods in the CAknNoteDialog class:

                +

              • CAknNoteDialog::SetIconL()

                • +

              • CAknNoteDialog::SetTextL()

                • +

              • CAknNoteDialog::SetTone()

                • +

              • CAknNoteDialog::SetTimeout()

                • +

              For information on customizing global notes, see Enhancing global notes. You can change the graphic, animation, +tone, and softkeys using the methods in the CAknGlobalNote class:

                +

              • CAknGlobalNote::SetGraphic()

                • +

              • CAknGlobalNote::SetAnimation()

                • +

              • CAknGlobalNote::SetTone()

                • +

              • CAknGlobalNote::SetSoftkeys()

                • +

              + +               +Confirmation +note +Information +note +Warning note + +Error note + +Permanent +note +Progress +note               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-93FFE6EF-9F6D-46BD-846C-CAC03F26E643_d0e53249_href.png Binary file Symbian3/SDK/Source/GUID-93FFE6EF-9F6D-46BD-846C-CAC03F26E643_d0e53249_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-93FFE6EF-9F6D-46BD-846C-CAC03F26E643_d0e59044_href.png Binary file Symbian3/SDK/Source/GUID-93FFE6EF-9F6D-46BD-846C-CAC03F26E643_d0e59044_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-94005A46-B4C6-4A30-A8E8-1B9C2D583D50.dita --- a/Symbian3/SDK/Source/GUID-94005A46-B4C6-4A30-A8E8-1B9C2D583D50.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-94005A46-B4C6-4A30-A8E8-1B9C2D583D50.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,63 +1,52 @@ - - - - - - -Classic -UI Guide - - - - - - -

              Classic UI provides the native UI support library, AVKON, including standard -controls, views, dialogs and some services for UI applications.

              -
              - - - -

              What you want to do

               -

              Where to start

               -               - - - -

              I want to understand the fundamental architecture of a GUI application.

               -Application -and UI frameworks -               - -

              I want to design my application for a phone with a touch screen.

               -Touch UI -               - -

              I want to use the standard controls and dialogs that Classic UI -provides.

               -UI components -               - -

              I want to create my own controls and animations.

               -The -UI Control Framework (CONE) -               - -

              I want to understand the user experience in Symbian platform devices -without touch

               -Symbian -device user experience for non-touch devices -               - - -
              -               -               - + + + + + +Classic +UI Guide +

              Classic UI provides the native UI support library, AVKON, including standard +controls, views, dialogs and some services for UI applications.

              +
              + + + +

              What you want to do

               +

              Where to start

               +               + + + +

              I want to understand the fundamental architecture of a GUI application.

               +Application +and UI frameworks +               + +

              I want to design my application for a phone with a touch screen.

               +Touch +UI +               + +

              I want to use the standard controls and dialogs that Classic UI +provides.

               +UI components +               + +

              I want to create my own controls and animations.

               +The UI Control Framework (CONE) +               + +

              I want to understand the user experience in Symbian platform devices +without touch

               + +               + + +
              +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-940AF1CE-3C33-54BF-B339-B8CF79C5FC9C_d0e129840_href.jpg Binary file Symbian3/SDK/Source/GUID-940AF1CE-3C33-54BF-B339-B8CF79C5FC9C_d0e129840_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-940AF1CE-3C33-54BF-B339-B8CF79C5FC9C_d0e136378_href.jpg Binary file Symbian3/SDK/Source/GUID-940AF1CE-3C33-54BF-B339-B8CF79C5FC9C_d0e136378_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-940F3F6E-BA9C-5E19-9AC5-D848B5E175FB.dita --- a/Symbian3/SDK/Source/GUID-940F3F6E-BA9C-5E19-9AC5-D848B5E175FB.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-940F3F6E-BA9C-5E19-9AC5-D848B5E175FB.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,177 +1,177 @@ - - - - - -Application -Architecture Overview -

              APPARC provides access to a cached list of applications, and their properties, -on the device. APPARC also provides a mechanism for launching applications -and switching between tasks.

              -
              Purpose

              The main purpose of APPARC is to

                -

              • manage and register -applications with the device

                • -

              • scan the device for -installed applications and associate data types to the applications based -on the information in the registration file

                • -

              • load applications and -manage the creation and destruction of application objects and document objects

                • -

              • support the registration -of non-native applications

                • -

              • define a Server Application -Framework, which allows applications to communicate through the client-server -architecture

                • -

              • support multiple service -types over the client-server link and establish a client-server connection -to an already running server application

                • -

              • monitor the lifetime -of the server application

                • -

              • define the basic polymorphic -interfaces that applications must conform to, such as, CApaApplication and CApaDocument

                • -

              • provide a list of available -control panel applications present on the device.

                • -
              -
              Key concepts and terms
              - -
              Server Application Framework
              -

              The Server Application Framework provides generic service support over -a client-server link, on which real services can be created. A service typically -provides a client-side interface that clients can use directly, and a server-side -interface that server applications have to implement.

              -               -
              -
              Architecture

              The following diagram shows the interaction -of APPARC with other components.

              - -

              The following list describes the interaction between APPARC and -each of the components depicted in the APPARC architectural diagram:

                -

              • APPARC provides the -basic behavior for GUI-based applications. APPARC also provides basic behavior -for documents in a document-view based application. Uikon builds on the basic -behavior that APPARC provides for GUI applications. PIM application components -(Contacts and Calendar) derive the basic behavior for GUI-based applications -from APPARC.

                • -

              • APPARC maintains a list -of installed applications on the device. APPARC supports rule-based application -launching which is implemented as ECOM plug-ins. These plug-ins define rules -that enable APPARC to either deny or accept the application launch requests.

                • -

              • Software Install (SWI) -allows installing, uninstalling and upgrading of native software on the device. -When an application needs to be installed, SWI uses APPARC for launching applications -if run-on-install or run-on-uninstall is specified.

                • -

              • When an application -is launched APPARC interacts with the GDI and BIT GDI components to associate -the application with the appropriate application icon, caption and display -screen.

                • -
              -
              API summary - - - -

              API

               -

              Description

               -               - - - -

              CApaApplication

              -

              A class that defines the basic twin roles of an application class:

                -

              • as a factory that creates -concrete document objects

                • -

              • as a supplier of utility -functions not specific to any particular instance of a document.

                • -
               -               - -

              CApaAppListNotifier

              -

              An application list change notifier that provides a notification -whenever an application is added or deleted.

              -               - -

              CApaCommandLine

              -

              A class that provides information for launching an application. -This class is often referred to as a command line and it contains

                -

              • the name of the application -EXE to be launched

                • -

              • the document name

                • -

              • a command code that -defines the way an application is launched (the structure of this depends -on the application to be launched).

                • -
               -               - -

              CApaDocument

              -

              The base class for all documents. A document contains the data associated -with the content of the application.

              -               - -

              CApaSystemControlList

              -

              A class that provides a list of all available control panel applications -present on the device. This class is implemented as a linked list of CApaSystemControl.

              -               - -

              CServiceRegistry

              -

              The Service Registry stores associations between service-datatype -pairs and applications. The service-datatype pair is the primary key for the -registry.

              -               - -

              RApaAppServiceBase

              -

              The base class that provides a client-side interface for accessing -server applications.

              -               - -

              RApaLsSession

              -

              A session with the APPARC server providing access to a cached list -of applications on the device.

              -               - - -
              -
              Typical uses

              Developing a GUI-based application

              A -GUI-based application can be developed using the CApaApplication and CApaDocument interfaces. -For more information, see A -Minimal UI Application.

              Enumerating applications

              APPARC -provides a set of APIs that can enumerate the list of applications on the -device. For more information, see Enumerating -applications.

              Accessing running applications

              Applications -running on a device are known as tasks. The TApaTaskList class -is used to access applications running on a device, where each task can be -an instance of the TApaTask class, which is used to manipulate -or query tasks. For more information, see Accessing -and manipulating running applications.

              Creating a control -panel application

              APPARC provides an API to create a control panel -application. For more information, see Creating -control panel applications.

              Creating a new service

              The -server application framework supports platform-level services between client -and server applications. These services must be defined for client and server -applications to communicate. For more information, see Creating -a new service.

              Using a service in a client

              Clients -and server applications interact through a common service, which adheres to -a protocol defining the communication channel between the two. This inter-process -communication channel also provides a security checkpoint for application -capability checking and so on. Services provide useful functionality to clients. -For more information, see Using -a service in a client.

              Implementing services in a server -application

              Server applications can have one or many services. -Each service type has a unique identification (UID). For more information, -see Implementing services -in a server application.

              -               -Generic Application -Support -Secure Software -Install -Using Uikon - -Graphics -Device Interface (GDI) -Calendar -Guide + + + + + +Application +Architecture Overview +

              APPARC provides access to a cached list of applications, and their properties, +on the device. APPARC also provides a mechanism for launching applications +and switching between tasks.

              +
              Purpose

              The main purpose of APPARC is to

                +

              • manage and register +applications with the device

                • +

              • scan the device for +installed applications and associate data types to the applications based +on the information in the registration file

                • +

              • load applications and +manage the creation and destruction of application objects and document objects

                • +

              • support the registration +of non-native applications

                • +

              • define a Server Application +Framework, which allows applications to communicate through the client-server +architecture

                • +

              • support multiple service +types over the client-server link and establish a client-server connection +to an already running server application

                • +

              • monitor the lifetime +of the server application

                • +

              • define the basic polymorphic +interfaces that applications must conform to, such as, CApaApplication and CApaDocument

                • +

              • provide a list of available +control panel applications present on the device.

                • +
              +
              Key concepts and terms
              + +
              Server Application Framework
              +

              The Server Application Framework provides generic service support over +a client-server link, on which real services can be created. A service typically +provides a client-side interface that clients can use directly, and a server-side +interface that server applications have to implement.

              +               +
              +
              Architecture

              The following diagram shows the interaction +of APPARC with other components.

              + +

              The following list describes the interaction between APPARC and +each of the components depicted in the APPARC architectural diagram:

                +

              • APPARC provides the +basic behavior for GUI-based applications. APPARC also provides basic behavior +for documents in a document-view based application. Uikon builds on the basic +behavior that APPARC provides for GUI applications. PIM application components +(Contacts and Calendar) derive the basic behavior for GUI-based applications +from APPARC.

                • +

              • APPARC maintains a list +of installed applications on the device. APPARC supports rule-based application +launching which is implemented as ECOM plug-ins. These plug-ins define rules +that enable APPARC to either deny or accept the application launch requests.

                • +

              • Software Install (SWI) +allows installing, uninstalling and upgrading of native software on the device. +When an application needs to be installed, SWI uses APPARC for launching applications +if run-on-install or run-on-uninstall is specified.

                • +

              • When an application +is launched APPARC interacts with the GDI and BIT GDI components to associate +the application with the appropriate application icon, caption and display +screen.

                • +
              +
              API summary + + + +

              API

               +

              Description

               +               + + + +

              CApaApplication

              +

              A class that defines the basic twin roles of an application class:

                +

              • as a factory that creates +concrete document objects

                • +

              • as a supplier of utility +functions not specific to any particular instance of a document.

                • +
               +               + +

              CApaAppListNotifier

              +

              An application list change notifier that provides a notification +whenever an application is added or deleted.

              +               + +

              CApaCommandLine

              +

              A class that provides information for launching an application. +This class is often referred to as a command line and it contains

                +

              • the name of the application +EXE to be launched

                • +

              • the document name

                • +

              • a command code that +defines the way an application is launched (the structure of this depends +on the application to be launched).

                • +
               +               + +

              CApaDocument

              +

              The base class for all documents. A document contains the data associated +with the content of the application.

              +               + +

              CApaSystemControlList

              +

              A class that provides a list of all available control panel applications +present on the device. This class is implemented as a linked list of CApaSystemControl.

              +               + +

              CServiceRegistry

              +

              The Service Registry stores associations between service-datatype +pairs and applications. The service-datatype pair is the primary key for the +registry.

              +               + +

              RApaAppServiceBase

              +

              The base class that provides a client-side interface for accessing +server applications.

              +               + +

              RApaLsSession

              +

              A session with the APPARC server providing access to a cached list +of applications on the device.

              +               + + +
              +
              Typical uses

              Developing a GUI-based application

              A +GUI-based application can be developed using the CApaApplication and CApaDocument interfaces. +For more information, see A +Minimal UI Application.

              Enumerating applications

              APPARC +provides a set of APIs that can enumerate the list of applications on the +device. For more information, see Enumerating +applications.

              Accessing running applications

              Applications +running on a device are known as tasks. The TApaTaskList class +is used to access applications running on a device, where each task can be +an instance of the TApaTask class, which is used to manipulate +or query tasks. For more information, see Accessing +and manipulating running applications.

              Creating a control +panel application

              APPARC provides an API to create a control panel +application. For more information, see Creating +control panel applications.

              Creating a new service

              The +server application framework supports platform-level services between client +and server applications. These services must be defined for client and server +applications to communicate. For more information, see Creating +a new service.

              Using a service in a client

              Clients +and server applications interact through a common service, which adheres to +a protocol defining the communication channel between the two. This inter-process +communication channel also provides a security checkpoint for application +capability checking and so on. Services provide useful functionality to clients. +For more information, see Using +a service in a client.

              Implementing services in a server +application

              Server applications can have one or many services. +Each service type has a unique identification (UID). For more information, +see Implementing services +in a server application.

              +               +Generic Application +Support +Secure Software +Install +Using Uikon + +Graphics +Device Interface (GDI) +Calendar +Guide               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9482CC98-2600-539D-A243-639CF11A2599_d0e426550_href.jpg Binary file Symbian3/SDK/Source/GUID-9482CC98-2600-539D-A243-639CF11A2599_d0e426550_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9482CC98-2600-539D-A243-639CF11A2599_d0e426712_href.jpg Binary file Symbian3/SDK/Source/GUID-9482CC98-2600-539D-A243-639CF11A2599_d0e426712_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-94EAB348-DB29-5814-BB93-968D9A2A8AD2.dita --- a/Symbian3/SDK/Source/GUID-94EAB348-DB29-5814-BB93-968D9A2A8AD2.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-94EAB348-DB29-5814-BB93-968D9A2A8AD2.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,585 +1,614 @@ - - - - - -List -of Example Code Use Cases -

              This document lists all the example code programs available for each module, -organised by use case.

              -
              Symbian Platform -Fundamentals
                -

              • Basic -helloworld application

                • -

              • How -to create a C class

                • -

              • How -to do single phase construction

                • -

              • How -to do two-phase construction

                • -

              • How -to use an R class

                • -

              • How -to use a T class

                • -

              • How -to use a mixin class

                • -

              • How -to create a static DLL

                • -

              • How -to use a static DLL

                • -
              -
              Application -Framework
                - - - - - - - -

              • How -to implement a simple GUI application with a single view

                • -

              • How to create an animation -using the Bitmap Animation framework

                • -

              • How to view an animation -inside a window

                • -
              - -
              Communication -Framework

              Data Server

                -

              • How -to do connection monitoring and management using the RConnection API

                • -
              - -
              High Level -Internet Protocols
                -

              • How -to use HTTP APIs

                • -
              -
              Generic Application -Support
                -

              • How -to add a floating alarm to the alarm server

                • -

              • How -to add a fixed alarm to the alarm server

                • -

              • How -to get notification from the alarm server

                • - - - -
              -
              Generic OS -Services
                -

              • How -to compress data using the EZLIB API

                • -

              • How -to decompress data using the EZLIB API

                • -

              • How -to create a secure directory using PIPS

                • -

              • How -to read data from a file using PIPS

                • -

              • How -to write data to a file using PIPS

                • -

              • How -to remove the secure directory using PIPS

                • -

              • How -to use the P.I.P.S. standard C maths library, libm.dll

                • -

              • How -to compress/ decompress a file using Open C library.

                • -

              • How -to compress/ decompress a string using Open C library.

                • -

              • How -to do filtered data compression and Huffman compression using Open C library.

                • -

              • How -to send/receive messages using open C message queue library

                • -

              • Shows -string utility using open C libraries

                • -

              • How -to write solution for Producer/ Consumer Problem using Open C

                • -

              • how -to redirect stdio to a file using libc library

                • -

              • How -to convert a MS-word document (i.e. .doc) file in to a plain text(i.e. .txt) -file/Adobe acrobat(i.e. .pdf) file/ post-script (i.e. .ps) file/ xml (i.e. -.xml) file.

                • -

              • How -to handle global variables within the library code

                • -

              • How -to solve WSD (Writable Static Data) problem

                • -

              • How -to write a simple console-based STDLIB (C Standard library) program

                • -

              • How -to write a Techview GUI application whose engine is written using STDLIB

                • -

              • How -to create the most basic STDLIB application

                • -

              • How -to develop hybrid application which uses both pure C and native Symbian C++ -APIs

                • -

              • How -to create a named pipe

                • -

              • How -a parent process communicates with its child process using named pipes (FIFO)

                • -

              • How -a parent process communicates with its child process using a single pipe (popen())

                • -

              • How -to create multiple threads in PIPS using libpthread

                • -

              • How -to synchronize among multi threads in PIPS

                • -

              • How to handle -a signal using the default handler

                • -

              • How to handle -a signal using a customized signal handler

                • -

              • How to ignore -an incoming signal

                • -

              • How to block -and release a signal

                • -

              • How to wait -for a signal

                • -

              • How to handle -a SIGPIPE signal

                • -

              • How to gracefully -terminate a process

                • -

              • How to handle -an asynchronous event using signals

                • -

              • How to create a data recognizer

                • -

              • How to get the MIME type(s) -that a data recognizer is capable of recognizing

                • -

              • How to do data recognition

                • -

              • How -to run tasks using the task scheduler

                • -

              • How -to use the XML framework to parse XML and WBXML files

                • -

              • How -to read data from a resource file into an array

                • -

              • How -to use a resource reader to read data from a resource file into the data members -of a class

                • -

              • How -to read a resource from a resource file

                • -

              • How -to read a string resource and print it

                • -

              • How -the signature of a resource file is checked before it is used

                • -

              • How -to read a text string from a resource file

                • -

              • How -to check the identity of a resource file

                • -

              • How -to read multiple resource files

                • -

              • How -to use multiple resource files with cross-referenced resources

                • -

              • How -to write an interface definition for an ECOM plug-in

                • -

              • How -to implement an interface in an ECOM plug-in

                • -

              • How -to obtain the default implementation of an interface in an ECOM plug-in

                • -

              • How -to obtain an implementation of an interface in an ECOM plug-in

                • -

              • How -a client application uses the interface in an ECOM plug-in

                • -

              • How to do string handling -with EUserHl

                • -

              • How to do resource management -using EUserHl

                • -

              • How to get the memory overhead -of using EUserHl

                • - - - - - -
              -
              Graphics
                -

              • How -to create an animated sprite from a bitmap

                • -

              • How -to use the window server's direct screen access interface

                • -

              • How -to do ordinal positioning of windows

                • -

              • How -to implement simple freehand drawing using a pointer buffer

                • -

              • How -to load a bitmap

                • -

              • How -to draw a bitmap

                • -

              • How -to construct a control

                • -

              • How -to rotate a bitmap

                • -

              • How -to create a label

                • - - - - - - - -

              • How -to draw various shapes in a window

                • - - - - - - - - - -
              -
              Kernel and -Hardware Services
                -

              • How -to insert elements into a dynamic array

                • -

              • How -to append elements to a dynamic array

                • -

              • How -to access elements of a dynamic array

                • -

              • How -to remove elements from a dynamic array

                • -

              • How -to search a dynamic array

                • -

              • How -to sort a dynamic array

                • -

              • How -to destroy a dynamic array

                • -

              • How -to check the range for fixed arrays

                • -

              • How -to create a circular buffer

                • -

              • How -to add elements to a circular buffer

                • -

              • How -to remove elements from a circular buffer

                • -

              • How -to insert elements into a dynamic buffer

                • -

              • How -to read the elements of a dynamic buffer

                • -

              • How -to overwrite a dynamic buffer

                • -

              • How -to expand a dynamic buffer

                • -

              • How -to delete elements from a dynamic buffer

                • -

              • How -to compress a dynamic buffer

                • -

              • How -to display the contents of a buffer

                • -

              • How -to do lexical analysis

                • -

              • How -to create a resizable buffer

                • -

              • How -to swap two resizable buffers

                • -

              • How -to assign data to a resizable buffer

                • -

              • How -to reallocate a resizable buffer

                • -

              • How -to replace and modify the data in a resizable buffer

                • -

              • How -to do date and time handling

                • -

              • How -to connect to the file server

                • -

              • How -to disconnect from the file server

                • -

              • How -to create a file

                • -

              • How -to retrieve the attributes of a file

                • -

              • How -to create a file server session

                • -

              • How -to retrieve default paths

                • -

              • How -to change the session and system path

                • -

              • How -to obtain information about the available drives

                • -

              • How -to parse filenames

                • -

              • How -to monitor the progress of a file copy

                • -

              • How -to use the Publish and Subscribe mechanism

                • -

              • How -to do security checking on a client by a server

                • -

              • How -to get locale-specific currency values and symbols

                • -

              • How -to synchronise threads

                • -

              • How -to use thread local storage

                • -

              • How -to implement an asynchronous timer

                • -

              • How -to implement a periodic timer

                • -

              • How -to implement a heartbeat timer

                • -

              • How -to create a global message queue

                • -

              • How -to send a message to another process

                • -

              • How -to receive a message from another process

                • -

              • How -to load and unload a driver

                • -

              • How -to create multiple connections to a server

                • -

              • How -to use active objects and an active scheduler

                • -

              • How -a wait loop can be used to identify request completion

                • -

              • How -to accept and print keyboard inputs to a console

                • -

              • How to create multiple subsessions within a session

                • -

              • How -to start a server

                • -

              • How -to create a single session with a server

                • - -

              • How -to load and read from the locale DLL

                • -

              • How -to construct an object and leave on failure

                • -

              • How -to construct an object and return an error code on failure

                • -

              • How -to cleanup compound classes

                • -

              • How -to implement the NewL() static function

                • -

              • How -to implement the NewLC() static function

                • -

              • How -to use the cleanup stack

                • -

              • How -to use the TRAPD macro

                • -

              • How -to use CleanupDeletePushL()

                • -

              • How -to use CleanupClosePushL()

                • -

              • How -to use CleanupReleasePushL()

                • -

              • How -to use CleanupArrayDeletePushL()

                • -

              • How to use a doubly linked list

                • -

              • How to use a singly linked list

                • -

              • How to use a delta queue

                • -

              • How to generate timer events

                • -

              • How -to use a logical device driver (LDD) and a physical device driver (PDD)

                • -

              • How -to use a global condition variable

                • -

              • How -to implement a write operation on a shared memory block

                • -

              • How -to use a local condition variable

                • -

              • How -to create a queue of integer tokens

                • -

              • How -to load and unload an ldd and pdd

                • -

              • How -to cancel an asynchronous request

                • -

              • How -multiple clients in different processes connect to a server

                • -

              • How to handle binary data using 8 bit descriptors

                • -

              • How to use basic buffer descriptors

                • -

              • How to create and use a heap buffer descriptor

                • -

              • How to use descriptors as function arguments

                • -

              • How to use modifiable descriptors

                • -

              • How to use non-modifiable descriptors

                • -

              • How to use pointer descriptors

                • -

              • How -to get the number of available power-related resources

                • -

              • How -to get information about a power-related resource

                • -

              • How -to get information about all power-related resources

                • -

              • How -to get the state of a power-related resource

                • -

              • How -to get the number of clients using a particular power-related resource

                • -

              • How -to get the number of power-related resources used by a client

                • -

              • How -to get information about all the power-related resources in use by a particular -client

                • -

              • How -to get information about all clients using a particular power-related resource

                • -

              • How -to get the names of all Resource Manager clients

                • -

              • How -to change the state of a power-related resource

                • -

              • How -to get notification about a state change to a power-related resource

                • - -

              • How -to use semaphore in a multithreaded application

                • -

              • How to understand -the differences between multithreaded code running in a unicore environment -and in a multiprocessor environment

                • -

              • How to use a -named database using RdbNamedDatabase

                • -
              -
              Messaging
                -

              • How -to create a client registry

                • -

              • How -to create an IMAP account

                • -

              • How -to create an SMTP account

                • -

              • How -to create an SMTP message

                • -

              • How -to send an SMTP message

                • -

              • How -to connect to the IMAP server and download mail sent using SMTP

                • -

              • How -to update registry information when MTM groups are installed or uninstalled

                • -

              • How -to create a POP3 account

                • -

              • How -to connect to a POP3 server and download mail sent using SMTP

                • -

              • How -to create a SendAs message

                • -

              • How -to display account names

                • -

              • How -to define the connected session's available message types

                • -

              • How -to forward a message from an MTM account

                • -

              • How -to query for the capability of an MTM account

                • -

              • How -to create a BIO message

                • -

              • How -to create a session with the message server

                • -

              • How -to send a BIO message

                • -

              • How -to create a BIO message parser

                • -

              • How -to read messages from the message store

                • -

              • How -to parse a message's body text using the BIO message parser

                • -

              • How -to display the header information for message entries

                • -

              • How -to search and sort a message store

                • -

              • How -to do a combined search/sort of a message store

                • -

              • How -to search and sort a message store iteratively

                • -

              • How -to search and sort a message store using a query ID

                • -

              • How -to create an SMS service

                • -

              • How -to create an SMS

                • -

              • How -to send an SMS

                • -

              • How -to access and display SMS messages in the inbox, outbox and sent folders

                • -

              • How -to delete SMS messages

                • -
              -
              Multimedia
                -

              • How -to play an audio tone

                • -

              • How -to play audio from a file

                • -

              • How -to convert an audio file to another format

                • -

              • How -to record an audio file

                • -

              • How -to stream data

                • -

              • How -to set the volume of an audio file

                • -

              • How -to capture a still image

                • -

              • How -to capture video

                • -

              • How -to transfer viewfinder data

                • -

              • How -to perform image processing

                • -

              • How -to implement sink and source plug-ins for the Multimedia Framework

                • -

              • How -to convert images from one format to another

                • -

              • How -to manipulate images, for instance rotate, flip and zoom

                • -

              • How -to record audio clips

                • -

              • How -to get the list of audio formats supported

                • -

              • How -to record audio

                • -

              • How -to implement a codec plug-in for the Multimedia Framework

                • -

              • How -to convert media data from one encoding into another

                • -

              • How -to convert PCM8 into PCM16 encoded audio data

                • -

              • How -to implement a format encoder plug-in to the Multimedia Framework

                • -

              • How -to implement a format decoder plug-in to the Multimedia Framework

                • -

              • Basic -panorama stitching

                • -

              • Panorama -stitching based on viewfinder tracking

                • -

              • Image -processing with some basic effects

                • -

              • Generating -Scalado SpeedView objects (Spmo)

                • -

              • Removing -effects from the images

                • -

              • Adding -effects to the images and generating a preview

                • -

              • Adding -effects to the images and generating an overlay

                • -

              • Adding -a SpeedView object to the image

                • -

              • Squeeze -an image from a file to a file

                • -

              • Squeeze -an image from buffer to buffer

                • -

              • Auto -squeeze an image from file to file

                • -

              • Rotate -an image from file to file

                • -

              • Blend -a jpg data in file to a file and squeeze it

                • -
              - -
              PC Tools
                -

              • How to create -a simple installation file for an application

                • -

              • How -to create an installation file for a multilingual application

                • -
              - - - -
              System GUI -Framework
                - - -

              • How to create and display -a digital clock

                • -

              • How to create and display -an analog clock

                • - - - -
              - + + + + + +List of Example Code Use Cases +

              This document lists all the example code programs available for +each module, organised by use case.

              +
              Symbian +Platform Fundamentals
                +

              • Basic helloworld +application

                • +

              • How to create a +C class

                • +

              • How to do single +phase construction

                • +

              • How to do two-phase +construction

                • +

              • How to use an R +class

                • +

              • How to use a T class

                • +

              • How to use a mixin +class

                • +

              • How to create a +static DLL

                • +

              • How to use a static +DLL

                • +
              +
              Application +Framework
                + + + + + + + +

              • How to implement +a simple GUI application with a single view

                • +

              • How to create an +animation using the Bitmap Animation framework

                • +

              • How to view an animation +inside a window

                • +
              + +
              Communication +Framework

              Data Server

                +

              • How to do connection +monitoring and management using the RConnection API

                • +
              + +
              High +Level Internet Protocols
                +

              • How to use HTTP APIs

                • +
              +
              Generic +Application Support
                +

              • How to add a floating +alarm to the alarm server

                • +

              • How to add a fixed +alarm to the alarm server

                • +

              • How to get notification +from the alarm server

                • + + + +
              +
              Generic +OS Services
                +

              • How to compress data +using the EZLIB API

                • +

              • How to decompress +data using the EZLIB API

                • +

              • How to create a secure +directory using PIPS

                • +

              • How to read data +from a file using PIPS

                • +

              • How to write data +to a file using PIPS

                • +

              • How to remove the +secure directory using PIPS

                • +

              • How to use the P.I.P.S. +standard C maths library, libm.dll

                • +

              • How to compress/ +decompress a file using Open C library.

                • +

              • How to compress/ +decompress a string using Open C library.

                • +

              • How to do filtered +data compression and Huffman compression using Open C library.

                • +

              • How to send/receive +messages using open C message queue library

                • +

              • Shows string utility +using open C libraries

                • +

              • How to write solution +for Producer/ Consumer Problem using Open C

                • +

              • how to redirect stdio +to a file using libc library

                • +

              • How to handle global +variables within the library code

                • +

              • How to solve WSD +(Writable Static Data) problem

                • +

              • How to write a simple +console-based STDLIB (C Standard library) program

                • +

              • How to write a Techview +GUI application whose engine is written using STDLIB

                • +

              • How to create the +most basic STDLIB application

                • +

              • How to develop hybrid +application which uses both pure C and native Symbian C++ APIs

                • +

              • How to create a named +pipe

                • +

              • How a parent process +communicates with its child process using named pipes (FIFO)

                • +

              • How a parent process +communicates with its child process using a single pipe (popen())

                • +

              • How to create multiple +threads in PIPS using libpthread

                • +

              • How to synchronize +among multi threads in PIPS

                • +

              • How +to handle a signal using the default handler

                • +

              • How +to handle a signal using a customized signal handler

                • +

              • How +to ignore an incoming signal

                • +

              • How +to block and release a signal

                • +

              • How +to wait for a signal

                • +

              • How +to handle a SIGPIPE signal

                • +

              • How +to gracefully terminate a process

                • +

              • How +to handle an asynchronous event using signals

                • +

              • How to create a data +recognizer

                • +

              • How to get the MIME +type(s) that a data recognizer is capable of recognizing

                • +

              • How to do data recognition

                • +

              • How to run tasks +using the task scheduler

                • +

              • How to use the XML +framework to parse XML and WBXML files

                • +

              • How to read data +from a resource file into an array

                • +

              • How to use a resource +reader to read data from a resource file into the data members of +a class

                • +

              • How to read a resource +from a resource file

                • +

              • How to read a string +resource and print it

                • +

              • How the signature +of a resource file is checked before it is used

                • +

              • How to read a text +string from a resource file

                • +

              • How to check the +identity of a resource file

                • +

              • How to read multiple +resource files

                • +

              • How to use multiple +resource files with cross-referenced resources

                • +

              • How to write an interface +definition for an ECOM plug-in

                • +

              • How to implement +an interface in an ECOM plug-in

                • +

              • How to obtain the +default implementation of an interface in an ECOM plug-in

                • +

              • How to obtain an +implementation of an interface in an ECOM plug-in

                • +

              • How a client application +uses the interface in an ECOM plug-in

                • +

              • How to do string +handling with EUserHl

                • +

              • How to do resource +management using EUserHl

                • +

              • How to get the memory +overhead of using EUserHl

                • + + + + + +
              +
              Graphics
                +

              • How to create an +animated sprite from a bitmap

                • +

              • How to use the window +server's direct screen access interface

                • +

              • How to do ordinal +positioning of windows

                • +

              • How to implement +simple freehand drawing using a pointer buffer

                • +

              • How to load a bitmap

                • +

              • How to draw a bitmap

                • +

              • How to construct +a control

                • +

              • How to rotate a bitmap

                • +

              • How to create a label

                • +

              • how to create OpenVG +content on a semi-transparent or transparent UI using the new Graphics +architecture using ScreenPlay

                • + + + + + + + +

              • How to draw various +shapes in a window

                • + + + + + + + + + +
              +
              Kernel +and Hardware Services
                +

              • How to insert elements +into a dynamic array

                • +

              • How to append elements +to a dynamic array

                • +

              • How to access elements +of a dynamic array

                • +

              • How to remove elements +from a dynamic array

                • +

              • How to search a dynamic +array

                • +

              • How to sort a dynamic +array

                • +

              • How to destroy a +dynamic array

                • +

              • How to check the +range for fixed arrays

                • +

              • How to create a circular +buffer

                • +

              • How to add elements +to a circular buffer

                • +

              • How to remove elements +from a circular buffer

                • +

              • How to insert elements +into a dynamic buffer

                • +

              • How to read the elements +of a dynamic buffer

                • +

              • How to overwrite +a dynamic buffer

                • +

              • How to expand a dynamic +buffer

                • +

              • How to delete elements +from a dynamic buffer

                • +

              • How to compress a +dynamic buffer

                • +

              • How to display the +contents of a buffer

                • +

              • How to do lexical +analysis

                • +

              • How to create a resizable +buffer

                • +

              • How to swap two resizable +buffers

                • +

              • How to assign data +to a resizable buffer

                • +

              • How to reallocate +a resizable buffer

                • +

              • How to replace and +modify the data in a resizable buffer

                • +

              • How to do date and +time handling

                • + + + + + + + + + + +

              • How to use the Publish +and Subscribe mechanism

                • +

              • How to do security +checking on a client by a server

                • +

              • How to get locale-specific +currency values and symbols

                • +

              • How to synchronise +threads

                • +

              • How to use thread +local storage

                • +

              • How to implement +an asynchronous timer

                • +

              • How to implement +a periodic timer

                • +

              • How to implement +a heartbeat timer

                • +

              • How to create a global +message queue

                • +

              • How to send a message +to another process

                • +

              • How to receive a +message from another process

                • +

              • How to load and unload +a driver

                • +

              • How to create multiple +connections to a server

                • +

              • How to use active +objects and an active scheduler

                • +

              • How a wait loop can +be used to identify request completion

                • +

              • How to accept and +print keyboard inputs to a console

                • +

              • How to create multiple subsessions within a session

                • +

              • How to start a server

                • +

              • How to create a single +session with a server

                • + +

              • How to load and read +from the locale DLL

                • +

              • How to construct +an object and leave on failure

                • +

              • How to construct +an object and return an error code on failure

                • +

              • How to cleanup compound +classes

                • +

              • How to implement +the NewL() static function

                • +

              • How to implement +the NewLC() static function

                • +

              • How to use the cleanup +stack

                • +

              • How to use the TRAPD +macro

                • +

              • How to use CleanupDeletePushL()

                • +

              • How to use CleanupClosePushL()

                • +

              • How to use CleanupReleasePushL()

                • +

              • How to use CleanupArrayDeletePushL()

                • +

              • How to use a doubly linked list

                • +

              • How to use a singly linked list

                • +

              • How to use a delta queue

                • +

              • How to generate timer events

                • +

              • How to use a logical +device driver (LDD) and a physical device driver (PDD)

                • +

              • How to use a global +condition variable

                • +

              • How to implement +a write operation on a shared memory block

                • +

              • How to use a local +condition variable

                • +

              • How to create a queue +of integer tokens

                • +

              • How to load and unload +an ldd and pdd

                • +

              • How to cancel an +asynchronous request

                • +

              • How multiple clients +in different processes connect to a server

                • +

              • How to handle binary data using 8 bit descriptors

                • +

              • How to use basic buffer descriptors

                • +

              • How to create and use a heap buffer descriptor

                • +

              • How to use descriptors as function arguments

                • +

              • How to use modifiable descriptors

                • +

              • How to use non-modifiable descriptors

                • +

              • How to use pointer descriptors

                • +

              • How to get the number +of available power-related resources

                • +

              • How to get information +about a power-related resource

                • +

              • How to get information +about all power-related resources

                • +

              • How to get the state +of a power-related resource

                • +

              • How to get the number +of clients using a particular power-related resource

                • +

              • How to get the number +of power-related resources used by a client

                • +

              • How to get information +about all the power-related resources in use by a particular client

                • +

              • How to get information +about all clients using a particular power-related resource

                • +

              • How to get the names +of all Resource Manager clients

                • +

              • How to change the +state of a power-related resource

                • +

              • How to get notification +about a state change to a power-related resource

                • + +

              • How to use semaphore +in a multithreaded application

                • +

              • How +to understand the differences between multithreaded code running in +a unicore environment and in a multiprocessor environment

                • +

              • How +to use a named database using RdbNamedDatabase

                • +
              +
              Messaging
                +

              • How to create a client +registry

                • +

              • How to create an +IMAP account

                • +

              • How to create an +SMTP account

                • +

              • How to create an +SMTP message

                • +

              • How to send an SMTP +message

                • +

              • How to connect to +the IMAP server and download mail sent using SMTP

                • +

              • How to update registry +information when MTM groups are installed or uninstalled

                • +

              • How to create a POP3 +account

                • +

              • How to connect to +a POP3 server and download mail sent using SMTP

                • +

              • How to create a SendAs +message

                • +

              • How to display account +names

                • +

              • How to define the +connected session's available message types

                • +

              • How to forward a +message from an MTM account

                • +

              • How to query for +the capability of an MTM account

                • +

              • How to create a BIO +message

                • +

              • How to create a session +with the message server

                • +

              • How to send a BIO +message

                • +

              • How to create a BIO +message parser

                • +

              • How to read messages +from the message store

                • +

              • How to parse a message's +body text using the BIO message parser

                • +

              • How to display the +header information for message entries

                • +

              • How to search and +sort a message store

                • +

              • How to do a combined +search/sort of a message store

                • +

              • How to search and +sort a message store iteratively

                • +

              • How to search and +sort a message store using a query ID

                • +

              • How to create an +SMS service

                • +

              • How to create an +SMS

                • +

              • How to send an SMS

                • +

              • How to access and +display SMS messages in the inbox, outbox and sent folders

                • +

              • How to delete SMS +messages

                • +
              +
              Multimedia
                +

              • How to play an audio +tone

                • +

              • How to play audio +from a file

                • +

              • How to convert an +audio file to another format

                • +

              • How to record an +audio file

                • +

              • How to stream data

                • +

              • How to set the volume +of an audio file

                • +

              • How to capture a +still image

                • +

              • How to capture video

                • +

              • How to transfer viewfinder +data

                • +

              • How to perform image +processing

                • +

              • How to implement +sink and source plug-ins for the Multimedia Framework

                • +

              • How to convert images +from one format to another

                • +

              • How to manipulate +images, for instance rotate, flip and zoom

                • +

              • How to implement +a codec plug-in for the Multimedia Framework

                • +

              • How to convert media +data from one encoding into another

                • +

              • How to convert PCM8 +into PCM16 encoded audio data

                • +

              • How to implement +a format encoder plug-in to the Multimedia Framework

                • +

              • How to implement +a format decoder plug-in to the Multimedia Framework

                • +
              +
              Networking +Services
                +

              • How to send an http +page request to the server

                • +

              • How to get the server +response

                • +

              • How to read the server +response

                • +

              • How to connect to +a socket using an IP address

                • +

              • How to connect to +a socket using the host name

                • +

              • How to read/write +data to/from a stream socket

                • +

              • How to read/write +data to/from a datagram socket

                • +
              +
              PC +Tools
                +

              • How +to create a simple installation file for an application

                • +

              • How to create an +installation file for a multilingual application

                • +
              +
              Persistent +Data Services
                +

              • How to store data +in a central repository

                • +

              • How to use the SQL +API for data creation

                • +

              • How to copy one database +to another using the SQL API

                • +

              • How to attach two +databases using the SQL API

                • +

              • How to query a database +using the SQL API

                • +

              • How to create a clipboard

                • +

              • How to copy an object +to the clipboard

                • +

              • How to fetch content +from the clipboard

                • +

              • How to create a database +using the DBMS API.

                • +

              • How to use a database +for indexing using the DBMS API

                • +

              • How to create and replace a direct file store

                • +

              • How to write objects to a single stream

                • +

              • How to close a file stream

                • +

              • How to restore objects from a root stream

                • +

              • How to externalize a network of objects to a direct file store

                • +

              • How to internalize a network of objects from a direct file store

                • +

              • How to construct and write a network of objects to a permanent file +store

                • +

              • How to write two +different types of object to a single stream contained in the memory +store

                • +

              • How to restrore objects +from a memory store

                • +

              • How to externalize a compound object to a memory stream

                • +

              • How to internalize a compound object from a memory stream

                • +

              • How to stream a simple class to and from a single stream

                • +

              • How to stream a compound object to multiple streams using a store +map

                • +

              • How to externalize objects to a single stream in a non-persistent +store

                • +

              • How to externalize an object to a store embedded within a permanent +file store

                • +

              • How to write a network of objects to more than one stream in a direct +file store

                • +

              • How to defer the loading of an object from the store into memory

                • +

              • How to get the list +of available features in a device

                • +

              • How to add a new +feature to the device

                • +

              • How to modify or +delete a feature

                • +

              • How to get notification +about a feature change

                • +
              +
              PIM
                +

              • How to view a contact +database

                • +

              • How to create and +use a calendar file

                • +

              • How to create and +open a calendar file

                • +

              • How to create a view +of the entries in a calendar file

                • +

              • How to add properties +to a calendar file

                • +

              • How to create a vCard +parser

                • +

              • How to export a vCard +to a file

                • +

              • How to import a vCard +from a file

                • +
              + +
              System +GUI Framework
                + + +

              • How to create and +display a digital clock

                • +

              • How to create and +display an analog clock

                • + + + +
              +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-94F21522-D598-5F85-BE04-D606AE8D5A25.dita --- a/Symbian3/SDK/Source/GUID-94F21522-D598-5F85-BE04-D606AE8D5A25.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-94F21522-D598-5F85-BE04-D606AE8D5A25.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,14 +1,14 @@ - - - - - -Overview

              Telnet refers to the client-side software implementation and TelnetD (Telnet Daemon) to the server-side implementation. A Telnet client (for example, host PC) is connected to a TelnetD (for example, device). Here the purpose is to run and control a shell on a device using a PC as a terminal with a keyboard.

              The main purpose of using Zsh connected through TelnetD is to launch utilities (such as, external programs), debug applications, generate logs and retrieve information (such as, contents of the file) from public directories. The Utilities are executables whose output can be made available to the remote Telnet user by viewing text, or archiving as files or as an another program.

              Zsh transfers characters to the Telnet client and vice versa using TelnetD. Zsh interface is provided to enable programs to be conveniently launched for testing purposes. The shell also supports a number of built-in commands.

              Using TelnetD and Zsh

              Zsh can be launched by selecting the Zsh icon on the device. It starts TelnetD automatically. A connection can then be established from the Telnet client (host PC) to TelnetD by giving the following command at a Windows® or a UNIX® command prompt:

              Telnet <ip-address of the device>

              For information on retrieving the IP address refer to Setup.

              Every login to Zsh is through a key handshake. The device prompts for a key when you try to connect from the host PC. The same key given to the device has to be given at the host PC for the login to be successful. If the login is successful then the device starts the Zsh application. The maximum number of characters a key can accept is eight. The characters can be a combination of alphabets, numerals, and special characters.

              For existing Telnet clients on the host PC such as Microsoft Windows or Linux to connect to the server running on the device, the device needs an IP address.

              TelnetD supports send and receive functionality: TelnetD sends any data to and from Zsh to the host PC. TelnetD runs only when it is connected through a TCP/IP network. When the Telnet client places a request, TelnetD starts Zsh on the device, executes the specified command on the device, and sends the resultant data back to the host PC.

              - Connection between the client (host PC) and the server (device) -
              Reference Setup               \ No newline at end of file + + + + + +Overview

              Telnet refers to the client-side software implementation and TelnetD (Telnet Daemon) to the server-side implementation. A Telnet client (for example, host PC) is connected to a TelnetD (for example, device). Here the purpose is to run and control a shell on a device using a PC as a terminal with a keyboard.

              The main purpose of using Zsh connected through TelnetD is to launch utilities (such as, external programs), debug applications, generate logs and retrieve information (such as, contents of the file) from public directories. The Utilities are executables whose output can be made available to the remote Telnet user by viewing text, or archiving as files or as an another program.

              Zsh transfers characters to the Telnet client and vice versa using TelnetD. Zsh interface is provided to enable programs to be conveniently launched for testing purposes. The shell also supports a number of built-in commands.

              Using TelnetD and Zsh

              Zsh can be launched by selecting the Zsh icon on the device. It starts TelnetD automatically. A connection can then be established from the Telnet client (host PC) to TelnetD by giving the following command at a Windows® or a UNIX® command prompt:

              Telnet <ip-address of the device>

              For information on retrieving the IP address refer to Setup.

              Every login to Zsh is through a key handshake. The device prompts for a key when you try to connect from the host PC. The same key given to the device has to be given at the host PC for the login to be successful. If the login is successful then the device starts the Zsh application. The maximum number of characters a key can accept is eight. The characters can be a combination of alphabets, numerals, and special characters.

              For existing Telnet clients on the host PC such as Microsoft Windows or Linux to connect to the server running on the device, the device needs an IP address.

              TelnetD supports send and receive functionality: TelnetD sends any data to and from Zsh to the host PC. TelnetD runs only when it is connected through a TCP/IP network. When the Telnet client places a request, TelnetD starts Zsh on the device, executes the specified command on the device, and sends the resultant data back to the host PC.

              + Connection between the client (host PC) and the server (device) +
              Reference Setup               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-95259B6D-19A0-569E-B04B-F75B8DADC80E.dita --- a/Symbian3/SDK/Source/GUID-95259B6D-19A0-569E-B04B-F75B8DADC80E.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-95259B6D-19A0-569E-B04B-F75B8DADC80E.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,12 +1,12 @@ - - - - - -The object container index

              All object containers must be held within a special type of container known as an object container index.

              An object container index is an instance of a CObjectConIx class.

              An object container index not only acts as a container for object containers, but also provides the mechanism through which object containers are created.

              CObjectConIx::CreateL() creates an object container and is responsible for assigning a unique ID to it. This unique ID forms part of the identity of all reference counting objects which that object container will, in due course, hold.

              For example, the sever creates a single object container index; from this it creates a number of object containers, each of which, in turn, holds reference counting objects. The following drawing shows the idea.

              An object container index is implemented as a simple array where each element of the array contains a pointer to an object container. CObjectConIx::CreateL() constructs an object container, assigns a unique ID to it and adds it into the CObjectConIx array.

              See also:

              • CObjectConIx

              • CObjectCon

              • CObject

              \ No newline at end of file + + + + + +The object container index

              All object containers must be held within a special type of container known as an object container index.

              An object container index is an instance of a CObjectConIx class.

              An object container index not only acts as a container for object containers, but also provides the mechanism through which object containers are created.

              CObjectConIx::CreateL() creates an object container and is responsible for assigning a unique ID to it. This unique ID forms part of the identity of all reference counting objects which that object container will, in due course, hold.

              For example, the sever creates a single object container index; from this it creates a number of object containers, each of which, in turn, holds reference counting objects. The following drawing shows the idea.

              An object container index is implemented as a simple array where each element of the array contains a pointer to an object container. CObjectConIx::CreateL() constructs an object container, assigns a unique ID to it and adds it into the CObjectConIx array.

              See also:

              • CObjectConIx

              • CObjectCon

              • CObject

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-95493C3D-58C6-5EBF-85E1-167D58E68658.dita --- a/Symbian3/SDK/Source/GUID-95493C3D-58C6-5EBF-85E1-167D58E68658.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-95493C3D-58C6-5EBF-85E1-167D58E68658.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,131 +1,131 @@ - - - - - -Bluetooth -Remote Control Framework -
              Purpose

              The Bluetooth Remote Control Framework -provides the APIs needed to send (CRemConCoreApiController) -and receive (CRemConCoreApiTarget) remote control commands -to/from a Bluetooth enabled device.

              In this overview

              You -will learn about the Bluetooth Remote Control Framework. Several tutorials -are provided, links are at the end of the overview, to help get you started -writing remote control applications.

              -
              Architectural relationships

              The Bluetooth subsystem -provides a number of APIs that you will use to establish a connection to a -Bluetooth device that provides the required services. The APIs you need to -know about include:

                -

              • Bluetooth -User

                Establishing a Bluetooth connection.

                • -

              • Bluetooth -SDP

                Finding a device that can provide the necessary services.

                • -

              • Serial -Comms C32

                The serial communications framework.

                • -

              • Socket -Server

                The interface to protocols.

                • -

              The Audio -Video Remote Control Profile (AVRCP) is implemented by the Remote Control -Framework. A remote control bearer plug-in is required, which uses socket -APIs internally to send and receive Audio Video Control Transport Protocol -(AVCTP) data over ESock.

              -
              Key Concepts
              - -
              Controller
              -

              The controller is a device that sends a control message or command -to a target device and is ready to capture responses.

              -               - -
              Target
              -

              The target is a device that accepts the control message or command -from the controller, invokes necessary procedures and sends out responses -to controller.

              -               - -
              Bearer
              -

              The bearer is a carrier that acts like a vehicle of transmission for -remote control messages. The bearer here is an Ecom plugin to the RemCon server.

              -               - -
              Audio Video Remote Control Profile (AVRCP)
              -

              The bearer that plugs into the RemCon server and transmits remote control -messages (commands) and status responses.

              -               - -
              Converter
              -

              This is an ECom plug-in that converts the message format from the Client -side API to the bearer format and vice versa.

              -               - -
              Audio Video Control Transport Protocol (AVCTP)
              -

              The protocol that defines the methods and messages used for controlling -Audio/Video devices.

              -               - -
              Audio Video Distribution Transport Protocol (AVDTP)
              -

              The AVDTP is used to send frames of encoded multimedia data over Bluetooth.

              -               -
              -
              Description

              The Bluetooth Remote Control Framework -provides APIs that make it possible for a device to participate in remote -control relationship. The framework can be used to create an application with -one of three behavior sets, they are:

                -

              • Device acts as a remote -controller

                • -

              • Device is controlled -remotely

                • -

              • Combination of the above -in a single device / application.

                • -

              Remote Controller

              As a controller the device will -send commands to a target device. A controller can be connection-orientated, -meaning it identifies a specific device to control and maintains a connection -with that device, or connectionless, meaning remote control commands are sent -out into the air for any receptive device to accept.

              The Controller -APIs allow an application to send commands to a remote controlled device.

              Controller -APIs include:

                -

              1. CRemConCoreApiController

                2. -

              2. CRemConTargetSelectorPlugin

                3. -

              3. CRemConBearerPlugin

                4. -

              4. CRemConInterfaceBase

                5. -

              5. CRemConInterfaceSelector

                6. -

              Controlled Remotely

              Known as the target device, this -device receives commands from a controller. Target devices may only be connectionless, -meaning they will always respond to valid remote control commands, regardless -of the source of said commands.

              The Target API enables applications -to receive commands and to query for information from the controller.

              Target -APIs include:

                -

              1. CRemConCoreApiTarget

                2. -

              2. MRemConInterfaceIf

                3. -

              3. CRemConInterfaceBase

                4. -

              How Remote Control Works

              The following diagram shows -how the Remote Control Framework works for a handsfree headset example.

              - Bluetooth Remote Control Headset -

              The controller application uses the Controller API, which is connected -to the RemCon Server. The ECom plugin or AVRCP in this case is plugged into -the RemCon server. The message format from the Controller API is converted -into AVRCP format by the Converter plugin which in turn converts it into target -API format at the other end. The target APIs invoke the necessary actions -on the application and update the RemCon server of the status. The applicable -Audio Video Distribution Transport Protocol (AVDTP) is used to deliver the -output stream from the multimedia application to the controller device. The -RemCon Server status is updated to the Controller through the AVRCP bearer.

              - -
              -
              What's next?

              The following tutorial series has -been provided to make writing remote control applications easier.

                -

              • Remote -Control Basics

                • -

              • Starting -as Controller

                • -

              • Starting -as Target

                • -

              • Commands -and Responses

                • -
              + + + + + +Bluetooth +Remote Control Framework +
              Purpose

              The Bluetooth Remote Control Framework +provides the APIs needed to send (CRemConCoreApiController) +and receive (CRemConCoreApiTarget) remote control commands +to/from a Bluetooth enabled device.

              In this overview

              You +will learn about the Bluetooth Remote Control Framework. Several tutorials +are provided, links are at the end of the overview, to help get you started +writing remote control applications.

              +
              Architectural relationships

              The Bluetooth subsystem +provides a number of APIs that you will use to establish a connection to a +Bluetooth device that provides the required services. The APIs you need to +know about include:

                +

              • Bluetooth +User

                Establishing a Bluetooth connection.

                • +

              • Bluetooth +SDP

                Finding a device that can provide the necessary services.

                • +

              • Serial +Comms C32

                The serial communications framework.

                • +

              • Socket +Server

                The interface to protocols.

                • +

              The Audio +Video Remote Control Profile (AVRCP) is implemented by the Remote Control +Framework. A remote control bearer plug-in is required, which uses socket +APIs internally to send and receive Audio Video Control Transport Protocol +(AVCTP) data over ESock.

              +
              Key Concepts
              + +
              Controller
              +

              The controller is a device that sends a control message or command +to a target device and is ready to capture responses.

              +               + +
              Target
              +

              The target is a device that accepts the control message or command +from the controller, invokes necessary procedures and sends out responses +to controller.

              +               + +
              Bearer
              +

              The bearer is a carrier that acts like a vehicle of transmission for +remote control messages. The bearer here is an Ecom plugin to the RemCon server.

              +               + +
              Audio Video Remote Control Profile (AVRCP)
              +

              The bearer that plugs into the RemCon server and transmits remote control +messages (commands) and status responses.

              +               + +
              Converter
              +

              This is an ECom plug-in that converts the message format from the Client +side API to the bearer format and vice versa.

              +               + +
              Audio Video Control Transport Protocol (AVCTP)
              +

              The protocol that defines the methods and messages used for controlling +Audio/Video devices.

              +               + +
              Audio Video Distribution Transport Protocol (AVDTP)
              +

              The AVDTP is used to send frames of encoded multimedia data over Bluetooth.

              +               +
              +
              Description

              The Bluetooth Remote Control Framework +provides APIs that make it possible for a device to participate in remote +control relationship. The framework can be used to create an application with +one of three behavior sets, they are:

                +

              • Device acts as a remote +controller

                • +

              • Device is controlled +remotely

                • +

              • Combination of the above +in a single device / application.

                • +

              Remote Controller

              As a controller the device will +send commands to a target device. A controller can be connection-orientated, +meaning it identifies a specific device to control and maintains a connection +with that device, or connectionless, meaning remote control commands are sent +out into the air for any receptive device to accept.

              The Controller +APIs allow an application to send commands to a remote controlled device.

              Controller +APIs include:

                +

              1. CRemConCoreApiController

                2. +

              2. CRemConTargetSelectorPlugin

                3. +

              3. CRemConBearerPlugin

                4. +

              4. CRemConInterfaceBase

                5. +

              5. CRemConInterfaceSelector

                6. +

              Controlled Remotely

              Known as the target device, this +device receives commands from a controller. Target devices may only be connectionless, +meaning they will always respond to valid remote control commands, regardless +of the source of said commands.

              The Target API enables applications +to receive commands and to query for information from the controller.

              Target +APIs include:

                +

              1. CRemConCoreApiTarget

                2. +

              2. MRemConInterfaceIf

                3. +

              3. CRemConInterfaceBase

                4. +

              How Remote Control Works

              The following diagram shows +how the Remote Control Framework works for a handsfree headset example.

              + Bluetooth Remote Control Headset +

              The controller application uses the Controller API, which is connected +to the RemCon Server. The ECom plugin or AVRCP in this case is plugged into +the RemCon server. The message format from the Controller API is converted +into AVRCP format by the Converter plugin which in turn converts it into target +API format at the other end. The target APIs invoke the necessary actions +on the application and update the RemCon server of the status. The applicable +Audio Video Distribution Transport Protocol (AVDTP) is used to deliver the +output stream from the multimedia application to the controller device. The +RemCon Server status is updated to the Controller through the AVRCP bearer.

              + +
              +
              What's next?

              The following tutorial series has +been provided to make writing remote control applications easier.

                +

              • Remote +Control Basics

                • +

              • Starting +as Controller

                • +

              • Starting +as Target

                • +

              • Commands +and Responses

                • +
               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-95580D64-315E-51E8-99C3-6C0B8FFF1522_d0e277871_href.png Binary file Symbian3/SDK/Source/GUID-95580D64-315E-51E8-99C3-6C0B8FFF1522_d0e277871_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-95580D64-315E-51E8-99C3-6C0B8FFF1522_d0e281557_href.png Binary file Symbian3/SDK/Source/GUID-95580D64-315E-51E8-99C3-6C0B8FFF1522_d0e281557_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-95CE2206-7AE0-48C0-97A7-4E2082F9F662.dita --- a/Symbian3/SDK/Source/GUID-95CE2206-7AE0-48C0-97A7-4E2082F9F662.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-95CE2206-7AE0-48C0-97A7-4E2082F9F662.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,94 +1,94 @@ - - - - - -Enabling -quick access to functions with a toolbar -

              To use the Toolbar API, follow the steps below.

              -
                -
              1. Link the AVKON libraries -(avkon.lib, eikcoctl.lib) to the project -file of the application.
                2. -
              2. Define the toolbar in the -application resources. Set it as application or view specific.
                3. -
              3. Provide a class that implements -the toolbar observer (MAknToolbarObserver) -interface. Set the class as the observer of the toolbar (CAknToolbar) -created in the previous step.
                4. -
              4. If the toolbar items were -not defined in the resources, add them dynamically in the application code.
                5. -
              5. In the case of a floating -toolbar, set the toolbar visible. (The framework sets the fixed toolbar automatically -visible when activating the application/view.)
                6. -
              6. Handle toolbar events using -the observer interface methods.
                7. -
              - -Fixed toolbar with implementation classes - - -
              Implementing -a toolbar

              To use a toolbar in your application, implement the following -use cases:

                -

              • Constructing -the toolbar

                • -

              • Adding and removing -toolbar items (the toolbar buttons are defined in the Generic -button API)

                • -

              • Accessing the -toolbar from applications or application views

                • -

              • Accessing toolbar -items

                • -

              • Handling toolbar -item events

                • -

              We need to provide more clarity -on the required order of implementing the use cases and clarify whether there -are alternative approaches for achieving the same results.

              The -following use cases are optional, allowing you to set additional properties -for your toolbar:

                -

              • Controlling -toolbar visibility

                • -

              • Showing and -hiding toolbar items

                • -

              • Dynamic initialization -of the toolbar

                • -

              • Setting toolbar -properties

                • -
              -
              Implementing -a toolbar extension (optional)

              To use a toolbar extension in your -application, implement the following use cases:

                -

              • Creating the -toolbar extension

                • -

              • Adding and removing -toolbar extension items

                • -

              • Accessing toolbar -extension items

                • -

              The following use cases are optional, allowing you to set additional -properties for your toolbar extension:

                -

              • Showing or hiding -the toolbar extension

                • -

              • Dimming or hiding -toolbar extension items

                • -
              -
              Main implementation -files

              The main implementation files for the Toolbar API are:

                -

              • akntoolbar.h for creating the toolbar and setting -its properties

                • -

              • akntoolbarobserver.h for handling toolbar events

                • -

              • akntoolbarextension.h for creating the toolbar extension -and setting its properties

                • -
              -               -Toolbar API -description -Look and -feel guidelines for the toolbar + + + + + +Enabling +quick access to functions with a toolbar +

              To use the Toolbar API, follow the steps below.

              +
                +
              1. Link the AVKON libraries +(avkon.lib, eikcoctl.lib) to the project +file of the application.
                2. +
              2. Define the toolbar in the +application resources. Set it as application or view specific.
                3. +
              3. Provide a class that implements +the toolbar observer (MAknToolbarObserver) +interface. Set the class as the observer of the toolbar (CAknToolbar) +created in the previous step.
                4. +
              4. If the toolbar items were +not defined in the resources, add them dynamically in the application code.
                5. +
              5. In the case of a floating +toolbar, set the toolbar visible. (The framework sets the fixed toolbar automatically +visible when activating the application/view.)
                6. +
              6. Handle toolbar events using +the observer interface methods.
                7. +
              + +Fixed toolbar with implementation classes + + +
              Implementing +a toolbar

              To use a toolbar in your application, implement the following +use cases:

                +

              • Constructing +the toolbar

                • +

              • Adding and removing +toolbar items (the toolbar buttons are defined in the Generic +button API)

                • +

              • Accessing the +toolbar from applications or application views

                • +

              • Accessing toolbar +items

                • +

              • Handling toolbar +item events

                • +

              We need to provide more clarity +on the required order of implementing the use cases and clarify whether there +are alternative approaches for achieving the same results.

              The +following use cases are optional, allowing you to set additional properties +for your toolbar:

                +

              • Controlling +toolbar visibility

                • +

              • Showing and +hiding toolbar items

                • +

              • Dynamic initialization +of the toolbar

                • +

              • Setting toolbar +properties

                • +
              +
              Implementing +a toolbar extension (optional)

              To use a toolbar extension in your +application, implement the following use cases:

                +

              • Creating the +toolbar extension

                • +

              • Adding and removing +toolbar extension items

                • +

              • Accessing toolbar +extension items

                • +

              The following use cases are optional, allowing you to set additional +properties for your toolbar extension:

                +

              • Showing or hiding +the toolbar extension

                • +

              • Dimming or hiding +toolbar extension items

                • +
              +
              Main implementation +files

              The main implementation files for the Toolbar API are:

                +

              • akntoolbar.h for creating the toolbar and setting +its properties

                • +

              • akntoolbarobserver.h for handling toolbar events

                • +

              • akntoolbarextension.h for creating the toolbar extension +and setting its properties

                • +
              +               +Toolbar API +description +Look and +feel guidelines for the toolbar               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-95E557D0-9A84-514C-B51E-0556F26B3C98.dita --- a/Symbian3/SDK/Source/GUID-95E557D0-9A84-514C-B51E-0556F26B3C98.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-95E557D0-9A84-514C-B51E-0556F26B3C98.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,48 +1,44 @@ - - - - - -EzlibExample: -Using EZLIB to Compress and Decompress Files -

              This overview describes the example application that demonstrates the usage -of the EZLIB API.

              -
              Download

              Click -on the following link to download the example: EzlibExample.zip

              Click: browse to view the example code.

              -
              Description

              EZLIB -is a utility API used to compress and decompress data. The API is an extension -of ZLIB compression library. For more information on ZLIB compression library, -refer to RFC1950.

              This -example application uses the EZLIB API to extract files from a .zip and -a .gz file into specified folders, and to compress a .wav file -into a .gz file. The application reads input files and -stores the extracted files in c:\private\E80000B7\.

              The -application uses an object of the RFs class to open the EzlibZipFolder.zip file. -It reads the properties of each file in the archive using the CZipFileMember object -and prints it to the console.

              After reading all the properties of -each file in the archive, the application extracts all the files to the specified -folder using the CZipFile::GetInputStreamL() method.

              Other -than extracting all the files in the archive, the application also searches -for a specific file using the CZipFile::CaseInsensitiveMemberL() method -and extracts it.

              The application also opens the icon.bmp.gz file -and extracts its contents to the specified location. The GZip file is represented -by an object of the CEZGZipToFile class and its contents -are extracted using the CEZGZipToFile::InflateL() method.

              Finally, -the application compresses the error.wav file to a .gz file. -The GZip file being created is represented by an object of the CEZFileToGZip class -and the .wav file is compressed using the CEZFileToGZip::DeflateL() method.

              -
              Class Summary

              CZipFile

              CZipFileMember

              CZipFileMemberIterator

              RZipFileMemberReaderStream

              CEZGZipToFile

              CEZFileToGZip

              -
              Build

              The Symbian build -process describes how to build an application.

              The EzlibExample builds -an executable file called ezlibexample.exe in the standard -location (\epoc32\release\winscw\ <build_variant > -for CodeWarrior). After launching the executable, depending on the emulator -you are using, you may need to navigate using the application launcher or -the eshell screen to view the console.

              + + + + + +EzlibExample: Using EZLIB to Compress and Decompress Files +

              This overview describes the example application that demonstrates +the usage of the EZLIB API.

              +
              Download

              Click on the following link to download the example: EzlibExample.zip

              Click: browse to view the example code.

              +
              Description

              EZLIB is a utility API used to compress and decompress data. +The API is an extension of ZLIB compression library. For more information +on ZLIB compression library, refer to RFC1950.

              This example application uses the EZLIB API to extract +files from a .zip and a .gz file into specified folders, and to compress a .wav file into a .gz file. The application reads +input files and stores the extracted files in c:\private\E80000B7\.

              The application uses an object of the RFs class to open the EzlibZipFolder.zip file. +It reads the properties of each file in the archive using the CZipFileMember object and prints it to the console.

              After reading all the properties of each file in the archive, +the application extracts all the files to the specified folder using +the CZipFile::GetInputStreamL() method.

              Other than extracting all the files in the archive, the application +also searches for a specific file using the CZipFile::CaseInsensitiveMemberL() method and extracts it.

              The application also opens the icon.bmp.gz file and extracts its contents to the specified +location. The GZip file is represented by an object of the CEZGZipToFile class and its contents are extracted using +the CEZGZipToFile::InflateL() method.

              Finally, +the application compresses the error.wav file +to a .gz file. The GZip file being created is +represented by an object of the CEZFileToGZip class +and the .wav file is compressed using the CEZFileToGZip::DeflateL() method.

              +
              Class +Summary
                +

              • CZipFile

                • +

              • CZipFileMember

                • +

              • CZipFileMemberIterator

                • +

              • RZipFileMemberReaderStream

                • +

              • CEZGZipToFile

                • +

              • CEZFileToGZip

                • +
              +
              Build

              The Symbian +build process describes how to build an application.

              The EzlibExample builds an executable file called ezlibexample.exe in the standard location (\epoc32\release\winscw\ <build_variant > for CodeWarrior). After launching +the executable, depending on the emulator you are using, you may need +to navigate using the application launcher or the eshell screen to view the console.

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-95EA435B-918A-4B68-8983-1D22B7840BA7.dita --- a/Symbian3/SDK/Source/GUID-95EA435B-918A-4B68-8983-1D22B7840BA7.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-95EA435B-918A-4B68-8983-1D22B7840BA7.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,21 +1,12 @@ - - - - - -Using -the Camera in Applications -

              The Camera API allows your application to use the device camera to capture -still images and video clips, and store them in the internal memory or on -removable media.

              -

              You can implement applications that make use of the camera to capture images, -record videos, or use the display as a viewfinder.

              -

              To capture images or to record videos, you need a combination of Symbian -APIs and classes, and device-specific components.

              -               \ No newline at end of file + + + + + +ConceptsThis section provides additional information about the Camera. \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9620407B-0560-5D95-A862-5AE406C48983-GENID-1-8-1-3-1-1-8-1-7-1.dita --- a/Symbian3/SDK/Source/GUID-9620407B-0560-5D95-A862-5AE406C48983-GENID-1-8-1-3-1-1-8-1-7-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,61 +0,0 @@ - - - - - -String -resource reader overview -
              Purpose

              String -Resource Reader is part of the Symbian Text Utilities component. It reads -strings from resource files without using the CCoeEnv instance. -This module is mainly for server usage, where there is a need for reading -resources, but there is no CCoeEnv instance -present.

              -
              Architectural -Relationships

              The key relationships between String Resource Reader -and the components in its environment are shown below. It uses the RResourceFile class to access -the actual resource files.

              - String Resource Reader environment - -

              String Resource Reader consists of one class, CTulStringResourceReader. -String Resource Reader uses BaflUtils and RResourceFile.

              - Class diagram - -
              -
              Description

              Usage

              String -Resource Reader is designed to load strings from normal resource files. The -interface can be accessed through the tulstringresourcereader.h file

                -

              • 1. The user must first -create an instance of the CTulStringResourceReader class -using one of the factory methods NewL() or NewLC().

                • -

              • 2. The user can then -call the exported ReadResourceString() method -to read resources

                • -

              • 3. After usage the created -instance must be deleted.

                • -

              If the resource file that is given to a constructor is not found, -the constructor leaves. The standard Symbian platform error codes are used.

              Example

              An -example of using the interface is given below:

              #include <tulstringresourcereader.h> -#include <errorres.rsg> // Resource to be read header - -//... -TFileName myFileName( _L("z:\\system\\data\\errorres.rsc") ); -TulTextResourceUtils* test = TulTextResourceUtils::NewL( myFileName ); - -TPtrC buf; -buf.Set(test-> ReadResourceString(R_ERROR_RES_GENERAL)); - -// Note that buf will only be valid as long as TulTextResourceUtils -// instance is alive and no new string is read by the same instance. -// If you need to read multiple strings, make copies. - -delete test; -

              For more information on individual methods, see the reference -API for CTulStringResourceReader.

              -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9620407B-0560-5D95-A862-5AE406C48983-GENID-1-8-1-6-1-1-4-1-7-1-7-1.dita --- a/Symbian3/SDK/Source/GUID-9620407B-0560-5D95-A862-5AE406C48983-GENID-1-8-1-6-1-1-4-1-7-1-7-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,61 +0,0 @@ - - - - - -String -resource reader overview -
              Purpose

              String -Resource Reader is part of the Symbian Text Utilities component. It reads -strings from resource files without using the CCoeEnv instance. -This module is mainly for server usage, where there is a need for reading -resources, but there is no CCoeEnv instance -present.

              -
              Architectural -Relationships

              The key relationships between String Resource Reader -and the components in its environment are shown below. It uses the RResourceFile class to access -the actual resource files.

              - String Resource Reader environment - -

              String Resource Reader consists of one class, CTulStringResourceReader. -String Resource Reader uses BaflUtils and RResourceFile.

              - Class diagram - -
              -
              Description

              Usage

              String -Resource Reader is designed to load strings from normal resource files. The -interface can be accessed through the tulstringresourcereader.h file

                -

              • 1. The user must first -create an instance of the CTulStringResourceReader class -using one of the factory methods NewL() or NewLC().

                • -

              • 2. The user can then -call the exported ReadResourceString() method -to read resources

                • -

              • 3. After usage the created -instance must be deleted.

                • -

              If the resource file that is given to a constructor is not found, -the constructor leaves. The standard Symbian platform error codes are used.

              Example

              An -example of using the interface is given below:

              #include <tulstringresourcereader.h> -#include <errorres.rsg> // Resource to be read header - -//... -TFileName myFileName( _L("z:\\system\\data\\errorres.rsc") ); -TulTextResourceUtils* test = TulTextResourceUtils::NewL( myFileName ); - -TPtrC buf; -buf.Set(test-> ReadResourceString(R_ERROR_RES_GENERAL)); - -// Note that buf will only be valid as long as TulTextResourceUtils -// instance is alive and no new string is read by the same instance. -// If you need to read multiple strings, make copies. - -delete test; -

              For more information on individual methods, see the reference -API for CTulStringResourceReader.

              -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9620407B-0560-5D95-A862-5AE406C48983.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-9620407B-0560-5D95-A862-5AE406C48983.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,61 @@ + + + + + +String +resource reader overview +
              Purpose

              String +Resource Reader is part of the Symbian Text Utilities component. It reads +strings from resource files without using the CCoeEnv instance. +This module is mainly for server usage, where there is a need for reading +resources, but there is no CCoeEnv instance +present.

              +
              Architectural +Relationships

              The key relationships between String Resource Reader +and the components in its environment are shown below. It uses the RResourceFile class to access +the actual resource files.

              + String Resource Reader environment + +

              String Resource Reader consists of one class, CTulStringResourceReader. +String Resource Reader uses BaflUtils and RResourceFile.

              + Class diagram + +
              +
              Description

              Usage

              String +Resource Reader is designed to load strings from normal resource files. The +interface can be accessed through the tulstringresourcereader.h file

                +

              • 1. The user must first +create an instance of the CTulStringResourceReader class +using one of the factory methods NewL() or NewLC().

                • +

              • 2. The user can then +call the exported ReadResourceString() method +to read resources

                • +

              • 3. After usage the created +instance must be deleted.

                • +

              If the resource file that is given to a constructor is not found, +the constructor leaves. The standard Symbian platform error codes are used.

              Example

              An +example of using the interface is given below:

              #include <tulstringresourcereader.h> +#include <errorres.rsg> // Resource to be read header + +//... +TFileName myFileName( _L("z:\\system\\data\\errorres.rsc") ); +TulTextResourceUtils* test = TulTextResourceUtils::NewL( myFileName ); + +TPtrC buf; +buf.Set(test-> ReadResourceString(R_ERROR_RES_GENERAL)); + +// Note that buf will only be valid as long as TulTextResourceUtils +// instance is alive and no new string is read by the same instance. +// If you need to read multiple strings, make copies. + +delete test; +

              For more information on individual methods, see the reference +API for CTulStringResourceReader.

              +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9665C072-EA52-54B8-87A3-A7F818940DCD.dita --- a/Symbian3/SDK/Source/GUID-9665C072-EA52-54B8-87A3-A7F818940DCD.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-9665C072-EA52-54B8-87A3-A7F818940DCD.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,39 +1,39 @@ - - - - - -What -is the CommsDat APIThis topic is an intrdouction to the CommsDat API. Tools and applications -use the CommsDat API to access the data in the Comms Database. -

              The CommsDat DLL implements the CommsDat API. Symbian platform -loads the CommsDat DLL at boot time. Tools and applications do not load the -DLL.

              -

              The API made available by the CommsDat DLL is the only method that users -can use to access the data in the Comms Database. The API maps between client-side -representations of the data and the data stored in the database.

              -

              Tools and applications see the data as a set of tables. A table is a set -of records, where each record is an ordered set of fields. Each field holds -a specified piece of information. A field at a given position in a record -contains the same type of data in all records. You can consider that each -field at a given location in a record is in a column. A table can also be -called a record set.

              - - - -

              Tables, records, columns and fields are all CommsDat elements. An element -is an item that can be stored in the Comms Database.

              -

              The CommsDat API gives tools and applications a set of classes to retrieve, -create and change the elements in the Comms Database. The API also gives the -functionality to access the Comms Database.

              -

              -               -How is the - Comms Database secured + + + + + +What +is the CommsDat APIThis topic is an intrdouction to the CommsDat API. Tools and applications +use the CommsDat API to access the data in the Comms Database. +

              The CommsDat DLL implements the CommsDat API. Symbian platform +loads the CommsDat DLL at boot time. Tools and applications do not load the +DLL.

              +

              The API made available by the CommsDat DLL is the only method that users +can use to access the data in the Comms Database. The API maps between client-side +representations of the data and the data stored in the database.

              +

              Tools and applications see the data as a set of tables. A table is a set +of records, where each record is an ordered set of fields. Each field holds +a specified piece of information. A field at a given position in a record +contains the same type of data in all records. You can consider that each +field at a given location in a record is in a column. A table can also be +called a record set.

              + + + +

              Tables, records, columns and fields are all CommsDat elements. An element +is an item that can be stored in the Comms Database.

              +

              The CommsDat API gives tools and applications a set of classes to retrieve, +create and change the elements in the Comms Database. The API also gives the +functionality to access the Comms Database.

              +

              +               +How is the + Comms Database secured               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-967F99EC-0C6E-468F-BB2D-C175C7F69B67_d0e3380_href.png Binary file Symbian3/SDK/Source/GUID-967F99EC-0C6E-468F-BB2D-C175C7F69B67_d0e3380_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-967F99EC-0C6E-468F-BB2D-C175C7F69B67_d0e4655_href.png Binary file Symbian3/SDK/Source/GUID-967F99EC-0C6E-468F-BB2D-C175C7F69B67_d0e4655_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-96BCE05D-2984-4A85-9633-69ECE5BE945E.dita --- a/Symbian3/SDK/Source/GUID-96BCE05D-2984-4A85-9633-69ECE5BE945E.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-96BCE05D-2984-4A85-9633-69ECE5BE945E.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,20 +1,20 @@ - - - - - -Soft -indicators -

              Soft indicators are textual indicators displayed in the main pane of the -Idle state. Examples of cases where a soft indicator can be used are call -charges indication and MCN (Micro-Cellular Network) area indication.

              -
              Using -soft indicators in C++ applications

              The soft indicators -are not accessible to applications.

              + + + + + +Soft +indicators +

              Soft indicators are textual indicators displayed in the main pane of the +homescreen. Examples of cases where a soft indicator can be used +are call charges indication and MCN (Micro-Cellular Network) area indication.

              +
              Using +soft indicators in applications

              The soft indicators are not accessible +to applications.

               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-96E46D0E-1CE3-58B4-AE99-6B2E622ADAF9.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-96E46D0E-1CE3-58B4-AE99-6B2E622ADAF9.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,66 @@ + + + + + +Transparent: Drawing Transparent Windows +
              Download

              Click on the following link to download the example: Transparent.zip

              Click: browse to view the example code.

              +
              Description

              This example application demonstrates how to implement the following:

                +

              • creating transparent, +non-transparent and blank windows,

                • +

              • changing the +transparency of a window,

                • +

              • drawing content +on a window.

                • +

              Creating transparent windows

              This example +creates a background and a foreground window using the RWindow class. The CPeriodic class triggers periodic +redraws on the window. The following functions are used to re-draw +content on the window:

                +

              • RWindow::Invalidate(const +TRect &)

                • +

              • RWindow::BeginRedraw()

                • +

              • RWindow::EndRedraw()

                • +

              • CWindowGc::Activate(RDrawableWindow +&)

                • +

              The transparency of the foreground window is changed using +the following functions:

                +

              • RWindow::SetTransparencyAlphaChannel(): this function enables the use of an alpha channel to vary a window's +transparency. The alpha value can be varied from 0 (fully transparent) +to 255 (fully opaque).

                • +

              • RWindow::SetTransparentRegion(const +TRegion&): this function restricts the transparency +to a specified region of the window.

                • +

              Handling window server events

              The user-defined class CEventHandler handles +pointer events when transparent areas of the window are clicked by +the pointer device. An appropriate message is displayed when a click event is detected.

              +
              Build

              The Symbian +build process describes how to build this example.

              The Transparent example builds an executable called transparent.exe in the standard location (\epoc32\release\winscw\<build_variant> for Carbide.c++).

              +
              Running +the example

              The example creates three windows:

                +

              • One background +window with height equal to the full emulator screen and width of +half the emulator screen. The "Background Window" label is set for +this window.

                • +

              • Two foreground +windows each half the size of the background window are used to demonstrate +the change in transparency . These windows can be identified by their +labels.

                • +

              1. Press the VaryTransparency button +located at the bottom of the window to vary the first foreground window's +transparency. The alpha value varies gradually from 0 to 255. This +demonstrates calling the RWindow::SetTransparencyAlphaChannel() API.

              2. Press the SetTransparent button +to call RWindow::SetTransparentRegion(const TRegion&) on the bottom half of the second foreground window. This makes that +half of the window transparent while the upper half stays opaque.

              3. Click different mouse buttons to display the various popup +messages

              +
              Related +information
                +

              • Transparent +Windows

                • +
              +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-971C9B81-1D6F-59E7-9416-385A0787D642-GENID-1-8-1-3-1-1-7-1-8-1-3-1.dita --- a/Symbian3/SDK/Source/GUID-971C9B81-1D6F-59E7-9416-385A0787D642-GENID-1-8-1-3-1-1-7-1-8-1-3-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,65 +0,0 @@ - - - - - -The -control stack -

              The control stack is a mechanism provided by the control framework for -handling key press events. The Window Server, which generates events for control -framework applications, channels all key press events to the application that -currently has keyboard focus (Strictly speaking it channels key press events -to the window group ). It is up to the application itself -to channel the event to the correct destination as the Window Server does -not associate a key press event with a particular control.

              -

              In control framework applications using the standard app - UI the control stack contains a list of controls that wish to -receive keyboard events. Controls are added to the stack using CCoeAppUi::AddToStackL() and -their ordering on the stack determines their priority in receiving key events: -The one with the lowest position on the stack receiving key events first. -When a key press event occurs, it is offered to each control on the stack -in turn until it is consumed (i.e. used by that control).

              -

              The ordering of controls on the stack is determined by their priority, -a value passed to CCoeAppUi::AddToStackL(). If several controls -on the stack have the same priority, their ordering is determined by the order -in which they were added to the stack.

              -enum - { - ECoeStackPriorityDefault=0, // Low Priority - ECoeStackPriorityMenu=10, - ECoeStackPriorityDialog=50, - ECoeStackPriorityCba=60, - ECoeStackPriorityAlert=200, - ECoeStackPriorityFep=250, - ECoeStackPriorityEnvironmentFilter=300 // High Priority - }; - -

              The diagram below shows a hypothetical stack containing 4 controls added -in the following order: control A (priority ECoeStackPriorityDialog), -control B (ECoeStackPriorityMenu), control C (ECoeStackPriorityDefault — -used for application views) and control D (ECoeStackPriorityDialog).

              - - Example showing the order and priority of controls on the -control stack - - -

              On the stack shown in the diagram key-press events will be offered first -to control D, followed by A, B and C in that order. A control on the stack -can refuse key press events by setting a flag. This might be done by a dialogs -when it is not visible.

              -

              Applications use the control stack to channel key press events to destinations -in decreasing order of priority, such as:

              -
                -

              • debug keys

                • -

              • any active dialog

                • -

              • any menu bar (i.e., -its hot-keys)

                • -

              • the application view

                • -
              -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-971C9B81-1D6F-59E7-9416-385A0787D642-GENID-1-8-1-6-1-1-4-1-6-1-8-1-3-1.dita --- a/Symbian3/SDK/Source/GUID-971C9B81-1D6F-59E7-9416-385A0787D642-GENID-1-8-1-6-1-1-4-1-6-1-8-1-3-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,65 +0,0 @@ - - - - - -The -control stack -

              The control stack is a mechanism provided by the control framework for -handling key press events. The Window Server, which generates events for control -framework applications, channels all key press events to the application that -currently has keyboard focus (Strictly speaking it channels key press events -to the window group ). It is up to the application itself -to channel the event to the correct destination as the Window Server does -not associate a key press event with a particular control.

              -

              In control framework applications using the standard app - UI the control stack contains a list of controls that wish to -receive keyboard events. Controls are added to the stack using CCoeAppUi::AddToStackL() and -their ordering on the stack determines their priority in receiving key events: -The one with the lowest position on the stack receiving key events first. -When a key press event occurs, it is offered to each control on the stack -in turn until it is consumed (i.e. used by that control).

              -

              The ordering of controls on the stack is determined by their priority, -a value passed to CCoeAppUi::AddToStackL(). If several controls -on the stack have the same priority, their ordering is determined by the order -in which they were added to the stack.

              -enum - { - ECoeStackPriorityDefault=0, // Low Priority - ECoeStackPriorityMenu=10, - ECoeStackPriorityDialog=50, - ECoeStackPriorityCba=60, - ECoeStackPriorityAlert=200, - ECoeStackPriorityFep=250, - ECoeStackPriorityEnvironmentFilter=300 // High Priority - }; - -

              The diagram below shows a hypothetical stack containing 4 controls added -in the following order: control A (priority ECoeStackPriorityDialog), -control B (ECoeStackPriorityMenu), control C (ECoeStackPriorityDefault — -used for application views) and control D (ECoeStackPriorityDialog).

              - - Example showing the order and priority of controls on the -control stack - - -

              On the stack shown in the diagram key-press events will be offered first -to control D, followed by A, B and C in that order. A control on the stack -can refuse key press events by setting a flag. This might be done by a dialogs -when it is not visible.

              -

              Applications use the control stack to channel key press events to destinations -in decreasing order of priority, such as:

              -
                -

              • debug keys

                • -

              • any active dialog

                • -

              • any menu bar (i.e., -its hot-keys)

                • -

              • the application view

                • -
              -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-971C9B81-1D6F-59E7-9416-385A0787D642.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-971C9B81-1D6F-59E7-9416-385A0787D642.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,65 @@ + + + + + +The +control stack +

              The control stack is a mechanism provided by the control framework for +handling key press events. The Window Server, which generates events for control +framework applications, channels all key press events to the application that +currently has keyboard focus (Strictly speaking it channels key press events +to the window group ). It is up to the application itself +to channel the event to the correct destination as the Window Server does +not associate a key press event with a particular control.

              +

              In control framework applications using the standard app + UI the control stack contains a list of controls that wish to +receive keyboard events. Controls are added to the stack using CCoeAppUi::AddToStackL() and +their ordering on the stack determines their priority in receiving key events: +The one with the lowest position on the stack receiving key events first. +When a key press event occurs, it is offered to each control on the stack +in turn until it is consumed (i.e. used by that control).

              +

              The ordering of controls on the stack is determined by their priority, +a value passed to CCoeAppUi::AddToStackL(). If several controls +on the stack have the same priority, their ordering is determined by the order +in which they were added to the stack.

              +enum + { + ECoeStackPriorityDefault=0, // Low Priority + ECoeStackPriorityMenu=10, + ECoeStackPriorityDialog=50, + ECoeStackPriorityCba=60, + ECoeStackPriorityAlert=200, + ECoeStackPriorityFep=250, + ECoeStackPriorityEnvironmentFilter=300 // High Priority + }; + +

              The diagram below shows a hypothetical stack containing 4 controls added +in the following order: control A (priority ECoeStackPriorityDialog), +control B (ECoeStackPriorityMenu), control C (ECoeStackPriorityDefault — +used for application views) and control D (ECoeStackPriorityDialog).

              + + Example showing the order and priority of controls on the +control stack + + +

              On the stack shown in the diagram key-press events will be offered first +to control D, followed by A, B and C in that order. A control on the stack +can refuse key press events by setting a flag. This might be done by a dialogs +when it is not visible.

              +

              Applications use the control stack to channel key press events to destinations +in decreasing order of priority, such as:

              +
                +

              • debug keys

                • +

              • any active dialog

                • +

              • any menu bar (i.e., +its hot-keys)

                • +

              • the application view

                • +
              +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-97545AEB-0518-5937-AEB6-C97443B449D3_d0e270252_href.jpg Binary file Symbian3/SDK/Source/GUID-97545AEB-0518-5937-AEB6-C97443B449D3_d0e270252_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-97545AEB-0518-5937-AEB6-C97443B449D3_d0e273960_href.jpg Binary file Symbian3/SDK/Source/GUID-97545AEB-0518-5937-AEB6-C97443B449D3_d0e273960_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-975CBC70-81E6-5FA2-80CE-88DD2ABE9595.dita --- a/Symbian3/SDK/Source/GUID-975CBC70-81E6-5FA2-80CE-88DD2ABE9595.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-975CBC70-81E6-5FA2-80CE-88DD2ABE9595.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,25 +1,25 @@ - - - - - -Graphics Guide -

              Find everything you need to know about the Symbian Graphics package in -this section.

              -

              The graphics documentation is organized around the collections and components -in the Graphics package in the Symbian System Model.

              - - -The collections and components in the Graphics package - - - -

              The following list gives links to high-level Graphics topics and the collections -that make up the Graphics package:

              + + + + + +Graphics Guide +

              Find everything you need to know about the Symbian Graphics package in +this section.

              +

              The graphics documentation is organized around the collections and components +in the Graphics package in the Symbian System Model.

              + + +The collections and components in the Graphics package + + + +

              The following list gives links to high-level Graphics topics and the collections +that make up the Graphics package:

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9770F3B4-998D-474F-9A82-1B134A4C2869_d0e294365_href.png Binary file Symbian3/SDK/Source/GUID-9770F3B4-998D-474F-9A82-1B134A4C2869_d0e294365_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-97712509-84AD-462F-8FFB-E1E6D8278938.dita --- a/Symbian3/SDK/Source/GUID-97712509-84AD-462F-8FFB-E1E6D8278938.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-97712509-84AD-462F-8FFB-E1E6D8278938.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,46 +1,46 @@ - - - - - -Enabling -touch support for buttons -

              To use a touch-enabled button in your application, implement the following -use cases:

              -
                -

              • Creating generic -button

                • -

              • Setting button -properties not specific to any state

                • -

              • Using button -states

                • -

              • Setting properties -for button states

                • -

              • Handling button -events

                • -
              -

              We need to provide more clarity -on the required order of implementing the use cases and clarify whether there -are alternative approaches for achieving the same results.

              -

              The following use cases are optional, allowing you to set additional properties -for your button:

              -
                -

              • Using long-tap -events

                • -

              • Using skin support -in buttons

                • -
              -
              Implementation file

              The implementation file for -the Generic button API is aknbutton.h.

              -               -Generic button -API description -Look and -feel guidelines for the generic button in a toolbar + + + + + +Enabling +touch support for buttons +

              To use a touch-enabled button in your application, implement the following +use cases:

              +
                +

              • Creating generic +button

                • +

              • Setting button +properties not specific to any state

                • +

              • Using button +states

                • +

              • Setting properties +for button states

                • +

              • Handling button +events

                • +
              +

              We need to provide more clarity +on the required order of implementing the use cases and clarify whether there +are alternative approaches for achieving the same results.

              +

              The following use cases are optional, allowing you to set additional properties +for your button:

              +
                +

              • Using long-tap +events

                • +

              • Using skin support +in buttons

                • +
              +
              Implementation +file

              The implementation file for the Generic button API is aknbutton.h.

              +               +Generic button +API description +Look and +feel guidelines for the generic button in a toolbar               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-979D7C71-A61A-5A49-AF67-8BB9CF67AFF0.dita --- a/Symbian3/SDK/Source/GUID-979D7C71-A61A-5A49-AF67-8BB9CF67AFF0.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-979D7C71-A61A-5A49-AF67-8BB9CF67AFF0.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,14 +1,14 @@ - - - - - -Bluetooth Manager OverviewThe Bluetooth Manager component provides non-volatile storage of details of Bluetooth devices in the Bluetooth Registry.
              Purpose

              The Bluetooth Manager enables you to store details of devices in the Bluetooth Registry. It also enables you to retrieve, modify and delete the information about devices.

              Key concepts and terms

              Documentation on the Bluetooth Manager component uses the following key concepts and terms:

              Cookie

              Stored data that can be used by the UI whenever it is needed.

              EIR (Extended Inquiry Response)

              Information that is supplied by the host and transmitted in the inquiry responses sub-state.

              'Bonded' settings

              Details of peer devices with which a device has formed secure relationships in the past.

              'Last used' settings

              Details of when devices were last connected.

              Architecture

              - Diagram showing Bluetooth Manager relationships -
              Bluetooth Manager summary

              The Bluetooth Manager component provides the following:

              • BT Device

                btdevice.dll

                Provides a mechanism for discovering, setting and retreiving information about the various properties of a Bluetooth device.

              • BT Manager Client

                btmanclient.dll

                Provides access to the Bluetooth Manager server.

              • BT Manager Server

                btmanserver.exe

                Provides access to the Bluetooth Registry.

              • EIR Client

                eirclient.dll

                Provides ways of publishing information over the Bluetooth EIR mechanism.

              \ No newline at end of file + + + + + +Bluetooth Manager OverviewThe Bluetooth Manager component provides non-volatile storage of details of Bluetooth devices in the Bluetooth Registry.
              Purpose

              The Bluetooth Manager enables you to store details of devices in the Bluetooth Registry. It also enables you to retrieve, modify and delete the information about devices.

              Key concepts and terms

              Documentation on the Bluetooth Manager component uses the following key concepts and terms:

              Cookie

              Stored data that can be used by the UI whenever it is needed.

              EIR (Extended Inquiry Response)

              Information that is supplied by the host and transmitted in the inquiry responses sub-state.

              'Bonded' settings

              Details of peer devices with which a device has formed secure relationships in the past.

              'Last used' settings

              Details of when devices were last connected.

              Architecture

              + Diagram showing Bluetooth Manager relationships +
              Bluetooth Manager summary

              The Bluetooth Manager component provides the following:

              • BT Device

                btdevice.dll

                Provides a mechanism for discovering, setting and retreiving information about the various properties of a Bluetooth device.

              • BT Manager Client

                btmanclient.dll

                Provides access to the Bluetooth Manager server.

              • BT Manager Server

                btmanserver.exe

                Provides access to the Bluetooth Registry.

              • EIR Client

                eirclient.dll

                Provides ways of publishing information over the Bluetooth EIR mechanism.

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-97ACFC53-4B55-5880-988D-7C376D8AFB16.dita --- a/Symbian3/SDK/Source/GUID-97ACFC53-4B55-5880-988D-7C376D8AFB16.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-97ACFC53-4B55-5880-988D-7C376D8AFB16.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,12 +1,12 @@ - - - - - -Overview

              The Session Description Protocol (SDP) provides the users with a standard representation for media details, transport addresses, and session description metadata. This representation is independent of the method the information is transported. The SDP Codec subsystem enables its clients the SDP Codec API do the following:

              • encode SDP descriptions into an internal form

              • decode the descriptions from an internal form

              • set and get the SDP field values

              Architectural Relationships

              The calls to the SDP Codec API are synchronous. The SDP Codec API does not require capabilities and it cannot be extended.

              SDP Codec API class structure

              The client uses some or all the SDP Codec API classes during the handling of a SDP description. The interface classes are derived from CBase. The client has a 'use' relationship with the SDP Codec API library.

              The following illustration shows the SDP Codec API class structure.

              Memory used

              The amount of memory used by every header object of the SDP Codec API is equivalent to the memory used by the header as text.

              See also

              • Multiparty Multimedia Session Control (mmusic)

              • Real Time Streaming Protocol (RTSP)

              • Integration of Resource Management and Session Initiation Protocol (SIP)

              • Grouping of Media Lines in the Session Description Protocol (SDP)

              • An Offer/Answer Model with the Session Description Protocol (SDP)

              \ No newline at end of file + + + + + +Overview

              The Session Description Protocol (SDP) provides the users with a standard representation for media details, transport addresses, and session description metadata. This representation is independent of the method the information is transported. The SDP Codec subsystem enables its clients the SDP Codec API do the following:

              • encode SDP descriptions into an internal form

              • decode the descriptions from an internal form

              • set and get the SDP field values

              Architectural Relationships

              The calls to the SDP Codec API are synchronous. The SDP Codec API does not require capabilities and it cannot be extended.

              SDP Codec API class structure

              The client uses some or all the SDP Codec API classes during the handling of a SDP description. The interface classes are derived from CBase. The client has a 'use' relationship with the SDP Codec API library.

              The following illustration shows the SDP Codec API class structure.

              Memory used

              The amount of memory used by every header object of the SDP Codec API is equivalent to the memory used by the header as text.

              See also

              • Multiparty Multimedia Session Control (mmusic)

              • Real Time Streaming Protocol (RTSP)

              • Integration of Resource Management and Session Initiation Protocol (SIP)

              • Grouping of Media Lines in the Session Description Protocol (SDP)

              • An Offer/Answer Model with the Session Description Protocol (SDP)

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-97C9A782-A7DE-480B-9DE0-97B213AAEDD0.dita --- a/Symbian3/SDK/Source/GUID-97C9A782-A7DE-480B-9DE0-97B213AAEDD0.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-97C9A782-A7DE-480B-9DE0-97B213AAEDD0.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,68 +1,68 @@ - - - - - -Query -input -

              Query input is a component for displaying data query with direct possibility -to touch input and uses the full screen. It is a standalone component from -input methods and thus user cannot change the input method from the Query -input.

              -

              In addition to data query content, it has Backspace button and ITU-T keypad -buttons. Softkeys are also displayed as buttons next to the editor, instead -of Control pane. This component is used for (PIN, PUK, time and date) queries -in start-up, and also in password editors.

              -

              Prompt text can be displayed in three lines, for example, “PIN code blocked” -and “Enter PIN code”, and is always aligned close to input field.

              - -Example of alpha-numeric input mode in portrait and landscape. - - -

              If only number entry is enabled, the Query input displays number buttons.

              - -Example of numeric input mode in portrait and landscape. - - -

              In other data queries, the touch input is opened with touch down and release -to the editor. In query input, the input is instantly available for immediate -usage. Some buttons may be dimmed if needed. Both portrait and landscape orientations -are available for Query input.

              -

              Tactile feedback follows the virtual ITU-T feedback.

              -

              The following table lists the default touch events for query input:

              -The default touch -events for query input - - - - - - -

              User action

               -

              State change

               -

              Feedback

               -               - - - -

              Touch down and release on SK1 §key_SK1_softkey§

               -

              Confirms the query.

              It is initially dimmed and changed active -when first character is entered.

               -

              Tactile: Basic button effect and audio feedback are provided with -touch down and basic button effect with release events.

               -               - -

              Touch down and release on SK2 §key_SK2_softkey§

               -

              Cancels the query.

               -

              Tactile: Basic button effect and audio feedback are provided with -touch down and basic button effect with release events.

               -               - - + + + + + +Query +input +

              Query input is a full screen component for displaying data query with direct +possibility for touch input. It uses the full screen. It is a standalone component +from input methods and thus user cannot change the input method from the Query +input.

              +

              In addition to data query content, it has Backspace button and ITU-T keypad +buttons. Softkeys are also displayed as buttons next to the editor, instead +of Control pane. This component is used for (PIN, PUK, time and date) queries +in start-up, and also in password editors.

              +

              Prompt text can be displayed in three lines, for example, “PIN code blocked” +and “Enter PIN code”, and is always aligned close to input field.

              + +Example of alpha-numeric input mode in portrait and landscape. + + +

              If only number entry is enabled, the Query input displays number buttons.

              + +Example of numeric input mode in portrait and landscape. + + +

              In other data queries, the touch input is opened with touch down and release +to the editor. In query input, the input is instantly available for immediate +usage. Some buttons may be dimmed if needed. Both portrait and landscape orientations +are available for Query input.

              +

              Tactile feedback follows the virtual ITU-T feedback.

              +

              The following table lists the default touch events for query input:

              +
              The default touch +events for query input + + + + + + +

              User action

               +

              State change

               +

              Feedback

               +               + + + +

              Touch down and release on left softkey.

               +

              Confirms the query.

              It is initially dimmed and changed active +when first character is entered.

               +

              Tactile: Basic button effect and audio feedback are provided with +touch down and basic button effect with release events.

               +               + +

              Touch down and release on right softkey.

               +

              Cancels the query.

               +

              Tactile: Basic button effect and audio feedback are provided with +touch down and basic button effect with release events.

               +               + +
               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-97F216EE-B7EA-4A8A-A038-83E1548AE254.dita --- a/Symbian3/SDK/Source/GUID-97F216EE-B7EA-4A8A-A038-83E1548AE254.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-97F216EE-B7EA-4A8A-A038-83E1548AE254.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,21 +1,24 @@ - - - - - -List -stretchList stretching is commonly used in lists (that have two lines) -viewed in landscape mode. -

              This also includes the settings list and lists with icons. By default, -list stretching is ON. Applications can turn it off if needed.

              - -Example image of list stretch - - + + + + + +List +stretchList stretching is commonly used in lists (that have two lines) +viewed in landscape mode. +

              This also includes the settings list and lists with icons. By default, +list stretching is ON. Applications can turn it OFF if needed.

              +

              The list stretching can be turned ON or OFF using KAknAutomaticListStretching. +The possible values of KAknAutomaticListStretching are 0 (list +stretching OFF) and 1 (list stretching ON).

              + +Example image of list stretch + +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-983C5DB9-85EF-541E-B494-19E3E617914A.dita --- a/Symbian3/SDK/Source/GUID-983C5DB9-85EF-541E-B494-19E3E617914A.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-983C5DB9-85EF-541E-B494-19E3E617914A.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,44 +1,44 @@ - - - - - -Introduction -to embedded stores Data contained in a stream can represent a store in its own right -rather than just objects. Such a store is known as an embedded store. -

              The stream containing the embedded store is known as the host stream.

              -

              It is often convenient, and sometimes necessary, to collect the streams -representing a partial object network into an embedded store. This makes it -easier for the streams representing such a partial object network to be deleted, -by deleting (from the top level store) the stream containing the embedded -store.

              -

              The alternative is to traverse the individual streams representing the -partial object network and deleting them in the correct sequence; this can -be difficult.

              -

              The following diagram shows the idea:

              - -Embedded store within stream - - -

              An embedded store can contain an arbitrarily complex network of streams. -As well as being easy to delete, this stream network can also be copied by -simply copying the host stream from the containing store.

              -

              Embedded stores are persistent stores.

              -

              The embedded store is constructed on a write stream in its containing store -and, for writing, the embedded store behaves like a direct file store — once -streams within the embedded store have been committed and closed, they cannot -subsequently be changed, i.e. streams cannot be replaced, deleted, extended -or changed in any way.

              -

              Embedded stores are used for object embedding by the application architecture. -Because the embedded store behaves like a direct file store, only document -types with direct representations can be embedded. In particular, documents -using permanent-type stores, such as the database or the agenda, cannot be -embedded. Such documents may, however, contain any type of embeddable document.

              -
              See also

              File stores

              Direct file store

              + + + + + +Introduction +to embedded stores Data contained in a stream can represent a store in its own right +rather than just objects. Such a store is known as an embedded store. +

              The stream containing the embedded store is known as the host stream.

              +

              It is often convenient, and sometimes necessary, to collect the streams +representing a partial object network into an embedded store. This makes it +easier for the streams representing such a partial object network to be deleted, +by deleting (from the top level store) the stream containing the embedded +store.

              +

              The alternative is to traverse the individual streams representing the +partial object network and deleting them in the correct sequence; this can +be difficult.

              +

              The following diagram shows the idea:

              + +Embedded store within stream + + +

              An embedded store can contain an arbitrarily complex network of streams. +As well as being easy to delete, this stream network can also be copied by +simply copying the host stream from the containing store.

              +

              Embedded stores are persistent stores.

              +

              The embedded store is constructed on a write stream in its containing store +and, for writing, the embedded store behaves like a direct file store — once +streams within the embedded store have been committed and closed, they cannot +subsequently be changed, i.e. streams cannot be replaced, deleted, extended +or changed in any way.

              +

              Embedded stores are used for object embedding by the application architecture. +Because the embedded store behaves like a direct file store, only document +types with direct representations can be embedded. In particular, documents +using permanent-type stores, such as the database or the agenda, cannot be +embedded. Such documents may, however, contain any type of embeddable document.

              +
              See also

              File stores

              Direct file store

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9901F6E2-0D36-59D6-A32A-D666C4F2DAAF_d0e76851_href.png Binary file Symbian3/SDK/Source/GUID-9901F6E2-0D36-59D6-A32A-D666C4F2DAAF_d0e76851_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9901F6E2-0D36-59D6-A32A-D666C4F2DAAF_d0e83563_href.png Binary file Symbian3/SDK/Source/GUID-9901F6E2-0D36-59D6-A32A-D666C4F2DAAF_d0e83563_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-993629CB-17B4-5E87-8DE1-06A4AC473FDD.dita --- a/Symbian3/SDK/Source/GUID-993629CB-17B4-5E87-8DE1-06A4AC473FDD.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-993629CB-17B4-5E87-8DE1-06A4AC473FDD.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,14 +1,14 @@ - - - - - -RTP overview
              Purpose

              The Multimedia Protocols RTP (Real-Time Transport Protocol) component provides RTP communication services. This overview shows the usage of the RTP/RTCP protocol as defined in RFC 3550.

              Required background

              The clients that make use of this API need to be familiar with RFC 3550 standard.

              Key concepts

              The component has the following key concepts:

              RTP

              RTP provides end-to-end network transport services for data with real-time characteristics, such as interactive audio and video. It is built on top of the User Datagram Protocol (UDP).

              RTP contains two closely linked parts:

              • RTP: Real-Time Transport Protocol to carry data that has real-time properties.

              • RTCP: RTP Control Protocol to provide feedback on the quality of service being provided by RTP.

              RTCP

              RTP Control Protocol used to provide feedback on the quality of service being provided by RTP. RTP and RTCP support transmission of the data and the control packets.

              Architectural Relationship

              The RTP component of MM-protocols uses the following:

              • Comms-infras ESOCK 

              • Networking INSOCK

              API summary

              The following are some of the main classes used for RTP communication.

              Class Name Description

              RRtpSession

              A handle to an RTP session that abstracts all RTP information going to and from an RTP socket, and its corresponding RTCP data.

              RRtpPacket

              A handle to an RTP packet used to access the packet through the interface provided by this handle.

              RRtpSendPacket

              Derived from RRtpPacket and used as a handle to an RTP send packet.

              RRtpReceivePacket

              Derived from RRtpPacket and used as a handle to an RTP receive packet.

              RRtpReceiveSource

              A handle to a receive stream. An object of this type represents the stream of data on a single SSRC and delivers the RTP packets and RTCP information in the order they arrive.

              RRtpSendSource

              A handle to a send stream, used to manage the creation and sending of packets.

              The following diagram shows the RTP classes and their relationships.

              - Class diagram for RTP classes -
              Typical uses

              Any application requiring RTP as its transport protocol should use this API. RTP provides the following key services:

              • Payload-type identification

              • Sequence numbering

              • Time stamping

              • Delivery monitoring

              The RTP API allows you to perform the following tasks:

              1. Creating and Managing an RTP session

              2. Registering for and handling events

              3. Accessing an RTP packet

              4. Creating a send stream

              5. Sending an RTP packet

              6. Creating receive stream

              7. Sending and receiving non RTP-data

              8. Managing RTCP packets and reports

              9. Managing send and receive reports

              10. Securing RTP with SRTP

              Note: Before using any of these services, a connection to the socket server must have been made and the socket must be open.

              See also

              RTPExample: RTP packet streaming

              \ No newline at end of file + + + + + +RTP overview
              Purpose

              The Multimedia Protocols RTP (Real-Time Transport Protocol) component provides RTP communication services. This overview shows the usage of the RTP/RTCP protocol as defined in RFC 3550.

              Required background

              The clients that make use of this API need to be familiar with RFC 3550 standard.

              Key concepts

              The component has the following key concepts:

              RTP

              RTP provides end-to-end network transport services for data with real-time characteristics, such as interactive audio and video. It is built on top of the User Datagram Protocol (UDP).

              RTP contains two closely linked parts:

              • RTP: Real-Time Transport Protocol to carry data that has real-time properties.

              • RTCP: RTP Control Protocol to provide feedback on the quality of service being provided by RTP.

              RTCP

              RTP Control Protocol used to provide feedback on the quality of service being provided by RTP. RTP and RTCP support transmission of the data and the control packets.

              Architectural Relationship

              The RTP component of MM-protocols uses the following:

              • Comms-infras ESOCK 

              • Networking INSOCK

              API summary

              The following are some of the main classes used for RTP communication.

              Class Name Description

              RRtpSession

              A handle to an RTP session that abstracts all RTP information going to and from an RTP socket, and its corresponding RTCP data.

              RRtpPacket

              A handle to an RTP packet used to access the packet through the interface provided by this handle.

              RRtpSendPacket

              Derived from RRtpPacket and used as a handle to an RTP send packet.

              RRtpReceivePacket

              Derived from RRtpPacket and used as a handle to an RTP receive packet.

              RRtpReceiveSource

              A handle to a receive stream. An object of this type represents the stream of data on a single SSRC and delivers the RTP packets and RTCP information in the order they arrive.

              RRtpSendSource

              A handle to a send stream, used to manage the creation and sending of packets.

              The following diagram shows the RTP classes and their relationships.

              + Class diagram for RTP classes +
              Typical uses

              Any application requiring RTP as its transport protocol should use this API. RTP provides the following key services:

              • Payload-type identification

              • Sequence numbering

              • Time stamping

              • Delivery monitoring

              The RTP API allows you to perform the following tasks:

              1. Creating and Managing an RTP session

              2. Registering for and handling events

              3. Accessing an RTP packet

              4. Creating a send stream

              5. Sending an RTP packet

              6. Creating receive stream

              7. Sending and receiving non RTP-data

              8. Managing RTCP packets and reports

              9. Managing send and receive reports

              10. Securing RTP with SRTP

              Note: Before using any of these services, a connection to the socket server must have been made and the socket must be open.

              See also

              RTPExample: RTP packet streaming

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-993A732B-13F8-48B6-B0C5-7246FA6828DF.dita --- a/Symbian3/SDK/Source/GUID-993A732B-13F8-48B6-B0C5-7246FA6828DF.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-993A732B-13F8-48B6-B0C5-7246FA6828DF.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,37 +1,37 @@ - - - - - -Class -structure for the toolbar API -

              The Toolbar API consists of following classes: CAknToolbar, CAknToolbarExtension, -and MAknToolbarObserver. -The Toolbar API class structure and its simplified environment is described -in the figure below.

              - -Toolbar API class structure - - -

              CAknToolbar is the API main class that provides the most -of the API functionality. The UI framework classes CEikAppUiFactory, CAknView, -and CAknAppUi take care of creating and destructing the CAknToolbar object. -Moreover, you can access the toolbar in your application through these UI -framework classes.

              -

              CAknToolbar is a compound (window-owning) control that -contains simple (non-window-owning) controls that are the toolbar items. Toolbar -items can be for example CAknButton type controls. Each toolbar -can also have one extension that expands the toolbar. The extension contains -also for example CAknButton type controls.

              -

              MAknToolbarObserver is an interface that can be used to -observe toolbar events. The application class can implement this interface -and register itself as the toolbar observer. CAknToolbar then -informs the observer when toolbar events occur (when toolbar is about to be -shown and when some toolbar item state has changed e.g. a button is pressed).

              + + + + + +Class +structure for the toolbar API +

              The Toolbar API consists of following classes: CAknToolbar, CAknToolbarExtension, +and MAknToolbarObserver. +The Toolbar API class structure and its simplified environment is described +in the figure below.

              + +Toolbar API class structure + + +

              CAknToolbar is the API main class that provides the most +of the API functionality. The UI framework classes CEikAppUiFactory, CAknView, +and CAknAppUi take care of creating and destructing the CAknToolbar object. +Moreover, you can access the toolbar in your application through these UI +framework classes.

              +

              CAknToolbar is a compound (window-owning) control that +contains simple (non-window-owning) controls that are the toolbar items. Toolbar +items can be for example CAknButton type controls. Each toolbar +can also have one extension that expands the toolbar. The extension contains +also for example CAknButton type controls.

              +

              MAknToolbarObserver is an interface that can be used to +observe toolbar events. The application class can implement this interface +and register itself as the toolbar observer. CAknToolbar then +informs the observer when toolbar events occur (when toolbar is about to be +shown and when some toolbar item state has changed e.g. a button is pressed).

               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9955D228-75CE-45B3-9714-AF635D04E553-master.png Binary file Symbian3/SDK/Source/GUID-9955D228-75CE-45B3-9714-AF635D04E553-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9955D228-75CE-45B3-9714-AF635D04E553_d0e56643_href.png Binary file Symbian3/SDK/Source/GUID-9955D228-75CE-45B3-9714-AF635D04E553_d0e56643_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9971A0B9-B2D7-59D3-8834-FDDEEC57AC67.dita --- a/Symbian3/SDK/Source/GUID-9971A0B9-B2D7-59D3-8834-FDDEEC57AC67.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-9971A0B9-B2D7-59D3-8834-FDDEEC57AC67.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,12 +1,12 @@ - - - - - -How to use the SIP Profile API
              Protocols

              This section provides the information about the protocol and error handling related to the SIP Profile API:

              • When you create a CSIPProfileRegistry object, the client connects to the shared SIP Profile server. Note: If the server is not running, it is started by the API implementation.

                When the CSIPProfileRegistry object is deleted, the corresponding connection to the server is closed. The server stops if it has no other users.

              • The profile data is transferred from the server to the client when a user retrieves a CSIPProfile object through CSIPProfileRegistry.

                When the client holds an instance of CSIPProfile in its memory, all events related to the corresponding profile use MSIPProfileRegistryObserver callback functions to notify the client. The callback functions are implemented by the client.

                Note: A CSIPProfile object is created each time a profile is retrieved.

              • When the client deletes the CSIPProfile object, the client is not notified about events.

              • The profile must be active before a CSIPProfile object is used by the SIP Client API. Use the MSIPRegistrationContext::IsContextActive() function to check. A profile becomes active when it is enabled by the client and the state of the profile is ERegistered. ERegistered is an enum value of the TSIPProfileState enum defined in the class CSIPProfileAgent.

              • All profiles are automatically registered when they are enabled. If a profile is not registered before being enabled, the registration status change is acknowledged through MSIPProfileRegistryObserver. If the enabled profile is already registered, no additional registration or status change events are sent.

              • When a profile is enabled and registered, the client can use it and the SIP Client API to create SIP sessions. An enabled profile cannot be removed from the system while it is used by the client.

              • When a profile is not needed by the client, it is disabled. When you delete an instance of the profile the profile is disabled.

              The following illustration shows use of the SIP Profile API.

              Error handling

              The errors are indicated by return codes, by functions leaving, or by calling callback functions. If an error occurs during a synchronous operation initiated by the client, the called function leaves with a correct error code.

              If an error occurs during an asynchronous operation, the error is passed to the client through the callback function MSIPProfileRegistryObserver::ProfileRegistryErrorOccurred(). In this case, both the profile identifier and an error code are passed to the client. Any error passed to the client means that the indicated profile is not registered or enabled by the client.

              \ No newline at end of file + + + + + +How to use the SIP Profile API
              Protocols

              This section provides the information about the protocol and error handling related to the SIP Profile API:

              • When you create a CSIPProfileRegistry object, the client connects to the shared SIP Profile server. Note: If the server is not running, it is started by the API implementation.

                When the CSIPProfileRegistry object is deleted, the corresponding connection to the server is closed. The server stops if it has no other users.

              • The profile data is transferred from the server to the client when a user retrieves a CSIPProfile object through CSIPProfileRegistry.

                When the client holds an instance of CSIPProfile in its memory, all events related to the corresponding profile use MSIPProfileRegistryObserver callback functions to notify the client. The callback functions are implemented by the client.

                Note: A CSIPProfile object is created each time a profile is retrieved.

              • When the client deletes the CSIPProfile object, the client is not notified about events.

              • The profile must be active before a CSIPProfile object is used by the SIP Client API. Use the MSIPRegistrationContext::IsContextActive() function to check. A profile becomes active when it is enabled by the client and the state of the profile is ERegistered. ERegistered is an enum value of the TSIPProfileState enum defined in the class CSIPProfileAgent.

              • All profiles are automatically registered when they are enabled. If a profile is not registered before being enabled, the registration status change is acknowledged through MSIPProfileRegistryObserver. If the enabled profile is already registered, no additional registration or status change events are sent.

              • When a profile is enabled and registered, the client can use it and the SIP Client API to create SIP sessions. An enabled profile cannot be removed from the system while it is used by the client.

              • When a profile is not needed by the client, it is disabled. When you delete an instance of the profile the profile is disabled.

              The following illustration shows use of the SIP Profile API.

              Error handling

              The errors are indicated by return codes, by functions leaving, or by calling callback functions. If an error occurs during a synchronous operation initiated by the client, the called function leaves with a correct error code.

              If an error occurs during an asynchronous operation, the error is passed to the client through the callback function MSIPProfileRegistryObserver::ProfileRegistryErrorOccurred(). In this case, both the profile identifier and an error code are passed to the client. Any error passed to the client means that the indicated profile is not registered or enabled by the client.

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-99AC84AE-C4C0-53AA-8984-51AE84EE7651.dita --- a/Symbian3/SDK/Source/GUID-99AC84AE-C4C0-53AA-8984-51AE84EE7651.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-99AC84AE-C4C0-53AA-8984-51AE84EE7651.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,80 +1,80 @@ - - - - - -Overview -
              Purpose

              The File Converter Framework converts data -from one format to another format. For example, HTML files can be converted -to Symbian word documents.

              -
              Architecture

              The File Converter Framework -architecture provides a framework for ECOM plug-ins, called converters, that -can convert data between different formats. When an application requests to -convert data from one format to another format, the framework checks the list -of available converters. If there is a converter that can do the conversion, -then the framework assigns the request to that converter.

              The following -diagram shows the File converter framework architecture.

              - -
              -
              API summary - - - -API -Description - - - - -

              CCnaConverter

              -

              A class that contains the properties of a converter. These are a -UID and the data types that the converter supports.

              -               - -

              CConverterBase

              -

              A class that provides an interface to access the converters.

              -               - -

              CConverterBase2

              -

              A base class for converters.

              -               - -

              CCnaConverterList

              -

              A class that provides a list of available converters. It allows -clients to search for and obtain converters for specific source and target -data types.

              -               - -

              CCnaConvInfoFileReader2

              -

              A class that encapsulates a collection of converter properties, CCnaConverter, -read from a converter information .rsc file.

              -               - -

              CMimeInfo

              -

              A class that contains the localized names for a data type.

              -               - -

              MConverterUiObserver

              -

              An interface implemented by the client of a conversion operation -to observe conversion progress.

              -               - - -
              -
              Typical uses

              Using a converter

              File -Converter Framework provides APIs to list and search for converters. It also -provides an observer interface through which the progress and success or failure -of the conversion can be reported. For more information, see Using -a converter.

              Writing a converter

              File Converter -Framework specifies a plug-in interface for converters. For more information, -see Writing a Converter.

              -               -File Converter -Tutorials + + + + + +Overview +
              Purpose

              The File Converter Framework converts data +from one format to another format. For example, HTML files can be converted +to Symbian word documents.

              +
              Architecture

              The File Converter Framework +architecture provides a framework for ECOM plug-ins, called converters, that +can convert data between different formats. When an application requests to +convert data from one format to another format, the framework checks the list +of available converters. If there is a converter that can do the conversion, +then the framework assigns the request to that converter.

              The following +diagram shows the File converter framework architecture.

              + +
              +
              API summary + + + +API +Description + + + + +

              CCnaConverter

              +

              A class that contains the properties of a converter. These are a +UID and the data types that the converter supports.

              +               + +

              CConverterBase

              +

              A class that provides an interface to access the converters.

              +               + +

              CConverterBase2

              +

              A base class for converters.

              +               + +

              CCnaConverterList

              +

              A class that provides a list of available converters. It allows +clients to search for and obtain converters for specific source and target +data types.

              +               + +

              CCnaConvInfoFileReader2

              +

              A class that encapsulates a collection of converter properties, CCnaConverter, +read from a converter information .rsc file.

              +               + +

              CMimeInfo

              +

              A class that contains the localized names for a data type.

              +               + +

              MConverterUiObserver

              +

              An interface implemented by the client of a conversion operation +to observe conversion progress.

              +               + + +
              +
              Typical uses

              Using a converter

              File +Converter Framework provides APIs to list and search for converters. It also +provides an observer interface through which the progress and success or failure +of the conversion can be reported. For more information, see Using +a converter.

              Writing a converter

              File Converter +Framework specifies a plug-in interface for converters. For more information, +see Writing a Converter.

              +               +File Converter +Tutorials               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-99C2E42F-1029-5E32-8446-CAAF29D733BA_d0e240083_href.png Binary file Symbian3/SDK/Source/GUID-99C2E42F-1029-5E32-8446-CAAF29D733BA_d0e240083_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-99C2E42F-1029-5E32-8446-CAAF29D733BA_d0e243820_href.png Binary file Symbian3/SDK/Source/GUID-99C2E42F-1029-5E32-8446-CAAF29D733BA_d0e243820_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9A38894D-98B8-5AFA-A36A-AC8B494EC2CC.dita --- a/Symbian3/SDK/Source/GUID-9A38894D-98B8-5AFA-A36A-AC8B494EC2CC.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-9A38894D-98B8-5AFA-A36A-AC8B494EC2CC.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,48 +1,44 @@ - - - - - -libmexample: -Using the Standard C Math LibraryThis example demonstrates the use of math functions, such as gamma(double), -that are part of the Standard C Maths support library (libm.dll). -
              Purpose

              This -example application shows how to use the libm.dll library. -It:

                -

              1. reads an input value -supplied by the user

                2. -

              2. applies the gamma function -on the input value

                3. -

              3. prints the output.

                4. -
              -
              Download

              Click -on the following link to download the example: libmexample.zip

              Click: browse to view the example code.

              -
              Class summary

              The -example shows the use of the following API:

                -

              • gamma(double) from -the Standard C Maths support library (libm.dll).

                • -
              -
              Building and -configuring

              To build the example:

                -

              • You can build the example -from your IDE or the command line.

                If you use an IDE, import the bld.inf file -of the example into your IDE, and use the build command of the IDE.

                If -you use the command line, open a command prompt, and set the current directory -to the source code directory of the example. You can then build the example -with the SBSv1 build tools with the following commands:

                bldmake -bldfiles

                abld build

                How to use bldmake and How to use abld describe -how to use the SBSv1 build tools.

                • -

              • For the emulator, the -example builds an executable called libmexample.exe in -the epoc32\release\winscw\<udeb or urel>\ folder.

                • -
              -
              Running the -example

              Run the libmexample.exe executable. -The example application waits for the user to enter an input value.

              + + + + + +libmexample: Using the Standard C Math LibraryThis example demonstrates the use of math functions, such +as gamma(double), that are part of the Standard C +Maths support library (libm.dll). +
              Purpose

              This example application shows how to use the libm.dll library. It:

                +

              1. reads an input +value supplied by the user

                2. +

              2. applies the +gamma function on the input value

                3. +

              3. prints the output.

                4. +
              +
              Download

              Click on the following link to download the example: libmexample.zip

              Click: browse to view the example code.

              +
              Class +summary

              The example shows the use of the following API:

                +

              • gamma(double) from the Standard C Maths support library (libm.dll).

                • +
              +
              Building +and configuring

              To build the example:

                +

              • You can build +the example from your IDE or the command line.

                If you use +an IDE, import the bld.inf file of the example +into your IDE, and use the build command of the IDE.

                If you +use the command line, open a command prompt, and set the current directory +to the source code directory of the example. You can then build the +example with the SBSv1 build tools with the following commands:

                bldmake bldfiles

                abld +build

                How to use bldmake and How to +use abld describe how to use the SBSv1 build tools.

                • +

              • For the emulator, +the example builds an executable called libmexample.exe in the epoc32\release\winscw\<udeb or urel>\ folder.

                • +
              +
              Running +the example

              Run the libmexample.exe executable. The example application waits for the user to enter +an input value.

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9A4543B3-2A79-5604-AE11-5087507C6755_d0e262222_href.png Binary file Symbian3/SDK/Source/GUID-9A4543B3-2A79-5604-AE11-5087507C6755_d0e262222_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9A4543B3-2A79-5604-AE11-5087507C6755_d0e265930_href.png Binary file Symbian3/SDK/Source/GUID-9A4543B3-2A79-5604-AE11-5087507C6755_d0e265930_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9AB5481B-C321-56C9-937D-2397AA80DE8E_d0e304377_href.jpg Binary file Symbian3/SDK/Source/GUID-9AB5481B-C321-56C9-937D-2397AA80DE8E_d0e304377_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9AB5481B-C321-56C9-937D-2397AA80DE8E_d0e310392_href.jpg Binary file Symbian3/SDK/Source/GUID-9AB5481B-C321-56C9-937D-2397AA80DE8E_d0e310392_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9AC6774A-41E9-5298-8696-0A317A09E1E9.dita --- a/Symbian3/SDK/Source/GUID-9AC6774A-41E9-5298-8696-0A317A09E1E9.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-9AC6774A-41E9-5298-8696-0A317A09E1E9.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,97 +1,97 @@ - - - - - -Librt -Overview -

              Support for the Librt library on the Symbian platform enables -you to port Librt-based applications onto the Symbian platform quickly and -easily. With knowledge of the Librt library you can also develop Librt-based -applications on the Symbian platform with minimal coding effort and without -much knowledge of the native Symbian Utility C++ APIs.

              -
              Librt library details

              The librt.dll provides -the Librt functionality and your code must link to librt.lib.

              Important: Your -application or library that uses the Librt library for the clock solutions -must link to librt.dll prior to all other libraries in -the link order. This is because both libc.dll and librt.dll provide -similar clock interfaces but only the Librt library is modified to behave -according to the LSB 3.1 specification.

              -
              Architecture

              The following image illustrates how -the Librt library interacts with the components of the P.I.P.S. environment -and also with the Symbian platform:

              - The Librt library interacting with P.I.P.S. and the Symbian -platform - -
              -
              APIs

              The following table is a comprehensive list -of Librt APIs as per the LSB 3.1 specification:

              - - - -API - - - - -

              Shared Memory APIs

              -               - -

              shm_open()

              -               - -

              shm_unlink()

              -               - -

              Clock APIs

              -               - -

              clock_getcpuclockid()

              -               - -

              clock_getres()

              -               - -

              clock_gettime()

              -               - -

              clock_nanosleep()

              -               - -

              clock_settime()

              -               - -

              Timer APIs

              -               - -

              timer_create()

              -               - -

              timer_delete()

              -               - -

              timer_getoverrun()

              -               - -

              timer_gettime()

              -               - -

              timer_settime

              -               - - -
              -
              Using Librt

              The following tutorials describe some -high-level usage scenarios of the Librt library functions:

                -

              • Shared -Memory Tutorial

                • -

              • Clocks -and Timers Tutorial

                • -
              + + + + + +Librt +Overview +

              Support for the Librt library on the Symbian platform enables +you to port Librt-based applications onto the Symbian platform quickly and +easily. With knowledge of the Librt library you can also develop Librt-based +applications on the Symbian platform with minimal coding effort and without +much knowledge of the native Symbian Utility C++ APIs.

              +
              Librt library details

              The librt.dll provides +the Librt functionality and your code must link to librt.lib.

              Important: Your +application or library that uses the Librt library for the clock solutions +must link to librt.dll prior to all other libraries in +the link order. This is because both libc.dll and librt.dll provide +similar clock interfaces but only the Librt library is modified to behave +according to the LSB 3.1 specification.

              +
              Architecture

              The following image illustrates how +the Librt library interacts with the components of the P.I.P.S. environment +and also with the Symbian platform:

              + The Librt library interacting with P.I.P.S. and the Symbian +platform + +
              +
              APIs

              The following table is a comprehensive list +of Librt APIs as per the LSB 3.1 specification:

              + + + +API + + + + +

              Shared Memory APIs

              +               + +

              shm_open()

              +               + +

              shm_unlink()

              +               + +

              Clock APIs

              +               + +

              clock_getcpuclockid()

              +               + +

              clock_getres()

              +               + +

              clock_gettime()

              +               + +

              clock_nanosleep()

              +               + +

              clock_settime()

              +               + +

              Timer APIs

              +               + +

              timer_create()

              +               + +

              timer_delete()

              +               + +

              timer_getoverrun()

              +               + +

              timer_gettime()

              +               + +

              timer_settime

              +               + + +
              +
              Using Librt

              The following tutorials describe some +high-level usage scenarios of the Librt library functions:

                +

              • Shared +Memory Tutorial

                • +

              • Clocks +and Timers Tutorial

                • +
               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9AD75103-CD56-5279-B639-5CA2BBF979B5.dita --- a/Symbian3/SDK/Source/GUID-9AD75103-CD56-5279-B639-5CA2BBF979B5.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-9AD75103-CD56-5279-B639-5CA2BBF979B5.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,291 +1,291 @@ - - - - - -Advanced -Pointer States and Event CommunicationThe Window Server provides advanced pointer features, such as support -for multiple pointers and proximity and pressure coordinates. This topic provides -a summary of advanced pointer states and the events that communicate changes -of their state. -

              Variant: ScreenPlay. Target -audience: Application developers.

              -

              This topic builds on the Advanced -Pointer Overview.

              -
              Communication -between an input driver and the Window Server

              The following diagram -shows how an input driver communicates changes in pointer state to the Window -Server. The diagram shows the logical pointer states and how TRawEvent types -change those states. From the driver's perspective, the pointer can be in -one of three basic logical states: Up, Down or OutOfRange.

              The -driver sends a number of types of event to move the pointer between these -states. For example, EButton1Up is an Up event that -changes the pointer from the Down to the Up state. EButton1Down is -a Down event. EButton1Down changes the pointer from -the Up to the Down state, and from OutOfRange to the Down state.

              There -can be any number of pointers, and each pointer has a maximum of three buttons. -A platform UI is free to implement buttons in any way. However, the Window -Server interprets only Button1 as an action and does not interpret -the other buttons.

              - Driver communicates pointer state changes to the Window Server - - -

              For a complete list of pointer states, the events that can be sent -by the driver, and the associated events that the Window Server sends to the -client, see the Pointer -states and event communication table below.

              -
              Pointer states

              Pointing -devices can be in one of the following basic states:

              - - - -State -Description - - - - -

              Out of range

              -

              Not detected by the device's sensors.

              -               - -

              Up

              -

              Detected by sensors, coordinates available, not performing an action.

              -               - -

              Down

              -

              Detected by sensors, coordinates available, performing an action -(as defined above).

              -               - - -

              The following diagram shows the extension of the Up and Down states -with additional substates. Up is extended with substates describing -the closeness of the pointer to the screen. Down is extended -with substates describing pressing.

              - Extension of Up and Down states with substates - -

              The Window Server generates the following events for changes of -closeness and pressing:

                -

              • EExitCloseProximity

                • -

              • EEnterCloseProximity

                • -

              • EExitHighPressure

                • -

              • EEnterHighPressure

                • -

              These are all types of TPointerEvent. Because -these state changes depend on the pressure and proximity of the pointer, both -of these values are checked each time a new TRawEvent concerning -the pointer arrives from the driver. TRawEvent::EPointer3DOutOfRange means -that the proximity is infinite and pressure is zero.

              These events -are based on four thresholds:

                -

              • The EExitHighPressure threshold -(EPointer3DExitHighPressureThreshold in HAL)

                This -is a threshold on the pointer's Z coordinate. In general, if the pointer crosses -this threshold by decreasing pressure (thus decreasing its Z coordinate), -the Window Server generates TPointerEvent::EExitHighPressure and -sends it to the client.

                • -

              • The EEnterHighPressure threshold -(EPointer3DEnterHighPressureThreshold in HAL)

                This -is a threshold on the pointer's Z coordinate. In general, if the pointer crosses -this threshold by increasing pressure (thus increasing its Z coordinate), -the Window Server generates TPointerEvent::EEnterHighPressure and -sends it to the client.

                • -

              • The EEnterCloseProximity threshold -( EPointer3DEnterCloseProximityThreshold in -HAL)

                This is a threshold on the pointer's Z coordinate. In general, -if the pointer crosses this threshold by decreasing its proximity from the -device (thus increasing its Z coordinate), the Window Server generates TPointerEvent::EEnterCloseProximity and -sends it to the client.

                • -

              • The EExitCloseProximity threshold -(EPointer3DExitCloseProximityThreshold in HAL)

                This -is a threshold on the pointer's Z coordinate. In general, if the pointer crosses -this threshold by increasing its proximity from the device (thus decreasing -its Z coordinate), the Window Server generates TPointerEvent::EExitCloseProximity and -sends it to the client.

                • -

              Applications can configure these thresholds at runtime by using Window -Server APIs in RWsSession. All applications can read these -thresholds. However, only code with WriteDeviceData capability -can change them because these changes should be made only by the device's -configuration application.

              -
              Pointer states -and event communication

              The table below shows all possible pointer -states. For each state it shows all of the events that can be sent by the -driver and all of the events that are sent by the Window Server to the client. -The end state of the pointer is also shown. There are five pointer zones (states) -and four thresholds. An event is generated when the pointer's z position crosses -a threshold.

              - - - - Pointer state - TRawEvent received from driver - TPointerEvent sent by Window Server -Resulting pointer state - - - - -

              OutOfRange

              -

              EPointer3DOutOfRange

              -

              —

              -

              EOutOfRange

              -               - -

              OutOfRange

              -

              EMove (Z < EEnterCloseProximity threshold)

              -

              EMove

              -

              Up/OutOfCloseProximity

              -               - -

              OutOfRange

              -

              EMove (Z >= EEnterCloseProximity threshold)

              -

              EEnterCloseProximity

              -

              Up/InCloseProximity

              -               - -

              OutOfRange

              -

              EButton1Down (Z < EEnterHighPressure threshold)

              -

              EButton1Down

              -

              Down/NotPressing

              -               - -

              OutOfRange

              -

              EButton1Down (Z >= EEnterHighPressure threshold)

              -

              EButton1Down, EEnterHighPressure

              -

              Down/Pressing

              -               - -

              Up/OutOfCloseProximity

              -

              EPointer3DOutOfRange

              -

              EOutOfRange

              -

              OutOfRange

              -               - -

              Up/OutOfCloseProximity

              -

              EMove (Z < EEnterCloseProximity threshold)

              -

              EMove

              -

              Up/OutOfCloseProximity

              -               - -

              Up/OutOfCloseProximity

              -

              EMove (Z >= EEnterCloseProximity threshold)

              -

              EEnterCloseProximity

              -

              Up/InCloseProximity

              -               - -

              Up/OutOfCloseProximity

              -

              EButton1Down (Z < EEnterHighPressure threshold)

              -

              EButton1Down

              -

              Down/OutOfHighPressure

              -               - -

              Up/OutOfCloseProximity

              -

              EButton1Down (Z >= EEnterHighPressure threshold)

              -

              EButton1Down, EEnterHighPressure

              -

              Down/InHighPressure

              -               - -

              Up/InCloseProximity

              -

              EPointer3DOutOfRange

              -

              EOutOfRange

              -

              OutOfRange

              -               - -

              Up/InCloseProximity

              -

              EMove (Z < EExitCloseProximity threshold)

              -

              EExitCloseProximity

              -

              Up/OutOfCloseProximity

              -               - -

              Up/InCloseProximity

              -

              EMove (Z >= EExitCloseProximity threshold)

              -

              EMove

              -

              Up/InCloseProximity

              -               - -

              Up/InCloseProximity

              -

              EButton1Down (Z < EEnterHighPressure threshold)

              -

              EButton1Down

              -

              Down/OutOfHighPressure

              -               - -

              Up/InCloseProximity

              -

              EButton1Down (Z >= EEnterHighPressure threshold)

              -

              EButton1Down, EEnterHighPressure

              -

              Down/InHighPressure

              -               - -

              Down/OutOfHighPressure

              -

              EButton1Up (Z < EExitCloseProximity threshold)

              -

              EButton1Up, EExitCloseProximity

              -

              Up/OutOfCloseProximity

              -               - -

              Down/OutOfHighPressure

              -

              EButton1Up (Z >= EExitCloseProximity threshold)

              -

              EButton1Up

              -

              Up/InCloseProximity

              -               - -

              Down/OutOfHighPressure

              -

              EMove (Z < EEnterHighPressure threshold)

              -

              EDrag

              -

              Down/OutOfHighPressure

              -               - -

              Down/OutOfHighPressure

              -

              EMove (Z >= EEnterHighPressure threshold)

              -

              EEnterHighPressure

              -

              Down/InHighPressure

              -               - -

              Down/InHighPressure

              -

              EButton1Up (Z < EExitCloseProximity threshold)

              -

              EButton1Up, EExitCloseProximity

              -

              Up/OutOfCloseProximity

              -               - -

              Down/InHighPressure

              -

              EButton1Up (Z >= EExitCloseProximity threshold)

              -

              EButton1Up

              -

              Up/InCloseProximity

              -               - -

              Down/InHighPressure

              -

              EMove (Z < EExitHighPressure threshold)

              -

              EExitHighPressure

              -

              Down/OutOfHighPressure

              -               - -

              Down/InHighPressure

              -

              EMove (Z >= EExitHighPressure threshold)

              -

              EDrag

              -

              Down/InHighPressure

              -               - - -

              The driver is prohibited from sending EPointer3DOutOfRange when -the pointer is in the Down state. Therefore this is not included in this table. -Because TRawEvent's EPointer3DOutOfRange events -do not have coordinates, the Window Server makes sure the event is delivered -to the place where the previous event for the same pointer occurred. It does -this by maintaining the last state of the pointer.

              The following diagram -shows the events sent from the Window Server to the client while -the pointer traverses the full cycle of events—from OutOfRange, through Down/InHighPressure -and back to OutOfRange. This diagram does not show all of the possible state -transitions that are described in the table above.

              - Events sent from Window Server to client while the pointer traverses -the full cycle of states. - -
              -               -Advanced -Pointer Overview -Advanced -Pointer Tutorial + + + + + +Advanced +Pointer States and Event CommunicationThe Window Server provides advanced pointer features, such as support +for multiple pointers and proximity and pressure coordinates. This topic provides +a summary of advanced pointer states and the events that communicate changes +of their state. +

              Variant: ScreenPlay. Target +audience: Application developers.

              +

              This topic builds on the Advanced +Pointer Overview.

              +
              Communication +between an input driver and the Window Server

              The following diagram +shows how an input driver communicates changes in pointer state to the Window +Server. The diagram shows the logical pointer states and how TRawEvent types +change those states. From the driver's perspective, the pointer can be in +one of three basic logical states: Up, Down or OutOfRange.

              The +driver sends a number of types of event to move the pointer between these +states. For example, EButton1Up is an Up event that +changes the pointer from the Down to the Up state. EButton1Down is +a Down event. EButton1Down changes the pointer from +the Up to the Down state, and from OutOfRange to the Down state.

              There +can be any number of pointers, and each pointer has a maximum of three buttons. +A platform UI is free to implement buttons in any way. However, the Window +Server interprets only Button1 as an action and does not interpret +the other buttons.

              + Driver communicates pointer state changes to the Window Server + + +

              For a complete list of pointer states, the events that can be sent +by the driver, and the associated events that the Window Server sends to the +client, see the Pointer +states and event communication table below.

              +
              Pointer states

              Pointing +devices can be in one of the following basic states:

              + + + +State +Description + + + + +

              Out of range

              +

              Not detected by the device's sensors.

              +               + +

              Up

              +

              Detected by sensors, coordinates available, not performing an action.

              +               + +

              Down

              +

              Detected by sensors, coordinates available, performing an action +(as defined above).

              +               + + +

              The following diagram shows the extension of the Up and Down states +with additional substates. Up is extended with substates describing +the closeness of the pointer to the screen. Down is extended +with substates describing pressing.

              + Extension of Up and Down states with substates + +

              The Window Server generates the following events for changes of +closeness and pressing:

                +

              • EExitCloseProximity

                • +

              • EEnterCloseProximity

                • +

              • EExitHighPressure

                • +

              • EEnterHighPressure

                • +

              These are all types of TPointerEvent. Because +these state changes depend on the pressure and proximity of the pointer, both +of these values are checked each time a new TRawEvent concerning +the pointer arrives from the driver. TRawEvent::EPointer3DOutOfRange means +that the proximity is infinite and pressure is zero.

              These events +are based on four thresholds:

                +

              • The EExitHighPressure threshold +(EPointer3DExitHighPressureThreshold in HAL)

                This +is a threshold on the pointer's Z coordinate. In general, if the pointer crosses +this threshold by decreasing pressure (thus decreasing its Z coordinate), +the Window Server generates TPointerEvent::EExitHighPressure and +sends it to the client.

                • +

              • The EEnterHighPressure threshold +(EPointer3DEnterHighPressureThreshold in HAL)

                This +is a threshold on the pointer's Z coordinate. In general, if the pointer crosses +this threshold by increasing pressure (thus increasing its Z coordinate), +the Window Server generates TPointerEvent::EEnterHighPressure and +sends it to the client.

                • +

              • The EEnterCloseProximity threshold +( EPointer3DEnterCloseProximityThreshold in +HAL)

                This is a threshold on the pointer's Z coordinate. In general, +if the pointer crosses this threshold by decreasing its proximity from the +device (thus increasing its Z coordinate), the Window Server generates TPointerEvent::EEnterCloseProximity and +sends it to the client.

                • +

              • The EExitCloseProximity threshold +(EPointer3DExitCloseProximityThreshold in HAL)

                This +is a threshold on the pointer's Z coordinate. In general, if the pointer crosses +this threshold by increasing its proximity from the device (thus decreasing +its Z coordinate), the Window Server generates TPointerEvent::EExitCloseProximity and +sends it to the client.

                • +

              Applications can configure these thresholds at runtime by using Window +Server APIs in RWsSession. All applications can read these +thresholds. However, only code with WriteDeviceData capability +can change them because these changes should be made only by the device's +configuration application.

              +
              Pointer states +and event communication

              The table below shows all possible pointer +states. For each state it shows all of the events that can be sent by the +driver and all of the events that are sent by the Window Server to the client. +The end state of the pointer is also shown. There are five pointer zones (states) +and four thresholds. An event is generated when the pointer's z position crosses +a threshold.

              + + + + Pointer state + TRawEvent received from driver + TPointerEvent sent by Window Server +Resulting pointer state + + + + +

              OutOfRange

              +

              EPointer3DOutOfRange

              +

              —

              +

              EOutOfRange

              +               + +

              OutOfRange

              +

              EMove (Z < EEnterCloseProximity threshold)

              +

              EMove

              +

              Up/OutOfCloseProximity

              +               + +

              OutOfRange

              +

              EMove (Z >= EEnterCloseProximity threshold)

              +

              EEnterCloseProximity

              +

              Up/InCloseProximity

              +               + +

              OutOfRange

              +

              EButton1Down (Z < EEnterHighPressure threshold)

              +

              EButton1Down

              +

              Down/NotPressing

              +               + +

              OutOfRange

              +

              EButton1Down (Z >= EEnterHighPressure threshold)

              +

              EButton1Down, EEnterHighPressure

              +

              Down/Pressing

              +               + +

              Up/OutOfCloseProximity

              +

              EPointer3DOutOfRange

              +

              EOutOfRange

              +

              OutOfRange

              +               + +

              Up/OutOfCloseProximity

              +

              EMove (Z < EEnterCloseProximity threshold)

              +

              EMove

              +

              Up/OutOfCloseProximity

              +               + +

              Up/OutOfCloseProximity

              +

              EMove (Z >= EEnterCloseProximity threshold)

              +

              EEnterCloseProximity

              +

              Up/InCloseProximity

              +               + +

              Up/OutOfCloseProximity

              +

              EButton1Down (Z < EEnterHighPressure threshold)

              +

              EButton1Down

              +

              Down/OutOfHighPressure

              +               + +

              Up/OutOfCloseProximity

              +

              EButton1Down (Z >= EEnterHighPressure threshold)

              +

              EButton1Down, EEnterHighPressure

              +

              Down/InHighPressure

              +               + +

              Up/InCloseProximity

              +

              EPointer3DOutOfRange

              +

              EOutOfRange

              +

              OutOfRange

              +               + +

              Up/InCloseProximity

              +

              EMove (Z < EExitCloseProximity threshold)

              +

              EExitCloseProximity

              +

              Up/OutOfCloseProximity

              +               + +

              Up/InCloseProximity

              +

              EMove (Z >= EExitCloseProximity threshold)

              +

              EMove

              +

              Up/InCloseProximity

              +               + +

              Up/InCloseProximity

              +

              EButton1Down (Z < EEnterHighPressure threshold)

              +

              EButton1Down

              +

              Down/OutOfHighPressure

              +               + +

              Up/InCloseProximity

              +

              EButton1Down (Z >= EEnterHighPressure threshold)

              +

              EButton1Down, EEnterHighPressure

              +

              Down/InHighPressure

              +               + +

              Down/OutOfHighPressure

              +

              EButton1Up (Z < EExitCloseProximity threshold)

              +

              EButton1Up, EExitCloseProximity

              +

              Up/OutOfCloseProximity

              +               + +

              Down/OutOfHighPressure

              +

              EButton1Up (Z >= EExitCloseProximity threshold)

              +

              EButton1Up

              +

              Up/InCloseProximity

              +               + +

              Down/OutOfHighPressure

              +

              EMove (Z < EEnterHighPressure threshold)

              +

              EDrag

              +

              Down/OutOfHighPressure

              +               + +

              Down/OutOfHighPressure

              +

              EMove (Z >= EEnterHighPressure threshold)

              +

              EEnterHighPressure

              +

              Down/InHighPressure

              +               + +

              Down/InHighPressure

              +

              EButton1Up (Z < EExitCloseProximity threshold)

              +

              EButton1Up, EExitCloseProximity

              +

              Up/OutOfCloseProximity

              +               + +

              Down/InHighPressure

              +

              EButton1Up (Z >= EExitCloseProximity threshold)

              +

              EButton1Up

              +

              Up/InCloseProximity

              +               + +

              Down/InHighPressure

              +

              EMove (Z < EExitHighPressure threshold)

              +

              EExitHighPressure

              +

              Down/OutOfHighPressure

              +               + +

              Down/InHighPressure

              +

              EMove (Z >= EExitHighPressure threshold)

              +

              EDrag

              +

              Down/InHighPressure

              +               + + +

              The driver is prohibited from sending EPointer3DOutOfRange when +the pointer is in the Down state. Therefore this is not included in this table. +Because TRawEvent's EPointer3DOutOfRange events +do not have coordinates, the Window Server makes sure the event is delivered +to the place where the previous event for the same pointer occurred. It does +this by maintaining the last state of the pointer.

              The following diagram +shows the events sent from the Window Server to the client while +the pointer traverses the full cycle of events—from OutOfRange, through Down/InHighPressure +and back to OutOfRange. This diagram does not show all of the possible state +transitions that are described in the table above.

              + Events sent from Window Server to client while the pointer traverses +the full cycle of states. + +
              +               +Advanced +Pointer Overview +Advanced +Pointer Tutorial               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9BB849A2-8F69-580D-8A52-C7002D919521.dita --- a/Symbian3/SDK/Source/GUID-9BB849A2-8F69-580D-8A52-C7002D919521.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-9BB849A2-8F69-580D-8A52-C7002D919521.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,16 +1,16 @@ - - - - - -Email Overview

              The Email collection provides support for sending and receiving emails using the individual email protocols, such as IMAP4, POP3 and SMTP, and also has support for parsing and generating plain and rich text, MIME and M-HTML format emails.

              Architecture

              The Email collection consists of a set of utilities and MTMs for the POP3, IMAP4 and SMTP messaging protocols.

              - Email architecture -
              Autosend

              Autosend is an executable file that is executed by the POP3 and IMAP4 client MTMs if the send on next connection setting is set. This executable makes a request to the SMTP server MTM to send messages associated with the SMTP service related to the POP3 or IMAP4 service, wait for the operation to finish and then exit.

              Server MTM

              A Server MTM provides specific message type storage and transport. It interacts with the Message Server to store and manage entries and provide a transport mechanism.

              Email client MTMs

              Email client MTMs provide client-side APIs (IMCM DLL) for IMAP4, POP3 and SMTP.

              The email client MTMs are used directly by clients to access parts of email messages for display. The CImEmailMessage class provides the functionality used by clients to display email messages, including listing attachments, getting body text and resolving URIs in M-HTML messages.

              Email client utilities

              The email client MTM uses the email client utilities when they are requested to create, reply to and forward messages. The CImEmailOperation class provides the functionality to perform these operations. Each email is represented by a parent message entry with child entries that represent MIME folders and MIME parts. Adding or deleting MIME parts involves navigating the tree of entries and inserting or removing entries as appropriate.

              Email server utilities

              Email server utilities are responsible for generating and parsing of RFC2822 format email messages and providing an API to wrap up a TCP/IP connection to a remote email server.

              Description

              Email messages are represented in a common format whether they are being sent by SMTP and downloaded by POP3 or IMAP4. Messaging clients can use the email client MTMs to create and compose email messages with attachments and a vCard signature. They can reply to or forward email messages. When connecting to a POP3 mailbox, just the header can be downloaded, or the entire message including attachments. However, when connecting to an IMAP4 mailbox, any or all of the following can be downloaded:

              • the header

              • the header and body text

              • the entire message including attachments

              • partial body text where the body text size limit is specified

              • download attachments if the attachment size is less then or equal to attachment size limit

              Messaging clients can access any part of the message for display to the user. Messages can be moved or copied within folders on the local device and, for IMAP4 only, within the mailbox as well.

              Email client MTMs provide APIs that allow configuration information, such as secure or non-secure TCP/IP connection, username, password and message limits to be stored on the local device. Email client MTMs can be commanded to stay online during a client session, or connect and disconnect only when necessary. Operations such as moving, deleting, or sending a message while not connected can be queued for execution when the next connection to the subscriber's mailbox is established.

              Note: Email client MTMs are not responsible for any graphical or user interface associated functionality, such as rendering HTML or images, although they do provide access to images and HTML downloaded to the local device.

              For each email account a pair of services entries is created in the Message Store. For a POP3 account there will be an SMTP service and a POP3 service. For an IMAP4 account there will be an SMTP service and an IMAP4 service. These entries are used to store the settings for the email transport. Each of the service entry has its related ID that is set to the other member of the pair. The SMTP service is invisible, so that the user only sees the POP3 or IMAP4 service entry. Copying a message to the SMTP service causes the SMTP server MTM to attempt to send the message. The POP3 and IMAP4 MTMs provide functionality to synchronise with a remote email server by using the client MTM interface through the InvokeAsync API.

              - Email operation sequence diagram -
              Components

              The Email collection constitutes the following components:

              • IMAP4 MTM

              • POP3 MTM

              • SMTP MTM

              Using Email

              Email client applications can use the following functionality provided by the Email collection to:

              • Store emails including MIME headers, RFC2822 headers, attachments, body text and encoding information in the Message Store.

              • Manipulate email messages, for example, adding attachments and replying.

              • Encapsulate the character converters, which are used to convert between standard character sets and Unicode.

              • Store email settings in the central repository.

              • Get progress information for email operations.

              Message Type Module Email Tutorials               \ No newline at end of file + + + + + +Email Overview

              The Email collection provides support for sending and receiving emails using the individual email protocols, such as IMAP4, POP3 and SMTP, and also has support for parsing and generating plain and rich text, MIME and M-HTML format emails.

              Architecture

              The Email collection consists of a set of utilities and MTMs for the POP3, IMAP4 and SMTP messaging protocols.

              + Email architecture +
              Autosend

              Autosend is an executable file that is executed by the POP3 and IMAP4 client MTMs if the send on next connection setting is set. This executable makes a request to the SMTP server MTM to send messages associated with the SMTP service related to the POP3 or IMAP4 service, wait for the operation to finish and then exit.

              Server MTM

              A Server MTM provides specific message type storage and transport. It interacts with the Message Server to store and manage entries and provide a transport mechanism.

              Email client MTMs

              Email client MTMs provide client-side APIs (IMCM DLL) for IMAP4, POP3 and SMTP.

              The email client MTMs are used directly by clients to access parts of email messages for display. The CImEmailMessage class provides the functionality used by clients to display email messages, including listing attachments, getting body text and resolving URIs in M-HTML messages.

              Email client utilities

              The email client MTM uses the email client utilities when they are requested to create, reply to and forward messages. The CImEmailOperation class provides the functionality to perform these operations. Each email is represented by a parent message entry with child entries that represent MIME folders and MIME parts. Adding or deleting MIME parts involves navigating the tree of entries and inserting or removing entries as appropriate.

              Email server utilities

              Email server utilities are responsible for generating and parsing of RFC2822 format email messages and providing an API to wrap up a TCP/IP connection to a remote email server.

              Description

              Email messages are represented in a common format whether they are being sent by SMTP and downloaded by POP3 or IMAP4. Messaging clients can use the email client MTMs to create and compose email messages with attachments and a vCard signature. They can reply to or forward email messages. When connecting to a POP3 mailbox, just the header can be downloaded, or the entire message including attachments. However, when connecting to an IMAP4 mailbox, any or all of the following can be downloaded:

              • the header

              • the header and body text

              • the entire message including attachments

              • partial body text where the body text size limit is specified

              • download attachments if the attachment size is less then or equal to attachment size limit

              Messaging clients can access any part of the message for display to the user. Messages can be moved or copied within folders on the local device and, for IMAP4 only, within the mailbox as well.

              Email client MTMs provide APIs that allow configuration information, such as secure or non-secure TCP/IP connection, username, password and message limits to be stored on the local device. Email client MTMs can be commanded to stay online during a client session, or connect and disconnect only when necessary. Operations such as moving, deleting, or sending a message while not connected can be queued for execution when the next connection to the subscriber's mailbox is established.

              Note: Email client MTMs are not responsible for any graphical or user interface associated functionality, such as rendering HTML or images, although they do provide access to images and HTML downloaded to the local device.

              For each email account a pair of services entries is created in the Message Store. For a POP3 account there will be an SMTP service and a POP3 service. For an IMAP4 account there will be an SMTP service and an IMAP4 service. These entries are used to store the settings for the email transport. Each of the service entry has its related ID that is set to the other member of the pair. The SMTP service is invisible, so that the user only sees the POP3 or IMAP4 service entry. Copying a message to the SMTP service causes the SMTP server MTM to attempt to send the message. The POP3 and IMAP4 MTMs provide functionality to synchronise with a remote email server by using the client MTM interface through the InvokeAsync API.

              + Email operation sequence diagram +
              Components

              The Email collection constitutes the following components:

              • IMAP4 MTM

              • POP3 MTM

              • SMTP MTM

              Using Email

              Email client applications can use the following functionality provided by the Email collection to:

              • Store emails including MIME headers, RFC2822 headers, attachments, body text and encoding information in the Message Store.

              • Manipulate email messages, for example, adding attachments and replying.

              • Encapsulate the character converters, which are used to convert between standard character sets and Unicode.

              • Store email settings in the central repository.

              • Get progress information for email operations.

              Message Type Module Email Tutorials               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9BF177DF-9E59-5C30-95BA-70A8250579E0_d0e429704_href.png Binary file Symbian3/SDK/Source/GUID-9BF177DF-9E59-5C30-95BA-70A8250579E0_d0e429704_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9BF177DF-9E59-5C30-95BA-70A8250579E0_d0e429866_href.png Binary file Symbian3/SDK/Source/GUID-9BF177DF-9E59-5C30-95BA-70A8250579E0_d0e429866_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9BFF0271-F5C3-45B6-AD4D-9179107F300A.dita --- a/Symbian3/SDK/Source/GUID-9BFF0271-F5C3-45B6-AD4D-9179107F300A.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-9BFF0271-F5C3-45B6-AD4D-9179107F300A.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,57 +1,57 @@ - - - - - -Open -C Producer Consumer Example -

              OpenCProducerConsumerEx is a hybrid application that depicts solution for -producer consumer problem using Open C. This application uses main() as an -entry point for the application. It uses libc and libpthread

              -
              Download

              Click -on the following link to download the example: opencproducerconsumerex.zip

              Click: browse to view the example code.

              -
              Design and -Implementation

              The following sections provide information about -the implementation of the example.

              Capabilities

              The program -capability is defined in: ProducerConsumer.mmp (EXE - -application): CAPABILITY NONE.

              Implementation details -of EXE

              This is a simple console based application. Main thread of -the application will create a thread named as Producer that will produce the -item and push it on to the stack. There will be N consumers which want to -consume some N(i) items from the Producer. Producer will produce N items at -a time and pushes them to the stack and totally it will produce sum(N(i)) -items. The consumer thread will try to pop items from the stack and each consumer -will pop N(i) items from the stack. The application will create one thread -for each consumer. Producer and all the consumer threads will be synchronized -using a semaphore. The main thread, Producer and the consumer codes are pure -C-code. the stack used by Producer and the consumer threads is Standard C++ -code. Apart from these threads, there is another thread named as Observer -that is created using Symbian platform API. Producer and the consumers will -establish a message queue with this thread and Observer will read message -from all other threads and will log them to a file wich is opened/written -using Symbian APIs. Hence, this application is a hybrid application with: -

              Standard C code -> Consumer.c, Producer.c, ProducerConsumer.c, CommanHeader.h

              Standard C++ code -> Stack.cpp,Stack.h, CommanHeader.h

              Symbian -platform code that uses libc APIs and Observer.cpp.

              -The application has its own icon and can be launched from the UI both in the -emulator and in the device.

              API Usage

              string APIs

              IPC -APIs (message queue and semaphore)

              Threading APIs -(from pthread)

              console I/O APIs

              File -APIs of Symbian platform

              Threading APIs of Symbian -platform

              -
              Building and -Using To build the OpenCProducerConsumerEx application, go to the -OpenCProducerConsumerEx\group directory and build the application. The definition -for the whole application can be found in the bld.infin -the group subdirectory of the applications main directory.

              The application -is simple console based application. It has its own default icon and can be -launched from the UI both in the emulator and in the device. The application -can be launched by: Executing OpenCProducerConsumerEx from eshell. Clicking -default icon with display text OpenCProducerConsumerEx within the install -folder launcher application.

              + + + + + +Open +C Producer Consumer Example +

              OpenCProducerConsumerEx is a hybrid application that depicts solution for +producer consumer problem using Open C. This application uses main() as an +entry point for the application. It uses libc and libpthread

              +
              Download

              Click +on the following link to download the example: opencproducerconsumerex.zip

              Click: browse to view the example code.

              +
              Design and +Implementation

              The following sections provide information about +the implementation of the example.

              Capabilities

              The program +capability is defined in: ProducerConsumer.mmp (EXE - +application): CAPABILITY NONE.

              Implementation details +of EXE

              This is a simple console based application. Main thread of +the application will create a thread named as Producer that will produce the +item and push it on to the stack. There will be N consumers which want to +consume some N(i) items from the Producer. Producer will produce N items at +a time and pushes them to the stack and totally it will produce sum(N(i)) +items. The consumer thread will try to pop items from the stack and each consumer +will pop N(i) items from the stack. The application will create one thread +for each consumer. Producer and all the consumer threads will be synchronized +using a semaphore. The main thread, Producer and the consumer codes are pure +C-code. the stack used by Producer and the consumer threads is Standard C++ +code. Apart from these threads, there is another thread named as Observer +that is created using Symbian platform API. Producer and the consumers will +establish a message queue with this thread and Observer will read message +from all other threads and will log them to a file wich is opened/written +using Symbian APIs. Hence, this application is a hybrid application with: +

              Standard C code -> Consumer.c, Producer.c, ProducerConsumer.c, CommanHeader.h

              Standard C++ code -> Stack.cpp,Stack.h, CommanHeader.h

              Symbian +platform code that uses libc APIs and Observer.cpp.

              +The application has its own icon and can be launched from the UI both in the +emulator and in the device.

              API Usage

              string APIs

              IPC +APIs (message queue and semaphore)

              Threading APIs +(from pthread)

              console I/O APIs

              File +APIs of Symbian platform

              Threading APIs of Symbian +platform

              +
              Building and +Using To build the OpenCProducerConsumerEx application, go to the +OpenCProducerConsumerEx\group directory and build the application. The definition +for the whole application can be found in the bld.infin +the group subdirectory of the applications main directory.

              The application +is simple console based application. It has its own default icon and can be +launched from the UI both in the emulator and in the device. The application +can be launched by: Executing OpenCProducerConsumerEx from eshell. Clicking +default icon with display text OpenCProducerConsumerEx within the install +folder launcher application.

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9C269F45-F160-5A4B-ABF8-896D2A538E3B.dita --- a/Symbian3/SDK/Source/GUID-9C269F45-F160-5A4B-ABF8-896D2A538E3B.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-9C269F45-F160-5A4B-ABF8-896D2A538E3B.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,19 +1,19 @@ - - - - - -Advanced Pointer Overview This is an overview of the Window Server extensions that support the use of advanced pointers. These extensions enable mobile devices to respond to events from multiple pointers, including their proximity and pressure. These extensions are available only in ScreenPlay.

              Variant: ScreenPlay. Target audience: Application developers.

              Architecture

              In response to multi-touch pointer movements, an input driver generates a pointer event for each touch. The Window Server changes and delivers the pointer events to the client application, as shown in the following diagram.

              - Pointer events -

              Pointer-related events move from the driver to the application. The TRawEvent, TWsEvent and TPointerEvent classes encapsulate the event information.

              Key concepts/terms

              The following terms are introduced here and are used throughout the advanced pointer documentation:

              Pointer

              A device that points at the screen, for example, a mouse, pen, finger, or touchpad.

              Multi-pointer support

              Handling more than one pointer at the same time.

              Proximity

              Proximity in this context means the distance of the pointer from the mobile device. Sensors detect the value of the proximity of the pointer from the mobile device.

              Pressure

              Pressure in this context is a value that indicates the force applied to the mobile device by the pointer. Sensors detect the value of the pressure of the pointer on the mobile device.

              Logical model of pointing devices

              A logical model is used to handle all of the different pointing devices correctly. In this logical model, the pointer is performing an action when any of the following scenarios occur:

              • An EButton1Down event is sent to the client.

              • EDrag events are sent to the client (optional).

              • An EButton1Up event is sent to the client.

              Pointing devices can be in one of the following states:

              State Description

              Out of range

              Not detected by the device's sensors.

              Up

              Detected by sensors, coordinates available, not performing an action.

              Down

              Detected by sensors, coordinates available, performing an action (as defined above).

              The mapping between these states and physical actions performed by the user vary for different pointing device types (mouse, finger) and different phone models. Here are two example interpretations of physical pointing device states:

              • Mouse. An example interpretation by a driver of the physical state of a mouse is as follows: It is always in the up state except when the left button is pressed, when it is in the down state. It is never out of range.

              • Fingers with proximity support. The following is an example interpretation of finger physical states when the device has proximity support (that is, it can measure the finger's proximity from the screen):

                • Out of range when proximity > 10cm

                • Up when 1cm < proximity <= 10cm

                • Down when proximity <= 1cm

                In this way the finger can perform actions (for example, press buttons, drag items) without touching the screen.

              Multiple pointers

              The system handles multiple pointers at the same time by identifying each one with a number and sending pointer events separately for each of them. A field (iPointerNumber) in the pointer event classes (TRawEvent and the TAdvancedPointerEvent class which extends TPointerEvent) identifies the pointer for which the event occurred. The order and frequency of pointer events depends on the driver of the pointing device.

              On each phone there is a pool of available pointer numbers, ranging from 0 to HALData::EPointerNumberOfPointers - 1. Every time the driver detects a new pointer coming into the range of the device, the driver assigns a number from the pool. After the pointer goes out of the range of the device, the number no longer identifies that particular pointer and the driver sends TRawEvent::EPointer3DOutOfRange with this pointer number. The number is then released back to the pool and may be reused to identify another pointer coming into the device's range.

              Pressure and proximity

              The pressure of the pointer on the screen is represented as a positive integer. The proximity of the pointer to the screen is represented as a negative integer. It is up to the UI Platform to define units of pressure and proximity, which may be non-linear. In the TRawEvent class, pressure and proximity are expressed in terms of the Z coordinate of the pointer. The definition of the Z coordinate is based on the assumption that the pointer is either hovering over the screen (proximity < 0, pressure = 0) or touching the screen (proximity = 0, pressure >= 0):

              • If proximity < 0 and pressure = 0 then the Z coordinate = proximity.

              • If proximity = 0 and pressure >= 0 then the Z coordinate = pressure.

              - Relationships between the pointer proximity, pressure and z - coordinate -
              API summary API Description

              HALData

              Includes z coordinate, pressure precision and number of pointers. Also contains threshold values for proximity and pressure.

              TRawEvent

              Includes the pointer number and a structure for proximity and pressure data.

              RWindowBase

              Enables advanced pointer events for the window.

              TWsEvent

              Supports TAdvancedPointerEvent (derived from TPointerEvent).

              TPointerEvent

              Includes event types for pressing and closeness.

              TAdvancedPointerEvent

              Inherits from TPointerEvent.

              Provides capabilities for pressure, proximity and multi-touch support.

              RWsSession

              Provides get and set methods to manipulate threshold values for proximity and pressure.

              Typical uses

              • Enabling many pointers for a window

                Enables multiple pointers to act on one window.

              • Enabling concurrent control of many objects

                Controls many objects on one or more windows with many pointers.

              • Getting z coordinates from TPointerEvent

                Reads the pressure and proximity values for a pointer.

              • Pinch zooming

                Enables the user to zoom in and out of data by using two fingers to pinch an area of the screen. Pinch zooming is normally used in web-page, map, picture, chart and control applications.

              • Responding to high pressure events

                As the pointer state changes, the pressure value can be checked. When it passes over a threshold value, the Window Server responds appropriately to the client.

              Pointer States and Event - Communication Advanced Pointer + + + + + +Advanced Pointer Overview This is an overview of the Window Server extensions that support the use of advanced pointers. These extensions enable mobile devices to respond to events from multiple pointers, including their proximity and pressure. These extensions are available only in ScreenPlay.

              Variant: ScreenPlay. Target audience: Application developers.

              Architecture

              In response to multi-touch pointer movements, an input driver generates a pointer event for each touch. The Window Server changes and delivers the pointer events to the client application, as shown in the following diagram.

              + Pointer events +

              Pointer-related events move from the driver to the application. The TRawEvent, TWsEvent and TPointerEvent classes encapsulate the event information.

              Key concepts/terms

              The following terms are introduced here and are used throughout the advanced pointer documentation:

              Pointer

              A device that points at the screen, for example, a mouse, pen, finger, or touchpad.

              Multi-pointer support

              Handling more than one pointer at the same time.

              Proximity

              Proximity in this context means the distance of the pointer from the mobile device. Sensors detect the value of the proximity of the pointer from the mobile device.

              Pressure

              Pressure in this context is a value that indicates the force applied to the mobile device by the pointer. Sensors detect the value of the pressure of the pointer on the mobile device.

              Logical model of pointing devices

              A logical model is used to handle all of the different pointing devices correctly. In this logical model, the pointer is performing an action when any of the following scenarios occur:

              • An EButton1Down event is sent to the client.

              • EDrag events are sent to the client (optional).

              • An EButton1Up event is sent to the client.

              Pointing devices can be in one of the following states:

              State Description

              Out of range

              Not detected by the device's sensors.

              Up

              Detected by sensors, coordinates available, not performing an action.

              Down

              Detected by sensors, coordinates available, performing an action (as defined above).

              The mapping between these states and physical actions performed by the user vary for different pointing device types (mouse, finger) and different phone models. Here are two example interpretations of physical pointing device states:

              • Mouse. An example interpretation by a driver of the physical state of a mouse is as follows: It is always in the up state except when the left button is pressed, when it is in the down state. It is never out of range.

              • Fingers with proximity support. The following is an example interpretation of finger physical states when the device has proximity support (that is, it can measure the finger's proximity from the screen):

                • Out of range when proximity > 10cm

                • Up when 1cm < proximity <= 10cm

                • Down when proximity <= 1cm

                In this way the finger can perform actions (for example, press buttons, drag items) without touching the screen.

              Multiple pointers

              The system handles multiple pointers at the same time by identifying each one with a number and sending pointer events separately for each of them. A field (iPointerNumber) in the pointer event classes (TRawEvent and the TAdvancedPointerEvent class which extends TPointerEvent) identifies the pointer for which the event occurred. The order and frequency of pointer events depends on the driver of the pointing device.

              On each phone there is a pool of available pointer numbers, ranging from 0 to HALData::EPointerNumberOfPointers - 1. Every time the driver detects a new pointer coming into the range of the device, the driver assigns a number from the pool. After the pointer goes out of the range of the device, the number no longer identifies that particular pointer and the driver sends TRawEvent::EPointer3DOutOfRange with this pointer number. The number is then released back to the pool and may be reused to identify another pointer coming into the device's range.

              Pressure and proximity

              The pressure of the pointer on the screen is represented as a positive integer. The proximity of the pointer to the screen is represented as a negative integer. It is up to the UI Platform to define units of pressure and proximity, which may be non-linear. In the TRawEvent class, pressure and proximity are expressed in terms of the Z coordinate of the pointer. The definition of the Z coordinate is based on the assumption that the pointer is either hovering over the screen (proximity < 0, pressure = 0) or touching the screen (proximity = 0, pressure >= 0):

              • If proximity < 0 and pressure = 0 then the Z coordinate = proximity.

              • If proximity = 0 and pressure >= 0 then the Z coordinate = pressure.

              + Relationships between the pointer proximity, pressure and z + coordinate +
              API summary API Description

              HALData

              Includes z coordinate, pressure precision and number of pointers. Also contains threshold values for proximity and pressure.

              TRawEvent

              Includes the pointer number and a structure for proximity and pressure data.

              RWindowBase

              Enables advanced pointer events for the window.

              TWsEvent

              Supports TAdvancedPointerEvent (derived from TPointerEvent).

              TPointerEvent

              Includes event types for pressing and closeness.

              TAdvancedPointerEvent

              Inherits from TPointerEvent.

              Provides capabilities for pressure, proximity and multi-touch support.

              RWsSession

              Provides get and set methods to manipulate threshold values for proximity and pressure.

              Typical uses

              • Enabling many pointers for a window

                Enables multiple pointers to act on one window.

              • Enabling concurrent control of many objects

                Controls many objects on one or more windows with many pointers.

              • Getting z coordinates from TPointerEvent

                Reads the pressure and proximity values for a pointer.

              • Pinch zooming

                Enables the user to zoom in and out of data by using two fingers to pinch an area of the screen. Pinch zooming is normally used in web-page, map, picture, chart and control applications.

              • Responding to high pressure events

                As the pointer state changes, the pressure value can be checked. When it passes over a threshold value, the Window Server responds appropriately to the client.

              Pointer States and Event + Communication Advanced Pointer Tutorial               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9C51D27D-BEDB-59D1-8F0E-8426B8FF2230.dita --- a/Symbian3/SDK/Source/GUID-9C51D27D-BEDB-59D1-8F0E-8426B8FF2230.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-9C51D27D-BEDB-59D1-8F0E-8426B8FF2230.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,12 +1,12 @@ - - - - - -Descriptors

              Descriptors are the classes that Symbian platform C++ uses to manage strings. They are fundamental to the Symbian platform, and an excellent example of the difference of approach between non-OO and OO designs.

              Overview

              In C, a string such as

              char* hello="hello";

              causes some memory to be set aside containing the six characters 'h', 'e', 'l', 'l', 'o', '\0'. A function such as strlen() works by scanning the bytes starting from the beginning, and counting until it reaches the trailing null character. If you wish to extend the string, you need to know how much memory is allocated to it.

              In Symbian platform C++ however, strings are managed using a family of classes called descriptors. The abstract descriptor classes define common interfaces for all descriptor classes. Buffer, pointer, and heap descriptor classes provide implementations of the abstract descriptor interfaces, and provide different methods of storing the data.

              Abstract descriptors

              We can represent the basic requirements for strings by two abstract classes: TDesC and TDes.

              TDesC is a constant, or non-modifiable, descriptor. It has an address and a length. Using a class like this, you can do any manipulations to a string, provided they do not alter the data. As a consequence, the TDesC class has many non-modifying functions.

              TDes is a modifiable descriptor: it has, in addition, a maximum length. This allows the data to be manipulated, extended or contracted, provided it does not exceed the maximum length. As a consequence, TDes has many modifying functions which allow string manipulation.

              It is a fundamental aspect of descriptors that they do not allow modification to exceed the allocated length. Other classes are provided to allow this, for instance CBufBase and derived classes. If a TDes function causes overflow, a panic will occur.

              Because TDesC and TDes define all the functions needed to access and manipulate string and memory data, many functions take a const TDesC& parameter if they need to access data, or a TDes& parameter if they need to modify it.

              Pointer descriptor

              The abstract descriptor classes have several implementations. The simplest are pointer descriptors.

              TPtrC just has length and address: its representation needs just two machine words. A TPtrC may be set up to describe any existing data. A TPtr adds a maximum length, and so may be used to describe a buffer which is perhaps only partially allocated.

              TPtrC and TPtr are somewhat like C char* pointers. But because the length is contained in the descriptor itself, there is no need to scan for trailing null characters, or to allocate room for them.

              Buffer descriptors

              Buffer descriptors, TBufC and TBuf, contain their data as part of themselves, like char[] arrays in C.

              These descriptor classes exploit C++'s template mechanism, using an integer parameter to specify the length.

              Heap descriptors

              Heap descriptors contain their data in heap cell. These are used when you do not know the length required for a buffer at build time, but decide it at run-time. This is like (char*) malloc(length+1) in C.

              The non-modifiable heap descriptor type, HBufC, is allocated on the heap. They are always referred to through an HBufC*, rather than an HBufC directly:

              The modifiable heap descriptor type, RBuf, can be created on the stack, but contains a pointer to data on the heap. This is similar to a TPtr pointer descriptor, but an RBuf owns the data that it points to, and is responsible for freeing the memory when it is closed. An RBuf object can allocate its own buffer, take ownership of a pre-existing section of allocated memory, or take ownership of a pre-existing heap descriptor.

              RBuf is easier to use than HBufC, so should generally be preferred. RBuf was only introduced in version 8.0, however, so older code and APIs use HBufC.

              Descriptor classes

              The complete descriptor class hierarchy is

              It represents an elegant use of OO. The TBufCBase class is used as an implementation convenience, which is also a frequent OO idiom (though it should be used with caution).

              Versions of the descriptors classes are available that store 16-bit or 8-bit wide items. When using descriptors for strings, you should always use classes such as TDes etc. These classes are typedef ed to use the 16-bit implementations, such as TDes16 etc.

              Because descriptors may contain any data, including nulls, they may also be used to refer to byte data and general buffers. In these contexts, you should use the 8-bit implementations, such as TDes8, directly.

              \ No newline at end of file + + + + + +Descriptors

              Descriptors are the classes that Symbian platform C++ uses to manage strings. They are fundamental to the Symbian platform, and an excellent example of the difference of approach between non-OO and OO designs.

              Overview

              In C, a string such as

              char* hello="hello";

              causes some memory to be set aside containing the six characters 'h', 'e', 'l', 'l', 'o', '\0'. A function such as strlen() works by scanning the bytes starting from the beginning, and counting until it reaches the trailing null character. If you wish to extend the string, you need to know how much memory is allocated to it.

              In Symbian platform C++ however, strings are managed using a family of classes called descriptors. The abstract descriptor classes define common interfaces for all descriptor classes. Buffer, pointer, and heap descriptor classes provide implementations of the abstract descriptor interfaces, and provide different methods of storing the data.

              Abstract descriptors

              We can represent the basic requirements for strings by two abstract classes: TDesC and TDes.

              TDesC is a constant, or non-modifiable, descriptor. It has an address and a length. Using a class like this, you can do any manipulations to a string, provided they do not alter the data. As a consequence, the TDesC class has many non-modifying functions.

              TDes is a modifiable descriptor: it has, in addition, a maximum length. This allows the data to be manipulated, extended or contracted, provided it does not exceed the maximum length. As a consequence, TDes has many modifying functions which allow string manipulation.

              It is a fundamental aspect of descriptors that they do not allow modification to exceed the allocated length. Other classes are provided to allow this, for instance CBufBase and derived classes. If a TDes function causes overflow, a panic will occur.

              Because TDesC and TDes define all the functions needed to access and manipulate string and memory data, many functions take a const TDesC& parameter if they need to access data, or a TDes& parameter if they need to modify it.

              Pointer descriptor

              The abstract descriptor classes have several implementations. The simplest are pointer descriptors.

              TPtrC just has length and address: its representation needs just two machine words. A TPtrC may be set up to describe any existing data. A TPtr adds a maximum length, and so may be used to describe a buffer which is perhaps only partially allocated.

              TPtrC and TPtr are somewhat like C char* pointers. But because the length is contained in the descriptor itself, there is no need to scan for trailing null characters, or to allocate room for them.

              Buffer descriptors

              Buffer descriptors, TBufC and TBuf, contain their data as part of themselves, like char[] arrays in C.

              These descriptor classes exploit C++'s template mechanism, using an integer parameter to specify the length.

              Heap descriptors

              Heap descriptors contain their data in heap cell. These are used when you do not know the length required for a buffer at build time, but decide it at run-time. This is like (char*) malloc(length+1) in C.

              The non-modifiable heap descriptor type, HBufC, is allocated on the heap. They are always referred to through an HBufC*, rather than an HBufC directly:

              The modifiable heap descriptor type, RBuf, can be created on the stack, but contains a pointer to data on the heap. This is similar to a TPtr pointer descriptor, but an RBuf owns the data that it points to, and is responsible for freeing the memory when it is closed. An RBuf object can allocate its own buffer, take ownership of a pre-existing section of allocated memory, or take ownership of a pre-existing heap descriptor.

              RBuf is easier to use than HBufC, so should generally be preferred. RBuf was only introduced in version 8.0, however, so older code and APIs use HBufC.

              Descriptor classes

              The complete descriptor class hierarchy is

              It represents an elegant use of OO. The TBufCBase class is used as an implementation convenience, which is also a frequent OO idiom (though it should be used with caution).

              Versions of the descriptors classes are available that store 16-bit or 8-bit wide items. When using descriptors for strings, you should always use classes such as TDes etc. These classes are typedef ed to use the 16-bit implementations, such as TDes16 etc.

              Because descriptors may contain any data, including nulls, they may also be used to refer to byte data and general buffers. In these contexts, you should use the 8-bit implementations, such as TDes8, directly.

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9C57F0C6-E2E3-58A2-907D-924A7E22EA97-GENID-1-11-1-1-5-1-4-1.dita --- a/Symbian3/SDK/Source/GUID-9C57F0C6-E2E3-58A2-907D-924A7E22EA97-GENID-1-11-1-1-5-1-4-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,94 +0,0 @@ - - - - - -Resource -compiler tool: rcomp -
              Purpose

              The -resource compiler, rcomp, compiles source rss resource -files into a rsc resource data file which can be used -by applications, and a rsg resource header file. The -operation of the resource compiler is usually wrapped in an abld batch -file. That provides the most commonly used rcomp functionality, -but does not provide some of the debugging options available directly through rcomp.

              Note: -From Symbian^4 onwards, rcomp supports long strings and -supplementary characters (not included in code point range of BMP) of the -range 0x10000 to 0x10ffff in rss files.

              -
              Command line syntaxrcomp [—v] [—p] [—l] -[—force] [—u] [—o DataOutputFile] [-{uid2,uid3 }] -[—h HeaderOutputFile] [—s SourceFileName] -[—i BaseInputFileName]

              Arguments

              - - - -

              -v

              -

              verbose output.

              -               - -

              -p

              -

              parser debugging

              -               - -

              -l

              -

              Check localisation comments

              -               - -

              -force

              -

              Emit warnings if the localisation comment tags are not present

              -               - -

              -u

              -

              generate Unicode resource binary

              -               - -

              -o DataOutputFile

              -

              Specify full path and name for data output file DataOutputFile. -If this is not specified, no data output file is created.

              -               - -

              [-{uid2,uid3 }]

              -

              Second and third UIDs for the resource file

              -               - -

              -h HeaderOutputFile

              -

              Specify header output file HeaderOutputFile; -this is the name only, and does not include the path. If this is not specified, -no header output file is created.

              -               - -

              -s SourceFileName

              -

              Specify resource compiler source file SourceFileName (output -of pre-processor BaseInputFileName.rpp). If not specified, -or specified as -s-, source is read from the standard input.

              -               - -

              -i BaseInputFileName

              -

              The file given to the pre-processor

              -               - - -

              Output files

              - - - -

              DataOutputFile

              -

              The resource data referred to by the application at run-time. Note -that the generated file can have any name. However, before the resource file -can be used it must be renamed to have an extension .rsc.

              -               - -

              HeaderOutputFile

              -

              The generated header file, which contains #define statements -for each resource defined in the source file.

              -               - - -
              -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9C57F0C6-E2E3-58A2-907D-924A7E22EA97-GENID-1-13-1-1-5-1-4-1.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-9C57F0C6-E2E3-58A2-907D-924A7E22EA97-GENID-1-13-1-1-5-1-4-1.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,94 @@ + + + + + +Resource +compiler tool: rcomp +
              Purpose

              The +resource compiler, rcomp, compiles source rss resource +files into a rsc resource data file which can be used +by applications, and a rsg resource header file. The +operation of the resource compiler is usually wrapped in an abld batch +file. That provides the most commonly used rcomp functionality, +but does not provide some of the debugging options available directly through rcomp.

              Note: +From Symbian^4 onwards, rcomp supports long strings and +supplementary characters (not included in code point range of BMP) of the +range 0x10000 to 0x10ffff in rss files.

              +
              Command line syntaxrcomp [—v] [—p] [—l] +[—force] [—u] [—o DataOutputFile] [-{uid2,uid3 }] +[—h HeaderOutputFile] [—s SourceFileName] +[—i BaseInputFileName]

              Arguments

              + + + +

              -v

              +

              verbose output.

              +               + +

              -p

              +

              parser debugging

              +               + +

              -l

              +

              Check localisation comments

              +               + +

              -force

              +

              Emit warnings if the localisation comment tags are not present

              +               + +

              -u

              +

              generate Unicode resource binary

              +               + +

              -o DataOutputFile

              +

              Specify full path and name for data output file DataOutputFile. +If this is not specified, no data output file is created.

              +               + +

              [-{uid2,uid3 }]

              +

              Second and third UIDs for the resource file

              +               + +

              -h HeaderOutputFile

              +

              Specify header output file HeaderOutputFile; +this is the name only, and does not include the path. If this is not specified, +no header output file is created.

              +               + +

              -s SourceFileName

              +

              Specify resource compiler source file SourceFileName (output +of pre-processor BaseInputFileName.rpp). If not specified, +or specified as -s-, source is read from the standard input.

              +               + +

              -i BaseInputFileName

              +

              The file given to the pre-processor

              +               + + +

              Output files

              + + + +

              DataOutputFile

              +

              The resource data referred to by the application at run-time. Note +that the generated file can have any name. However, before the resource file +can be used it must be renamed to have an extension .rsc.

              +               + +

              HeaderOutputFile

              +

              The generated header file, which contains #define statements +for each resource defined in the source file.

              +               + + +
              +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9C837724-B00E-58F4-8B71-53ECDBFF5CCE_d0e376410_href.png Binary file Symbian3/SDK/Source/GUID-9C837724-B00E-58F4-8B71-53ECDBFF5CCE_d0e376410_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9C837724-B00E-58F4-8B71-53ECDBFF5CCE_d0e382477_href.png Binary file Symbian3/SDK/Source/GUID-9C837724-B00E-58F4-8B71-53ECDBFF5CCE_d0e382477_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9C848E60-DD02-4787-90F3-1857AC3C3D1A_d0e68886_href.png Binary file Symbian3/SDK/Source/GUID-9C848E60-DD02-4787-90F3-1857AC3C3D1A_d0e68886_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9CC5E096-74FB-59AB-BAB9-A5486B961B7D_d0e262298_href.png Binary file Symbian3/SDK/Source/GUID-9CC5E096-74FB-59AB-BAB9-A5486B961B7D_d0e262298_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9CC5E096-74FB-59AB-BAB9-A5486B961B7D_d0e266006_href.png Binary file Symbian3/SDK/Source/GUID-9CC5E096-74FB-59AB-BAB9-A5486B961B7D_d0e266006_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9D2752D1-4153-5978-A7B8-4C3F860B6B87_d0e264555_href.png Binary file Symbian3/SDK/Source/GUID-9D2752D1-4153-5978-A7B8-4C3F860B6B87_d0e264555_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9D2752D1-4153-5978-A7B8-4C3F860B6B87_d0e268263_href.png Binary file Symbian3/SDK/Source/GUID-9D2752D1-4153-5978-A7B8-4C3F860B6B87_d0e268263_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9D3637D4-43BD-51ED-B4BC-1F234F09E24B.dita --- a/Symbian3/SDK/Source/GUID-9D3637D4-43BD-51ED-B4BC-1F234F09E24B.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-9D3637D4-43BD-51ED-B4BC-1F234F09E24B.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,198 +1,198 @@ - - - - - -How -to construct and manipulate a singly linked listCode fragments showing how to create a singly linked list and how -to manipulate the list and the elements of the list. -

              The following code fragments show how a singly linked list can be constructed -and manipulated. The list consists of instances of an example class, CItem, -which forms items on a stack implemented as a singly linked list using the iSlink data -member as the link object. In this example, a CItem object -can contain an item of text implemented as an HBufC.

              -

              The class is declared as:

              -class CItem : public CBase - { -public : - static CItem* NewL(const TDesC& aText); - static CItem* NewLC(const TDesC& aText); - CItem(); - virtual ~CItem(); - const HBufC* GetText(); -public : - static const TInt iOffset; -private : - void ConstructL(const TDesC& aText); -private : - TSglQueLink iSlink; - HBufC* iText; - friend class CStack; - }; -

              The CItem member functions are implemented as:

              -const TInt CItem::iOffset = _FOFF(CItem,iSlink); -CItem* CItem::NewLC(const TDesC& aText) - { - CItem* self = new (ELeave) CItem(); - CleanupStack::PushL(self); - self->ConstructL(aText); - return self; - } -CItem* CItem::NewL(const TDesC& aText) - { - CItem* self = CItem::NewLC(aText); - CleanupStack::Pop(); - return self; - } -void CItem::ConstructL(const TDesC& aText) - { - iText = aText.AllocL(); - } -CItem::CItem() - {} -CItem::~CItem() - { - delete iText; - } -const HBufC* CItem::GetText() - { - return (iText); - } - -

              As part of the construction process, a CItem constructs -an HBufC of the correct length and copies the content of -the descriptor parameter into it.

              -

              The stack is implemented by an instance of the example class CStack. -This maintains the stack by adding CItem objects onto the -end of the list and removing them from the end of the list. When removing -them from the end of the list, a pointer to the removed CItem object -is returned.

              -

              In this example, the list header, iStack, and the iterator, iStackIter, -are declared as data members of the class and are constructed when the CStack object -is constructed. A C++ constructor must be supplied so that iStackIter can -be constructed. (TSglQueIter has no default constructor).

              -

              AddToStack() takes a CItem object and -adds it to the end of the singly linked list.

              -

              RemoveFromStack() takes the CItem object -at the end of the singly linked list, removes it from the list and returns -a pointer to it.

              -

              The CStack class is declared as:

              -class CStack : public CBase - { -public : - static CStack* NewL(); - static CStack* NewLC(); - CStack(); - void Construct(); - virtual ~CStack(); - CItem* RemoveFromStack(); - void AddToStack(CItem& anItem); -private : - TSglQue<CItem> iStack; - TSglQueIter<CItem> iStackIter; - }; - -

              The CStack member functions are implemented as:

              -CStack* CStack::NewLC() - { - CStack* self = CStack::NewL(); - CleanupStack::PushL(self); - return self; - } -CStack* CStack::NewL() - { - CStack* self = new (ELeave) CStack; - return self; - } -CStack::CStack() - : iStack(CItem::iOffset),iStackIter(iStack) - {} -
              Using the list -iterator

              The C++ constructor is needed so that the list header -(iStack) and the list iterator (iStackIter) -can be properly constructed.

              Before destroying a CStack object, -the list is destroyed. This is achieved using the iterator (iStackIter). -The iterator pointer is set to point to each element in turn, removing that -element from the list before destroying it.

              Once the iterator has reached -the end of the list, the operator++ returns NULL.

              The -destruction process is safe if the list is empty; the statement iStackIter.SetToFirst() is -harmless, the operator++ returns NULL and -execution of the body of the while loop never happens.

              CStack::~CStack() - { - CItem* item; - - iStackIter.SetToFirst(); - while ((item = iStackIter++) != NULL) - { - iStack.Remove(*item); - delete item; - }; - }
              -
              Adding an element -to the stack

              Adding an element to the stack simply involves adding -the CItem object to the end of the list.

              void CStack::AddToStack(CItem& anItem) - { - iStack.AddLast(anItem); - }
              -
              Removing an -element from the stack

              The RemoveFromStack() function -returns NULL, if the list is empty, otherwise it just uses -the Last() member function to return a pointer to the last -element in the list before removing it.

              CItem* CStack::RemoveFromStack() - { - CItem* lastitem; - - if (iStack.IsEmpty()) - return NULL; - - lastitem = iStack.Last(); - iStack.Remove(*lastitem); - - return (lastitem); - }
              -
              Executing the -code

              Executing the code results in a singly linked list of CItem objects -each containing a pointer to an HBufC descriptor each of -which, in turn, contains the text “8”, “89”, and so on through to “89ABCDEF”:

              { - CStack* stack; - CItem* item; - TBuf<16> buffer; - - TRAPD(leavecode,stack = CStack::NewL()); - if (leavecode != KErrNone) - { - // Cannot create stack - return; - } for (TUint jj = 8; jj < 16; jj++) - { - buffer.AppendNumUC(jj,EHex); - TRAPD(leavecode,item = CItem::NewL(buffer)); - if (leavecode != KErrNone) - { - // Cannot create item - delete stack; - return; - } - stack->AddToStack(*item); - }

              as the following shows:

              -Example singly linked list - -
              -
              Removing elements -from list

              The following code removes each CItem element -from the list, starting with the last and working through to the first until -the list is empty.

              while ((item = stack->RemoveFromStack()) != NULL) - { - // item->GetText());can be used to access the text. - delete item; - }; delete stack;

              Note -that unlike doubly linked lists, elements can only be added to the start or -the end of a singly linked list. Elements cannot be added to the middle -of the list.

              + + + + + +How +to construct and manipulate a singly linked listCode fragments showing how to create a singly linked list and how +to manipulate the list and the elements of the list. +

              The following code fragments show how a singly linked list can be constructed +and manipulated. The list consists of instances of an example class, CItem, +which forms items on a stack implemented as a singly linked list using the iSlink data +member as the link object. In this example, a CItem object +can contain an item of text implemented as an HBufC.

              +

              The class is declared as:

              +class CItem : public CBase + { +public : + static CItem* NewL(const TDesC& aText); + static CItem* NewLC(const TDesC& aText); + CItem(); + virtual ~CItem(); + const HBufC* GetText(); +public : + static const TInt iOffset; +private : + void ConstructL(const TDesC& aText); +private : + TSglQueLink iSlink; + HBufC* iText; + friend class CStack; + }; +

              The CItem member functions are implemented as:

              +const TInt CItem::iOffset = _FOFF(CItem,iSlink); +CItem* CItem::NewLC(const TDesC& aText) + { + CItem* self = new (ELeave) CItem(); + CleanupStack::PushL(self); + self->ConstructL(aText); + return self; + } +CItem* CItem::NewL(const TDesC& aText) + { + CItem* self = CItem::NewLC(aText); + CleanupStack::Pop(); + return self; + } +void CItem::ConstructL(const TDesC& aText) + { + iText = aText.AllocL(); + } +CItem::CItem() + {} +CItem::~CItem() + { + delete iText; + } +const HBufC* CItem::GetText() + { + return (iText); + } + +

              As part of the construction process, a CItem constructs +an HBufC of the correct length and copies the content of +the descriptor parameter into it.

              +

              The stack is implemented by an instance of the example class CStack. +This maintains the stack by adding CItem objects onto the +end of the list and removing them from the end of the list. When removing +them from the end of the list, a pointer to the removed CItem object +is returned.

              +

              In this example, the list header, iStack, and the iterator, iStackIter, +are declared as data members of the class and are constructed when the CStack object +is constructed. A C++ constructor must be supplied so that iStackIter can +be constructed. (TSglQueIter has no default constructor).

              +

              AddToStack() takes a CItem object and +adds it to the end of the singly linked list.

              +

              RemoveFromStack() takes the CItem object +at the end of the singly linked list, removes it from the list and returns +a pointer to it.

              +

              The CStack class is declared as:

              +class CStack : public CBase + { +public : + static CStack* NewL(); + static CStack* NewLC(); + CStack(); + void Construct(); + virtual ~CStack(); + CItem* RemoveFromStack(); + void AddToStack(CItem& anItem); +private : + TSglQue<CItem> iStack; + TSglQueIter<CItem> iStackIter; + }; + +

              The CStack member functions are implemented as:

              +CStack* CStack::NewLC() + { + CStack* self = CStack::NewL(); + CleanupStack::PushL(self); + return self; + } +CStack* CStack::NewL() + { + CStack* self = new (ELeave) CStack; + return self; + } +CStack::CStack() + : iStack(CItem::iOffset),iStackIter(iStack) + {} +
              Using the list +iterator

              The C++ constructor is needed so that the list header +(iStack) and the list iterator (iStackIter) +can be properly constructed.

              Before destroying a CStack object, +the list is destroyed. This is achieved using the iterator (iStackIter). +The iterator pointer is set to point to each element in turn, removing that +element from the list before destroying it.

              Once the iterator has reached +the end of the list, the operator++ returns NULL.

              The +destruction process is safe if the list is empty; the statement iStackIter.SetToFirst() is +harmless, the operator++ returns NULL and +execution of the body of the while loop never happens.

              CStack::~CStack() + { + CItem* item; + + iStackIter.SetToFirst(); + while ((item = iStackIter++) != NULL) + { + iStack.Remove(*item); + delete item; + }; + }
              +
              Adding an element +to the stack

              Adding an element to the stack simply involves adding +the CItem object to the end of the list.

              void CStack::AddToStack(CItem& anItem) + { + iStack.AddLast(anItem); + }
              +
              Removing an +element from the stack

              The RemoveFromStack() function +returns NULL, if the list is empty, otherwise it just uses +the Last() member function to return a pointer to the last +element in the list before removing it.

              CItem* CStack::RemoveFromStack() + { + CItem* lastitem; + + if (iStack.IsEmpty()) + return NULL; + + lastitem = iStack.Last(); + iStack.Remove(*lastitem); + + return (lastitem); + }
              +
              Executing the +code

              Executing the code results in a singly linked list of CItem objects +each containing a pointer to an HBufC descriptor each of +which, in turn, contains the text “8”, “89”, and so on through to “89ABCDEF”:

              { + CStack* stack; + CItem* item; + TBuf<16> buffer; + + TRAPD(leavecode,stack = CStack::NewL()); + if (leavecode != KErrNone) + { + // Cannot create stack + return; + } for (TUint jj = 8; jj < 16; jj++) + { + buffer.AppendNumUC(jj,EHex); + TRAPD(leavecode,item = CItem::NewL(buffer)); + if (leavecode != KErrNone) + { + // Cannot create item + delete stack; + return; + } + stack->AddToStack(*item); + }

              as the following shows:

              +Example singly linked list + +
              +
              Removing elements +from list

              The following code removes each CItem element +from the list, starting with the last and working through to the first until +the list is empty.

              while ((item = stack->RemoveFromStack()) != NULL) + { + // item->GetText());can be used to access the text. + delete item; + }; delete stack;

              Note +that unlike doubly linked lists, elements can only be added to the start or +the end of a singly linked list. Elements cannot be added to the middle +of the list.

               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9D5641BC-226B-538F-B805-48511781B7C1_d0e334781_href.jpg Binary file Symbian3/SDK/Source/GUID-9D5641BC-226B-538F-B805-48511781B7C1_d0e334781_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9D5641BC-226B-538F-B805-48511781B7C1_d0e340938_href.jpg Binary file Symbian3/SDK/Source/GUID-9D5641BC-226B-538F-B805-48511781B7C1_d0e340938_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9D6C086F-7621-5522-AE0B-81CBD5E99125.dita --- a/Symbian3/SDK/Source/GUID-9D6C086F-7621-5522-AE0B-81CBD5E99125.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-9D6C086F-7621-5522-AE0B-81CBD5E99125.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,18 +1,18 @@ - - - - - -Bitmap Transform Library GuideThis topic provides more detailed information about and code snippets for the Bitmap Transform library.
              Purpose

              Bitmap Transform makes it possible for bitmap images to be resized and rotated as described below.

              Introducing Bitmap Transformation

              The resizing or scale (CBitmapScaler) and rotation (CBitmapRotator) actions are asynchronous operations that take a pointer to a TRequestStatus object, which is signalled on completion of the requested action. The client application or calling DLL will hold the TRequestStatus values within active objects. As with any use of an active object it is necessary to have an active scheduler present in the same thread as the application making use of the object.

              Note: CBitmapScaler and CBitmapRotator are not able them to run in their own thread.

              Bitmap Transformation Example - Bitmap scaling

              There are two variants of the CBitmapScaler::Scale() function. The first variant performs rescaling on an image contained in one CFbsBitmap object and places the result in another object. The second variant rescales an image contained in a CFbsBitmap object and places the result back in the same object. This is illustrated below.

              void Scale(TRequestStatus* aRequestStatus, CFbsBitmap& aSrcBitmap, CFbsBitmap& aTgtBitmap, TBool aMaintainAspectRatio = ETrue); -void Scale(TRequestStatus* aRequestStatus, CFbsBitmap& aBitmap, const TSize& aDestinationSize, TBool aMaintainAspectRatio = ETrue);

              If two CFbsBitmap objects are specified in the scale operation, the dimensions of the destination object are used as the rescaling factors, subject to the aspect ratio setting (described below).

              If only the one CFbsBitmap object is specified in the scale operation, the scaling factor is taken from TSize subject to the aspect ratio setting.

              The aspect ratio is maintained if aMaintainAspectRatio is ETrue. If the ratio is used, then the image is rescaled to the smaller of the horizontal and vertical scaling factors. This is best explained by use of an example.

              In this example, the source image is 50 pixels wide by 150 pixels high (an aspect ratio of 1:3), aMaintainAspectRatio is set to ETrue, and the proposed rescaling is to 75 pixels wide by 300 high. Applying this ratio to the smaller of the horizontal and vertical factors means using a new value for the larger rescaling factor so that the aspect ratio matches that of the source image. The smaller value is 75 pixels, the aspect ratio required is 1:3 so the larger value will be 75*3 which is 225. The image will be rescaled to 75 wide by 225 high.

              Bitmap Transformation Example - Bitmap rotation

              There are two variants of the CBitmapScaler::Rotate() function. The first performs a rotational action on an image contained in one CFbsBitmap object and places the result in another object. The second variant performs a rotational action on an image contained in a CFbsBitmap object and places the result back in the same object. Valid rotational increments are specified in CBitmapRotator::TRotationAngle.

              Note: CBitmapScaler::Rotate() does not support user specified rotational angles. The only values allowed are those specified in CBitmapRotator::TRotationAngle.

              void Rotate(TRequestStatus* aRequestStatus, CFbsBitmap& aSrcBitmap, CFbsBitmap& aTgtBitmap, TRotationAngle aAngle); - -void Rotate(TRequestStatus* aRequestStatus, CFbsBitmap& aBitmap, TRotationAngle aAngle); -

              ERotation90DegreesClockwise

              ERotation180DegreesClockwise

              ERotation270DegreesClockwise

              EMirrorHorizontalAxis

              EMirrorVerticalAxis

              Imaging Frameworks overview Bitmap Transform Library - Overview Bitmap Transform Library Guide Enhanced Features for Encoder and + + + + + +Bitmap Transform Library GuideThis topic provides more detailed information about and code snippets for the Bitmap Transform library.
              Purpose

              Bitmap Transform makes it possible for bitmap images to be resized and rotated as described below.

              Introducing Bitmap Transformation

              The resizing or scale (CBitmapScaler) and rotation (CBitmapRotator) actions are asynchronous operations that take a pointer to a TRequestStatus object, which is signalled on completion of the requested action. The client application or calling DLL will hold the TRequestStatus values within active objects. As with any use of an active object it is necessary to have an active scheduler present in the same thread as the application making use of the object.

              Note: CBitmapScaler and CBitmapRotator are not able them to run in their own thread.

              Bitmap Transformation Example - Bitmap scaling

              There are two variants of the CBitmapScaler::Scale() function. The first variant performs rescaling on an image contained in one CFbsBitmap object and places the result in another object. The second variant rescales an image contained in a CFbsBitmap object and places the result back in the same object. This is illustrated below.

              void Scale(TRequestStatus* aRequestStatus, CFbsBitmap& aSrcBitmap, CFbsBitmap& aTgtBitmap, TBool aMaintainAspectRatio = ETrue); +void Scale(TRequestStatus* aRequestStatus, CFbsBitmap& aBitmap, const TSize& aDestinationSize, TBool aMaintainAspectRatio = ETrue);

              If two CFbsBitmap objects are specified in the scale operation, the dimensions of the destination object are used as the rescaling factors, subject to the aspect ratio setting (described below).

              If only the one CFbsBitmap object is specified in the scale operation, the scaling factor is taken from TSize subject to the aspect ratio setting.

              The aspect ratio is maintained if aMaintainAspectRatio is ETrue. If the ratio is used, then the image is rescaled to the smaller of the horizontal and vertical scaling factors. This is best explained by use of an example.

              In this example, the source image is 50 pixels wide by 150 pixels high (an aspect ratio of 1:3), aMaintainAspectRatio is set to ETrue, and the proposed rescaling is to 75 pixels wide by 300 high. Applying this ratio to the smaller of the horizontal and vertical factors means using a new value for the larger rescaling factor so that the aspect ratio matches that of the source image. The smaller value is 75 pixels, the aspect ratio required is 1:3 so the larger value will be 75*3 which is 225. The image will be rescaled to 75 wide by 225 high.

              Bitmap Transformation Example - Bitmap rotation

              There are two variants of the CBitmapScaler::Rotate() function. The first performs a rotational action on an image contained in one CFbsBitmap object and places the result in another object. The second variant performs a rotational action on an image contained in a CFbsBitmap object and places the result back in the same object. Valid rotational increments are specified in CBitmapRotator::TRotationAngle.

              Note: CBitmapScaler::Rotate() does not support user specified rotational angles. The only values allowed are those specified in CBitmapRotator::TRotationAngle.

              void Rotate(TRequestStatus* aRequestStatus, CFbsBitmap& aSrcBitmap, CFbsBitmap& aTgtBitmap, TRotationAngle aAngle); + +void Rotate(TRequestStatus* aRequestStatus, CFbsBitmap& aBitmap, TRotationAngle aAngle); +

              ERotation90DegreesClockwise

              ERotation180DegreesClockwise

              ERotation270DegreesClockwise

              EMirrorHorizontalAxis

              EMirrorVerticalAxis

              Imaging Frameworks overview Bitmap Transform Library + Overview Bitmap Transform Library Guide Enhanced Features for Encoder and Decoder Tutorial               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9D6D07D3-A93C-5290-AC08-15750AD34802_d0e402571_href.png Binary file Symbian3/SDK/Source/GUID-9D6D07D3-A93C-5290-AC08-15750AD34802_d0e402571_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9D6D07D3-A93C-5290-AC08-15750AD34802_d0e402733_href.png Binary file Symbian3/SDK/Source/GUID-9D6D07D3-A93C-5290-AC08-15750AD34802_d0e402733_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9DCAB1DC-D085-576C-A0B9-713E3BF2CAD5_d0e210051_href.png Binary file Symbian3/SDK/Source/GUID-9DCAB1DC-D085-576C-A0B9-713E3BF2CAD5_d0e210051_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9DCAB1DC-D085-576C-A0B9-713E3BF2CAD5_d0e214846_href.png Binary file Symbian3/SDK/Source/GUID-9DCAB1DC-D085-576C-A0B9-713E3BF2CAD5_d0e214846_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9DD43E77-FB3D-5931-899B-F17198F726D0_d0e272117_href.jpg Binary file Symbian3/SDK/Source/GUID-9DD43E77-FB3D-5931-899B-F17198F726D0_d0e272117_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9DD43E77-FB3D-5931-899B-F17198F726D0_d0e275798_href.jpg Binary file Symbian3/SDK/Source/GUID-9DD43E77-FB3D-5931-899B-F17198F726D0_d0e275798_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9DE1CE5D-F148-5A7E-908A-DDD57A32C629.dita --- a/Symbian3/SDK/Source/GUID-9DE1CE5D-F148-5A7E-908A-DDD57A32C629.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,12 +0,0 @@ - - - - - -Camera API

              This document gives you more information about the Camera API.

              Purpose

              The clients can use the Camera API to access the camera on a phone. This includes configuring the camera, running viewfinder and capturing still images and video.

              Note: The functionality that can be obtained through the API is camera hardware dependent. The API includes functions that you should call to check if functionality is available before using it.

              Required Background

              The camera client is a component of the Multimedia subsystem.

              Introduction

              Ecam is an API which allows an application to access and control any camera hardware which is attached to the device. The API provides functions to query the status of the camera, adjust camera settings, and capture still images and video.

              Using Camera

              The camera can be used for:

              • Capturing still images

              • Capturing video

              What's Next?

              The following tasks will be covered in this tutorial series:

              • Accessing and Power Control of Camera

              • Capturing Image

              • Capturing Video

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9E00A9B2-9656-5569-B164-B7EFD2B2A9F6.dita --- a/Symbian3/SDK/Source/GUID-9E00A9B2-9656-5569-B164-B7EFD2B2A9F6.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,12 +0,0 @@ - - - - - -Example Code

              An example application that demonstrates the use of the Camera Frameworks is shown below:

              \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9E0C8892-E67F-4DC9-8253-2F65611AD4C6_d0e66389_href.png Binary file Symbian3/SDK/Source/GUID-9E0C8892-E67F-4DC9-8253-2F65611AD4C6_d0e66389_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9E0C8892-E67F-4DC9-8253-2F65611AD4C6_d0e71631_href.png Binary file Symbian3/SDK/Source/GUID-9E0C8892-E67F-4DC9-8253-2F65611AD4C6_d0e71631_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9E12593C-38EF-5052-A2E8-0AB25EEFF4D0_d0e304473_href.jpg Binary file Symbian3/SDK/Source/GUID-9E12593C-38EF-5052-A2E8-0AB25EEFF4D0_d0e304473_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9E12593C-38EF-5052-A2E8-0AB25EEFF4D0_d0e310488_href.jpg Binary file Symbian3/SDK/Source/GUID-9E12593C-38EF-5052-A2E8-0AB25EEFF4D0_d0e310488_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9E2AEFF3-6C6E-5F09-B5C0-A70AECB421B0-GENID-1-8-1-3-1-1-7-1-7-1-10-1.dita --- a/Symbian3/SDK/Source/GUID-9E2AEFF3-6C6E-5F09-B5C0-A70AECB421B0-GENID-1-8-1-3-1-1-7-1-7-1-10-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,81 +0,0 @@ - - - - - -Text -and Zooming -
              Text Style and Colour

              Note that the following does -not yet apply for S60 and MOAP.

              The style (plain, bold, shadowed etc.) -and colour of text in a control typically depends upon the state or properties -of its parent control. Prior to Symbian OS 9.1 a control was able to use the MCoeControlContext interface -to share properties. That interface is now deprecated. Text is now drawn using -a Text Drawer. The Text Drawer takes the text itself as a parameter along -with the font, graphics context and text location rectangle.

              The text -drawer is provided by the run-time hierarchy. Each control in the hierarchy, -from the topmost downwards, has the option of modifying or replacing the text -drawer.

              Text drawers are derived from CCoeTextDrawerBase (a -default CCoePlainTextDrawer is provided by Cone) and require -special use to avoid multiple allocations on the heap. Instead of being allocated -directly text drawers must be used through the XCoeTextDrawer class -which acts as a smart-pointer to a single CCoeTextDrawerBase derived -class on the heap. The smart-pointer deletes or resets the text drawer on -the heap if necessary and provides fail-safe measures to ensure that a valid -text drawer is returned.

              A control that draws text calls its TextDrawer() function -to retrieve the appropriate text drawer from the run-time hierarchy

              XCoeTextDrawer textDrawer( TextDrawer() ); -textDrawer->SetAlignment( iAlignment ); -textDrawer->SetMargins( iMargin ); -textDrawer->SetLineGapInPixels( iGapBetweenLines ); -textDrawer.SetClipRect( aRect ); - -textDrawer.DrawText( gc, *iTextToDraw, Rect(), *Font() ); -

              Note that XCoeTextDrawer's ->() operator -is overriden to return a pointer to the CCoeTextDrawerBase object. -i.e.

              - textDrawer->SetAlignment(iAlignment); -

              is equivalent to

              - textDrawer.(iTextDrawer*).SetAlignment(iAlignment); -

              Unfortunately, as SetClipRect() is not a function -of CCoeTextDrawerBase, but of XCoeTextDrawer, -it can only be accessed through the . [dot] operator. There are worse things -in life.

              A control that wishes to provide its own text drawer, or to -modify its parent's text drawer, may do so by providing its own implementation -of the virtual function GetTextDrawer().

              -
              Fonts

              The control framework provides a mechanism -for delivering the correct font at run-time. The mechanism consists of a Font -Provider (CCoeFontProvider) and a TCoeFont class, -which represents a font's size (logical or absolute in pixels) and style (plain, -bold, italic, subscript or superscript). Along similar lines to the Text Drawer, -the Font Provider is attached to a parent control and serves controls further -down the run-time hierarchy.

              CCoeEnv includes a -default CCoeFontProvider: UI-variant specific libraries -are expected to provide their own.

              The desired font is affected by -the control's zoom state (see below) which must be included when requesting -a font from a font provider.

              CCoeControl includes -a ScreenFont() method which encapsulates the font -provider and zoom APIs to provide a simple means of obtaining a CFont object -for drawing text.

              The final line of the code snippet above should, -therefore, look like this:

              textDrawer.DrawText(gc, *iTextToDraw, Rect(), ScreenFont(TCoeFont::NormalFont());

              Controls must not keep references or pointers to CFont objects -in member data. Nor should they use the CCoeEnv functions NormalFont(), LegendFont(), TitleFont(), AnnotationFont() and DenseFont(). -Moreover, instances of these calls should be removed from old code and replaced -with code like that above. This is so that run-time font changes can be propagated -and is essential for zoom support.

              -
              Zooming

              Each control may have a TZoomFactor attached. -It applies to the control itself and all of its component controls. The factor -can be absolute or relative to a control's parent and influences the size -of the font in the control and all of its children.

              CCoeControl has -an AccumulatedZoom() function which aggregates its own zoom -factor with those of its parents.

              -
              See also
                -

              • Run-time control -hierarchy

                • -

              • How to write -controls

                • -
              -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9E2AEFF3-6C6E-5F09-B5C0-A70AECB421B0-GENID-1-8-1-6-1-1-4-1-6-1-7-1-10-1.dita --- a/Symbian3/SDK/Source/GUID-9E2AEFF3-6C6E-5F09-B5C0-A70AECB421B0-GENID-1-8-1-6-1-1-4-1-6-1-7-1-10-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,81 +0,0 @@ - - - - - -Text -and Zooming -
              Text Style and Colour

              Note that the following does -not yet apply for S60 and MOAP.

              The style (plain, bold, shadowed etc.) -and colour of text in a control typically depends upon the state or properties -of its parent control. Prior to Symbian OS 9.1 a control was able to use the MCoeControlContext interface -to share properties. That interface is now deprecated. Text is now drawn using -a Text Drawer. The Text Drawer takes the text itself as a parameter along -with the font, graphics context and text location rectangle.

              The text -drawer is provided by the run-time hierarchy. Each control in the hierarchy, -from the topmost downwards, has the option of modifying or replacing the text -drawer.

              Text drawers are derived from CCoeTextDrawerBase (a -default CCoePlainTextDrawer is provided by Cone) and require -special use to avoid multiple allocations on the heap. Instead of being allocated -directly text drawers must be used through the XCoeTextDrawer class -which acts as a smart-pointer to a single CCoeTextDrawerBase derived -class on the heap. The smart-pointer deletes or resets the text drawer on -the heap if necessary and provides fail-safe measures to ensure that a valid -text drawer is returned.

              A control that draws text calls its TextDrawer() function -to retrieve the appropriate text drawer from the run-time hierarchy

              XCoeTextDrawer textDrawer( TextDrawer() ); -textDrawer->SetAlignment( iAlignment ); -textDrawer->SetMargins( iMargin ); -textDrawer->SetLineGapInPixels( iGapBetweenLines ); -textDrawer.SetClipRect( aRect ); - -textDrawer.DrawText( gc, *iTextToDraw, Rect(), *Font() ); -

              Note that XCoeTextDrawer's ->() operator -is overriden to return a pointer to the CCoeTextDrawerBase object. -i.e.

              - textDrawer->SetAlignment(iAlignment); -

              is equivalent to

              - textDrawer.(iTextDrawer*).SetAlignment(iAlignment); -

              Unfortunately, as SetClipRect() is not a function -of CCoeTextDrawerBase, but of XCoeTextDrawer, -it can only be accessed through the . [dot] operator. There are worse things -in life.

              A control that wishes to provide its own text drawer, or to -modify its parent's text drawer, may do so by providing its own implementation -of the virtual function GetTextDrawer().

              -
              Fonts

              The control framework provides a mechanism -for delivering the correct font at run-time. The mechanism consists of a Font -Provider (CCoeFontProvider) and a TCoeFont class, -which represents a font's size (logical or absolute in pixels) and style (plain, -bold, italic, subscript or superscript). Along similar lines to the Text Drawer, -the Font Provider is attached to a parent control and serves controls further -down the run-time hierarchy.

              CCoeEnv includes a -default CCoeFontProvider: UI-variant specific libraries -are expected to provide their own.

              The desired font is affected by -the control's zoom state (see below) which must be included when requesting -a font from a font provider.

              CCoeControl includes -a ScreenFont() method which encapsulates the font -provider and zoom APIs to provide a simple means of obtaining a CFont object -for drawing text.

              The final line of the code snippet above should, -therefore, look like this:

              textDrawer.DrawText(gc, *iTextToDraw, Rect(), ScreenFont(TCoeFont::NormalFont());

              Controls must not keep references or pointers to CFont objects -in member data. Nor should they use the CCoeEnv functions NormalFont(), LegendFont(), TitleFont(), AnnotationFont() and DenseFont(). -Moreover, instances of these calls should be removed from old code and replaced -with code like that above. This is so that run-time font changes can be propagated -and is essential for zoom support.

              -
              Zooming

              Each control may have a TZoomFactor attached. -It applies to the control itself and all of its component controls. The factor -can be absolute or relative to a control's parent and influences the size -of the font in the control and all of its children.

              CCoeControl has -an AccumulatedZoom() function which aggregates its own zoom -factor with those of its parents.

              -
              See also
                -

              • Run-time control -hierarchy

                • -

              • How to write -controls

                • -
              -               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9E2AEFF3-6C6E-5F09-B5C0-A70AECB421B0.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-9E2AEFF3-6C6E-5F09-B5C0-A70AECB421B0.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,81 @@ + + + + + +Text +and Zooming +
              Text Style and Colour

              Note that the following does +not yet apply for S60 and MOAP.

              The style (plain, bold, shadowed etc.) +and colour of text in a control typically depends upon the state or properties +of its parent control. Prior to Symbian OS 9.1 a control was able to use the MCoeControlContext interface +to share properties. That interface is now deprecated. Text is now drawn using +a Text Drawer. The Text Drawer takes the text itself as a parameter along +with the font, graphics context and text location rectangle.

              The text +drawer is provided by the run-time hierarchy. Each control in the hierarchy, +from the topmost downwards, has the option of modifying or replacing the text +drawer.

              Text drawers are derived from CCoeTextDrawerBase (a +default CCoePlainTextDrawer is provided by Cone) and require +special use to avoid multiple allocations on the heap. Instead of being allocated +directly text drawers must be used through the XCoeTextDrawer class +which acts as a smart-pointer to a single CCoeTextDrawerBase derived +class on the heap. The smart-pointer deletes or resets the text drawer on +the heap if necessary and provides fail-safe measures to ensure that a valid +text drawer is returned.

              A control that draws text calls its TextDrawer() function +to retrieve the appropriate text drawer from the run-time hierarchy

              XCoeTextDrawer textDrawer( TextDrawer() ); +textDrawer->SetAlignment( iAlignment ); +textDrawer->SetMargins( iMargin ); +textDrawer->SetLineGapInPixels( iGapBetweenLines ); +textDrawer.SetClipRect( aRect ); + +textDrawer.DrawText( gc, *iTextToDraw, Rect(), *Font() ); +

              Note that XCoeTextDrawer's ->() operator +is overriden to return a pointer to the CCoeTextDrawerBase object. +i.e.

              + textDrawer->SetAlignment(iAlignment); +

              is equivalent to

              + textDrawer.(iTextDrawer*).SetAlignment(iAlignment); +

              Unfortunately, as SetClipRect() is not a function +of CCoeTextDrawerBase, but of XCoeTextDrawer, +it can only be accessed through the . [dot] operator. There are worse things +in life.

              A control that wishes to provide its own text drawer, or to +modify its parent's text drawer, may do so by providing its own implementation +of the virtual function GetTextDrawer().

              +
              Fonts

              The control framework provides a mechanism +for delivering the correct font at run-time. The mechanism consists of a Font +Provider (CCoeFontProvider) and a TCoeFont class, +which represents a font's size (logical or absolute in pixels) and style (plain, +bold, italic, subscript or superscript). Along similar lines to the Text Drawer, +the Font Provider is attached to a parent control and serves controls further +down the run-time hierarchy.

              CCoeEnv includes a +default CCoeFontProvider: UI-variant specific libraries +are expected to provide their own.

              The desired font is affected by +the control's zoom state (see below) which must be included when requesting +a font from a font provider.

              CCoeControl includes +a ScreenFont() method which encapsulates the font +provider and zoom APIs to provide a simple means of obtaining a CFont object +for drawing text.

              The final line of the code snippet above should, +therefore, look like this:

              textDrawer.DrawText(gc, *iTextToDraw, Rect(), ScreenFont(TCoeFont::NormalFont());

              Controls must not keep references or pointers to CFont objects +in member data. Nor should they use the CCoeEnv functions NormalFont(), LegendFont(), TitleFont(), AnnotationFont() and DenseFont(). +Moreover, instances of these calls should be removed from old code and replaced +with code like that above. This is so that run-time font changes can be propagated +and is essential for zoom support.

              +
              Zooming

              Each control may have a TZoomFactor attached. +It applies to the control itself and all of its component controls. The factor +can be absolute or relative to a control's parent and influences the size +of the font in the control and all of its children.

              CCoeControl has +an AccumulatedZoom() function which aggregates its own zoom +factor with those of its parents.

              +
              See also
                +

              • Run-time control +hierarchy

                • +

              • How to write +controls

                • +
              +               \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9E3ADEB4-C000-525D-B220-2BAFF5DC6B0C.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-9E3ADEB4-C000-525D-B220-2BAFF5DC6B0C.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,82 @@ + + + + + +Password Based Encryption (PBE) example support code

              Below is the supporting code for the PBE example code.

              <codeblock id="GUID-E9CCC5E6-FDB6-53A0-B7F3-85CFD57FE290" xml:space="preserve"> +#include "e32std.h" +#include "f32file.h" +#include "s32file.h" +#include "pbe.h" +#include "pbedata.h" + </codeblock> <codeblock id="GUID-A6FDAAD3-8418-59BD-BE62-6F4C31F0F3CF" xml:space="preserve"> +/* + * Class to demonstrate the use of the PBE API. + */ +class CPBEExample : public CBase + { +public: + static CPBEExample* NewLC(); + virtual ~CPBEExample(); + + void WriteEncryptedDataL(const TDesC8& aInput, const TDesC& aFilename, const TDesC& aPassword); + HBufC8* ReadEncryptedDataLC(const TDesC& aFilename, const TDesC& aPassword); +private: + CPBEExample(); + void ConstructL(); +private: + RFs iFs; + }; + </codeblock> <codeblock id="GUID-4F7B60AF-62C3-55B3-B1F9-3084D68A97AB" xml:space="preserve"> +CPBEExample* CPBEExample::NewLC() + { + CPBEExample* self = new (ELeave) CPBEExample(); + CleanupStack::PushL(self); + self->ConstructL(); + return self; + } + +CPBEExample::CPBEExample() + { + } + +void CPBEExample::ConstructL() + { + User::LeaveIfError(iFs.Connect()); + } + +CPBEExample::~CPBEExample() + { + iFs.Close(); + } + </codeblock> <codeblock id="GUID-17DECEE0-FE01-5F1F-9143-02462DE3C418" xml:space="preserve"> +LOCAL_D void RunPBEExampleL() + { + _LIT(KFilename, "c:\\pbe_example_data.dat"); + _LIT8(KInputData, "This is the data to be encrypted"); + _LIT(KPassword, "pa55w0rd"); + + CPBEExample* main = CPBEExample::NewLC(); + main->WriteEncryptedDataL(KInputData, KFilename, KPassword); + HBufC8* outputData = main->ReadEncryptedDataLC(KFilename, KPassword); + ASSERT(*outputData == KInputData); + CleanupStack::PopAndDestroy(2, main); + } + </codeblock> <codeblock id="GUID-589330F6-B593-5722-AD3B-73CA53BEDB76" xml:space="preserve"> +GLDEF_C TInt E32Main() // main function called by E32 + { + __UHEAP_MARK; + CTrapCleanup* cleanup = CTrapCleanup::New(); // get clean-up stack + TRAPD(error, RunPBEExampleL()); + __ASSERT_ALWAYS(!error,User::Panic(_L("pbe_example_code"),error)); + delete cleanup; // destroy clean-up stack + __UHEAP_MARKEND; + return 0; + } + </codeblock> </section> </conbody></concept> \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9E3D71A2-34FA-5A66-B0B9-550816021D79_d0e356932_href.png Binary file Symbian3/SDK/Source/GUID-9E3D71A2-34FA-5A66-B0B9-550816021D79_d0e356932_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9E3D71A2-34FA-5A66-B0B9-550816021D79_d0e363012_href.png Binary file Symbian3/SDK/Source/GUID-9E3D71A2-34FA-5A66-B0B9-550816021D79_d0e363012_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9E705383-5D3F-45D9-82F7-EB76112F2800-master.png Binary file Symbian3/SDK/Source/GUID-9E705383-5D3F-45D9-82F7-EB76112F2800-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9E705383-5D3F-45D9-82F7-EB76112F2800_d0e52568_href.png Binary file Symbian3/SDK/Source/GUID-9E705383-5D3F-45D9-82F7-EB76112F2800_d0e52568_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9E705383-5D3F-45D9-82F7-EB76112F2800_d0e58503_href.png Binary file Symbian3/SDK/Source/GUID-9E705383-5D3F-45D9-82F7-EB76112F2800_d0e58503_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9E9C00E1-00A2-5248-946B-D3AE182F44EC_d0e278090_href.jpg Binary file Symbian3/SDK/Source/GUID-9E9C00E1-00A2-5248-946B-D3AE182F44EC_d0e278090_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9E9C00E1-00A2-5248-946B-D3AE182F44EC_d0e281776_href.jpg Binary file Symbian3/SDK/Source/GUID-9E9C00E1-00A2-5248-946B-D3AE182F44EC_d0e281776_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9EE78D5A-32BC-5E0F-9139-AF00CDB95CC1.dita --- a/Symbian3/SDK/Source/GUID-9EE78D5A-32BC-5E0F-9139-AF00CDB95CC1.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-9EE78D5A-32BC-5E0F-9139-AF00CDB95CC1.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,15 +1,15 @@ -<?xml version="1.0" encoding="utf-8"?> -<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> -<!-- This component and the accompanying materials are made available under the terms of the License -"Eclipse Public License v1.0" which accompanies this distribution, -and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> -<!-- Initial Contributors: - Nokia Corporation - initial contribution. -Contributors: ---> -<!DOCTYPE concept - PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> -<concept xml:lang="en" id="GUID-9EE78D5A-32BC-5E0F-9139-AF00CDB95CC1"><title>How to use the audio tone player utility

              The Audio Tone Player, provided by the class CMdaAudioToneUtility, has an interface for generating the following tones on all audio capable devices. Using this class you can play the following tones:

              • Single tone of a specified duration and frequency

              • Dual Tone Multi Frequency (DTMF) strings

              • Sequences of tones held in files or descriptors

              • Predefined (fixed) sequences of tones held in any mobile equipment

              Client applications such as ringtone applications, use CMdaAudioToneUtility to generate the tones they produce. The tone player in turn uses MMF for playing sounds and is also credited for interfacing with the audio hardware. An active scheduler is needed for all the clients applications for the use of active objects and callbacks.

              Using the tone player

              The tone player provides a simple interface to generate single and multiple tones. Once the tone player object has been constructed, multiple tones and tone sequences can be played without having to create new instances of the object.

              Using the tone player typically involves the following steps:

              - Tone Player Utility -

              1. Constructing a tone player

              2. Preparing a tone player

              3. Playing a tone

              4. Cancelling a tone

              5. Retrieving a custom interface

              Constructing a tone player

              The CMdaAudioToneUtility object can be constructed using the NewL() member function. There are two versions of this constructor function:

              • create a tone player with default priority settings:

                static CMdaAudioToneUtility* NewL(MMdaAudioToneObserver& aObserver, CMdaServer* aServer=NULL);

              • create a tone player with your own settings:

                static CMdaAudioToneUtility* NewL(MMdaAudioToneObserver& aObserver, CMdaServer* aServer, TInt aPriority, + + + + + +How to use the audio tone player utility

                The Audio Tone Player, provided by the class CMdaAudioToneUtility, has an interface for generating the following tones on all audio capable devices. Using this class you can play the following tones:

                • Single tone of a specified duration and frequency

                • Dual Tone Multi Frequency (DTMF) strings

                • Sequences of tones held in files or descriptors

                • Predefined (fixed) sequences of tones held in any mobile equipment

                Client applications such as ringtone applications, use CMdaAudioToneUtility to generate the tones they produce. The tone player in turn uses MMF for playing sounds and is also credited for interfacing with the audio hardware. An active scheduler is needed for all the clients applications for the use of active objects and callbacks.

                Using the tone player

                The tone player provides a simple interface to generate single and multiple tones. Once the tone player object has been constructed, multiple tones and tone sequences can be played without having to create new instances of the object.

                Using the tone player typically involves the following steps:

                + Tone Player Utility +

                1. Constructing a tone player

                2. Preparing a tone player

                3. Playing a tone

                4. Cancelling a tone

                5. Retrieving a custom interface

                Constructing a tone player

                The CMdaAudioToneUtility object can be constructed using the NewL() member function. There are two versions of this constructor function:

                • create a tone player with default priority settings:

                  static CMdaAudioToneUtility* NewL(MMdaAudioToneObserver& aObserver, CMdaServer* aServer=NULL);

                • create a tone player with your own settings:

                  static CMdaAudioToneUtility* NewL(MMdaAudioToneObserver& aObserver, CMdaServer* aServer, TInt aPriority, TMdaPriorityPreference aPref=EMdaPriorityPreferenceTimeAndQuality);

                Both functions pass a reference of the MMdaAudioToneObserver object to the tone player. The MMdaAudioToneObserver is an observer interface to notifications from the member functions Prepare, Play, and, CancelPlay callback functions.

                Preparing a tone player

                Once the tone player object is created, it has to be prepared to play a tone or a DTMF string. use one of the following prepare member functions to get it ready for playing the corresponding tone.

                • PrepareToPlayTone() - to play a single tone of a fixed frequency (Hz) and duration (microseconds). For example:

                  virtual void PrepareToPlayTone(TInt aFrequency, const TTimeIntervalMicroSeconds& aDuration);

                • PrepareToPlayDTMFString() - to play a DTMF string held in a descriptor. For example:

                  virtual void PrepareToPlayDTMFString(const TDesC& aDTMF);

                • PrepareToPlayFileSequence() - to play a sequence of non-DTMF tones held in a file. For example:

                  virtual void PrepareToPlayFileSequence(const TDesC& aFilename);

                • PrepareToPlayDesSequence() - to play a sequence of non-DTMF tones held in a descriptor. For example:

                  virtual void PrepareToPlayDesSequence(const TDesC8& aSequence);

                • PrepareToPlayFixedSequence() - to play a sequence of non-DTMF tones stored on the mobile equipment. For example:

                  virtual void PrepareToPlayFixedSequence(TInt aSequenceNumber);

                • PrepareToPlayDualTone() - to play a dual tone. For example:

                  void PrepareToPlayDualTone(TInt aFrequencyOne, TInt aFrequencyTwo, const TTimeIntervalMicroSeconds& aDuration);

                  The two tones, aFrequencyOne and aFrequencyTwo, are measured in Hz, and the duration of the tone, aDuration, is measured in microseconds.

                All the prepare member functions are asynchronous. In response to each, CMdaAudioToneUtility creates a CMMFToneConfig derived object that stores the data for the type of tone to play.

                On completion of a prepare, the observer function MMdaAudioToneObserver::MatoPrepareComplete() is called, indicating the success or failure of the prepare operation. If successful you can play the tone.

                You can cancel any prepare function using CancelPrepare() (the observer callback function is not called on completion of the cancel).

                Playing a tone

                Once the player is prepared successfully, certain configurations can be done before playing the tone as listed below:

                • Volume() and SetVolume() - This retrieves the current volume settings and sets to a new value specified by the user respectively.

                • GetBalanceL() and SetBalanceL() - This retrieves the current balance of the audio device and sets the audio balance specified by the user respectively..

                • SetPriority() - This sets the priority of the audio device. The priority is defined to arbitrate between multiple objects trying to access the controller at the same time.

                • SetVolumeRamp() - This defines the period over which the volume level is to rise (in microseconds) smoothly from zero to the specified volume level. A value of 0 causes the tone to be played at the SetVolume() level for the full duration of the playback. A value that is longer than the duration of the tone sequence means that the tone never reaches the specified volume.

                  virtual void SetVolumeRamp(const TTimeIntervalMicroSeconds &aRampDuration);

                • SetDTMFLengths() - This alters the duration of DTMF tone, the gaps between two DTMF tones, and the pauses in microseconds.

                • FixedSequenceCount() - This returns the number of available pre-defined tone sequences, the number always being greater than zero.

                • FixedSequenceName() - This returns the name of the specified fixed tone sequence.

                Upon successful configuration, the Play() can be called as shown below.

                Play() - plays the tone, DTMF or tone sequence specified by the prepare statement. For example:

                virtual void Play();

                Here, the tone player uses the Play() from the audio player utility to play the tone.

                This function is asynchronous. It retrieves the details of the type of tone to play from the previous Prepare statement. When the tone has been played to completion, the observer callback function MMdaAudioToneObserver::MatoPlayComplete() is called, indicating the success or failure of the play operation. The play operation can be cancelled by calling the CancelPlay() member function.

                Playing the tone or DTMF string can be customised using the following member functions as mentioned below:

                • SetRepeats() - sets the number of times the tone sequence (plus an optional trailing silent period, measured in microseconds) is repeated during the play operation. For example:

                  virtual void SetRepeats(TInt aRepeatNumberOfTimes, const TTimeIntervalMicroSeconds &aTrailingSilence);

                  You can repeat the tone sequence indefinitely by setting aRepeatNumberOfTimes to KMdaRepeatForever.

                • State() - returns the current state of the tone player (an enum):

                  • EMdaAudioToneUtilityNotReady - not prepared to play a tone

                  • EMdaAudioToneUtilityPrepared - prepared and ready to play a tone

                  • EMdaAudioToneUtilityPlaying - currently playing a tone

                  For example:

                  virtual TMdaAudioToneUtilityState State();

                To play another tone or sequence, either wait for MMdaAudioToneObserver::MatoPlayComplete() callback to be issued when the current tone or DTMF string completes playing, or use CancelPlay() and then issue the relevant prepare statement. The Play() function following the prepare statement plays the tone or DTMF string based on the previously issued prepare statement.

                Cancelling a tone

                CancelPlay() - cancels the tone, DTMF, or tone sequence currently playing. For example:

                virtual void CancelPlay();

                The observer callback function is not called on completion of the cancel.

                Retrieving a custom interface

                To retrieve a custom interface to the underlying device, use the CustomInterface() member function. For example:

                IMPORT_C TAny *CustomInterface(TUid aInterfaceId);

                aInterfaceId is the UID of the interface function required.

                The function returns a pointer to the interface implementation, or NULL if the device does not implement the interface requested. You must cast the return value to the correct type.

                See Also

                How to use the audio player utility

                How to use the audio convert utility

                How to use audio recorder utility

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9F14FB98-D7CD-55C9-8D27-715642B8FFC3_d0e404850_href.png Binary file Symbian3/SDK/Source/GUID-9F14FB98-D7CD-55C9-8D27-715642B8FFC3_d0e404850_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9F14FB98-D7CD-55C9-8D27-715642B8FFC3_d0e405012_href.png Binary file Symbian3/SDK/Source/GUID-9F14FB98-D7CD-55C9-8D27-715642B8FFC3_d0e405012_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9F4C948B-7A6B-4E90-BBB7-A6CC6F4A6769_d0e3400_href.png Binary file Symbian3/SDK/Source/GUID-9F4C948B-7A6B-4E90-BBB7-A6CC6F4A6769_d0e3400_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9F4C948B-7A6B-4E90-BBB7-A6CC6F4A6769_d0e3531_href.png Binary file Symbian3/SDK/Source/GUID-9F4C948B-7A6B-4E90-BBB7-A6CC6F4A6769_d0e3531_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9F4C948B-7A6B-4E90-BBB7-A6CC6F4A6769_d0e4675_href.png Binary file Symbian3/SDK/Source/GUID-9F4C948B-7A6B-4E90-BBB7-A6CC6F4A6769_d0e4675_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9F4C948B-7A6B-4E90-BBB7-A6CC6F4A6769_d0e4806_href.png Binary file Symbian3/SDK/Source/GUID-9F4C948B-7A6B-4E90-BBB7-A6CC6F4A6769_d0e4806_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9F96807F-25DC-5DE1-B327-3E339665FF64.dita --- a/Symbian3/SDK/Source/GUID-9F96807F-25DC-5DE1-B327-3E339665FF64.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-9F96807F-25DC-5DE1-B327-3E339665FF64.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,14 +1,99 @@ - - - - - -ReferenceThis topic contains all reference information for the Network Interface Manager (NifMan).
                Time-out values in the CommDb bearer table

                There are three time-out values, which are set in the CommDb bearer table:

                Name

                Description

                LAST_SESSION_CLOSED_TIMEOUT

                This time-out is used if there are no ESock RConnection objects and no sockets for the interface.

                LAST_SOCKET_CLOSED_TIMEOUT

                This time-out used if there are RConnection objects, but no sockets for the interface.

                LAST_SOCKET_ACTIVITY_TIMEOUT

                This time-out used if there are any sockets for the interface.

                Progress Notification Types

                The NIFMAN configuration plug-in that calls the daemon provides progress notifications for a range of generic events. These are:

                Progress type

                Description

                KConfigDaemonLoading

                Generated before the daemon is loaded

                KConfigDaemonLoaded

                Generated after the daemon was successfully loaded

                KConfigDaemonStartingRegistration

                Generated before the EConfigDaemonConfigure message is sent

                KConfigDaemonFinishedRegistration

                Generated after the EConfigDaemonConfigure message is completed by the daemon

                KConfigDaemonStartingDeregistration

                Generated before the EConfigDaemonDeregister message is sent

                KConfigDaemonFinishedDeregistrationStop

                Generated after the EConfigDaemonDeregister message is completed by the daemon indicating that the NIF is to be stopped (EConfigDaemonDeregisterActionStop)

                KConfigDaemonFinishedDeregistrationPreserve

                Generated after the EConfigDaemonDeregister message is is completed by the daemon indicating that the system is in dormant mode (EConfigDaemonDeregisterActionPreserve)

                KConfigDaemonUnloading

                Generated immediately before the session to the daemon is closed

                KConfigDaemonUnloaded

                Generated after the session to the daemon is closed

                What is Network Interface Management - (NifMan)? What are the daemon message - types?                 \ No newline at end of file + + + + + +ReferenceThis topic contains all reference information for the Network Interface +Manager (NifMan). +
                Time-out values in the CommDb bearer table

                There +are three time-out values, which are set in the CommDb bearer table:

                + + + +

                Name

                +

                Description

                +                 + +

                LAST_SESSION_CLOSED_TIMEOUT

                +

                This time-out is used if there are no ESock RConnection objects +and no sockets for the interface.

                +                 + +

                LAST_SOCKET_CLOSED_TIMEOUT

                +

                This time-out used if there are RConnection objects, +but no sockets for the interface.

                +                 + +

                LAST_SOCKET_ACTIVITY_TIMEOUT

                +

                This time-out used if there are any sockets for the interface.

                +                 + + +
                +
                Progress Notification Types
                + +

                The NIFMAN configuration plug-in that calls the daemon provides +progress notifications for a range of generic events. These are:

                + + + + +

                Progress type

                +

                Description

                +                 + +

                KConfigDaemonLoading

                +

                Generated before the daemon is loaded

                +                 + +

                KConfigDaemonLoaded

                +

                Generated after the daemon was successfully loaded

                +                 + +

                KConfigDaemonStartingRegistration

                +

                Generated before the EConfigDaemonConfigure message +is sent

                +                 + +

                KConfigDaemonFinishedRegistration

                +

                Generated after the EConfigDaemonConfigure message +is completed by the daemon

                +                 + +

                KConfigDaemonStartingDeregistration

                +

                Generated before the EConfigDaemonDeregister message +is sent

                +                 + +

                KConfigDaemonFinishedDeregistrationStop

                +

                Generated after the EConfigDaemonDeregister message +is completed by the daemon indicating that the NIF is to be stopped (EConfigDaemonDeregisterActionStop)

                +                 + +

                KConfigDaemonFinishedDeregistrationPreserve

                +

                Generated after the EConfigDaemonDeregister message +is is completed by the daemon indicating that the system is in dormant mode +(EConfigDaemonDeregisterActionPreserve)

                +                 + +

                KConfigDaemonUnloading

                +

                Generated immediately before the session to the daemon is closed

                +                 + +

                KConfigDaemonUnloaded

                +

                Generated after the session to the daemon is closed

                +                 + + +
                 +What is Network +Interface Management (NifMan)? +What are +the daemon message types? +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9FB3502C-B3DF-5FBC-972D-0D476D661954_d0e107398_href.png Binary file Symbian3/SDK/Source/GUID-9FB3502C-B3DF-5FBC-972D-0D476D661954_d0e107398_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9FB3502C-B3DF-5FBC-972D-0D476D661954_d0e113936_href.png Binary file Symbian3/SDK/Source/GUID-9FB3502C-B3DF-5FBC-972D-0D476D661954_d0e113936_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9FB82D95-F110-5D42-B39E-BCFAE574E18F_d0e77328_href.png Binary file Symbian3/SDK/Source/GUID-9FB82D95-F110-5D42-B39E-BCFAE574E18F_d0e77328_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9FB82D95-F110-5D42-B39E-BCFAE574E18F_d0e84040_href.png Binary file Symbian3/SDK/Source/GUID-9FB82D95-F110-5D42-B39E-BCFAE574E18F_d0e84040_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-9FDF961E-D6CA-599C-8D1C-605ECA50F504.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-9FDF961E-D6CA-599C-8D1C-605ECA50F504.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,24 @@ + + + + + +PtBuffer: +the pointer move buffer +
                Description

                This example implements simple freehand +drawing. The example illustrates the use of RWindowBase's +pointer move buffer functions: AllocPointerMoveBuffer(), EnablePointerMoveBuffer(), RetrievePointerMoveBuffer() and DisablePointerMoveBuffer().

                +
                Download

                Click +on the following link to download the example: PtBuffer.zip

                Click: browse to view the example code.

                +
                Class Summary

                RWindowBase

                +
                Running on the emulator

                Hold down the shift key +and drag the mouse (with left mouse button down) for freehand drawing.

                +
                Running on the target phone

                Hold down the shift key +and draw using the pointer device.

                +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A007DDF7-AC6D-5378-B7A6-84CB421E970F_d0e336695_href.png Binary file Symbian3/SDK/Source/GUID-A007DDF7-AC6D-5378-B7A6-84CB421E970F_d0e336695_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A007DDF7-AC6D-5378-B7A6-84CB421E970F_d0e342892_href.png Binary file Symbian3/SDK/Source/GUID-A007DDF7-AC6D-5378-B7A6-84CB421E970F_d0e342892_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A0208BE3-127F-4D04-8045-09C54EF202DD-master.png Binary file Symbian3/SDK/Source/GUID-A0208BE3-127F-4D04-8045-09C54EF202DD-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A0208BE3-127F-4D04-8045-09C54EF202DD_d0e51905_href.png Binary file Symbian3/SDK/Source/GUID-A0208BE3-127F-4D04-8045-09C54EF202DD_d0e51905_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A0208BE3-127F-4D04-8045-09C54EF202DD_d0e57512_href.png Binary file Symbian3/SDK/Source/GUID-A0208BE3-127F-4D04-8045-09C54EF202DD_d0e57512_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A0208BE3-127F-4D04-8045-09C54EF202DD_d0e67708_href.png Binary file Symbian3/SDK/Source/GUID-A0208BE3-127F-4D04-8045-09C54EF202DD_d0e67708_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A0208BE3-127F-4D04-8045-09C54EF202DD_d0e69130_href.png Binary file Symbian3/SDK/Source/GUID-A0208BE3-127F-4D04-8045-09C54EF202DD_d0e69130_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A0208BE3-127F-4D04-8045-09C54EF202DD_d0e72845_href.png Binary file Symbian3/SDK/Source/GUID-A0208BE3-127F-4D04-8045-09C54EF202DD_d0e72845_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A0208BE3-127F-4D04-8045-09C54EF202DD_d0e74273_href.png Binary file Symbian3/SDK/Source/GUID-A0208BE3-127F-4D04-8045-09C54EF202DD_d0e74273_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A049B0C2-5C30-5B07-AC4F-32A75046B60B.dita --- a/Symbian3/SDK/Source/GUID-A049B0C2-5C30-5B07-AC4F-32A75046B60B.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-A049B0C2-5C30-5B07-AC4F-32A75046B60B.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,69 +1,69 @@ - - - - - -Buffer -descriptorsDescribes modifiable and non-modifiable buffer descriptors. -

                A buffer descriptor provides a fixed length buffer to contain and access -data. The data is part of the descriptor object.

                -

                A buffer descriptor object is an instance of a templated class, where the -template parameter is an integer value that defines the size of the descriptor's -data area.

                -

                A buffer descriptor comes in two forms:

                -
                  -

                • a non-modifiable buffer -descriptor.

                  • -

                • a modifiable buffer -descriptor.

                  • -
                -
                Non-modifiable buffer descriptor

                The data contained -in a non-modifiable buffer descriptor can be accessed, but not changed, through -this descriptor. The data can, however, be completely replaced using the assignment -operators.

                Data is accessed through functions provided by the base -class.

                A non-modifiable buffer descriptor is supplied in two variants:

                  -

                • the 16 bit variant, -a TBufC16<TInt>, to contain Unicode strings.

                  • -

                • the 8 bit variant, a TBufC8<TInt>, -to contain non-Unicode strings and binary data.

                  • -

                There is also a build independent type, TBufC<TInt>. -This is the type which is most commonly used in program code; the appropriate -variant is selected at build time.

                An explicit 8 bit variant is chosen -for binary data. The explicit 16 bit variant is rarely used.

                The base -class, TDesC, contains a data member which holds the length -of the data. The following drawing shows the layout of a TBufC<5> object -initialised with the string of five characters representing the English word -"Hello".

                - -
                -
                Modifiable buffer descriptor

                The data contained -in a modifiable buffer descriptor can be both accessed and changed through -this descriptor.

                The template parameter, as well as determining the -size of the data area created as part of the descriptor object, also defines -the maximum length of the descriptor.

                The length of the data can vary -between zero and the maximum length. When the length of the data is less than -the maximum, a portion of the data area within the descriptor is unused.

                Data -is accessed and modified through functions provided by the base classes.

                A -modifiable buffer descriptor is supplied in two variants:

                  -

                • the 16 bit variant, -a TBuf16<TInt>, to contain Unicode strings.

                  • -

                • the 8 bit variant, a TBuf8<TInt>, -to contain non-Unicode strings and binary data.

                  • -

                There is also a build independent type, TBuf<TInt>. -This is the type which is most commonly used in program code; the appropriate -variant is selected at build time.

                An explicit 8 bit variant is chosen -for binary data. The explicit 16 bit variant is rarely used.

                The base -class TDesC, contains a data member that holds the length -of the data. The base class TDes, contains a data member -that holds the maximum length of the data. The following drawing shows the -layout of a TBuf<12> object initialised with the string -of five characters representing the English word "Hello".

                - -
                + + + + + +Buffer +descriptorsDescribes modifiable and non-modifiable buffer descriptors. +

                A buffer descriptor provides a fixed length buffer to contain and access +data. The data is part of the descriptor object.

                +

                A buffer descriptor object is an instance of a templated class, where the +template parameter is an integer value that defines the size of the descriptor's +data area.

                +

                A buffer descriptor comes in two forms:

                +
                  +

                • a non-modifiable buffer +descriptor.

                  • +

                • a modifiable buffer +descriptor.

                  • +
                +
                Non-modifiable buffer descriptor

                The data contained +in a non-modifiable buffer descriptor can be accessed, but not changed, through +this descriptor. The data can, however, be completely replaced using the assignment +operators.

                Data is accessed through functions provided by the base +class.

                A non-modifiable buffer descriptor is supplied in two variants:

                  +

                • the 16 bit variant, +a TBufC16<TInt>, to contain Unicode strings.

                  • +

                • the 8 bit variant, a TBufC8<TInt>, +to contain non-Unicode strings and binary data.

                  • +

                There is also a build independent type, TBufC<TInt>. +This is the type which is most commonly used in program code; the appropriate +variant is selected at build time.

                An explicit 8 bit variant is chosen +for binary data. The explicit 16 bit variant is rarely used.

                The base +class, TDesC, contains a data member which holds the length +of the data. The following drawing shows the layout of a TBufC<5> object +initialised with the string of five characters representing the English word +"Hello".

                + +
                +
                Modifiable buffer descriptor

                The data contained +in a modifiable buffer descriptor can be both accessed and changed through +this descriptor.

                The template parameter, as well as determining the +size of the data area created as part of the descriptor object, also defines +the maximum length of the descriptor.

                The length of the data can vary +between zero and the maximum length. When the length of the data is less than +the maximum, a portion of the data area within the descriptor is unused.

                Data +is accessed and modified through functions provided by the base classes.

                A +modifiable buffer descriptor is supplied in two variants:

                  +

                • the 16 bit variant, +a TBuf16<TInt>, to contain Unicode strings.

                  • +

                • the 8 bit variant, a TBuf8<TInt>, +to contain non-Unicode strings and binary data.

                  • +

                There is also a build independent type, TBuf<TInt>. +This is the type which is most commonly used in program code; the appropriate +variant is selected at build time.

                An explicit 8 bit variant is chosen +for binary data. The explicit 16 bit variant is rarely used.

                The base +class TDesC, contains a data member that holds the length +of the data. The base class TDes, contains a data member +that holds the maximum length of the data. The following drawing shows the +layout of a TBuf<12> object initialised with the string +of five characters representing the English word "Hello".

                + +
                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A0531C8B-22F2-5FAE-9F37-92BACBBD9EEB-GENID-1-10-1-15-1-1-4-1-4-1-22-1-6-1-4-1.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-A0531C8B-22F2-5FAE-9F37-92BACBBD9EEB-GENID-1-10-1-15-1-1-4-1-4-1-22-1-6-1-4-1.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,20 @@ + + + + + +How +to stop a periodic timerDescribes how to stop a periodic timer. +

                To stop a periodic timer, call Cancel(). After the cancel, +the CPeriodic may be started again, and so on until it is +destroyed.

                + +iPeriodic->Cancel(); + +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A0531C8B-22F2-5FAE-9F37-92BACBBD9EEB-GENID-1-10-1-15-1-1-4-1-4-1-22-1-7-1-4-1.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-A0531C8B-22F2-5FAE-9F37-92BACBBD9EEB-GENID-1-10-1-15-1-1-4-1-4-1-22-1-7-1-4-1.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,20 @@ + + + + + +How +to stop a periodic timerDescribes how to stop a periodic timer. +

                To stop a periodic timer, call Cancel(). After the cancel, +the CPeriodic may be started again, and so on until it is +destroyed.

                + +iPeriodic->Cancel(); + +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A0531C8B-22F2-5FAE-9F37-92BACBBD9EEB-GENID-1-8-1-14-1-1-4-1-4-1-22-1-6-1-4-1.dita --- a/Symbian3/SDK/Source/GUID-A0531C8B-22F2-5FAE-9F37-92BACBBD9EEB-GENID-1-8-1-14-1-1-4-1-4-1-22-1-6-1-4-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,20 +0,0 @@ - - - - - -How -to stop a periodic timerDescribes how to stop a periodic timer. -

                To stop a periodic timer, call Cancel(). After the cancel, -the CPeriodic may be started again, and so on until it is -destroyed.

                - -iPeriodic->Cancel(); - -                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A0531C8B-22F2-5FAE-9F37-92BACBBD9EEB-GENID-1-8-1-14-1-1-4-1-4-1-22-1-7-1-4-1.dita --- a/Symbian3/SDK/Source/GUID-A0531C8B-22F2-5FAE-9F37-92BACBBD9EEB-GENID-1-8-1-14-1-1-4-1-4-1-22-1-7-1-4-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,20 +0,0 @@ - - - - - -How -to stop a periodic timerDescribes how to stop a periodic timer. -

                To stop a periodic timer, call Cancel(). After the cancel, -the CPeriodic may be started again, and so on until it is -destroyed.

                - -iPeriodic->Cancel(); - -                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A0620D7E-F54C-5DE1-BED9-B34C5B851716-GENID-1-8-1-18-1-1-4-1-10-1.dita --- a/Symbian3/SDK/Source/GUID-A0620D7E-F54C-5DE1-BED9-B34C5B851716-GENID-1-8-1-18-1-1-4-1-10-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,28 +0,0 @@ - - - - - -MmfExFormatPlugin: -Multimedia Framework format encoder/decoder plug-ins example -
                Description

                MmfExFormatPlugin demonstrates -how to implement format encoder and decoder plug-ins for the Multimedia Framework. -Multimedia data is usually packaged in a particular format, which specify -the properties of the data (e.g. duration, frame intervals), and how the buffers -for holding the data are organised. A format decoder plug-in is responsible -for reading a particular format; a format encoder plug-in for writing a particular -format.

                The example handles the RAW audio format (PCM data with no -headers). The decoder plug-in CMMFRawFormatRead reads RAW -audio; it implements the ECom interface CMMFFormatDecode. -The encoder plug-in CMMFRawFormatWrite writes RAW audio: -it implements the ECom interface CMMFFormatEncode.

                -
                Download

                Click -on the following link to download the example: MmfExFormatPlugin.zip file

                Click: browse to view the example code.

                -
                Class summary

                MDataSink CMMFFormatDecode MDataSource CMMFDataBuffer CMMFChannelAndSampleRateConverterFactory CMMFChannelAndSampleRateConverter CMMFBuffer CMMFFormatEncode

                -                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A0620D7E-F54C-5DE1-BED9-B34C5B851716-GENID-1-8-1-18-1-1-5-1-7-1-6-1-6-1.dita --- a/Symbian3/SDK/Source/GUID-A0620D7E-F54C-5DE1-BED9-B34C5B851716-GENID-1-8-1-18-1-1-5-1-7-1-6-1-6-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,28 +0,0 @@ - - - - - -MmfExFormatPlugin: -Multimedia Framework format encoder/decoder plug-ins example -
                Description

                MmfExFormatPlugin demonstrates -how to implement format encoder and decoder plug-ins for the Multimedia Framework. -Multimedia data is usually packaged in a particular format, which specify -the properties of the data (e.g. duration, frame intervals), and how the buffers -for holding the data are organised. A format decoder plug-in is responsible -for reading a particular format; a format encoder plug-in for writing a particular -format.

                The example handles the RAW audio format (PCM data with no -headers). The decoder plug-in CMMFRawFormatRead reads RAW -audio; it implements the ECom interface CMMFFormatDecode. -The encoder plug-in CMMFRawFormatWrite writes RAW audio: -it implements the ECom interface CMMFFormatEncode.

                -
                Download

                Click -on the following link to download the example: MmfExFormatPlugin.zip file

                Click: browse to view the example code.

                -
                Class summary

                MDataSink CMMFFormatDecode MDataSource CMMFDataBuffer CMMFChannelAndSampleRateConverterFactory CMMFChannelAndSampleRateConverter CMMFBuffer CMMFFormatEncode

                -                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A0620D7E-F54C-5DE1-BED9-B34C5B851716.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-A0620D7E-F54C-5DE1-BED9-B34C5B851716.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,28 @@ + + + + + +MmfExFormatPlugin: +Multimedia Framework format encoder/decoder plug-ins example +
                Description

                MmfExFormatPlugin demonstrates +how to implement format encoder and decoder plug-ins for the Multimedia Framework. +Multimedia data is usually packaged in a particular format, which specify +the properties of the data (e.g. duration, frame intervals), and how the buffers +for holding the data are organised. A format decoder plug-in is responsible +for reading a particular format; a format encoder plug-in for writing a particular +format.

                The example handles the RAW audio format (PCM data with no +headers). The decoder plug-in CMMFRawFormatRead reads RAW +audio; it implements the ECom interface CMMFFormatDecode. +The encoder plug-in CMMFRawFormatWrite writes RAW audio: +it implements the ECom interface CMMFFormatEncode.

                +
                Download

                Click +on the following link to download the example: MmfExFormatPlugin.zip file

                Click: browse to view the example code.

                +
                Class summary

                MDataSink CMMFFormatDecode MDataSource CMMFDataBuffer CMMFChannelAndSampleRateConverterFactory CMMFChannelAndSampleRateConverter CMMFBuffer CMMFFormatEncode

                +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A10EAF58-6B9F-55A5-B3E4-3D4B91A93C41_d0e237205_href.png Binary file Symbian3/SDK/Source/GUID-A10EAF58-6B9F-55A5-B3E4-3D4B91A93C41_d0e237205_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A10EAF58-6B9F-55A5-B3E4-3D4B91A93C41_d0e240942_href.png Binary file Symbian3/SDK/Source/GUID-A10EAF58-6B9F-55A5-B3E4-3D4B91A93C41_d0e240942_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A1148010-887F-549D-9DA0-D36FF4661FFE.dita --- a/Symbian3/SDK/Source/GUID-A1148010-887F-549D-9DA0-D36FF4661FFE.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-A1148010-887F-549D-9DA0-D36FF4661FFE.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,14 +1,14 @@ - - - - - -What are Access PointsThis topic describes the concept of an Access Point in the Communications Framework.

                A Layer can make a service available to the Layer immediately above it. The service is called an Access Point.

                Each Layer except the highest Layer can have an Access Point. The highest Layer is called the Application Layer. The Communications Framework can limit the use of an Access Point to selected clients.

                The following diagram shows five Access Points. Each Access Point offers a service to the Layer above it.

                - Access Points in the Communications Framework -

                In this diagram the Link Layer has three bearers. Each bearer has an Access Point. An application or a Layer above the Link Layer does not need to know which bearer in the Link Layer is in use during the connection. The Communication Framework can replace the bearer with another bearer. The Communication Framework does not need to tell the application when the bearer changes. An application can continue to send and receive data when the change occurs.

                For example, consider an email application on a device. The device connects over a GPRS network. A short time later the device detects that a Wi-Fi connection is available. This event can occur if the device has moved from an office location to a coffee shop. The device can have a selection policy. The policy can state that the device switch to WiFi without the creation of a new connection.

                The selection policy contains a list of Access Points in order of priority. Device manufacturers, Network Operators and users can configure the order of priority. The priority can be based on items like available bandwidth and cost. An alternative to selection policy is the concept of connection preference. For example, a device connects with a specific bearer (for example, GPRS) unless the application changes the bearer explicitly.

                It is useful to note that an Internet Access Point (IAP) is a specialisation of the Access Point concept for a Link Layer. IAPs identify a service to be accessed through a concrete link-layer bearer. Each IAP has an associated Access Point with the same physical value.

                IAP Layers                 \ No newline at end of file + + + + + +What are Access PointsThis topic describes the concept of an Access Point in the Communications Framework.

                A Layer can make a service available to the Layer immediately above it. The service is called an Access Point.

                Each Layer except the highest Layer can have an Access Point. The highest Layer is called the Application Layer. The Communications Framework can limit the use of an Access Point to selected clients.

                The following diagram shows five Access Points. Each Access Point offers a service to the Layer above it.

                + Access Points in the Communications Framework +

                In this diagram the Link Layer has three bearers. Each bearer has an Access Point. An application or a Layer above the Link Layer does not need to know which bearer in the Link Layer is in use during the connection. The Communication Framework can replace the bearer with another bearer. The Communication Framework does not need to tell the application when the bearer changes. An application can continue to send and receive data when the change occurs.

                For example, consider an email application on a device. The device connects over a GPRS network. A short time later the device detects that a Wi-Fi connection is available. This event can occur if the device has moved from an office location to a coffee shop. The device can have a selection policy. The policy can state that the device switch to WiFi without the creation of a new connection.

                The selection policy contains a list of Access Points in order of priority. Device manufacturers, Network Operators and users can configure the order of priority. The priority can be based on items like available bandwidth and cost. An alternative to selection policy is the concept of connection preference. For example, a device connects with a specific bearer (for example, GPRS) unless the application changes the bearer explicitly.

                It is useful to note that an Internet Access Point (IAP) is a specialisation of the Access Point concept for a Link Layer. IAPs identify a service to be accessed through a concrete link-layer bearer. Each IAP has an associated Access Point with the same physical value.

                IAP Layers                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A15EDC87-A6EF-40D8-AA78-B52449465FEA.dita --- a/Symbian3/SDK/Source/GUID-A15EDC87-A6EF-40D8-AA78-B52449465FEA.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-A15EDC87-A6EF-40D8-AA78-B52449465FEA.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,54 +1,54 @@ - - - - - -Receiving -long-tap events -

                To receive long-tap events in your application using the Touch UI utilities -API, follow the steps below:

                -
                  -

                1. Link the AVKON libraries avkon.lib and eikcoctl.lib to -the project file of the application.

                  2. -

                2. Provide an observer -class that implements the MAknLongTapDetectorCallBack interface.

                  3. -

                3. Create an instance of -the class CAknLongTapDetector and pass pointer events to -the long-tap detector.

                  4. -

                4. Receive long-tap events -through the observer interface.

                  5. -

                5. Delete the long-tap -detector.

                  6. -
                -

                Use cases for the long-tap detector are shown in the figure below.

                - -Touch UI utilities API use cases - - -

                To use the Touch UI utilities long-tap detector in your application, implement -the following use cases.

                -
                  -

                • Creating the -long-tap detector

                  • -

                • Handling long-tap -events

                  • -

                • Deleting long-tap -detector

                  • -
                -

                The following use cases are optional, allowing you to set additional properties -for your long-tap detector.

                -
                  -

                • Enabling and -disabling the long-tap detector

                  • -

                • Setting the -time after which the long-tap event is sent

                  • -

                • Setting the -time before the long-tap animation starts

                  • -
                + + + + + +Receiving +long-tap events +

                To receive long-tap events in your application using the Touch UI utilities +API, follow the steps below:

                +
                  +

                1. Link the AVKON libraries avkon.lib and eikcoctl.lib to +the project file of the application.

                  2. +

                2. Provide an observer +class that implements the MAknLongTapDetectorCallBack interface.

                  3. +

                3. Create an instance of +the class CAknLongTapDetector and pass pointer events to +the long-tap detector.

                  4. +

                4. Receive long-tap events +through the observer interface.

                  5. +

                5. Delete the long-tap +detector.

                  6. +
                +

                Use cases for the long-tap detector are shown in the figure below.

                + +Touch UI utilities API use cases + + +

                To use the Touch UI utilities long-tap detector in your application, implement +the following use cases.

                +
                  +

                • Creating the +long-tap detector

                  • +

                • Handling long-tap +events

                  • +

                • Deleting long-tap +detector

                  • +
                +

                The following use cases are optional, allowing you to set additional properties +for your long-tap detector.

                +
                  +

                • Enabling and +disabling the long-tap detector

                  • +

                • Setting the +time after which the long-tap event is sent

                  • +

                • Setting the +time before the long-tap animation starts

                  • +
                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A188606F-4A8E-5A85-A241-E15219960EFA.dita --- a/Symbian3/SDK/Source/GUID-A188606F-4A8E-5A85-A241-E15219960EFA.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-A188606F-4A8E-5A85-A241-E15219960EFA.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,127 +1,127 @@ - - - - - -Loader -OverviewThis topic describes the overview, purpose, key concepts and architecture -of loader. -
                  -

                • Purpose

                  • -

                • Key concepts

                  • -

                • Architectural relationships

                  • -
                -
                Purpose

                The -loader makes EXEs and DLLs ready to run.

                The build tools compile the -source code into an executable file. An executable file is called a binary. -The build tools arrange the compiled code into EXEs and DLLs. The source code, -header files and other information that defines an executable file is defined -in an mmp file. The loader applies relocation information to the code and -data sections of EXEs and DLLs. The loader also loads DLLs that are referred -to by other EXEs and DLLs. EXEs and DLLs can then run in the process into -which they are loaded.

                -
                Key concepts

                The loader server

                The Symbian platform loader is a server. -The loader server has no public client interface. The client interface is -internal to Symbian platform. Requests to load an EXE or a DLL are passed -to the loader when you do the following:

                  -

                • start a new process -- a call to RProcess::Create()

                  • -

                • load a DLL - a call -to RLibrary::Load()

                  • -

                • load a logical device -driver - a call to User::LoadLogicalDevice(). A logical -device driver is a type of DLL.

                  • -

                • load a physical device -driver - a call to User::LoadPhysicalDevice(). A physical -device driver is a type of DLL.

                  • -

                • load a file system - -a call to RFs::AddFileSystem(). A file system is a type -of DLL. A call to RFs::AddFileSystem() requires DiskAdmin -capability. See ECapabilityDiskAdmin.

                  • -

                • load a file server extension -- call to RFs::AddExtension(). A file server extension -is a type of DLL. This function requires DiskAdmin capability. See ECapabilityDiskAdmin.

                  • -

                • load a locale - a call -to TExtendedLocale::LoadLocale().

                  • -

                Version -numbers

                The -reason for version numbers

                More than one version of an EXE can -exist on a device at the same time. More than one version of a DLL can exist -on a device at the same time. A device can store versions of an EXE or DLL -that are not compatible with an older version of that EXE or DLL.

                A -version number is a set of two numbers. The loader uses these numbers to identify -copies of the executable file. The two numbers are called the major version -number and the minor version number. The build tools encode the two numbers -into the header of the executable file. When a DLL is built, the version numbers -are encoded into the import library.

                The -structure of version information

                DLLs are the most common users -of versions. You assign new values to the version numbers of a DLL when you -change the published API of the DLL. Symbian recommends the following procedure:

                  -

                • change the minor version -number if you make a change to a DLL that is backward compatible. An example -is a new function in the DLL.

                  • -

                • change the major version -number if you make a change to a DLL that breaks an interface. An example -is the removal of a function or a change to the signature of a function. An -interface break is disruptive and must be prevented.

                  • -

                The major and minor version numbers are defined in the .mmp file -that defines the source code, header files and other options that apply to -the executable file.

                If you do not specify version numbers, the build -tools apply the following default values:

                  -

                • Major version number -: 10

                  • -

                • Minor version number -: 0

                  • -

                The major version number and the minor version number are stored -in the header of an EXE and DLL. The two numbers are stored in a single 32 -bit value. The high 16 bits hold the major version number. The low 16 bits -hold the minor version number.

                When you build a DLL, the build tools -encode the version numbers into the filename of the import library (the .lib file). -The build tools also create an import library that does not have the version -numbers encoded as part of the filename.The following example shows how the -version numbers are encoded in the filename. The major version number is (decimal) -11 and the minor version number is (decimal) 2. The version numbers in the -filename are in hexadecimal.

                abcdsrv{000B0002}.lib

                Notes:

                  -

                • The left bracket and -the right bracket are part of the name.

                  • -

                • The first four digits -after the open bracket are the hexadecimal representation of the major version -number.

                  • -

                • The second four digits -are the hexadecimal representation of the minor version number.

                  • -

                The build tools do not encode the version numbers in the filename -of the executable file.

                Loader -search rules

                EXEs and DLLs can exist on more than one drive. There -can be more than one version of an EXE and more than one version of a DLL. -The loader uses search rules to select the EXE and DLL to load.

                See Loader search rules

                Emulator

                Version numbers are stored in import files for DLLs -that run on devices and the emulator. Version numbers change how the loader -functions on devices, but not in the emulator. You cannot encode the version -numbers in the import library file name on the emulator.

                Tools support

                Use the build tools to apply version numbers -to EXEs and DLLs. You specify version numbers in the .mmp file -that describes the EXE or DLL.

                See also mmp -file syntax and Build -tools guide.

                -
                Architectural -relationships

                The loader is a server that runs in a separate thread -in the file server process. The loader is built as part of the file server.

                The -loader server starts when the file server starts. The file server starts after -the kernel is loaded at system start.

                The loader runs on the user -side, but calls the kernel for services that are not available to general -applications. Examples of services are process creation and code segment creation. -A code segment is an object that represents a piece of code loaded into RAM. -A code segment also represents a piece of code that runs directly from ROM. -The kernel services that the loader uses are protected. The file server process -only is allowed to access these services.

                The following picture is -an example of program flow. In this example, a client calls RLibrary::Load(), -which exists in euser.dll. Internal functions make client-server -calls to the loader server. The loader server code exists in efile.exe. -The loader server uses kernel services.

                - -
                + + + + + +Loader +OverviewThis topic describes the overview, purpose, key concepts and architecture +of loader. +
                  +

                • Purpose

                  • +

                • Key concepts

                  • +

                • Architectural relationships

                  • +
                +
                Purpose

                The +loader makes EXEs and DLLs ready to run.

                The build tools compile the +source code into an executable file. An executable file is called a binary. +The build tools arrange the compiled code into EXEs and DLLs. The source code, +header files and other information that defines an executable file is defined +in an mmp file. The loader applies relocation information to the code and +data sections of EXEs and DLLs. The loader also loads DLLs that are referred +to by other EXEs and DLLs. EXEs and DLLs can then run in the process into +which they are loaded.

                +
                Key concepts

                The loader server

                The Symbian platform loader is a server. +The loader server has no public client interface. The client interface is +internal to Symbian platform. Requests to load an EXE or a DLL are passed +to the loader when you do the following:

                  +

                • start a new process +- a call to RProcess::Create()

                  • +

                • load a DLL - a call +to RLibrary::Load()

                  • +

                • load a logical device +driver - a call to User::LoadLogicalDevice(). A logical +device driver is a type of DLL.

                  • +

                • load a physical device +driver - a call to User::LoadPhysicalDevice(). A physical +device driver is a type of DLL.

                  • +

                • load a file system - +a call to RFs::AddFileSystem(). A file system is a type +of DLL. A call to RFs::AddFileSystem() requires DiskAdmin +capability. See ECapabilityDiskAdmin.

                  • +

                • load a file server extension +- call to RFs::AddExtension(). A file server extension +is a type of DLL. This function requires DiskAdmin capability. See ECapabilityDiskAdmin.

                  • +

                • load a locale - a call +to TExtendedLocale::LoadLocale().

                  • +

                Version +numbers

                The +reason for version numbers

                More than one version of an EXE can +exist on a device at the same time. More than one version of a DLL can exist +on a device at the same time. A device can store versions of an EXE or DLL +that are not compatible with an older version of that EXE or DLL.

                A +version number is a set of two numbers. The loader uses these numbers to identify +copies of the executable file. The two numbers are called the major version +number and the minor version number. The build tools encode the two numbers +into the header of the executable file. When a DLL is built, the version numbers +are encoded into the import library.

                The +structure of version information

                DLLs are the most common users +of versions. You assign new values to the version numbers of a DLL when you +change the published API of the DLL. Symbian recommends the following procedure:

                  +

                • change the minor version +number if you make a change to a DLL that is backward compatible. An example +is a new function in the DLL.

                  • +

                • change the major version +number if you make a change to a DLL that breaks an interface. An example +is the removal of a function or a change to the signature of a function. An +interface break is disruptive and must be prevented.

                  • +

                The major and minor version numbers are defined in the .mmp file +that defines the source code, header files and other options that apply to +the executable file.

                If you do not specify version numbers, the build +tools apply the following default values:

                  +

                • Major version number +: 10

                  • +

                • Minor version number +: 0

                  • +

                The major version number and the minor version number are stored +in the header of an EXE and DLL. The two numbers are stored in a single 32 +bit value. The high 16 bits hold the major version number. The low 16 bits +hold the minor version number.

                When you build a DLL, the build tools +encode the version numbers into the filename of the import library (the .lib file). +The build tools also create an import library that does not have the version +numbers encoded as part of the filename.The following example shows how the +version numbers are encoded in the filename. The major version number is (decimal) +11 and the minor version number is (decimal) 2. The version numbers in the +filename are in hexadecimal.

                abcdsrv{000B0002}.lib

                Notes:

                  +

                • The left bracket and +the right bracket are part of the name.

                  • +

                • The first four digits +after the open bracket are the hexadecimal representation of the major version +number.

                  • +

                • The second four digits +are the hexadecimal representation of the minor version number.

                  • +

                The build tools do not encode the version numbers in the filename +of the executable file.

                Loader +search rules

                EXEs and DLLs can exist on more than one drive. There +can be more than one version of an EXE and more than one version of a DLL. +The loader uses search rules to select the EXE and DLL to load.

                See Loader search rules

                Emulator

                Version numbers are stored in import files for DLLs +that run on devices and the emulator. Version numbers change how the loader +functions on devices, but not in the emulator. You cannot encode the version +numbers in the import library file name on the emulator.

                Tools support

                Use the build tools to apply version numbers +to EXEs and DLLs. You specify version numbers in the .mmp file +that describes the EXE or DLL.

                See also mmp +file syntax and Build +tools guide.

                +
                Architectural +relationships

                The loader is a server that runs in a separate thread +in the file server process. The loader is built as part of the file server.

                The +loader server starts when the file server starts. The file server starts after +the kernel is loaded at system start.

                The loader runs on the user +side, but calls the kernel for services that are not available to general +applications. Examples of services are process creation and code segment creation. +A code segment is an object that represents a piece of code loaded into RAM. +A code segment also represents a piece of code that runs directly from ROM. +The kernel services that the loader uses are protected. The file server process +only is allowed to access these services.

                The following picture is +an example of program flow. In this example, a client calls RLibrary::Load(), +which exists in euser.dll. Internal functions make client-server +calls to the loader server. The loader server code exists in efile.exe. +The loader server uses kernel services.

                + +
                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A1D2C673-3B91-403A-800B-5E1504FB19EE.dita --- a/Symbian3/SDK/Source/GUID-A1D2C673-3B91-403A-800B-5E1504FB19EE.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-A1D2C673-3B91-403A-800B-5E1504FB19EE.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,124 +1,130 @@ - - - - - -Capturing -still images -

                To capture still images or to use the display as a viewfinder, build -your application around the Symbian Ecam camera utility. To make use of the -device camera to capture an image, the application needs to repeat the steps -described in the illustration below.

                -The steps required to capture a still image - -

                The settings you can use in your application depend on what the camera -hardware on the device supports.

                -                 -

                To capture images, use the methods of the CCamera and MCameraObserver2 classes to construct your application. MCameraObserver2 uses -the advanced camera features of the CCamera::CCameraAdvancedSettings class.

                -

                For reference examples, see:

                -
                  -

                • Camera -Example: Capturing and controlling the images using Camera

                  • -

                • Introduction to the Camera API on the Symbian Foundation

                  -
                  • -

                • S60 Platform: Camera Example on Forum Nokia.

                  • -
                -
                To capture still images on a mobile device -
                  -

                1. Initialize -the onboard camera.

                  -
                    -

                  • Create a camera object using the CCamera::New2L() method.

                    • -

                  • Reserve the camera for your application using the CCamera::Reserve() method. MCameraObserver2::HandleEvent is called upon -completion.

                    • -

                  • Switch on the camera power using the CCamera::PowerOn() method. MCameraObserver2::HandleEvent is called upon -completion.

                    • -

                  • If needed, share the camera between multiple clients using -the CCamera::NewDuplicate2L() function. This function -needs the handle of an existing camera object (use CCamera::Handle()).

                    • -
                  -
                  2. -

                2. Configure -the camera settings.

                  -
                    -

                  • Before you adjust the settings, make sure the camera hardware -supports the particular option. Use CCamera::CameraInfo() to retrieve and TCameraInfo to -specify the camera information.

                    For example, to find out what -image formats are supported by the onboard camera, use the TCameraInfo::iImageFormatsSupported member variable.

                    • -

                  • Specify the image format using the CCamera::PrepareImageCaptureL method. For a list of -possible formats, see CCamera::TFormat.

                    Devices support image capture in EXIF JPEG format (CCamera::EFormatExif), which is encoded with -JPEG and requires no additional conversion.

                    • -

                  • Specify the desired image size using the CCamera::EnumerateCaptureSizes() method.

                    -
                    • -

                  • Additionally, you can set, for example, the brightness, contrast, -zoom level, flash mode, exposure and white balance of the image. For more -information on the options, see the CCamera::CCameraAdvancedSettings class. You can also use the settings directly under CCamera.

                    -
                    • -
                  -
                    -

                  • Before you can call CCamera::CaptureImage(), -allocate memory and set up image format, size and clipping rectangle using -the CCamera::PrepareImageCaptureL() method. This -needs to be called only once for multiple captures.

                    • -
                  -
                  3. -

                3. Use the display -of the device as a viewfinder by transferring image data from the camera to -the display memory.

                  -
                    -

                  • Start the transfer of viewfinder data with direct screen -access using the CCamera::StartViewFinderDirectL() method.

                    -
                    • -

                  • Transfer viewfinder data as a bitmap using the CCamera::StartViewFinderBitmapsL() method. - MCameraObserver2::ViewFinderReady is called -upon completion.

                    • -

                  • Set viewfinder mirroring on and flip the image horizontally -using the CCamera::SetViewFinderMirrorL() method.

                    -
                    • -

                  • Stop the transfer of viewfinder data to the screen using -the CCamera::StopViewFinder() method.

                    • -
                  -
                  4. -

                4. Capture one -or multiple images using the CCamera::CaptureImage() method. MCameraObserver2::ImageBufferReady() is called -upon completion.

                  5. -

                5. To exit the -application or to switch it to the background, switch off the camera power -using the CCamera::PowerOff() method and release the -camera for other applications using the CCamera::Release() method.

                  6. -

                6. The CCamera and MCameraObserver2 classes -are defined in the ecam.h header file. Add the following -line to the .h file, which is used to deploy the API:

                  -#include <ecam.h> -
                  7. -

                7. Make sure -you have correct capabilities information -set for your application. You need at least the UserEnvironment capability.

                  -
                  8. -

                8. Make sure ecam.lib is -accessible to your linker when compiling your application by including it -in your mmp file or by editing the project properties in -your IDE, depending on your build environment.

                  9. -
                -
                -
                See also -

                Capturing Image

                -

                Controlling Pre-Image -Capture

                -

                Controlling Captured -Image

                -

                Controlling Still-image -Capture

                -

                Using Time Nudge -Capture Drive Mode

                -

                Background Processing -for Ecam

                -
                + + + + + +Capturing +Still Images +

                To capture still images or to use the display as a viewfinder, build +your application around the Symbian Ecam camera utility. To make use of the +device camera to capture an image, the application needs to repeat the steps +described in the illustration below.

                +The steps required to capture a still image +

                Important implementation considerations include:

                +
                  +

                • The settings you can use in your application depend on what +the camera hardware on the device supports.

                  • +

                • To capture images, use the methods of the CCamera and MCameraObserver2 classes +to construct your application. MCameraObserver2 uses the +advanced camera features of the CCamera::CCameraAdvancedSettings class. +The CCamera and MCameraObserver2 classes +are defined in the ecam.h header file. Add the following +line to the .h file, which is used to deploy the API:

                  +#include <ecam.h> +
                  • +

                • Make sure you have correct capabilities information +set for your application. You need at least the UserEnvironment capability.

                  +
                  • +

                • Make sure ecam.lib is accessible to your +linker when compiling your application by including it in your mmp file +or by editing the project properties in your IDE, depending on your build +environment.

                  • +
                +
                To capture still +images on a mobile device +
                  +

                1. Initialize +the onboard camera.

                  +
                    +

                  • Create a camera object using the CCamera::New2L() method.

                    +
                    • +

                  • Reserve the camera for your application using the CCamera::Reserve() method. MCameraObserver2::HandleEvent is called upon completion.

                    • +

                  • Switch on the camera power using the CCamera::PowerOn() method. MCameraObserver2::HandleEvent is +called upon completion.

                    • +

                  • If needed, share the camera between multiple clients using +the CCamera::NewDuplicate2L() function. This function needs +the handle of an existing camera object (use CCamera::Handle()).

                    +
                    • +
                  +
                  2. +

                2. Configure +the camera settings.

                  +
                    +

                  • Before you adjust the settings, make sure the camera hardware +supports the particular option. Use CCamera::CameraInfo() to +retrieve and TCameraInfo to specify the camera information.

                    +

                    For example, to find out what image formats are supported by the onboard +camera, use the TCameraInfo::iImageFormatsSupported member +variable.

                    • +

                  • Specify the image format using the CCamera::PrepareImageCaptureL method. +For a list of possible formats, see CCamera::TFormat.

                    +

                    Devices support image capture in EXIF JPEG format (CCamera::EFormatExif), +which is encoded with JPEG and requires no additional conversion.

                    • +

                  • Specify the desired image size using the CCamera::EnumerateCaptureSizes() method.

                    +
                    • +

                  • Additionally, you can set, for example, the brightness, contrast, +zoom level, flash mode, exposure and white balance of the image. For more +information on the options, see the CCamera::CCameraAdvancedSettings class. +You can also use the settings directly under CCamera.

                    +
                    • +
                  +
                    +

                  • Before you can call CCamera::CaptureImage(), +allocate memory and set up image format, size and clipping rectangle using +the CCamera::PrepareImageCaptureL() method. This needs to +be called only once for multiple captures.

                    • +
                  +
                  3. +

                3. Use the display +of the device as a viewfinder by transferring image data from the camera to +the display memory.

                  +
                    +

                  • Start the transfer of viewfinder data with direct screen +access using the CCamera::StartViewFinderDirectL() method.

                    +
                    • +

                  • Transfer viewfinder data as a bitmap using the CCamera::StartViewFinderBitmapsL() method. + MCameraObserver2::ViewFinderReady is called upon completion.

                    +
                    • +

                  • Set viewfinder mirroring on and flip the image horizontally +using the CCamera::SetViewFinderMirrorL() method.

                    +
                    • +

                  • Stop the transfer of viewfinder data to the screen using +the CCamera::StopViewFinder() method.

                    • +
                  +
                  4. +

                4. Capture one +or multiple images using the CCamera::CaptureImage() method. MCameraObserver2::ImageBufferReady() is +called upon completion.

                  5. +

                5. To exit the +application or to switch it to the background, switch off the camera power +using the CCamera::PowerOff() method and release the camera +for other applications using the CCamera::Release() method.

                  +
                  6. +
                +
                +
                Additional information +on capturing still images +

                For reference examples, see:

                +
                  +

                • Camera +Example: Capturing and controlling the images using Camera

                  • +

                • Introduction to the Camera API on the Symbian Foundation

                  +
                  • +

                • S60 Platform: Camera Example on Forum Nokia.

                  • +
                +

                For information on how to capture an image using Time-Nudge-Capture +drive mode, see Using +Time Nudge Capture Drive Mode .

                +

                For information on how to capture an image using standalone background +processing, see Background +Processing for Ecam.

                +

                For information on displaying images on the screen, see Image +Display Library Overview

                +
                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A1DBE03F-728E-4F31-BE74-5BDA3906C8DD.dita --- a/Symbian3/SDK/Source/GUID-A1DBE03F-728E-4F31-BE74-5BDA3906C8DD.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-A1DBE03F-728E-4F31-BE74-5BDA3906C8DD.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,42 +1,42 @@ - - - - - -Themes -

                The term theme refers to a set of design elements installed in -a package in a mobile device based on the Symbian platform that determines -the visual appearance of the UI. Themes, also known as skins, only -affect the visual appearance of the UI, the underlying architecture, interaction -style, language settings, and general functionality are not affected.

                -Personalization through themes -

                The Symbian platform provides an API to allow you to support themes -in your applications. Although a mobile device based on the Symbian platform -can contain several themes, mobile device users can only activate one theme -at a time. When a new theme is activated, the appearance of all applications -that support themes is altered.

                -

                The following list contains some of the UI design elements that can -change:

                -
                  -

                • display background

                  • -

                • color palette

                  • -

                • highlights

                  • -

                • pop-up window appearance

                  • -

                • ring tones

                  • -

                • common component look and feel

                  • -
                -

                Themes also support SVG-T graphics, which allow them to be scalable. -Themes can contain bitmaps or SVG graphics or a mixture of both.

                -

                For more information on the API that enables theme support in applications, -see the Skins -API documentation.

                -

                For information on tools available for creating and modifying themes, -see Forum -Nokia.

                + + + + + +Themes +

                The term theme refers to a set of design elements installed in +a package in a mobile device based on the Symbian platform that determines +the visual appearance of the UI. Themes, also known as skins, only +affect the visual appearance of the UI, the underlying architecture, interaction +style, language settings, and general functionality are not affected.

                +Personalization through themes +

                The Symbian platform provides an API to allow you to support themes +in your applications. Although a mobile device based on the Symbian platform +can contain several themes, mobile device users can only activate one theme +at a time. When a new theme is activated, the appearance of all applications +that support themes is altered.

                +

                The following list contains some of the UI design elements that can +change:

                +
                  +

                • display background

                  • +

                • color palette

                  • +

                • highlights

                  • +

                • pop-up window appearance

                  • +

                • ring tones

                  • +

                • common component look and feel

                  • +
                +

                Themes also support SVG-T graphics, which allow them to be scalable. +Themes can contain bitmaps or SVG graphics or a mixture of both.

                +

                For more information on the API that enables theme support in applications, +see the Skins +API documentation.

                +

                For information on tools available for creating and modifying themes, +see Forum +Nokia.

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A2031A61-3319-4FBA-BC71-AC1327182053.dita --- a/Symbian3/SDK/Source/GUID-A2031A61-3319-4FBA-BC71-AC1327182053.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-A2031A61-3319-4FBA-BC71-AC1327182053.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,91 +1,91 @@ - - - - - -Getting -started with C++ Standard LibraryThe Standard C++ library depends on P.I.P.S.. The user must have -the P.I.P.S. components installed before using the library. -
                C++ IOstream -and Standard Template Library Documentation

                C++ IOStream library -documentation can be found at http://www.slac.stanford.edu/comp/unix/gnu-info/iostream_toc.html.

                Similarly, -Standard Template Library (STL) documentation can be found at http://www.informatik.uni-freiburg.de/~danlee/fun/STL-doc/STL.html.

                -
                Changes to -the MMP file

                Add needed libraries used by the MMP file structure:

                If -developers want to use any of Standard C++ library, they must link to the -corresponding library in the MMP file using the LIBRARY keyword.

                If -the application has main() as the entry point, the library libcrt0.lib must -be specified as the first library otherwise, it results in linker errors. -The user must link to the Symbian platform euser.dll. -This is required since the static library uses some of the services of the -Symbian platform, such as, creating cleanup stack, and having a top level -TRAP. All these details are hidden from the developer. The developer will -write the application as if it were for the UNIX environment.

                STATICLIBRARY libcrt0.lib -LIBRARY libc.lib -LIBRARY euser.lib // Needed in order to use Symbian services -

                The libcrt0.lib library is required for -writing to E32Main within our application (EXE). This static -library has an implementation of E32Main within which it -calls the library initialization method followed by calling main written by -the developer. This static library also retrieves command-line arguments and -passes the same to main.

                If the application has E32Main() as -an entry point, there is no need to link to libcrt0.lib like -in the example below.

                LIBRARY libc.lib -LIBRARY euser.lib

                Add required include paths

                SYSTEMINCLUDE \epoc32\include\stdapis -SYSTEMINCLUDE \epoc32\include\stdapis\sys -SYSTEMINCLUDE \epoc32\include\stdapis\stlport -

                Linking of libstdcpp

                Following -snippet shows how to perform the linking to libstdcpp on -an emulator:

                #ifdef EPOC32 -LIBRARY libstdcpp.lib -#else -FIRSTLIB ../udeb/libstdcpp.lib -STATICLIBRARY eexe.lib -#endif

                Add the below option and macro in the MMP file

                //This is required even if the wchar type is not used. -OPTION CW -wchar_t on -MACRO _WCHAR_T_DECLARED Standard C++ applications may require -more stack space. The recommended stack size is 10K. To set the stack size -to 10K add: EPOCSTACKSIZE 0x10000

                in the MMP -file.

                -
                Example using <codeph>main()</codeph> -

                A simple example using main() as an entry point is -described below. The example writes a text to a console.

                  -

                • Modify the MMP file as mentioned before.

                  • -

                • Do usual C++ style coding.

                  • -
                // Include Files -#include <iostream> -#include <cstring> -// This is a GCCE toolchain workaround needed when compiling with GCCE -// and using main() entry point -#ifdef __GCCE__ - -// This is a GCCE toolchain workaround needed when compiling with GCCE -// and using main() entry point -#ifdef __GCCE__ - -#include <staticlibinit_gcce.h> -#endif - -using namespace std; - -class myclass { -public: - void show(){cout<<"Hello World\n"; } -} ; - -int main() -{ - myclass obj; - obj.show(); - cout<<"Press a character to exit!"; - int c = getchar(); - return 0; -} -
                + + + + + +Getting +started with C++ Standard LibraryThe Standard C++ library depends on P.I.P.S.. The user must have +the P.I.P.S. components installed before using the library. +
                C++ IOstream +and Standard Template Library Documentation

                C++ IOStream library +documentation can be found at http://www.slac.stanford.edu/comp/unix/gnu-info/iostream_toc.html.

                Similarly, +Standard Template Library (STL) documentation can be found at http://www.informatik.uni-freiburg.de/~danlee/fun/STL-doc/STL.html.

                +
                Changes to +the MMP file

                Add needed libraries used by the MMP file structure:

                If +developers want to use any of Standard C++ library, they must link to the +corresponding library in the MMP file using the LIBRARY keyword.

                If +the application has main() as the entry point, the library libcrt0.lib must +be specified as the first library otherwise, it results in linker errors. +The user must link to the Symbian platform euser.dll. +This is required since the static library uses some of the services of the +Symbian platform, such as, creating cleanup stack, and having a top level +TRAP. All these details are hidden from the developer. The developer will +write the application as if it were for the UNIX environment.

                STATICLIBRARY libcrt0.lib +LIBRARY libc.lib +LIBRARY euser.lib // Needed in order to use Symbian services +

                The libcrt0.lib library is required for +writing to E32Main within our application (EXE). This static +library has an implementation of E32Main within which it +calls the library initialization method followed by calling main written by +the developer. This static library also retrieves command-line arguments and +passes the same to main.

                If the application has E32Main() as +an entry point, there is no need to link to libcrt0.lib like +in the example below.

                LIBRARY libc.lib +LIBRARY euser.lib

                Add required include paths

                SYSTEMINCLUDE \epoc32\include\stdapis +SYSTEMINCLUDE \epoc32\include\stdapis\sys +SYSTEMINCLUDE \epoc32\include\stdapis\stlport +

                Linking of libstdcpp

                Following +snippet shows how to perform the linking to libstdcpp on +an emulator:

                #ifdef EPOC32 +LIBRARY libstdcpp.lib +#else +FIRSTLIB ../udeb/libstdcpp.lib +STATICLIBRARY eexe.lib +#endif

                Add the below option and macro in the MMP file

                //This is required even if the wchar type is not used. +OPTION CW -wchar_t on +MACRO _WCHAR_T_DECLARED Standard C++ applications may require +more stack space. The recommended stack size is 10K. To set the stack size +to 10K add: EPOCSTACKSIZE 0x10000

                in the MMP +file.

                +
                Example using <codeph>main()</codeph> +

                A simple example using main() as an entry point is +described below. The example writes a text to a console.

                  +

                • Modify the MMP file as mentioned before.

                  • +

                • Do usual C++ style coding.

                  • +
                // Include Files +#include <iostream> +#include <cstring> +// This is a GCCE toolchain workaround needed when compiling with GCCE +// and using main() entry point +#ifdef __GCCE__ + +// This is a GCCE toolchain workaround needed when compiling with GCCE +// and using main() entry point +#ifdef __GCCE__ + +#include <staticlibinit_gcce.h> +#endif + +using namespace std; + +class myclass { +public: + void show(){cout<<"Hello World\n"; } +} ; + +int main() +{ + myclass obj; + obj.show(); + cout<<"Press a character to exit!"; + int c = getchar(); + return 0; +} +
                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A24491E4-867F-4006-9798-07281553EA51.dita --- a/Symbian3/SDK/Source/GUID-A24491E4-867F-4006-9798-07281553EA51.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-A24491E4-867F-4006-9798-07281553EA51.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,82 +1,103 @@ - - - - - -Release -NotesThis library is intended for application developers for the Symbian^3 -platform. -
                Major changes -between the week 03 2010 release and week 12 2010 release

                Since -the week 03 2010 documentation submission to the Symbian Foundation, the following -major additions have been made:

                  -

                • Inclusion of API reference extracted from the Symbian^3 source code.

                  • -

                • Inclusion of API specifications.

                  • -

                • A new About -Symbian^3 topic, including What's new and Porting applications from -S60 5th Edition to Symbian^3.

                  • -

                • A new Getting -Started, consisting of the Symbian Foundation's C++ Quick Start and -Going Beyond Hello tutorials.

                  • -

                • Integration of the Panic -Codes Reference.

                  • -

                • Addition of new topics: Common -Email Guide and System -Resource Monitoring.

                  • -

                • The Graphics Guide has been updated for Symbian^3. For details, see What's New in Graphics in -Symbian^3.

                  • -

                • The Classic -UI Guide has been updated for Symbian^3.

                  • -

                • All guides have been updated to refer to the Symbian platform rather -than to Symbian OS and to S60, apart from where it is necessary to refer to -past releases.

                  • -

                Bug fixes:

                This release contains fixes for the following -bugs:

                  -

                • Change section headings in Symbian^3 product/app reference

                  • -

                • Fix up the links in the Platform security architecture page

                  • -

                • Link to sample chapter of quick recipes book in SDK docs

                  • -

                • Remove "Using the Indexes"

                  • -

                • ambiguous documentation of text-options

                  • -

                • Remove references to SDN and SDN++ from Symbian Developer -Library

                  • -

                • Guide landing page is empty

                  • -
                -
                Major changes -between the week 43 2009 release and week 03 2010 release

                New -content:

                  -

                • Classic UI Guide

                  • -

                • High Level Internet -Protocols Guide

                  • -

                • Short Link Services -Guide

                  • -

                • Web Guide

                  • -

                The following S60 5th Edition C++ Developer's Library 'Technology -area guides' have been integrated into the Symbian guide:

                  -

                • Application -and UI frameworks is now in Classic UI Guide.

                  • -

                • S60 UI components is -now in Classic UI Guide.

                  • -

                • Multimedia is -now in Multimedia Guide.

                  • -

                • Browsing and -downloading is now in Web Guide.

                  • -

                • Location is -now in Location Based Services (LBS).

                  • -

                • Security is -now found at the top level.

                  • -

                The S60 Open C and Open C++ documentation has been merged into the -Symbian P.I.P.S. documentation and is now in Generic -OS Services Guide.

                Other changes:

                The Symbian Developer -Library for Application Developers is released under the Eclipse Public License (EPL).

                -
                Upcoming releases -and improvements in the Symbian Developer Library for Application Developers

                See -the Documentation Content Package Backlog.

                -
                Feedback

                To -give feedback, please go to the Symbian Foundation Bugtracker (login required).

                + + + + + +Release NotesThis library is intended for application developers for +the Symbian^3 platform. +
                Major changes between the week 12 2010 release and +week 22 2010 release

                Since the week 12 2010 documentation +submission to the Symbian Foundation, the following major additions +have been made:

                  +

                • CryptoSPI + documentation.

                  • +

                • API +changes and compatibility breaks.

                  • +

                • IP Connection +Management.

                  • +

                Bug fixes:

                This release contains fixes for the +following bugs and known issues:

                  +

                • Symbian^3 documentation.

                  • +

                • Buildrom content is missing.

                  • +

                • Some links to Multimedia example code occur more than once +in the table of contents and in landing pages.

                  • +

                • Links to the Open C examples in the full example code list +are broken.

                  • +

                • Broken and incorrect links in Platform security architecture +and Optional resource file statements topics.

                  • +

                • The breadcrumb trails for Application framework guide, Multimedia +example code and System GUI Framework example code are wrong and contains +duplicates.

                  • +
                +
                Major +changes between the week 03 2010 release and week 12 2010 release

                Since the week 03 2010 documentation submission to the Symbian +Foundation, the following major additions have been made:

                  +

                • Inclusion of API reference extracted from the Symbian^3 source +code.

                  • +

                • Inclusion of API specifications.

                  • +

                • A new About Symbian^3 topic, including What's new and Porting applications +from S60 5th Edition to Symbian^3.

                  • +

                • A new Getting Started, consisting of the Symbian Foundation's C++ +Quick Start and Going Beyond Hello tutorials.

                  • +

                • Integration of the Panic Codes Reference.

                  • +

                • Addition of new topics: Common Email Guide and System +Resource Monitoring.

                  • +

                • The Graphics Guide has been updated for Symbian^3. For details, +see What's +New in Graphics in Symbian^3.

                  • +

                • The Classic UI Guide has been updated for Symbian^3.

                  • +

                • All guides have been updated to refer to the Symbian platform +rather than to Symbian OS and to S60, apart from where it is necessary +to refer to past releases.

                  • +

                Bug fixes:

                This release contains fixes for the +following bugs:

                  +

                • Change section headings in Symbian^3 product/app +reference

                  • +

                • Fix up the links in the Platform security architecture +page

                  • +

                • Link to sample chapter of quick recipes book in SDK +docs

                  • +

                • Remove "Using the Indexes"

                  • +

                • ambiguous documentation of text-options

                  • +

                • Remove references to SDN and SDN++ from Symbian Developer +Library

                  • +

                • Guide landing page is empty

                  • +
                +
                Major +changes between the week 43 2009 release and week 03 2010 release

                New content:

                  +

                • Classic +UI Guide

                  • +

                • High +Level Internet Protocols Guide

                  • +

                • Short +Link Services Guide

                  • +

                • Web +Guide

                  • +

                The following S60 5th Edition C++ Developer's Library 'Technology +area guides' have been integrated into the Symbian guide:

                  +

                • Application +and UI frameworks is now in Classic UI Guide.

                  • +

                • S60 +UI components is now in Classic UI Guide.

                  • +

                • Multimedia is now in Multimedia Guide.

                  • +

                • Browsing +and downloading is now in Web Guide.

                  • +

                • Location is now in Location Based Services (LBS).

                  • +

                • Security is now found at the top level.

                  • +

                The S60 Open C and Open C++ documentation has been merged +into the Symbian P.I.P.S. documentation and is now in Generic OS Services +Guide.

                Other changes:

                The Symbian Developer +Library for Application Developers is released under the Eclipse Public License (EPL).

                +
                Known issues in the week 22 2010 release

                See Known issues with Symbian3 product developers +library.

                +
                Upcoming +releases and improvements in the Symbian Developer Library for Application +Developers

                See the Documentation Content Package Backlog.

                +
                Feedback

                To give feedback, please go to the Symbian Foundation Bugtracker (login required).

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A29FD82C-B3CC-5862-8DAB-1398A61D8B1F.dita --- a/Symbian3/SDK/Source/GUID-A29FD82C-B3CC-5862-8DAB-1398A61D8B1F.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-A29FD82C-B3CC-5862-8DAB-1398A61D8B1F.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,185 +1,185 @@ - - - - - -Overview -

                The SIP Client API manages the multimedia sessions, subscribes to events, -and sends SIP messages. It also provides access to the basic services of the -SIP stack such as:

                -
                  -

                • Sending and receiving -of SIP messages

                  • -

                • Creating registrations

                  • -

                • Forming and tearing -down dialogs initiated by INVITE, REFER and SUBSCRIBE requests

                  • -
                -
                Architectural -relationships

                The SIP Client API uses the client-server mechanism -to interact with the SIP stack. This means more than one client can use the -SIP stack at the same time. The calls to the SIP Client API are synchronous. -The SIP Client API implements a set of callback functions to pass the events -back to the application.

                Capability information

                The -following table describes the capabilities required to use the SIP Client -API and the conditions in which they are required:

                - - - -Capability -Reason needed - - - - -

                NetworkServices

                -

                to send or receive SIP messages

                -                 - -

                WriteDeviceData

                -

                to create an instance of the CSIP class

                -                 - -

                NetworkControl

                Location

                ReadDeviceData

                -

                to use the function CSIPConnection::SetOptL()

                -                 - - -

                Extending the API

                SIP Client API cannot be extended.

                -
                SIP Client -API class structure
                  -

                • CSIP, MSIPObserver, CSIPConnection and MSIPConnectionObserver

                  • -

                • Registration services

                  • -

                • SIP dialog associations

                  • -

                • Requests sent to, and received from, the network

                  • -

                • SIP message related classes

                  • -

                • Automatically refreshing a SIP request

                  • -

                • Managing HTTP digest security settings

                  • -

                CSIP, MSIPObserver, -CSIPConnection and MSIPConnectionObserver

                - -

                An application creates a single instance of the CSIP class, -and implements the callback functions defined by MSIPObserver. -The CSIP uses the MSIPObserver functions. -The CSIP class asks the supported security mechanisms and -determines whether a CSIPConnection object exists for a -given IAP.

                The CSIP object creates an instance -of CSIPConnection that allows you to send standalone SIP -requests and ask for the state of the network connection. Responses are received -through the MSIPConnectionObserver interface that defines -a set of callback functions that an application must implement.

                An -application can have many CSIPConnection objects, but each -of them must have a different IAP.

                Registration -services

                - -

                An existing CSIPConnection is required to create -an instance of CSIPRegistrationBinding. The CSIPRegistrationBinding class -provides services for registration, updating the registration, and deregistration. -This class also provides instructions to the SIP stack to automatically refresh -the registration, and to query and set the outbound proxy used by the registration.

                SIP dialog -associations

                - -

                CSIPDialogAssocBase is the base class for SIP -dialog associations, such as CSIPInviteDialogAssoc, CSIPSubscribeDialogAssoc, CSIPReferDialogAssoc and CSIPNotifyDialogAssoc. The CSIPDialogAssocBase class -is used to obtain the associated SIP dialog, for the associated CSIPDialog instance, -and for sending a non-target Refresh request within the dialog.

                Note: The -SIP Client API creates the CSIPDialog instance, it cannot -be created by the application.

                If any of the CSIPInviteDialogAssoc, CSIPSubscribeDialogAssoc, CSIPReferDialogAssoc and CSIPNotifyDialogAssoc objects -are associated, they are bound to an existing CSIPDialog object, -or they can be used to create a new CSIPDialog object.

                Note:

                  -

                • CSIPInviteDialogAssoc allows -an application to initiate a dialog and to send INVITE,,PRACK,,ACK, UPDATE, and BYE requests related to the dialog.

                  • -

                • CSIPSubscribeDialogAssoc allows -an application to subscribe to different events by sending SUBSCRIBE and UNSUBSCRIBE -requests. It also orders the SIP stack to automatically refresh the SUBSCRIBE -request.

                  • -

                • CSIPReferDialogAssoc allows -an application to define and send REFER requests.

                  • -

                • CSIPNotifyDialogAssoc allows -an application to define and send NOTIFY requests.

                  • -

                Sent and received -network requests

                - -

                When a SIP request is sent to the network, the SIP Client API implementation -creates a CSIPClientTransaction object and returns it to -the application. A CSIPClientTransaction object represents -the SIP transaction and consists of the SIP request and the SIP response. -After receiving a response, the application gets CSIPResponseElements from -the CSIPClientTransaction object. Note: Some client -transactions can also be cancelled or refreshed.

                When a SIP request -is received from the network, it is passed to the application as a CSIPServerTransaction object. -The application gets CSIPRequestElements from the CSIPServerTransaction object. -A CSIPRequestElements object describes the kind of SIP request -received. After the application determines the type of response to send, it -uses the CSIPServerTransaction to send the responses.

                CSIPTransactionBase is -the base class for CSIPClientTransaction and CSIPServerTransaction. -It provides the functions to obtain the current state of the transaction and -the transaction type. Some operations are only allowed when the transaction -is in a certain state. Note: The SIP Client API creates instances of CSIPClientTransaction and CSIPServerTransaction and they cannot be created by the application.

                SIP -message related classes

                - -

                When a SIP request is sent to the network, the SIP Client API implementation -creates a CSIPClientTransaction object and returns it to -the application. A CSIPClientTransaction object represents -the SIP transaction and consists of the SIP request and the SIP response. -After receiving a response the application gets CSIPResponseElements from -the CSIPClientTransaction object. Note: Some client -transactions can be cancelled or refreshed.

                When a SIP request is -received from the network, it is passed to the application as a CSIPServerTransaction object. -The application gets CSIPRequestElements from the CSIPServerTransaction object. -A CSIPRequestElements object describes the type of SIP request -received. After the application determines the type of response to send, it -uses the CSIPServerTransaction to send the responses.

                CSIPTransactionBase is -the base class for CSIPClientTransaction and CSIPServerTransaction. -It provides functions to obtain the current state of the transaction and the -transaction type. Some operations are only allowed when the transaction is -in a certain state. Note: The SIP Client API creates instances of CSIPClientTransaction and CSIPServerTransaction and they cannot be created by the application.

                Automatically -refreshing a SIP request

                - -

                The SIP stack automatically refreshes a SIP request using the CSIPRefresh object. REGISTER, SUBSCRIBE and a request outside the dialog are refreshed. After -sending a refresh request, the application queries the state of the refresh -from CSIPRefresh.

                CSIPRefresh provides -functions for updating and terminating the refresh, for requests outside the -dialog. The CSIPRegistrationBinding and CSIPSubscribeDialogAssoc classes -are used to update and terminate a refreshed REGISTER or SUBSCRIBE.

                Managing HTTP digest security -settings

                - -

                An application must create an instance of the CSIP class -to use CSIPHttpDigest. The CSIPHttpDigest class -manages HTTP digest security settings and contains only static functions.

                -
                Memory used

                After -the CSIP and CSIPConnection objects -are created, most of the memory consumed is by CSIPMessageElements, CSIPRequestElements and CSIPResponseElements classes. CSIPTransactionBase holds the most recent SIP -response in a CSIPResponseElements object. When another -response is received, the previous CSIPResponseElements object -is deleted and a new one is created.

                CSIPClientTransaction contains -a CSIPRequestElements object until the SIP request is transferred -to the server side of the SIP stack. CSIPServerTransaction contains -the SIP request as CSIPRequestElements. The application -owns the CSIPClientTransaction and CSIPServerTransaction objects. -When the transaction terminates, the application deletes these objects to -conserve memory.

                A non-INVITE CSIPClientTransaction is -deleted when it has received a final response or when the ErrorOccured() callback -is called. A non-INVITE CSIPServerTransaction is -deleted after the application sends a final response.

                The INVITE related -transactions are deleted if the ErrorOccured() callback function -is called. These transactions behave differently because of the presence of -an ACK.

                When the application sends a 2xx response -to an INVITE related CSIPServerTransaction, -it enters the CSIPTransactionBase::ETerminated state and -it is deleted at this point. A new CSIPServerTransaction object -receives the ACK.

                When the application sends an INVITE request -and the CSIPClientTransaction receives a 2xx response, the -transaction enters the CSIPTransactionBase::ETerminated state. -The associated CSIPClientTransaction must not be deleted -as it is required to send the ACK and also to receive the MSIPConnectionObserver::InviteCompleted() callback. -An INVITE related CSIPClientTransaction must -be deleted only after a MSIPConnectionObserver::InviteCompleted or MSIPConnectionObserver -::ErrorOccured event is received, or if the state of the associated CSIPConnection goes -to CSIPConnection::EInactive or CSIPConnection::EUnavailable.

                + + + + + +Overview +

                The SIP Client API manages the multimedia sessions, subscribes to events, +and sends SIP messages. It also provides access to the basic services of the +SIP stack such as:

                +
                  +

                • Sending and receiving +of SIP messages

                  • +

                • Creating registrations

                  • +

                • Forming and tearing +down dialogs initiated by INVITE, REFER and SUBSCRIBE requests

                  • +
                +
                Architectural +relationships

                The SIP Client API uses the client-server mechanism +to interact with the SIP stack. This means more than one client can use the +SIP stack at the same time. The calls to the SIP Client API are synchronous. +The SIP Client API implements a set of callback functions to pass the events +back to the application.

                Capability information

                The +following table describes the capabilities required to use the SIP Client +API and the conditions in which they are required:

                + + + +Capability +Reason needed + + + + +

                NetworkServices

                +

                to send or receive SIP messages

                +                 + +

                WriteDeviceData

                +

                to create an instance of the CSIP class

                +                 + +

                NetworkControl

                Location

                ReadDeviceData

                +

                to use the function CSIPConnection::SetOptL()

                +                 + + +

                Extending the API

                SIP Client API cannot be extended.

                +
                SIP Client +API class structure
                  +

                • CSIP, MSIPObserver, CSIPConnection and MSIPConnectionObserver

                  • +

                • Registration services

                  • +

                • SIP dialog associations

                  • +

                • Requests sent to, and received from, the network

                  • +

                • SIP message related classes

                  • +

                • Automatically refreshing a SIP request

                  • +

                • Managing HTTP digest security settings

                  • +

                CSIP, MSIPObserver, +CSIPConnection and MSIPConnectionObserver

                + +

                An application creates a single instance of the CSIP class, +and implements the callback functions defined by MSIPObserver. +The CSIP uses the MSIPObserver functions. +The CSIP class asks the supported security mechanisms and +determines whether a CSIPConnection object exists for a +given IAP.

                The CSIP object creates an instance +of CSIPConnection that allows you to send standalone SIP +requests and ask for the state of the network connection. Responses are received +through the MSIPConnectionObserver interface that defines +a set of callback functions that an application must implement.

                An +application can have many CSIPConnection objects, but each +of them must have a different IAP.

                Registration +services

                + +

                An existing CSIPConnection is required to create +an instance of CSIPRegistrationBinding. The CSIPRegistrationBinding class +provides services for registration, updating the registration, and deregistration. +This class also provides instructions to the SIP stack to automatically refresh +the registration, and to query and set the outbound proxy used by the registration.

                SIP dialog +associations

                + +

                CSIPDialogAssocBase is the base class for SIP +dialog associations, such as CSIPInviteDialogAssoc, CSIPSubscribeDialogAssoc, CSIPReferDialogAssoc and CSIPNotifyDialogAssoc. The CSIPDialogAssocBase class +is used to obtain the associated SIP dialog, for the associated CSIPDialog instance, +and for sending a non-target Refresh request within the dialog.

                Note: The +SIP Client API creates the CSIPDialog instance, it cannot +be created by the application.

                If any of the CSIPInviteDialogAssoc, CSIPSubscribeDialogAssoc, CSIPReferDialogAssoc and CSIPNotifyDialogAssoc objects +are associated, they are bound to an existing CSIPDialog object, +or they can be used to create a new CSIPDialog object.

                Note:

                  +

                • CSIPInviteDialogAssoc allows +an application to initiate a dialog and to send INVITE,,PRACK,,ACK, UPDATE, and BYE requests related to the dialog.

                  • +

                • CSIPSubscribeDialogAssoc allows +an application to subscribe to different events by sending SUBSCRIBE and UNSUBSCRIBE +requests. It also orders the SIP stack to automatically refresh the SUBSCRIBE +request.

                  • +

                • CSIPReferDialogAssoc allows +an application to define and send REFER requests.

                  • +

                • CSIPNotifyDialogAssoc allows +an application to define and send NOTIFY requests.

                  • +

                Sent and received +network requests

                + +

                When a SIP request is sent to the network, the SIP Client API implementation +creates a CSIPClientTransaction object and returns it to +the application. A CSIPClientTransaction object represents +the SIP transaction and consists of the SIP request and the SIP response. +After receiving a response, the application gets CSIPResponseElements from +the CSIPClientTransaction object. Note: Some client +transactions can also be cancelled or refreshed.

                When a SIP request +is received from the network, it is passed to the application as a CSIPServerTransaction object. +The application gets CSIPRequestElements from the CSIPServerTransaction object. +A CSIPRequestElements object describes the kind of SIP request +received. After the application determines the type of response to send, it +uses the CSIPServerTransaction to send the responses.

                CSIPTransactionBase is +the base class for CSIPClientTransaction and CSIPServerTransaction. +It provides the functions to obtain the current state of the transaction and +the transaction type. Some operations are only allowed when the transaction +is in a certain state. Note: The SIP Client API creates instances of CSIPClientTransaction and CSIPServerTransaction and they cannot be created by the application.

                SIP +message related classes

                + +

                When a SIP request is sent to the network, the SIP Client API implementation +creates a CSIPClientTransaction object and returns it to +the application. A CSIPClientTransaction object represents +the SIP transaction and consists of the SIP request and the SIP response. +After receiving a response the application gets CSIPResponseElements from +the CSIPClientTransaction object. Note: Some client +transactions can be cancelled or refreshed.

                When a SIP request is +received from the network, it is passed to the application as a CSIPServerTransaction object. +The application gets CSIPRequestElements from the CSIPServerTransaction object. +A CSIPRequestElements object describes the type of SIP request +received. After the application determines the type of response to send, it +uses the CSIPServerTransaction to send the responses.

                CSIPTransactionBase is +the base class for CSIPClientTransaction and CSIPServerTransaction. +It provides functions to obtain the current state of the transaction and the +transaction type. Some operations are only allowed when the transaction is +in a certain state. Note: The SIP Client API creates instances of CSIPClientTransaction and CSIPServerTransaction and they cannot be created by the application.

                Automatically +refreshing a SIP request

                + +

                The SIP stack automatically refreshes a SIP request using the CSIPRefresh object. REGISTER, SUBSCRIBE and a request outside the dialog are refreshed. After +sending a refresh request, the application queries the state of the refresh +from CSIPRefresh.

                CSIPRefresh provides +functions for updating and terminating the refresh, for requests outside the +dialog. The CSIPRegistrationBinding and CSIPSubscribeDialogAssoc classes +are used to update and terminate a refreshed REGISTER or SUBSCRIBE.

                Managing HTTP digest security +settings

                + +

                An application must create an instance of the CSIP class +to use CSIPHttpDigest. The CSIPHttpDigest class +manages HTTP digest security settings and contains only static functions.

                +
                Memory used

                After +the CSIP and CSIPConnection objects +are created, most of the memory consumed is by CSIPMessageElements, CSIPRequestElements and CSIPResponseElements classes. CSIPTransactionBase holds the most recent SIP +response in a CSIPResponseElements object. When another +response is received, the previous CSIPResponseElements object +is deleted and a new one is created.

                CSIPClientTransaction contains +a CSIPRequestElements object until the SIP request is transferred +to the server side of the SIP stack. CSIPServerTransaction contains +the SIP request as CSIPRequestElements. The application +owns the CSIPClientTransaction and CSIPServerTransaction objects. +When the transaction terminates, the application deletes these objects to +conserve memory.

                A non-INVITE CSIPClientTransaction is +deleted when it has received a final response or when the ErrorOccured() callback +is called. A non-INVITE CSIPServerTransaction is +deleted after the application sends a final response.

                The INVITE related +transactions are deleted if the ErrorOccured() callback function +is called. These transactions behave differently because of the presence of +an ACK.

                When the application sends a 2xx response +to an INVITE related CSIPServerTransaction, +it enters the CSIPTransactionBase::ETerminated state and +it is deleted at this point. A new CSIPServerTransaction object +receives the ACK.

                When the application sends an INVITE request +and the CSIPClientTransaction receives a 2xx response, the +transaction enters the CSIPTransactionBase::ETerminated state. +The associated CSIPClientTransaction must not be deleted +as it is required to send the ACK and also to receive the MSIPConnectionObserver::InviteCompleted() callback. +An INVITE related CSIPClientTransaction must +be deleted only after a MSIPConnectionObserver::InviteCompleted or MSIPConnectionObserver +::ErrorOccured event is received, or if the state of the associated CSIPConnection goes +to CSIPConnection::EInactive or CSIPConnection::EUnavailable.

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A2EFD9AD-F230-545C-8C5D-193F717B9FE2_d0e34881_href.png Binary file Symbian3/SDK/Source/GUID-A2EFD9AD-F230-545C-8C5D-193F717B9FE2_d0e34881_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A2EFD9AD-F230-545C-8C5D-193F717B9FE2_d0e40447_href.png Binary file Symbian3/SDK/Source/GUID-A2EFD9AD-F230-545C-8C5D-193F717B9FE2_d0e40447_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A2F691C8-9525-4028-BF82-70E9D50630C6.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-A2F691C8-9525-4028-BF82-70E9D50630C6.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,51 @@ + + + + + +Prompting +the User to Select a Destination NetworkIf there is no connection specified in the connection setup and +no default connection has been defined, your application can +prompt the user to select the connection. +

                To prompt +the user select the destination network:

                 + +Start the connection +with RConnection::Start(ECommDbDialogPrefPrompt). RConnection +handle is returned to the application. + +The user makes a selection. A destination network is the preferred +selection, but the user can also select a specific access point with this +dialog. + +Link layer is now ready for the application. + +Send NewL(RConnection handle, MMobilityProtocolResp(). + The application can now use the mobility API, but if the user selected an +access point this has no meaning, because roaming cannot be used. For information +on how to start the connection through a destination network, see Starting +the connection through the destination network. + + +RSocketServ ss; + +// Connect to ESOCK +ss.Connect(); + +// Open an RConnection object. Note that you must provide an RSocketServ object +RConnection conn; +conn.Open( ss ); + +// Create overrides +TCommDbConnPref prefs; +prefs.SetDialogPreference( ECommDbDialogPrefPrompt ); + +// Start an Outgoing Connection with overrides +conn.Start( prefs ); +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A308643D-6EEA-5C41-BD9C-5DA76EE83BA6_d0e158775_href.jpg Binary file Symbian3/SDK/Source/GUID-A308643D-6EEA-5C41-BD9C-5DA76EE83BA6_d0e158775_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A308643D-6EEA-5C41-BD9C-5DA76EE83BA6_d0e165376_href.jpg Binary file Symbian3/SDK/Source/GUID-A308643D-6EEA-5C41-BD9C-5DA76EE83BA6_d0e165376_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A3155AA1-8D42-5855-AD49-089DC510BCB0-master.png Binary file Symbian3/SDK/Source/GUID-A3155AA1-8D42-5855-AD49-089DC510BCB0-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A3155AA1-8D42-5855-AD49-089DC510BCB0_d0e383259_href.png Binary file Symbian3/SDK/Source/GUID-A3155AA1-8D42-5855-AD49-089DC510BCB0_d0e383259_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A331AA9C-ECEC-4497-B45A-7C08845DE0A4_d0e3331_href.png Binary file Symbian3/SDK/Source/GUID-A331AA9C-ECEC-4497-B45A-7C08845DE0A4_d0e3331_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A331AA9C-ECEC-4497-B45A-7C08845DE0A4_d0e4606_href.png Binary file Symbian3/SDK/Source/GUID-A331AA9C-ECEC-4497-B45A-7C08845DE0A4_d0e4606_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A36C2DE6-21D8-5558-B223-1E81CEB16891-GENID-1-8-1-3-1-1-6-1-3-1.dita --- a/Symbian3/SDK/Source/GUID-A36C2DE6-21D8-5558-B223-1E81CEB16891-GENID-1-8-1-3-1-1-6-1-3-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,36 +0,0 @@ - - - - - -Clock -OverviewProvides the graphical display of digital and analogue clocks. The -clocks are animated to change with system time. -
                Architectural relationships

                The animation -of the clocks is performed by an animation DLL that plugs-in to the Window -Server. The key classes in this API are client-side animation classes, derived -from the animation client-side class RAnim.

                -
                Description

                The API has three key concepts: clock -base classes, analogue clock, and digital clock.

                Clock base classes

                A -number of base classes provide shared functionality for the clocks, including -basic display control, and time setting. They derive ultimately from RAnim, -and are, in inheritance order, RAnimWithUtils, RTimeDevice, -and RClock.

                Analogue clock

                Derived -from RClock, the class RAnalogClock provides -an analogue clock with configurable color, size, position, and number of hands.

                How -a hand is drawn is specified by a TAnalogDisplayHand object. -The settings for displaying an AM/PM indicator is provided by SAnalogDisplayAmPm.

                Digital -clock

                Derived from RClock, the class RDigitalClock provides -a digital clock with configurable color, size, position, and font. What time -information is displayed is configured through one or more TDigitalDisplayTextSection objects.

                -
                See also
                  -

                • Animation

                  • -

                • Window server

                  • -
                -                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A36C2DE6-21D8-5558-B223-1E81CEB16891-GENID-1-8-1-6-1-1-4-1-5-1-3-1.dita --- a/Symbian3/SDK/Source/GUID-A36C2DE6-21D8-5558-B223-1E81CEB16891-GENID-1-8-1-6-1-1-4-1-5-1-3-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,36 +0,0 @@ - - - - - -Clock -OverviewProvides the graphical display of digital and analogue clocks. The -clocks are animated to change with system time. -
                Architectural relationships

                The animation -of the clocks is performed by an animation DLL that plugs-in to the Window -Server. The key classes in this API are client-side animation classes, derived -from the animation client-side class RAnim.

                -
                Description

                The API has three key concepts: clock -base classes, analogue clock, and digital clock.

                Clock base classes

                A -number of base classes provide shared functionality for the clocks, including -basic display control, and time setting. They derive ultimately from RAnim, -and are, in inheritance order, RAnimWithUtils, RTimeDevice, -and RClock.

                Analogue clock

                Derived -from RClock, the class RAnalogClock provides -an analogue clock with configurable color, size, position, and number of hands.

                How -a hand is drawn is specified by a TAnalogDisplayHand object. -The settings for displaying an AM/PM indicator is provided by SAnalogDisplayAmPm.

                Digital -clock

                Derived from RClock, the class RDigitalClock provides -a digital clock with configurable color, size, position, and font. What time -information is displayed is configured through one or more TDigitalDisplayTextSection objects.

                -
                See also
                  -

                • Animation

                  • -

                • Window server

                  • -
                -                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A36C2DE6-21D8-5558-B223-1E81CEB16891.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-A36C2DE6-21D8-5558-B223-1E81CEB16891.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,36 @@ + + + + + +Clock +OverviewProvides the graphical display of digital and analogue clocks. The +clocks are animated to change with system time. +
                Architectural relationships

                The animation +of the clocks is performed by an animation DLL that plugs-in to the Window +Server. The key classes in this API are client-side animation classes, derived +from the animation client-side class RAnim.

                +
                Description

                The API has three key concepts: clock +base classes, analogue clock, and digital clock.

                Clock base classes

                A +number of base classes provide shared functionality for the clocks, including +basic display control, and time setting. They derive ultimately from RAnim, +and are, in inheritance order, RAnimWithUtils, RTimeDevice, +and RClock.

                Analogue clock

                Derived +from RClock, the class RAnalogClock provides +an analogue clock with configurable color, size, position, and number of hands.

                How +a hand is drawn is specified by a TAnalogDisplayHand object. +The settings for displaying an AM/PM indicator is provided by SAnalogDisplayAmPm.

                Digital +clock

                Derived from RClock, the class RDigitalClock provides +a digital clock with configurable color, size, position, and font. What time +information is displayed is configured through one or more TDigitalDisplayTextSection objects.

                +
                See also
                  +

                • Animation

                  • +

                • Window server

                  • +
                +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A3B58436-07E4-565B-800B-86435D205461.dita --- a/Symbian3/SDK/Source/GUID-A3B58436-07E4-565B-800B-86435D205461.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-A3B58436-07E4-565B-800B-86435D205461.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,181 +1,181 @@ - - - - - -Certificate -Validation in PKIX -

                Certificates of different types are trusted by different applications. -Therefore certificates need to be signed by certification authority (CA) and -the signature must be verified and validated. This section describes about -certificate chain and certificate validation processes.

                -
                Certificate Chain

                Certificate validation is a recursive -process. It begins with the need to verify the signature on some data presented -by an End Entity (EE). This involves checking that the key pair is actually -owned by that EE. To do this the public signing key of that EE is acquired -by getting its certificate. That certificate would have been signed by the -EE's certification authority (CA), so the signature on the certificate can -be verified by getting the CA's public signing key. In turn the CA's certificate -might require verifying in which case the process is repeated until the process -bottoms out when an entity which is already trusted is reached; that entity -is usually self signed. This process is illustrated in the figure below:

                - Certificate chain - -

                The set of certificates from an EE up to a trusted root CA certificate -is called a certificate chain. Once a certificate chain -has been constructed ,the EE's key pair at the start can be validated.

                -
                Input to Certificate Validation

                End -Entity & Intermediate Certificates

                A set of certificates, -from the entity requesting authentication up to, but not including, one already -trusted by the relying party.

                Where these certificates come from is -potentially a difficult problem if certificate management is expected to search -for intermediate certificates in remote repositories; however for TLS at least -servers are required to supply a complete, ordered set of certificates in -the form of DER-encoded ASN.1; so client code can just pass this into the -certificate chain object.

                Trusted -Root Certificates

                Authentication cannot be done entirely by software: -there must be a point at which the user confirms that they trust a particular -entity. The validation algorithm can only ascertain that if the user trusts -certificate X then they may also trust certificate Y. Certificates which the -user trusts directly are called root certificates because they are the root -of the validation chain. They are usually self-signed.

                It is likely -that different applications will have different requirements about which certificates -may be considered trust roots and for the level of protection they require -for trust roots. To this end, applications will pass in a unique ID (TUid) -which Certificate and Key Management will use to identify the application, -and so work out which certificates can be considered trusted for that application.

                For -additional flexibility, an overload is provided enabling clients to pass a -set of root certificates directly into the validation function.

                For -more detailed discussion of the storage and management of root certificates -see Root Certificate -Management, Storage, and Client registration.

                Validation -Time

                The time for which validation will be performed.

                Acceptable Policies

                A -set of OIDs, each of which represents a certification policy acceptable to -the application. This enables client code to restrict the certificates that -may occur in a valid certificate chain. Client code does not have to specify -any preferred policies here. An empty set is interpreted as any policy.

                -
                Configuring -for Certificate Validation

                The following settings can be configured -for the validation process:

                - - - -

                Supported critical extensions

                -

                You can list supported X.509 v3 critical extensions. Once you have -set a list, you have full control over the processing of X.509 v3 critical -extensions. If a critical extension is found whose OID matches an element -in this list, certificate validation treats this as a warning instead of an -error.

                You can set, add, remove and reset the list of supported critical -extensions.

                If critical extensions are not configured, the validation -process uses a default set. This includes standard X.509 critical extensions -and Symbian specific critical extensions.

                -                 - -

                Date validity checks

                -

                You can specify whether a failed check on the certificate validity -date is treated as an error or a warning. You can use this to verify the certificate -validity period post-installation. By default the certificate validity period -only needs to be checked at installation.

                -                 - - -
                -
                Chain Validation

                Chain Construction

                The -chain object parses the encoded set of certificates. The first certificate -is considered to be the EE certificate, and subsequent certificates must each -certify the preceding one. The chain object then searches the set of trusted -root certificates for a certificate trusted by the client and whose subject -name matches the issuer name in the last certificate in the decoded set. If -two or more match, it will attempt to resolve this be comparing the authority -key ID in the last certificate with the subject key ID in each candidate root. -If this extension is not present, it will attempt to find a single root by -signature verification. If no root is found validation will fail immediately -with an error.

                Initialisation of Chain Validation Algorithm

                The -certificate chain initialises the following state variables:

                  -

                • Validation Time: time -for which validation is calculated. Initialised to the time supplied by client -code.

                  • -

                • Initial Policies: set -of policy OIDs, initialised to the policies supplied by client code

                  • -

                • Acceptable Policies: -set of X.509 policy information objects, initially any policy

                  • -

                • Mapped Policies: set -of policy OIDs, initially empty

                  • -

                • Excluded Subtrees: set -of X.500 General Name objects, initially empty

                  • -

                • Permitted Subtrees: -set of X.500 General Name objects, initially any subtree

                  • -

                • Max Path Length: integer -representing the maximum path length. Initially the actual path length

                  • -

                • Inhibit Policy Mapping: -integer whose value is the number of certificates that may appear after the -current one before policy mapping is no longer permitted. Initially the chain -length

                  • -

                • Require Explicit Policy: -integer whose value is the number of certificates that may appear after the -current one before an acceptable policy OID must appear in the certificate. -Initially the chain length

                  • -

                • Current Cert: integer -whose value is the position of the current certificate in the chain. Initially -the chain length -1

                  • -

                Validation Algorithm

                Validation of a certificate -chain starts at the root and ends at the End Entity.

                Validation -warnings

                Validation returns warnings. Warnings enable client code -to evaluate whether irregularities are errors.

                From Version 9.3, validation -returns a warning object for every certificate in the chain. Each warning -object has the following characteristics:

                  -

                • It includes the object's -index. Clients use the index to get the certificate from the certificate chain -object (CX509CertChain::Cert()).

                  • -

                • It encapsulates the -warnings and the critical extensions' OID values for that certificate.

                  • -

                Clients can query the object for two sets of data:

                  -

                • the critical extensions -for the certificate

                  • -

                • a set of warning values, -each consisting of a reason for the warning and an integer identifying the -certificate that the warning is associated with.

                  • -

                After querying the warning object for the critical extension, the -client must process any custom critical extensions it supplied that are not -in the supported list. This meets the X.509 certificate specification.

                Prior -to version 9.3, the set of warning values returned included any warnings about -critical extensions. Warning values no longer include this information. But -backward compatibility has been maintained for warning objects prior to version -9.3.

                Certificate validation steps

                Certificate -validation takes place through the following steps:

                  -

                • Signature Verification -& Name Chaining

                  Each certificate must be signed by, and its subject -name should match the issuer name in, the certificate above it in the chain. -The only exception is the root certificate, which, if it claims to be self -signed (i.e. its subject and issuer names match) must really be self signed; -otherwise its signature is not verified, but a warning is generated.

                  • -

                • Validity Period Checking

                  For -each certificate, the Validation Time must lie within the validity period -in the certificate. The check is always carried out. The check treats a failure -as an error or a warning depending on how the validation process is configured -(See Date validity checks in Configuring -for Certificate Validation). By default the check treats the failure -as an error.

                  • -

                • Extension Processing

                  Extensions -can be marked critical. All critical extensions must be in the supported list -to be recognized and processed. When a critical extension that is not in the -supported list is encountered, an error results and validation fails. The -client must process critical extensions that are not in the supported list.

                  • -

                • Revocation Checking

                  • -

                Additionally, for each certificate:

                  -

                • the Max Path Length, Inhibit -Policy Mapping and Require Explicit Policy variables are decremented,

                  • -

                • and Current Cert must -be less than or equal to Max Path Length.

                  • -

                When validation is complete the Acceptable Policies variable -will be copied into the set of policies in the result object.

                -
                See also
                  -

                • PKIXCert

                  • -
                + + + + + +Certificate +Validation in PKIX +

                Certificates of different types are trusted by different applications. +Therefore certificates need to be signed by certification authority (CA) and +the signature must be verified and validated. This section describes about +certificate chain and certificate validation processes.

                +
                Certificate Chain

                Certificate validation is a recursive +process. It begins with the need to verify the signature on some data presented +by an End Entity (EE). This involves checking that the key pair is actually +owned by that EE. To do this the public signing key of that EE is acquired +by getting its certificate. That certificate would have been signed by the +EE's certification authority (CA), so the signature on the certificate can +be verified by getting the CA's public signing key. In turn the CA's certificate +might require verifying in which case the process is repeated until the process +bottoms out when an entity which is already trusted is reached; that entity +is usually self signed. This process is illustrated in the figure below:

                + Certificate chain + +

                The set of certificates from an EE up to a trusted root CA certificate +is called a certificate chain. Once a certificate chain +has been constructed ,the EE's key pair at the start can be validated.

                +
                Input to Certificate Validation

                End +Entity & Intermediate Certificates

                A set of certificates, +from the entity requesting authentication up to, but not including, one already +trusted by the relying party.

                Where these certificates come from is +potentially a difficult problem if certificate management is expected to search +for intermediate certificates in remote repositories; however for TLS at least +servers are required to supply a complete, ordered set of certificates in +the form of DER-encoded ASN.1; so client code can just pass this into the +certificate chain object.

                Trusted +Root Certificates

                Authentication cannot be done entirely by software: +there must be a point at which the user confirms that they trust a particular +entity. The validation algorithm can only ascertain that if the user trusts +certificate X then they may also trust certificate Y. Certificates which the +user trusts directly are called root certificates because they are the root +of the validation chain. They are usually self-signed.

                It is likely +that different applications will have different requirements about which certificates +may be considered trust roots and for the level of protection they require +for trust roots. To this end, applications will pass in a unique ID (TUid) +which Certificate and Key Management will use to identify the application, +and so work out which certificates can be considered trusted for that application.

                For +additional flexibility, an overload is provided enabling clients to pass a +set of root certificates directly into the validation function.

                For +more detailed discussion of the storage and management of root certificates +see Root Certificate +Management, Storage, and Client registration.

                Validation +Time

                The time for which validation will be performed.

                Acceptable Policies

                A +set of OIDs, each of which represents a certification policy acceptable to +the application. This enables client code to restrict the certificates that +may occur in a valid certificate chain. Client code does not have to specify +any preferred policies here. An empty set is interpreted as any policy.

                +
                Configuring +for Certificate Validation

                The following settings can be configured +for the validation process:

                + + + +

                Supported critical extensions

                +

                You can list supported X.509 v3 critical extensions. Once you have +set a list, you have full control over the processing of X.509 v3 critical +extensions. If a critical extension is found whose OID matches an element +in this list, certificate validation treats this as a warning instead of an +error.

                You can set, add, remove and reset the list of supported critical +extensions.

                If critical extensions are not configured, the validation +process uses a default set. This includes standard X.509 critical extensions +and Symbian specific critical extensions.

                +                 + +

                Date validity checks

                +

                You can specify whether a failed check on the certificate validity +date is treated as an error or a warning. You can use this to verify the certificate +validity period post-installation. By default the certificate validity period +only needs to be checked at installation.

                +                 + + +
                +
                Chain Validation

                Chain Construction

                The +chain object parses the encoded set of certificates. The first certificate +is considered to be the EE certificate, and subsequent certificates must each +certify the preceding one. The chain object then searches the set of trusted +root certificates for a certificate trusted by the client and whose subject +name matches the issuer name in the last certificate in the decoded set. If +two or more match, it will attempt to resolve this be comparing the authority +key ID in the last certificate with the subject key ID in each candidate root. +If this extension is not present, it will attempt to find a single root by +signature verification. If no root is found validation will fail immediately +with an error.

                Initialisation of Chain Validation Algorithm

                The +certificate chain initialises the following state variables:

                  +

                • Validation Time: time +for which validation is calculated. Initialised to the time supplied by client +code.

                  • +

                • Initial Policies: set +of policy OIDs, initialised to the policies supplied by client code

                  • +

                • Acceptable Policies: +set of X.509 policy information objects, initially any policy

                  • +

                • Mapped Policies: set +of policy OIDs, initially empty

                  • +

                • Excluded Subtrees: set +of X.500 General Name objects, initially empty

                  • +

                • Permitted Subtrees: +set of X.500 General Name objects, initially any subtree

                  • +

                • Max Path Length: integer +representing the maximum path length. Initially the actual path length

                  • +

                • Inhibit Policy Mapping: +integer whose value is the number of certificates that may appear after the +current one before policy mapping is no longer permitted. Initially the chain +length

                  • +

                • Require Explicit Policy: +integer whose value is the number of certificates that may appear after the +current one before an acceptable policy OID must appear in the certificate. +Initially the chain length

                  • +

                • Current Cert: integer +whose value is the position of the current certificate in the chain. Initially +the chain length -1

                  • +

                Validation Algorithm

                Validation of a certificate +chain starts at the root and ends at the End Entity.

                Validation +warnings

                Validation returns warnings. Warnings enable client code +to evaluate whether irregularities are errors.

                From Version 9.3, validation +returns a warning object for every certificate in the chain. Each warning +object has the following characteristics:

                  +

                • It includes the object's +index. Clients use the index to get the certificate from the certificate chain +object (CX509CertChain::Cert()).

                  • +

                • It encapsulates the +warnings and the critical extensions' OID values for that certificate.

                  • +

                Clients can query the object for two sets of data:

                  +

                • the critical extensions +for the certificate

                  • +

                • a set of warning values, +each consisting of a reason for the warning and an integer identifying the +certificate that the warning is associated with.

                  • +

                After querying the warning object for the critical extension, the +client must process any custom critical extensions it supplied that are not +in the supported list. This meets the X.509 certificate specification.

                Prior +to version 9.3, the set of warning values returned included any warnings about +critical extensions. Warning values no longer include this information. But +backward compatibility has been maintained for warning objects prior to version +9.3.

                Certificate validation steps

                Certificate +validation takes place through the following steps:

                  +

                • Signature Verification +& Name Chaining

                  Each certificate must be signed by, and its subject +name should match the issuer name in, the certificate above it in the chain. +The only exception is the root certificate, which, if it claims to be self +signed (i.e. its subject and issuer names match) must really be self signed; +otherwise its signature is not verified, but a warning is generated.

                  • +

                • Validity Period Checking

                  For +each certificate, the Validation Time must lie within the validity period +in the certificate. The check is always carried out. The check treats a failure +as an error or a warning depending on how the validation process is configured +(See Date validity checks in Configuring +for Certificate Validation). By default the check treats the failure +as an error.

                  • +

                • Extension Processing

                  Extensions +can be marked critical. All critical extensions must be in the supported list +to be recognized and processed. When a critical extension that is not in the +supported list is encountered, an error results and validation fails. The +client must process critical extensions that are not in the supported list.

                  • +

                • Revocation Checking

                  • +

                Additionally, for each certificate:

                  +

                • the Max Path Length, Inhibit +Policy Mapping and Require Explicit Policy variables are decremented,

                  • +

                • and Current Cert must +be less than or equal to Max Path Length.

                  • +

                When validation is complete the Acceptable Policies variable +will be copied into the set of policies in the result object.

                +
                See also
                  +

                • PKIXCert

                  • +
                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A3EBB297-1494-579C-83D5-8FDBBD01B674.dita --- a/Symbian3/SDK/Source/GUID-A3EBB297-1494-579C-83D5-8FDBBD01B674.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-A3EBB297-1494-579C-83D5-8FDBBD01B674.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,37 +1,37 @@ - - - - - -Drawing Bitmaps

                This topic provides example code that demonstrates blitting a bitmap to the screen, blitting a rectangular piece of a bitmap to the screen and blitting a bitmap under a mask.

                These examples assume that bitmap is a pointer to a valid CFbsBitmap object.

                Bitmap block transfer

                Use CBitmapContext::BitBlt() to blit a CFbsBitmap to the screen.

                // draw the bitmap using bitmap block transfer -TPoint pos(50,50); -gc.BitBlt(pos, bitmap);
                Block transfer of a rectangular piece of a bitmap

                You can blit a rectangular piece of a bitmap to the screen.

                ... -// set a rectangle for the top-left quadrant of the source bitmap -TSize bmpSizeInPixels=bitmap->SizeInPixels(); -TSize bmpPieceSize(bmpSizeInPixels.iWidth/2,bmpSizeInPixels.iHeight/2); -TRect bmpPieceRect(TPoint(0,0),bmpPieceSize); - -// blit only the piece of the bitmap indicated by bmpPieceRect -TPoint pos(100,100); -gc.BitBlt(pos, bitmap, bmpPieceRect);
                Masked bitmap block transfer

                Masks can be used to select which parts of a bitmap are drawn by CBitmapContext::BitBltMasked().

                Masks can be used to not display pixels of the source bitmap if their corresponding mask pixel is black, or, alternatively, where the mask is white (called an inverted mask).

                The following figure shows successively a source bitmap, a mask, and the outcome when they are blitted with BitBltMasked().

                // Load the mask bitmap, just like any other -CFbsBitmap* maskBitmap = new (ELeave) CFbsBitmap(); -CleanupStack::PushL(maskBitmap); -User::LeaveIfError(maskBitmap-> - Load(multiBitmapFile,EMbmGrbmap2Smilmask)); - -// Calculate rectangle for the whole bitmap -TRect bmpPieceRect(TPoint(0,0),bitmap->SizeInPixels()); - -// Blit using a masking bitmap, with no inversion -gc.BitBltMasked(TPoint(50,50),bitmap,bmpPieceRect,maskBitmap,EFalse); - -... -// clean up -CleanupStack::PopAndDestroy(); + + + + + +Drawing Bitmaps

                This topic provides example code that demonstrates blitting a bitmap to the screen, blitting a rectangular piece of a bitmap to the screen and blitting a bitmap under a mask.

                These examples assume that bitmap is a pointer to a valid CFbsBitmap object.

                Bitmap block transfer

                Use CBitmapContext::BitBlt() to blit a CFbsBitmap to the screen.

                // draw the bitmap using bitmap block transfer +TPoint pos(50,50); +gc.BitBlt(pos, bitmap);
                Block transfer of a rectangular piece of a bitmap

                You can blit a rectangular piece of a bitmap to the screen.

                ... +// set a rectangle for the top-left quadrant of the source bitmap +TSize bmpSizeInPixels=bitmap->SizeInPixels(); +TSize bmpPieceSize(bmpSizeInPixels.iWidth/2,bmpSizeInPixels.iHeight/2); +TRect bmpPieceRect(TPoint(0,0),bmpPieceSize); + +// blit only the piece of the bitmap indicated by bmpPieceRect +TPoint pos(100,100); +gc.BitBlt(pos, bitmap, bmpPieceRect);
                Masked bitmap block transfer

                Masks can be used to select which parts of a bitmap are drawn by CBitmapContext::BitBltMasked().

                Masks can be used to not display pixels of the source bitmap if their corresponding mask pixel is black, or, alternatively, where the mask is white (called an inverted mask).

                The following figure shows successively a source bitmap, a mask, and the outcome when they are blitted with BitBltMasked().

                // Load the mask bitmap, just like any other +CFbsBitmap* maskBitmap = new (ELeave) CFbsBitmap(); +CleanupStack::PushL(maskBitmap); +User::LeaveIfError(maskBitmap-> + Load(multiBitmapFile,EMbmGrbmap2Smilmask)); + +// Calculate rectangle for the whole bitmap +TRect bmpPieceRect(TPoint(0,0),bitmap->SizeInPixels()); + +// Blit using a masking bitmap, with no inversion +gc.BitBltMasked(TPoint(50,50),bitmap,bmpPieceRect,maskBitmap,EFalse); + +... +// clean up +CleanupStack::PopAndDestroy();

                Notes

                • Unlike with an ordinary BitBlit(), with BitBltMasked() you always have to specify what part of the bitmap to display: here we just set bmpPieceRect so that the whole bitmap is displayed.

                • If the mask bitmap is smaller than the source bitmap, then it is tiled across the bitmap.

                • For an inverted mask, set the last argument to BitBltMasked() to ETrue.

                BitGDI Tutorials BitGDI Component                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A4560E99-C124-49A1-ADA1-D1B1F18EE539.dita --- a/Symbian3/SDK/Source/GUID-A4560E99-C124-49A1-ADA1-D1B1F18EE539.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-A4560E99-C124-49A1-ADA1-D1B1F18EE539.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,52 +1,51 @@ - - - - - -Relationship -between framework and applications -

                Comment for reviewers: we will -be adding a picture to illustrate this point in future releases of the CDL.

                -

                The displays and keys for the mobile device are shared between all running -applications. The Symbian platform controls and coordinates access to them. -When you meet the application -framework architecture requirements, the application framework manages -connections to the underlying architecture and also controls some of the elements -on the display. While the details of what is controlled by default by the -Symbian platform and what is controlled by your application are covered in -the relevant sections of this UI section, the following cases illustrate some -divisions about what is managed where:

                -
                  -

                • in the status pane:

                  - -

                  The drawing of the status pane is managed by the Symbian platform.

                  -

                  The battery pane/universal indicator pane and signal pane are -managed by the Symbian platform.

                  -

                  The title pane, context pane, and navi pane are -managed by your application, although a default behavior is provided by the -application framework.

                  -                   -
                  • -

                • in the control pane:

                  - -

                  The drawing of the control pane is managed by the Symbian platform.

                  -

                  The labels associated with the two softkeys are provided by application -resources.

                  -

                  The event loop that collects the commands that result from selections -and the passing of these commands on to your application are handled by the -application framework.

                  -

                  The handling -of the commands received from the application framework need to be -handled in your application.

                  -

                  For more details, see CBA buttons and Menu -bars.

                  -                   -
                  • -
                + + + + + +Relationship +between framework and applications +

                Comment for reviewers: we will +be adding a picture to illustrate this point in future releases of the CDL.

                +

                The displays and keys for the mobile device are shared between all running +applications. The Symbian platform controls and coordinates access to them. +When you meet the application +framework architecture requirements, the application framework manages +connections to the underlying architecture and also controls some of the elements +on the display. While the details of what is controlled by default by the +Symbian platform and what is controlled by your application are covered in +the relevant sections of this UI section, the following cases illustrate some +divisions about what is managed where:

                +
                  +

                • in the status pane:

                  + +

                  The drawing of the status pane is managed by the Symbian platform.

                  +

                  The battery pane, universal indicator paneand signal +pane are managed by the Symbian platform.

                  +

                  The title pane, context pane, and navi pane are +managed by your application, although a default behavior is provided by the +application framework.

                  +                   +
                  • +

                • in the control pane:

                  + +

                  The drawing of the control pane is managed by the Symbian platform.

                  +

                  The labels associated with the two softkeys are provided by application +resources.

                  +

                  The event loop that collects the commands that result from selections +and the passing of these commands on to your application are handled by the +application framework.

                  +

                  The handling +of the commands received from the application framework need to be +handled in your application.

                  +

                  For more details, see CBA buttons and Menu bars.

                  +                   +
                  • +
                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A467E933-C4B4-5518-96D6-471E44B216B3.dita --- a/Symbian3/SDK/Source/GUID-A467E933-C4B4-5518-96D6-471E44B216B3.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-A467E933-C4B4-5518-96D6-471E44B216B3.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,16 +1,16 @@ - - - - - - Advanced Pond GuideThis topic describes Comms ponds in more detail.
                APIs

                The following diagram is a partial representation of the class relationships for RCommsBufPond.

                - Comms pond -

                An RCommsBufPond instance manages a number of memory pools. Each pool contains buffers of identical size.

                The Comms Data Plane uses chains of buffers to transfer data up and down the stack. For more information about buffers and chains, see Comms Buffers (MBuf) and Comms Chains.

                Lifecycle

                1. c32start.exe reads the pond configuration stored in the c32start.ini file (see Pond Configuration Reference).

                2. c32start.exe provides the configuration information to the Root Server when initializing it. For more information about the C32 process, see Root Server.

                3. The Root Server creates the pond with the specified pools.

                4. The Root Server puts the pond handle in the TLS of each thread in c32exe.exe (see TLS Look-up Reduction Tutorial).

                Overview Comms Buffers (MBuf) - and Comms Chains Pond Configuration + + + + + + Advanced Pond GuideThis topic describes Comms ponds in more detail.
                APIs

                The following diagram is a partial representation of the class relationships for RCommsBufPond.

                + Comms pond +

                An RCommsBufPond instance manages a number of memory pools. Each pool contains buffers of identical size.

                The Comms Data Plane uses chains of buffers to transfer data up and down the stack. For more information about buffers and chains, see Comms Buffers (MBuf) and Comms Chains.

                Lifecycle

                1. c32start.exe reads the pond configuration stored in the c32start.ini file (see Pond Configuration Reference).

                2. c32start.exe provides the configuration information to the Root Server when initializing it. For more information about the C32 process, see Root Server.

                3. The Root Server creates the pond with the specified pools.

                4. The Root Server puts the pond handle in the TLS of each thread in c32exe.exe (see TLS Look-up Reduction Tutorial).

                Overview Comms Buffers (MBuf) + and Comms Chains Pond Configuration Reference                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A4799558-AF8C-5E97-9B03-7D1C04FEC243.dita --- a/Symbian3/SDK/Source/GUID-A4799558-AF8C-5E97-9B03-7D1C04FEC243.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-A4799558-AF8C-5E97-9B03-7D1C04FEC243.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,81 +1,81 @@ - - - - - -Duplicating -handles to Kernel side objectsThis document describes when you should duplicate a handle in kernel -side programming. -
                Duplicating a thread-relative handle in another thread

                A -handle in one thread (a thread-relative handle) may be duplicated in another -thread within the same process.

                Typically, thread B may want to access -a Kernel object which already exists and for which thread A, within the same -process, already holds a handle.

                For example, if thread A has a handle -on a semaphore, it is insufficient to pass a copy of the handle, an RSemaphore, -to thread B. The handle passed to thread B does not refer to anything known -by thread B. In order for thread B to gain a valid handle on the DLL, the -handle must be duplicated.

                Note that, in practice, real code may or -may not want to duplicate a semaphore handle, however the principle remains -valid.

                In thread B, then:

                ... -RSemaphore cs; -cs.SetHandle(h.Handle()); - // ...where h is an RSemaphore, the - // handle to the DLL, and - // passed from thread A code. - -cs.Duplicate(tA); - // ...where tA is an RThread, the handle to - // thread A, and passed from threadA code. - // Duplicate also opens the resulting - // handle, cs. -... -

                The dotted line in the following diagram shows the effect -of this:

                - -

                Note that for process-relative handles, there is no need to use Duplicate(); -the handle passed from thread A to thread B can be used directly.

                -
                Making specific handles from generic handles

                There -are two types of generic handle, one for threads and one for processes, both -of which are created using the default constructor of the appropriate handle.

                RThread thisThread; // Generic handle meaning "the current thread" -RProcess thisProcess; // Generic handle meaning "the current process" -

                An important fact about generic handles is that they make -no claim on the object that they refer to, so you don't need to call Close() when -you get rid of them. This is not true of specific handles, which always add -a reference to the object that they refer to, preventing that object being -fully destroyed until all specific handles have been closed.

                Use Duplicate() -to make a specific handle from a generic handle; for example:

                RThread thisThread; // generic handle -TInt err=thisThread.Duplicate(thisThread); // a specific handle -... -thisThread.Close(); // don't forget. -
                -
                Promoting a thread-relative handle to a process-wide handle

                The -second parameter passed to Duplicate() specifies whether -the resulting handle is specific to the calling thread, or is valid for all -threads in the same process.

                Duplicate() offers a -way of making a handle, which is specific to a thread, known to all the threads -in a process.

                This does not work for all handles but RLibrary is -an example of one where it can make sense to promote an RLibrary thread-relative -handle to a process-relative handle because this ensures that the library -will not be automatically unloaded when the original thread terminates. For -example:

                ... -_LIT(KMyLib,"MYLIB"); -... -RLibrary threadLibrary; -err=threadLibrary.Load(KMyLib); // Load up a DLL, this gives - // a thread-specific handle. -RLibrary aDup=threadLibrary; // Copies handle without - // doing Open(). -err=threadLibrary.Duplicate(RThread());// Overwrite the original. -if (err==KErrNone) - { - aDup.Close(); // Close the original. - } -... -
                + + + + + +Duplicating +handles to Kernel side objectsThis document describes when you should duplicate a handle in kernel +side programming. +
                Duplicating a thread-relative handle in another thread

                A +handle in one thread (a thread-relative handle) may be duplicated in another +thread within the same process.

                Typically, thread B may want to access +a Kernel object which already exists and for which thread A, within the same +process, already holds a handle.

                For example, if thread A has a handle +on a semaphore, it is insufficient to pass a copy of the handle, an RSemaphore, +to thread B. The handle passed to thread B does not refer to anything known +by thread B. In order for thread B to gain a valid handle on the DLL, the +handle must be duplicated.

                Note that, in practice, real code may or +may not want to duplicate a semaphore handle, however the principle remains +valid.

                In thread B, then:

                ... +RSemaphore cs; +cs.SetHandle(h.Handle()); + // ...where h is an RSemaphore, the + // handle to the DLL, and + // passed from thread A code. + +cs.Duplicate(tA); + // ...where tA is an RThread, the handle to + // thread A, and passed from threadA code. + // Duplicate also opens the resulting + // handle, cs. +... +

                The dotted line in the following diagram shows the effect +of this:

                + +

                Note that for process-relative handles, there is no need to use Duplicate(); +the handle passed from thread A to thread B can be used directly.

                +
                Making specific handles from generic handles

                There +are two types of generic handle, one for threads and one for processes, both +of which are created using the default constructor of the appropriate handle.

                RThread thisThread; // Generic handle meaning "the current thread" +RProcess thisProcess; // Generic handle meaning "the current process" +

                An important fact about generic handles is that they make +no claim on the object that they refer to, so you don't need to call Close() when +you get rid of them. This is not true of specific handles, which always add +a reference to the object that they refer to, preventing that object being +fully destroyed until all specific handles have been closed.

                Use Duplicate() +to make a specific handle from a generic handle; for example:

                RThread thisThread; // generic handle +TInt err=thisThread.Duplicate(thisThread); // a specific handle +... +thisThread.Close(); // don't forget. +
                +
                Promoting a thread-relative handle to a process-wide handle

                The +second parameter passed to Duplicate() specifies whether +the resulting handle is specific to the calling thread, or is valid for all +threads in the same process.

                Duplicate() offers a +way of making a handle, which is specific to a thread, known to all the threads +in a process.

                This does not work for all handles but RLibrary is +an example of one where it can make sense to promote an RLibrary thread-relative +handle to a process-relative handle because this ensures that the library +will not be automatically unloaded when the original thread terminates. For +example:

                ... +_LIT(KMyLib,"MYLIB"); +... +RLibrary threadLibrary; +err=threadLibrary.Load(KMyLib); // Load up a DLL, this gives + // a thread-specific handle. +RLibrary aDup=threadLibrary; // Copies handle without + // doing Open(). +err=threadLibrary.Duplicate(RThread());// Overwrite the original. +if (err==KErrNone) + { + aDup.Close(); // Close the original. + } +... +
                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A4F3738C-CBFD-4151-9132-26FE05966715.dita --- a/Symbian3/SDK/Source/GUID-A4F3738C-CBFD-4151-9132-26FE05966715.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-A4F3738C-CBFD-4151-9132-26FE05966715.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,35 +1,44 @@ - - - - - -CBA buttons -Application with Options and Exit softkeys, portrait and landscape -views -

                The Symbian platform uses Control Button Area (CBA) resources to set -the options in the control pane above the softkeys. CBA resources map the -text that appears above the softkeys in the control pane with commands that -are collected by the event loop of the application framework and delivered -to your application for command -handling.

                -

                When a mobile device user selects an Options softkey, -the application framework displays the Options menu based -upon the definitions in the menu -bars resources.

                -

                Depending upon the requirements of your application, you can either:

                -
                  -

                • use -precompiled CBA button options contained in avkon.hrh

                  -
                  • -

                • create -your own buttons

                  • -
                -

                CBA buttons are constructed using the Buttons -API.

                + + + + + +CBA buttons +Application with Options and Exit softkeys in portrait +and landscape views +

                The Symbian platform uses Control Button Area (CBA) resources to set +the options in the control pane above the softkeys. CBA resources map the +text that appears above the softkeys in the control pane with commands that +are collected by the event loop of the application framework and delivered +to your application for command +handling.

                + +
                  +

                • The left softkey and right softkey are placed inside the +CBA.

                  • +

                • You must disable item-specific softkeys.

                  • +

                • If there is no highlight then, the left softkey is hidden.

                  +
                  • +
                +                 +

                When a mobile device user selects an Options softkey, +the application framework displays the Options menu based +upon the definitions in the menu +bars resources.

                +

                Depending upon the requirements of your application, you can either:

                +
                  +

                • use +precompiled CBA button options contained in avkon.hrh

                  +
                  • +

                • create +your own buttons

                  • +
                +

                CBA buttons are constructed using the Buttons +API.

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A50BBBE2-2E23-5AEE-BF53-9EF54FD7F00E_d0e334165_href.jpg Binary file Symbian3/SDK/Source/GUID-A50BBBE2-2E23-5AEE-BF53-9EF54FD7F00E_d0e334165_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A50BBBE2-2E23-5AEE-BF53-9EF54FD7F00E_d0e340322_href.jpg Binary file Symbian3/SDK/Source/GUID-A50BBBE2-2E23-5AEE-BF53-9EF54FD7F00E_d0e340322_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A51AB0B8-A13D-52D0-BEF8-435F76B30941_d0e184934_href.png Binary file Symbian3/SDK/Source/GUID-A51AB0B8-A13D-52D0-BEF8-435F76B30941_d0e184934_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A51AB0B8-A13D-52D0-BEF8-435F76B30941_d0e191530_href.png Binary file Symbian3/SDK/Source/GUID-A51AB0B8-A13D-52D0-BEF8-435F76B30941_d0e191530_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A51E334E-F410-55A9-AB07-82F8A1D113B4.dita --- a/Symbian3/SDK/Source/GUID-A51E334E-F410-55A9-AB07-82F8A1D113B4.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-A51E334E-F410-55A9-AB07-82F8A1D113B4.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,71 +1,71 @@ - - - - - -Graphics -Quick StartThe Graphics package provides Symbian devices with a means of visual -communication. It is responsible for providing a system-wide interface with -the physical display(s) and handles input events from physical input devices -such as keypads and touch screens. -

                There are two variants of the graphics architecture in Symbian^3. These -are referred to as ScreenPlay (sometimes -also called the New Graphics Architecture or NGA) and the non-ScreenPlay -variant (sometimes called the non-NGA variant). The Graphics guide -documentation covers both variants. When the documentation applies to only -one variant, it is clearly stated at the top of the page.

                - - - -
                System Model

                The -following diagram shows the Graphics package within the Symbian^3 System Model. -The System Model is a high-level overview of the Symbian architecture. The -components are grouped to show their relationships to each other. Within the -Graphics package, components are grouped into collections, which are shown -as white boxes in the diagram. The Graphics documentation is organized according -to the System Model structure.

                Although the System Model provides a -useful way of grouping the large number of components that make up the Graphics -package, it does not completely reflect the architectural relationships between -the components.

                - The Graphics package in the Symbian Foundation System -Model - -

                This documentation -only covers collections and components that are relevant to application developers.

                -
                Technologies
                  -

                • For information on the -two architectures, see The -ScreenPlay Architecture and The -Non-ScreenPlay Architecture.

                  • - -

                • The graphics architecture -enables device creators to take advantage of graphics processing hardware -when it is available, and to use software implementations when it is not. -For more information, see Graphics -Hardware Acceleration.

                  • -

                • Symbian provides support -for a number of APIs defined and administered by the Khronos group. These -enable the authoring and playback of dynamic media on a wide variety of platforms -and devices. For more information, see Khronos -API Support .

                  • -

                • Application developers -use the Window Server client-side library to control windows and respond to -key and pointer events in their applications. For more information, see Window Server Client-Side -Library.

                  • -
                -                 -Graphics -Example Code -Graphics - Guide -Graphics -Concepts - - + + + + + +Graphics +Quick StartThe Graphics package provides Symbian devices with a means of visual +communication. It is responsible for providing a system-wide interface with +the physical display(s) and handles input events from physical input devices +such as keypads and touch screens. +

                There are two variants of the graphics architecture in Symbian^3. These +are referred to as ScreenPlay (sometimes +also called the New Graphics Architecture or NGA) and the non-ScreenPlay +variant (sometimes called the non-NGA variant). The Graphics guide +documentation covers both variants. When the documentation applies to only +one variant, it is clearly stated at the top of the page.

                + + + +
                System Model

                The +following diagram shows the Graphics package within the Symbian^3 System Model. +The System Model is a high-level overview of the Symbian architecture. The +components are grouped to show their relationships to each other. Within the +Graphics package, components are grouped into collections, which are shown +as white boxes in the diagram. The Graphics documentation is organized according +to the System Model structure.

                Although the System Model provides a +useful way of grouping the large number of components that make up the Graphics +package, it does not completely reflect the architectural relationships between +the components.

                + The Graphics package in the Symbian Foundation System +Model + +

                This documentation +only covers collections and components that are relevant to application developers.

                +
                Technologies
                  +

                • For information on the +two architectures, see The +ScreenPlay Architecture and The +Non-ScreenPlay Architecture.

                  • + +

                • The graphics architecture +enables device creators to take advantage of graphics processing hardware +when it is available, and to use software implementations when it is not. +For more information, see Graphics +Hardware Acceleration.

                  • +

                • Symbian provides support +for a number of APIs defined and administered by the Khronos group. These +enable the authoring and playback of dynamic media on a wide variety of platforms +and devices. For more information, see Khronos +API Support .

                  • +

                • Application developers +use the Window Server client-side library to control windows and respond to +key and pointer events in their applications. For more information, see Window Server Client-Side +Library.

                  • +
                +                 +Graphics +Example Code +Graphics + Guide +Graphics +Concepts + +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A5693758-495B-598E-A514-24C48D459BB6.dita --- a/Symbian3/SDK/Source/GUID-A5693758-495B-598E-A514-24C48D459BB6.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-A5693758-495B-598E-A514-24C48D459BB6.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,55 +1,55 @@ - - - - - -Drawing Arcs and Ellipses

                This topic provides examples that demonstrate how to draw ellipses and arcs. The first draws the whole ellipse; the second, one section of the ellipse; and in the third, the other section of the ellipse is drawn (also illustrating construction lines and points). It also shows how to draw two pie slices making an ellipse.

                The code assumes that the ellipse and arc examples all use a common pre-defined rectangle:

                ... -TRect ellipseRect=Rect(); // for arcs and ellipse -ellipseRect.Shrink(10,10); // set size so inside the border rectangle -...

                The arc and pie slice examples use two construction points as arguments:

                ... -TPoint screenCenterPoint=rect.Center(); // the center of the screen - -// set up a pair of construction points for arc and pie slice drawing -TPoint constructionPoint1(15,15); // outside the construction ellipse -TPoint constructionPoint2(200,150); // inside the construction ellipse -...

                The center point is drawn in the second arc example to clarify arc construction.

                How to draw an ellipse

                You can use DrawEllipse() to draw an ellipse.

                ... -// draw an ellipse centered in the rectangle -gc.DrawEllipse(ellipseRect); -...
                How to draw an arc

                An arc is drawn as a portion of an ellipse. As well as the ellipse rectangle, the call must specify the two points: the first defines one end of a line from the geometric center of the ellipse; the point of intersection between this line and the ellipse defines the start point of the arc. The second specified point acts in the same way for the end of the arc.

                - Arc construction -

                The example code here shows how an arc is drawn in an anti-clockwise direction using constructionPoint1 and constructionPoint2 as the start to the end points.

                ... -// draw an arc centered in the rectangle -gc.DrawArc(ellipseRect,constructionPoint1,constructionPoint2); -...

                You can reverse the pair of construction point arguments to draw the other half of the ellipse. The construction points and screen center are also drawn, with dotted construction lines:

                ... -// draw an arc centered in the rectangle -// that is the other portion of the ellipse - gc.DrawArc(ellipseRect,constructionPoint2,constructionPoint1); - -// draw construction lines and points -gc.SetPenStyle(CGraphicsContext::EDottedPen); -gc.MoveTo(constructionPoint1); -gc.DrawLineTo(screenCenterPoint); -gc.DrawLineTo(constructionPoint2); -gc.SetPenSize(penSizeBold); -gc.Plot(constructionPoint1); -gc.Plot(constructionPoint2); -gc.Plot(screenCenterPoint); -...
                Drawing pie slices

                The example code here shows how two pie slices are drawn. A pie slice is the area bounded by:

                an arc as used above

                the straight line from the start point from the geometric center of the ellipse

                the straight line from the end point from the geometric center of the ellipse

                - Pie slice construction -

                Solid and patterned brush styles are used to fill the portions of the elliptical disc.

                1. Use SetBrushStyle() to set the brush style to solid.

                2. Use SetBrushColour() to set the brush color to black.

                3. Use DrawPie() to draw a pie slice.

                4. Use SetBrushStyle() to set the patterned brush style.

                5. Use DrawPie() and reverse the pair of construction point arguments so that the two pie slices together form a whole ellipse.

                ... -// draw a pie slice centered in the rectangle -gc.SetBrushStyle(CGraphicsContext::ESolidBrush); -gc.SetBrushColor(black); -gc.DrawPie(ellipseRect,constructionPoint1,constructionPoint2); - -// draw the other portion of the elliptical disc -gc.SetBrushStyle(CGraphicsContext::EVerticalHatchBrush); -gc.DrawPie(ellipseRect,constructionPoint2,constructionPoint1); -...
                Drawing + + + + + +Drawing Arcs and Ellipses

                This topic provides examples that demonstrate how to draw ellipses and arcs. The first draws the whole ellipse; the second, one section of the ellipse; and in the third, the other section of the ellipse is drawn (also illustrating construction lines and points). It also shows how to draw two pie slices making an ellipse.

                The code assumes that the ellipse and arc examples all use a common pre-defined rectangle:

                ... +TRect ellipseRect=Rect(); // for arcs and ellipse +ellipseRect.Shrink(10,10); // set size so inside the border rectangle +...

                The arc and pie slice examples use two construction points as arguments:

                ... +TPoint screenCenterPoint=rect.Center(); // the center of the screen + +// set up a pair of construction points for arc and pie slice drawing +TPoint constructionPoint1(15,15); // outside the construction ellipse +TPoint constructionPoint2(200,150); // inside the construction ellipse +...

                The center point is drawn in the second arc example to clarify arc construction.

                How to draw an ellipse

                You can use DrawEllipse() to draw an ellipse.

                ... +// draw an ellipse centered in the rectangle +gc.DrawEllipse(ellipseRect); +...
                How to draw an arc

                An arc is drawn as a portion of an ellipse. As well as the ellipse rectangle, the call must specify the two points: the first defines one end of a line from the geometric center of the ellipse; the point of intersection between this line and the ellipse defines the start point of the arc. The second specified point acts in the same way for the end of the arc.

                + Arc construction +

                The example code here shows how an arc is drawn in an anti-clockwise direction using constructionPoint1 and constructionPoint2 as the start to the end points.

                ... +// draw an arc centered in the rectangle +gc.DrawArc(ellipseRect,constructionPoint1,constructionPoint2); +...

                You can reverse the pair of construction point arguments to draw the other half of the ellipse. The construction points and screen center are also drawn, with dotted construction lines:

                ... +// draw an arc centered in the rectangle +// that is the other portion of the ellipse + gc.DrawArc(ellipseRect,constructionPoint2,constructionPoint1); + +// draw construction lines and points +gc.SetPenStyle(CGraphicsContext::EDottedPen); +gc.MoveTo(constructionPoint1); +gc.DrawLineTo(screenCenterPoint); +gc.DrawLineTo(constructionPoint2); +gc.SetPenSize(penSizeBold); +gc.Plot(constructionPoint1); +gc.Plot(constructionPoint2); +gc.Plot(screenCenterPoint); +...
                Drawing pie slices

                The example code here shows how two pie slices are drawn. A pie slice is the area bounded by:

                an arc as used above

                the straight line from the start point from the geometric center of the ellipse

                the straight line from the end point from the geometric center of the ellipse

                + Pie slice construction +

                Solid and patterned brush styles are used to fill the portions of the elliptical disc.

                1. Use SetBrushStyle() to set the brush style to solid.

                2. Use SetBrushColour() to set the brush color to black.

                3. Use DrawPie() to draw a pie slice.

                4. Use SetBrushStyle() to set the patterned brush style.

                5. Use DrawPie() and reverse the pair of construction point arguments so that the two pie slices together form a whole ellipse.

                ... +// draw a pie slice centered in the rectangle +gc.SetBrushStyle(CGraphicsContext::ESolidBrush); +gc.SetBrushColor(black); +gc.DrawPie(ellipseRect,constructionPoint1,constructionPoint2); + +// draw the other portion of the elliptical disc +gc.SetBrushStyle(CGraphicsContext::EVerticalHatchBrush); +gc.DrawPie(ellipseRect,constructionPoint2,constructionPoint1); +...
                Drawing to a Graphics Context Tutorials Drawing and Graphics Contexts                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A5756C5F-9C93-4949-8B60-03DCA1BAF683.dita --- a/Symbian3/SDK/Source/GUID-A5756C5F-9C93-4949-8B60-03DCA1BAF683.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-A5756C5F-9C93-4949-8B60-03DCA1BAF683.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,162 +1,161 @@ - - - - - -Form -items -

                Empty items (that contain no data) can be hidden in a form's View state. -However, this is not a requirement; forms can be designed either way, whichever -is better for the given application.

                -

                Unlike ordinary list items, the form items may have different sizes in -the layout but only in the Edit state. A long data field may occupy more than -one line in the Edit state, but in the View state it is truncated to the first -line.

                -

                The user may be able to add and remove form items. This is done with commands -in the Options menu.

                -

                Form items always have a label. The label has a text part, or a text and -a graphical part; however, all items in one form must have the same column -layout (see List layouts for -detailed information about layouts). Field label cannot be directly edited -even if the form is in Edit state. However, it is possible to let the user -edit the label text when the form is in edit state. User can choose to edit -the label with an option, which can be found in the Options menu.

                -

                The form field types that can be used are described in the following table:

                - Form field types - - - -Field -Description - - - - -

                Text field (alphanumeric or numeric content)

                 -

                A text field contains some type of numeric or alphanumeric data. -It can be edited directly using the usual editing functions when the form -is in the Edit state. The text field can expand to more than one lines if -necessary.

                In the View state, a text field looks identical to a corresponding -list item.

                 -                 - -

                Pop-up field

                 -

                A pop-up field offers the possibility to choose one value from a -pre-defined list. In the View state, a pop-up field looks identical to a list -item; the text is the current value of the field. In the Edit state, it has -a distinct look that identifies the field as a pop-up list.

                To edit -an item in the Edit state, the user can press the Selection key or with single -click (in tap enabled devices), which opens a menu list that contains the -available values. The highlight is on the current value. When the list is -open, the softkeys are OK and Cancel, as usual with a menu list. -Both the softkeys return to the Edit state in the form.

                A pop-up field -may also allow the user to enter a textual value in addition to the pre-defined -values. In this case, the last option is named for example Other, and -selecting it opens a Data query.

                See figure below.

                 -                 - -

                Slider

                 -

                With a slider, the user can adjust a numeric value (although it -is not necessary to present the actual value to the user as a number). In -the View state, the item is presented as a textual item. In the Edit state, -the value of the slider is immediately adjustable using the Arrow left and -Arrow right keys.

                 -                 - - -
                - -Pop-up field - - -

                Any combination of these types is possible within one form.

                -

                When a form is in the Edit state, the user can move the focus up and down -like in a list. The highlight in the Edit state is different from the highlight -in the View state, acting as a visual cue. The cursor blinks in the text field -that is in focus. There is no need to save each field separately; the user -can browse and modify the fields in any order and then accept all modifications. -During the browsing of a form in the Edit state, the keypad functions are -as follows:

                -

                The field types are described in the following table:

                -Default key events -in editing state of a form - - - -Key -Action - - - - -

                Arrow up / down

                 -

                Move the focus between form items (when in a text field, move the -cursor within an item line by line).

                 -                 - -

                Arrow left / right

                 -
                  -

                • In a pop-up field: change the value without opening the list.

                  • -

                • In a text field: move the cursor character by character.

                  • -

                • In a slider: adjust the slider value.

                  • -
                 -                 - -

                Selection key

                 -
                  -

                • In a pop-up field: opens the list.

                  • -

                • In a text field: opens the context sensitive Options menu or -no action.

                  • -
                 -                 - -

                Left softkey (Options)

                 -

                Opens the Options menu (in a form without the Options menu, -the left softkey is Done).

                 -                 - -

                Right softkey (Done)

                 -

                Accepts the contents and returns to the previous state (in a form -without the Options menu, the right softkey is Cancel.)

                 -                 - -

                Clear

                 -
                  -

                • Pop-up: ignored.

                  • -

                • Text: deletes characters.

                  • -

                • Slider: ignored.

                  • -
                 -                 - -

                Edit

                 -
                  -

                • Pop-up: ignored.

                  • -

                • Text: opens the editing menu; selects text.

                  • -

                • Slider: ignored.

                  • -
                 -                 - -

                Numeric keypad

                 -
                  -

                • Pop-up: ignored.

                  • -

                • Text: input.

                  • -

                • Slider: ignored.

                  • -
                 -                 - -

                Other keys

                 -

                The default action of the key.

                 -                 - - -
                -
                Using -forms in C++ applications

                The API to use for creating forms is the Form API. For implementation information, -see Using the Form API.

                + + + + + +Form items +

                Form items can either be displayed or hidden (for empty items that +contain no data) in a form's View state.

                +

                Unlike ordinary list items, the form items may have different sizes +in the layout but only in the Edit state. A long data field may occupy +more than one line in the Edit state, but in the View state it is +truncated to the first line.

                +

                The user may be able to add and remove form items. This is done +with commands in the Options menu.

                +

                Form items always have a label. The label has a text part, or a +text and a graphical part; however, all items in one form must have +the same column layout (see List layouts for detailed information about layouts). Field label cannot be directly +edited even if the form is in Edit state. However, it is possible +to let the user edit the label text when the form is in edit state. +User can choose to edit the label with an option, which can be found +in the Options menu.

                +

                The form field types that can be used are described in the following +table:

                + Form +field types + + + +Field +Description + + + + +

                Text field (alphanumeric or numeric content)

                 +

                A text field contains some type of numeric or alphanumeric +data. It can be edited directly using the usual editing functions +when the form is in the Edit state. The text field can expand to more +than one lines if necessary.

                In the View state, a text field +looks identical to a corresponding list item.

                 +                 + +

                Pop-up field

                 +

                A pop-up field offers the possibility to choose one value +from a pre-defined list. In the View state, a pop-up field looks identical +to a list item; the text is the current value of the field. In the +Edit state, it has a distinct look that identifies the field as a +pop-up list.

                To edit an item in the Edit state, the user can +press the Selection key or with single tap (in devices supporting +touch), which opens a menu list that contains the available values. +The highlight is on the current value. When the list is open, the +softkeys are OK and Cancel, as usual with a menu list. +Both the softkeys return to the Edit state in the form.

                A pop-up +field may also allow the user to enter a textual value in addition +to the pre-defined values. In this case, the last option is named +for example Other, and selecting it opens a Data query.

                See figure below.

                 +                 + +

                Slider

                 +

                With a slider, the user can adjust a numeric value (although +it is not necessary to present the actual value to the user as a number). +In the View state, the item is presented as a textual item. In the +Edit state, the value of the slider is immediately adjustable using +the Arrow left and Arrow right keys.

                 +                 + + +
                + +Pop-up field + + + +

                Any combination of these types is possible within one form.

                +

                When a form is in the Edit state, the user can move the focus up +and down like in a list. The highlight in the Edit state is different +from the highlight in the View state, acting as a visual cue. The +cursor blinks in the text field that is in focus. There is no need +to save each field separately; the user can browse and modify the +fields in any order and then accept all modifications. During the +browsing of a form in the Edit state, the keypad functions are as +follows:

                +

                The field types are described in the following table:

                +Default +key events in editing state of a form + + + +Key +Action + + + + +

                Arrow up / down

                 +

                Move the focus between form items (when in a text field, +move the cursor within an item line by line).

                 +                 + +

                Arrow left / right

                 +
                  +

                • In a pop-up field: change the value without opening the list.

                  • +

                • In a text field: move the cursor character by character.

                  • +

                • In a slider: adjust the slider value.

                  • +
                 +                 + +

                Selection key

                 +
                  +

                • In a pop-up field: opens the list.

                  • +

                • In a text field: opens the context sensitive Options menu or no action.

                  • +
                 +                 + +

                Left softkey (Options)

                 +

                Opens the Options menu (in a form without the Options menu, the left softkey is Done).

                 +                 + +

                Right softkey (Done)

                 +

                Accepts the contents and returns to the previous state (in +a form without the Options menu, the right softkey is Cancel.)

                 +                 + +

                Clear

                 +
                  +

                • Pop-up: ignored.

                  • +

                • Text: deletes characters.

                  • +

                • Slider: ignored.

                  • +
                 +                 + +

                Edit

                 +
                  +

                • Pop-up: ignored.

                  • +

                • Text: opens the editing menu; selects text.

                  • +

                • Slider: ignored.

                  • +
                 +                 + +

                Numeric keypad

                 +
                  +

                • Pop-up: ignored.

                  • +

                • Text: input.

                  • +

                • Slider: ignored.

                  • +
                 +                 + +

                Other keys

                 +

                The default action of the key.

                 +                 + + +
                +
                Using forms in applications

                The API to use for creating forms is the Form API. For implementation information, see Using the Form API.

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A5E152B2-F15C-4809-A52A-BCDDBCD93255_d0e36431_href.png Binary file Symbian3/SDK/Source/GUID-A5E152B2-F15C-4809-A52A-BCDDBCD93255_d0e36431_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A5E152B2-F15C-4809-A52A-BCDDBCD93255_d0e41998_href.png Binary file Symbian3/SDK/Source/GUID-A5E152B2-F15C-4809-A52A-BCDDBCD93255_d0e41998_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A5F65344-BE05-5295-85BB-E8114505FB82.dita --- a/Symbian3/SDK/Source/GUID-A5F65344-BE05-5295-85BB-E8114505FB82.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-A5F65344-BE05-5295-85BB-E8114505FB82.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,125 +1,125 @@ - - - - - -Alarm -Sound Play Control -

                This section explains the use of sound, which is one of the several ways -that the Alarm Server can notify the user.

                -
                Alarm Play Interval Configuration

                The alarm sound -play definition (TASCliSoundPlayDefinition) is set using -the RASCliSession class. Alarm sounds are played according -to intervals that consist of a duration and an offset. The TASCliSoundPlayDefinition class -defines when alarm sounds are to be played, and for how long.

                The -purpose of configuring alarm sound play is to enable the Alarm Server to perform -the following operations:

                  -

                • set the alarm sound -state to ON or OFF (RASCliSession::SetAlarmSoundState()).

                  • -

                • silence all alarms until -a specific time (RASCliSession::SetAlarmSoundsSilentUntil()). -No sound is played for any alarm that is notified before this time.

                  • -

                • silence all alarms for -a specified interval (RASCliSession::SetAlarmSoundsSilentFor()). -No alarm sound is played for any alarm notified during this period.

                  • -

                • cancel the silent period, -turning the alarm sounds ON (RASCliSession::CancelAlarmSilence()).

                  • -

                • configure alarm sound -play intervals (RASCliSession::SetAlarmPlayIntervalsL()), -which specify the duration of the ‘play/silence/play’ when an alarm expires.

                  • -

                • determine whether the -alarm server has temporarily silenced the sounds (RASCliSession::AlarmSoundsTemporarilySilenced()). -This returns ETrue if alarm sound playing is temporarily -silenced, else EFalse is specified.

                  • -

                NOTE: These APIs can be used only if the alarm sound -play control is enabled from the Alarm Server side.

                To perform these -operations, the Alarm Server uses a resource file, which defines the sound -play intervals and durations.

                Resource File

                The alarm -play intervals are defined in AlarmServer.rss resource file. -The compiled resource file (configuration file) must be named as alarmserver.rsc and -be placed in the Alarm Server’s private directory (C:\private\101F5027 on -emulator, or Z:\private\101F5027 on target platforms).

                The -resource file must start with the necessary include directives, resource name, -and standard signature entry as illustrated in the following code fragment:

                #include <badef.rh> -#include <alarmserver.rh> - -NAME ASRV -RESOURCE BA_RSS_SIGNATURE - { - signature = 1; - }

                The resource file specifies only the Offset (in minutes) -and Duration (in seconds) of the Alarm play intervals. It is used only for -initial configuration.

                At runtime, Alarm Server configurations are -backed up to a file called as AlarmServer.ini, on the -PC side. The backup operation performed can be one of the following types:

                  -

                • Secure Backup - -In this method, backuprestorenotification.lib (provides a -notification mechanism) is used for backing and restoring operation to and -from C:\private\101F5027\AlarmServer.ini.

                  • -

                • Passive Backup - -In this method, the required backup behavior is mentioned in a backup registration -file called backup_registration.xml, placed in its private -directory. The list of private directories and files that must be backed up -are mentioned in this backup registration file.

                  • -

                NOTE: The backup file takes precedence over the resource -file the next time the Alarm Server is started. Therefore, if changes are -made to the resource file, AlarmServer.ini must be deleted -manually before restarting the Alarm Server.

                Alarm Sound Play Intervals -and Durations

                The following diagram illustrates the alarm sound -play intervals:

                - ALARM SOUND PLAY INTERVALS - -

                Alarm play intervals define the toggling of alarm sound playing/stopping -and alarm dialog show/hide when an alarm expires. It consists of a duration -and an offset. The offset is the time, in minutes, from the beginning alarm -time or the end of the last snooze. The duration is the time period, in seconds, -during which the alarm sound is played.

                At each offset, the Alarm -Server makes a request to the Alarm Alert server to display the alarm dialog -and play the alarm sound. At the end of each duration period, the Alarm Server -makes a request to the Alarm Alert server to hide the alarm and stop playing -the alarm sound.

                The following is an example code fragment that plays -the sound for 30 seconds, then pauses for 30 seconds, and repeats the pattern -two more times:

                RESOURCE sound_controller - { - intervals = - { - SOUND_INTERVAL { offset = 0; duration = 30; }, - SOUND_INTERVAL { offset = 1; duration = 30; }, - SOUND_INTERVAL { offset = 2; duration = 30; }; - }; - }

                An interval must have an offset of zero if more than -one offset is specified.

                NOTE: The TASCliSoundPlayDefinition class -is the runtime equivalent of the sound intervals array. It defines TASCliSoundPlayDefinition::Offset() length -in minutes and defines TASCliSoundPlayDefinition::Duration() length -in seconds. The API to set a TASCliSoundPlayDefinition array -is TASCliSoundPlayDefinition::SetAlarmPlayIntervalsL().

                -
                Alarm Play Sequence Repeat Option

                The resource -file provides an option to repeat the sequence when the end of the alarm play -sequence is reached.

                For backward compatibility, the default behavior -is to restart the sequence when the end of the alarm play sequence is reached -(see EAlarmSoundRepeatSettingStop). This occurs if there -is no resource file, or if the resource file does not specify an option. There -are two more end-of-sequence options:

                  -

                • EAlarmSoundRepeatSettingLoop - -stop when the end of sequence reached.

                  • -

                • EAlarmSoundRepeatSettingRepeatLast - -repeat last interval indefinitely. This is an optional entry in the resource -file.

                  • -

                The following is a resource file example illustrating the use of -an option to repeat the alarm play sequence:

                RESOURCE sound_controller - { - option = EAlarmSoundRepeatSettingRepeatLast; - intervals = - { - ... - } - }
                -
                See also

                Playing -Alarm Sound Continuously

                + + + + + +Alarm +Sound Play Control +

                This section explains the use of sound, which is one of the several ways +that the Alarm Server can notify the user.

                +
                Alarm Play Interval Configuration

                The alarm sound +play definition (TASCliSoundPlayDefinition) is set using +the RASCliSession class. Alarm sounds are played according +to intervals that consist of a duration and an offset. The TASCliSoundPlayDefinition class +defines when alarm sounds are to be played, and for how long.

                The +purpose of configuring alarm sound play is to enable the Alarm Server to perform +the following operations:

                  +

                • set the alarm sound +state to ON or OFF (RASCliSession::SetAlarmSoundState()).

                  • +

                • silence all alarms until +a specific time (RASCliSession::SetAlarmSoundsSilentUntil()). +No sound is played for any alarm that is notified before this time.

                  • +

                • silence all alarms for +a specified interval (RASCliSession::SetAlarmSoundsSilentFor()). +No alarm sound is played for any alarm notified during this period.

                  • +

                • cancel the silent period, +turning the alarm sounds ON (RASCliSession::CancelAlarmSilence()).

                  • +

                • configure alarm sound +play intervals (RASCliSession::SetAlarmPlayIntervalsL()), +which specify the duration of the ‘play/silence/play’ when an alarm expires.

                  • +

                • determine whether the +alarm server has temporarily silenced the sounds (RASCliSession::AlarmSoundsTemporarilySilenced()). +This returns ETrue if alarm sound playing is temporarily +silenced, else EFalse is specified.

                  • +

                NOTE: These APIs can be used only if the alarm sound +play control is enabled from the Alarm Server side.

                To perform these +operations, the Alarm Server uses a resource file, which defines the sound +play intervals and durations.

                Resource File

                The alarm +play intervals are defined in AlarmServer.rss resource file. +The compiled resource file (configuration file) must be named as alarmserver.rsc and +be placed in the Alarm Server’s private directory (C:\private\101F5027 on +emulator, or Z:\private\101F5027 on target platforms).

                The +resource file must start with the necessary include directives, resource name, +and standard signature entry as illustrated in the following code fragment:

                #include <badef.rh> +#include <alarmserver.rh> + +NAME ASRV +RESOURCE BA_RSS_SIGNATURE + { + signature = 1; + }

                The resource file specifies only the Offset (in minutes) +and Duration (in seconds) of the Alarm play intervals. It is used only for +initial configuration.

                At runtime, Alarm Server configurations are +backed up to a file called as AlarmServer.ini, on the +PC side. The backup operation performed can be one of the following types:

                  +

                • Secure Backup - +In this method, backuprestorenotification.lib (provides a +notification mechanism) is used for backing and restoring operation to and +from C:\private\101F5027\AlarmServer.ini.

                  • +

                • Passive Backup - +In this method, the required backup behavior is mentioned in a backup registration +file called backup_registration.xml, placed in its private +directory. The list of private directories and files that must be backed up +are mentioned in this backup registration file.

                  • +

                NOTE: The backup file takes precedence over the resource +file the next time the Alarm Server is started. Therefore, if changes are +made to the resource file, AlarmServer.ini must be deleted +manually before restarting the Alarm Server.

                Alarm Sound Play Intervals +and Durations

                The following diagram illustrates the alarm sound +play intervals:

                + ALARM SOUND PLAY INTERVALS + +

                Alarm play intervals define the toggling of alarm sound playing/stopping +and alarm dialog show/hide when an alarm expires. It consists of a duration +and an offset. The offset is the time, in minutes, from the beginning alarm +time or the end of the last snooze. The duration is the time period, in seconds, +during which the alarm sound is played.

                At each offset, the Alarm +Server makes a request to the Alarm Alert server to display the alarm dialog +and play the alarm sound. At the end of each duration period, the Alarm Server +makes a request to the Alarm Alert server to hide the alarm and stop playing +the alarm sound.

                The following is an example code fragment that plays +the sound for 30 seconds, then pauses for 30 seconds, and repeats the pattern +two more times:

                RESOURCE sound_controller + { + intervals = + { + SOUND_INTERVAL { offset = 0; duration = 30; }, + SOUND_INTERVAL { offset = 1; duration = 30; }, + SOUND_INTERVAL { offset = 2; duration = 30; }; + }; + }

                An interval must have an offset of zero if more than +one offset is specified.

                NOTE: The TASCliSoundPlayDefinition class +is the runtime equivalent of the sound intervals array. It defines TASCliSoundPlayDefinition::Offset() length +in minutes and defines TASCliSoundPlayDefinition::Duration() length +in seconds. The API to set a TASCliSoundPlayDefinition array +is TASCliSoundPlayDefinition::SetAlarmPlayIntervalsL().

                +
                Alarm Play Sequence Repeat Option

                The resource +file provides an option to repeat the sequence when the end of the alarm play +sequence is reached.

                For backward compatibility, the default behavior +is to restart the sequence when the end of the alarm play sequence is reached +(see EAlarmSoundRepeatSettingStop). This occurs if there +is no resource file, or if the resource file does not specify an option. There +are two more end-of-sequence options:

                  +

                • EAlarmSoundRepeatSettingLoop - +stop when the end of sequence reached.

                  • +

                • EAlarmSoundRepeatSettingRepeatLast - +repeat last interval indefinitely. This is an optional entry in the resource +file.

                  • +

                The following is a resource file example illustrating the use of +an option to repeat the alarm play sequence:

                RESOURCE sound_controller + { + option = EAlarmSoundRepeatSettingRepeatLast; + intervals = + { + ... + } + }
                +
                See also

                Playing +Alarm Sound Continuously

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A626197A-3FA7-588C-B649-E33CCA990B99-GENID-1-8-1-3-1-1-9-1-4-1-3-1.dita --- a/Symbian3/SDK/Source/GUID-A626197A-3FA7-588C-B649-E33CCA990B99-GENID-1-8-1-3-1-1-9-1-4-1-3-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,34 +0,0 @@ - - - - - -FEP -Introduction -

                This guide is -adapted from material originally intended to accompany source code for sample -front end processors (FEPs) TFEP1Plugin (a keyboard-based FEP) and TFEP2Plugin -(a mouse/pen-based FEP).

                TFEP1Plugin and TFEP2Plugin are available -to Symbian DevKit licensees and may be found in the Symbian platform source -in the app-framework\feptest\ directory.

                SDK -licensees do not have access to the source but must find sufficient information -within the guide.

                Note: Platform security that was introduced -in Symbian OS v9.1, brought some changes to the way FEPs are created and loaded. Prospective -FEP developers must note that FEPs now require a capability of All-Tcb and -must therefore ensure that they are able to achieve this before commencing.

                The -guide is divided into the following sections:

                Implementing -the FEP API

                Fixed -and Floating Windows

                Simulating -and Intercepting Key Events

                Processing -Pen Events

                Synchronizing -FEP Instantiations

                Detecting -Changes in the Environment

                Interacting -with Text Editor Controls

                FEP -References

                -                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A626197A-3FA7-588C-B649-E33CCA990B99-GENID-1-8-1-6-1-1-4-1-8-1-4-1-3-1.dita --- a/Symbian3/SDK/Source/GUID-A626197A-3FA7-588C-B649-E33CCA990B99-GENID-1-8-1-6-1-1-4-1-8-1-4-1-3-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,34 +0,0 @@ - - - - - -FEP -Introduction -

                This guide is -adapted from material originally intended to accompany source code for sample -front end processors (FEPs) TFEP1Plugin (a keyboard-based FEP) and TFEP2Plugin -(a mouse/pen-based FEP).

                TFEP1Plugin and TFEP2Plugin are available -to Symbian DevKit licensees and may be found in the Symbian platform source -in the app-framework\feptest\ directory.

                SDK -licensees do not have access to the source but must find sufficient information -within the guide.

                Note: Platform security that was introduced -in Symbian OS v9.1, brought some changes to the way FEPs are created and loaded. Prospective -FEP developers must note that FEPs now require a capability of All-Tcb and -must therefore ensure that they are able to achieve this before commencing.

                The -guide is divided into the following sections:

                Implementing -the FEP API

                Fixed -and Floating Windows

                Simulating -and Intercepting Key Events

                Processing -Pen Events

                Synchronizing -FEP Instantiations

                Detecting -Changes in the Environment

                Interacting -with Text Editor Controls

                FEP -References

                -                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A626197A-3FA7-588C-B649-E33CCA990B99.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-A626197A-3FA7-588C-B649-E33CCA990B99.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,34 @@ + + + + + +FEP +Introduction +

                This guide is +adapted from material originally intended to accompany source code for sample +front end processors (FEPs) TFEP1Plugin (a keyboard-based FEP) and TFEP2Plugin +(a mouse/pen-based FEP).

                TFEP1Plugin and TFEP2Plugin are available +to Symbian DevKit licensees and may be found in the Symbian platform source +in the app-framework\feptest\ directory.

                SDK +licensees do not have access to the source but must find sufficient information +within the guide.

                Note: Platform security that was introduced +in Symbian OS v9.1, brought some changes to the way FEPs are created and loaded. Prospective +FEP developers must note that FEPs now require a capability of All-Tcb and +must therefore ensure that they are able to achieve this before commencing.

                The +guide is divided into the following sections:

                Implementing +the FEP API

                Fixed +and Floating Windows

                Simulating +and Intercepting Key Events

                Processing +Pen Events

                Synchronizing +FEP Instantiations

                Detecting +Changes in the Environment

                Interacting +with Text Editor Controls

                FEP +References

                +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A62E89DE-0762-5827-856D-F20EEF46EE4B-GENID-1-10-1-6-1-1-4-1-6-1-7-1-4-1.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-A62E89DE-0762-5827-856D-F20EEF46EE4B-GENID-1-10-1-6-1-1-4-1-6-1-7-1-4-1.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,12 @@ + + + + + +Simple controls and compound controls

                In addition to being window-owning or non-window-owning, each control is either a simple control or a compound control.

                Simple controls

                A simple control, such as a label or an image, is one which contains no other controls. A simple control may be window-owning or non-window-owning. The majority of simple controls, in practice, are non-window-owning.

                Compound controls

                A compound control is one which contains one or more simple or compound controls. Compound controls are also known as container controls and may be window-owning or non-window-owning.

                The controls contained by a compound control are its component controls. Components may also be window-owning or non-window-owning. The majority, in practice, are non-window-owning.

                The implementation of compound controls changed in version 9.1 of Symbian OS. The previous APIs and the old 'way of working' are still supported but do not support new automated features such as background drawing, font provision, layout managers and accumulated zoom.

                The new 'way of working' is currently used by UIQ v3.

                S60, MOAP and older versions of UIQ use the old scheme.

                Under the old (pre 9.1) scheme the way in which a compound control stored its component controls is not mandated by the framework. Controls derived from CCoeControl are free to store their components as they see fit. They have to implement the virtual function CCoeControl::CountComponentControls() to return the number of components, and also to provide CCoeControl::ComponentControl() to return the CCoeControl* pointing to a particular component. This is very flexible but places a greater burden on application developers and means that it is impossible for tools or agents to make assumptions about the internal structure of controls.

                Under the new (9.1 and onwards) scheme CCoeControl provides a storage mechanism and an API for adding, retrieving and removing components. Besides simplifying the API and making life easier for developers this ensures consistency which allows run-time agents, such as layout managers and skins managers, to act across all of the controls in the UI. The CCoeControl::CountComponentControls() and CCoeControl::ComponentControl() functions are now implemented by the base class. By default, CCoeControl also now takes responsibility for deleting its lodgers.

                The new scheme provides two methods for identifying component controls - one to be used by the parent, which gives each sibling component a unique ID, and one which allows each control within a view to have a UniqueHandle. The latter is primarily to enable resource driven view construction but is also useful for automated testing.

                The control framework (both old and new) provides logic to handle redrawing and the distribution of pointer events to component controls. A compound control must handle distribution of key events to its components. Non-window owning lodger components should not overlap* and must be contained within the extent of the compound control. This does not pose a restriction for most UI elements, such as buttons and labels, as they never need to overlap and never need to be displayed outside their containers.

                Component controls may themselves be compound. There is no limit on the number of levels of compounding.

                *Overlapping controls may be used in conjunction with MCoeControlHitTest. See How to write controls

                See also

                Run-time control hierarchy

                How to write controls

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A62E89DE-0762-5827-856D-F20EEF46EE4B-GENID-1-8-1-3-1-1-7-1-7-1-4-1.dita --- a/Symbian3/SDK/Source/GUID-A62E89DE-0762-5827-856D-F20EEF46EE4B-GENID-1-8-1-3-1-1-7-1-7-1-4-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,12 +0,0 @@ - - - - - -Simple controls and compound controls

                In addition to being window-owning or non-window-owning, each control is either a simple control or a compound control.

                Simple controls

                A simple control, such as a label or an image, is one which contains no other controls. A simple control may be window-owning or non-window-owning. The majority of simple controls, in practice, are non-window-owning.

                Compound controls

                A compound control is one which contains one or more simple or compound controls. Compound controls are also known as container controls and may be window-owning or non-window-owning.

                The controls contained by a compound control are its component controls. Components may also be window-owning or non-window-owning. The majority, in practice, are non-window-owning.

                The implementation of compound controls changed in version 9.1 of Symbian OS. The previous APIs and the old 'way of working' are still supported but do not support new automated features such as background drawing, font provision, layout managers and accumulated zoom.

                The new 'way of working' is currently used by UIQ v3.

                S60, MOAP and older versions of UIQ use the old scheme.

                Under the old (pre 9.1) scheme the way in which a compound control stored its component controls is not mandated by the framework. Controls derived from CCoeControl are free to store their components as they see fit. They have to implement the virtual function CCoeControl::CountComponentControls() to return the number of components, and also to provide CCoeControl::ComponentControl() to return the CCoeControl* pointing to a particular component. This is very flexible but places a greater burden on application developers and means that it is impossible for tools or agents to make assumptions about the internal structure of controls.

                Under the new (9.1 and onwards) scheme CCoeControl provides a storage mechanism and an API for adding, retrieving and removing components. Besides simplifying the API and making life easier for developers this ensures consistency which allows run-time agents, such as layout managers and skins managers, to act across all of the controls in the UI. The CCoeControl::CountComponentControls() and CCoeControl::ComponentControl() functions are now implemented by the base class. By default, CCoeControl also now takes responsibility for deleting its lodgers.

                The new scheme provides two methods for identifying component controls - one to be used by the parent, which gives each sibling component a unique ID, and one which allows each control within a view to have a UniqueHandle. The latter is primarily to enable resource driven view construction but is also useful for automated testing.

                The control framework (both old and new) provides logic to handle redrawing and the distribution of pointer events to component controls. A compound control must handle distribution of key events to its components. Non-window owning lodger components should not overlap* and must be contained within the extent of the compound control. This does not pose a restriction for most UI elements, such as buttons and labels, as they never need to overlap and never need to be displayed outside their containers.

                Component controls may themselves be compound. There is no limit on the number of levels of compounding.

                *Overlapping controls may be used in conjunction with MCoeControlHitTest. See How to write controls

                See also

                Run-time control hierarchy

                How to write controls

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A62E89DE-0762-5827-856D-F20EEF46EE4B-GENID-1-8-1-6-1-1-4-1-6-1-7-1-4-1.dita --- a/Symbian3/SDK/Source/GUID-A62E89DE-0762-5827-856D-F20EEF46EE4B-GENID-1-8-1-6-1-1-4-1-6-1-7-1-4-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,12 +0,0 @@ - - - - - -Simple controls and compound controls

                In addition to being window-owning or non-window-owning, each control is either a simple control or a compound control.

                Simple controls

                A simple control, such as a label or an image, is one which contains no other controls. A simple control may be window-owning or non-window-owning. The majority of simple controls, in practice, are non-window-owning.

                Compound controls

                A compound control is one which contains one or more simple or compound controls. Compound controls are also known as container controls and may be window-owning or non-window-owning.

                The controls contained by a compound control are its component controls. Components may also be window-owning or non-window-owning. The majority, in practice, are non-window-owning.

                The implementation of compound controls changed in version 9.1 of Symbian OS. The previous APIs and the old 'way of working' are still supported but do not support new automated features such as background drawing, font provision, layout managers and accumulated zoom.

                The new 'way of working' is currently used by UIQ v3.

                S60, MOAP and older versions of UIQ use the old scheme.

                Under the old (pre 9.1) scheme the way in which a compound control stored its component controls is not mandated by the framework. Controls derived from CCoeControl are free to store their components as they see fit. They have to implement the virtual function CCoeControl::CountComponentControls() to return the number of components, and also to provide CCoeControl::ComponentControl() to return the CCoeControl* pointing to a particular component. This is very flexible but places a greater burden on application developers and means that it is impossible for tools or agents to make assumptions about the internal structure of controls.

                Under the new (9.1 and onwards) scheme CCoeControl provides a storage mechanism and an API for adding, retrieving and removing components. Besides simplifying the API and making life easier for developers this ensures consistency which allows run-time agents, such as layout managers and skins managers, to act across all of the controls in the UI. The CCoeControl::CountComponentControls() and CCoeControl::ComponentControl() functions are now implemented by the base class. By default, CCoeControl also now takes responsibility for deleting its lodgers.

                The new scheme provides two methods for identifying component controls - one to be used by the parent, which gives each sibling component a unique ID, and one which allows each control within a view to have a UniqueHandle. The latter is primarily to enable resource driven view construction but is also useful for automated testing.

                The control framework (both old and new) provides logic to handle redrawing and the distribution of pointer events to component controls. A compound control must handle distribution of key events to its components. Non-window owning lodger components should not overlap* and must be contained within the extent of the compound control. This does not pose a restriction for most UI elements, such as buttons and labels, as they never need to overlap and never need to be displayed outside their containers.

                Component controls may themselves be compound. There is no limit on the number of levels of compounding.

                *Overlapping controls may be used in conjunction with MCoeControlHitTest. See How to write controls

                See also

                Run-time control hierarchy

                How to write controls

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A6363EC1-D9A2-5011-94F2-08B38E8247E0.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-A6363EC1-D9A2-5011-94F2-08B38E8247E0.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,12 @@ + + + + + +Weak and strong cryptography

                • Introduction

                • Weak cryptography

                • Strong cryptography

                • Build targets and variants

                Introduction

                The Cryptography library is provided in two separate builds, “weak” and “strong”, in order to comply with governmental export rules. These two builds are identical with the exception that the weak build rejects requests to apply an encryption scheme with key sizes greater than a size specified by the UK Government.

                Currently, symmetric algorithms with keys greater than 56 bits, and asymmetric with keys greater than 512 are deemed export controlled and are classed within Symbian as strong encryption. Keys of less than 56 and 512 bits respectively are classed as weak. Some algorithms – such as 3DES and AES cannot operate with weak keys, and are therefore strong-only algorithms.

                At present, two versions of the Cryptography library can be built:

                • weak_cryptography.dll

                • strong_cryptography.dll

                Clients always link against cryptography.dll.

                The strong/weak libraries are interchangeable (link compatible) except that the weak one will fail at run-time if an attempt is made to employ keys that are larger than bounds laid down by UK export restrictions.

                On hardware, the version used is determined at ROM build time by including the appropriate version of the Cryptography library as cryptography.dll. On the emulator, the crypto switch sub-component supplies cryptography.dll, and this transparently forwards calls to the appropriate version of the Cryptography library.

                The strong and weak Cryptography APIs are identical. The TCrypto API allows higher level components to determine at run-time whether the Cryptography library supports full strength cryptography. See How to find the cryptographic strength.

                Weak cryptography

                The weak version of the Cryptography library is the default one. This is the version that is exported to the \epoc32 tree as cryptography.dll. This default version may be replaced with any of the other versions. See How to change the cryptographic strength for instructions on how to do this.

                The default weak Cryptography library (weak_cryptography.dll) is limited as follows:

                • Symmetric algorithms (DES, RC2, ARC4) are limited to 56 bit key sizes.

                • The 3DES symmetric algorithm is not supported since this requires key sizes greater than 56 bits.

                • Asymmetric algorithms, RSA and DSA, may be used for decryption using any key size, but encryption is limited to 512 bits.

                • DH is limited to 512 bits.

                If attempts are made to use key lengths not supported by a weak crypto library then the library will return an error.

                Strong cryptography

                The strong Cryptography library supports any key length.

                Build targets and variants

                The two versions of the Cryptography library are available for different build targets and variants in:

                <your-SDK-path>\src\generic\security\cryptalg\import\bin\<target>\<variant>\

                Where target is one of the following build targets: wins, winscw, winc, thumb, armi, or arm4. And variant is either udeb or urel.

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A69D2707-CB47-42C2-A6E9-5FB9BD86A30B-master.png Binary file Symbian3/SDK/Source/GUID-A69D2707-CB47-42C2-A6E9-5FB9BD86A30B-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A69D2707-CB47-42C2-A6E9-5FB9BD86A30B_d0e40575_href.png Binary file Symbian3/SDK/Source/GUID-A69D2707-CB47-42C2-A6E9-5FB9BD86A30B_d0e40575_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A69D2707-CB47-42C2-A6E9-5FB9BD86A30B_d0e46132_href.png Binary file Symbian3/SDK/Source/GUID-A69D2707-CB47-42C2-A6E9-5FB9BD86A30B_d0e46132_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A69D2707-CB47-42C2-A6E9-5FB9BD86A30B_d0e58819_href.png Binary file Symbian3/SDK/Source/GUID-A69D2707-CB47-42C2-A6E9-5FB9BD86A30B_d0e58819_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A69D2707-CB47-42C2-A6E9-5FB9BD86A30B_d0e64364_href.png Binary file Symbian3/SDK/Source/GUID-A69D2707-CB47-42C2-A6E9-5FB9BD86A30B_d0e64364_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A69D2707-CB47-42C2-A6E9-5FB9BD86A30B_d0e67789_href.png Binary file Symbian3/SDK/Source/GUID-A69D2707-CB47-42C2-A6E9-5FB9BD86A30B_d0e67789_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A69D2707-CB47-42C2-A6E9-5FB9BD86A30B_d0e72940_href.png Binary file Symbian3/SDK/Source/GUID-A69D2707-CB47-42C2-A6E9-5FB9BD86A30B_d0e72940_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A6C9E7DF-1ACF-4768-851E-350E3DADEC56-master.png Binary file Symbian3/SDK/Source/GUID-A6C9E7DF-1ACF-4768-851E-350E3DADEC56-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A6C9E7DF-1ACF-4768-851E-350E3DADEC56_d0e57198_href.png Binary file Symbian3/SDK/Source/GUID-A6C9E7DF-1ACF-4768-851E-350E3DADEC56_d0e57198_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A6C9E7DF-1ACF-4768-851E-350E3DADEC56_d0e63102_href.png Binary file Symbian3/SDK/Source/GUID-A6C9E7DF-1ACF-4768-851E-350E3DADEC56_d0e63102_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A6EE8A2A-8B17-5D3A-A9B9-C8D25C92EA21_d0e359404_href.png Binary file Symbian3/SDK/Source/GUID-A6EE8A2A-8B17-5D3A-A9B9-C8D25C92EA21_d0e359404_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A6EE8A2A-8B17-5D3A-A9B9-C8D25C92EA21_d0e365484_href.png Binary file Symbian3/SDK/Source/GUID-A6EE8A2A-8B17-5D3A-A9B9-C8D25C92EA21_d0e365484_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A6F1F6AC-5D3C-5055-AEF1-B64671941BCB_d0e393431_href.png Binary file Symbian3/SDK/Source/GUID-A6F1F6AC-5D3C-5055-AEF1-B64671941BCB_d0e393431_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A6F1F6AC-5D3C-5055-AEF1-B64671941BCB_d0e393593_href.png Binary file Symbian3/SDK/Source/GUID-A6F1F6AC-5D3C-5055-AEF1-B64671941BCB_d0e393593_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A719FDFA-903B-5340-AA47-9E5B22DBB253_d0e185379_href.png Binary file Symbian3/SDK/Source/GUID-A719FDFA-903B-5340-AA47-9E5B22DBB253_d0e185379_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A719FDFA-903B-5340-AA47-9E5B22DBB253_d0e191975_href.png Binary file Symbian3/SDK/Source/GUID-A719FDFA-903B-5340-AA47-9E5B22DBB253_d0e191975_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A780F684-0F67-4A7F-B766-E69A5223F917-master.png Binary file Symbian3/SDK/Source/GUID-A780F684-0F67-4A7F-B766-E69A5223F917-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A780F684-0F67-4A7F-B766-E69A5223F917_d0e55415_href.png Binary file Symbian3/SDK/Source/GUID-A780F684-0F67-4A7F-B766-E69A5223F917_d0e55415_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A780F684-0F67-4A7F-B766-E69A5223F917_d0e63312_href.png Binary file Symbian3/SDK/Source/GUID-A780F684-0F67-4A7F-B766-E69A5223F917_d0e63312_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A7884A6F-384E-5A52-B2F4-C2FA1B3BAC29-GENID-1-8-1-3-1-1-6-1-4-1.dita --- a/Symbian3/SDK/Source/GUID-A7884A6F-384E-5A52-B2F4-C2FA1B3BAC29-GENID-1-8-1-3-1-1-6-1-4-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,31 +0,0 @@ - - - - - -Message -Window Overview -
                Purpose

                Provides a window that displays a message -to the user and then disappears.

                -
                Architectural relationships

                The animation of the -window is performed by an animation DLL that plugs-in to the Window Server. -The message window class is a client-side animation class, derived from the -animation client-side class RAnim.

                The API is used -by such higher-level APIs and device-family specific UIs to provide -information and message windows. Such APIs would normally be used by client -applications, but this API can be used to implement specialist new types of -message window.

                -
                Description

                A message window is provided by RMessageWindow. -The window's font and colors for background, text, border and plinth can be -configured.

                -
                See also
                  -

                • Animation

                  • -

                • Window server

                  • -
                -                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A7884A6F-384E-5A52-B2F4-C2FA1B3BAC29-GENID-1-8-1-6-1-1-4-1-5-1-4-1.dita --- a/Symbian3/SDK/Source/GUID-A7884A6F-384E-5A52-B2F4-C2FA1B3BAC29-GENID-1-8-1-6-1-1-4-1-5-1-4-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,31 +0,0 @@ - - - - - -Message -Window Overview -
                Purpose

                Provides a window that displays a message -to the user and then disappears.

                -
                Architectural relationships

                The animation of the -window is performed by an animation DLL that plugs-in to the Window Server. -The message window class is a client-side animation class, derived from the -animation client-side class RAnim.

                The API is used -by such higher-level APIs and device-family specific UIs to provide -information and message windows. Such APIs would normally be used by client -applications, but this API can be used to implement specialist new types of -message window.

                -
                Description

                A message window is provided by RMessageWindow. -The window's font and colors for background, text, border and plinth can be -configured.

                -
                See also
                  -

                • Animation

                  • -

                • Window server

                  • -
                -                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A7884A6F-384E-5A52-B2F4-C2FA1B3BAC29.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-A7884A6F-384E-5A52-B2F4-C2FA1B3BAC29.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,31 @@ + + + + + +Message +Window Overview +
                Purpose

                Provides a window that displays a message +to the user and then disappears.

                +
                Architectural relationships

                The animation of the +window is performed by an animation DLL that plugs-in to the Window Server. +The message window class is a client-side animation class, derived from the +animation client-side class RAnim.

                The API is used +by such higher-level APIs and device-family specific UIs to provide +information and message windows. Such APIs would normally be used by client +applications, but this API can be used to implement specialist new types of +message window.

                +
                Description

                A message window is provided by RMessageWindow. +The window's font and colors for background, text, border and plinth can be +configured.

                +
                See also
                  +

                • Animation

                  • +

                • Window server

                  • +
                +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A7E39E45-02BA-58F4-8807-EFABB8F6E5D0-GENID-1-8-1-3-1-1-9-1-4-1-7-1.dita --- a/Symbian3/SDK/Source/GUID-A7E39E45-02BA-58F4-8807-EFABB8F6E5D0-GENID-1-8-1-3-1-1-9-1-4-1-7-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,84 +0,0 @@ - - - - - -Processing -pen eventsThis topic describes various events processed by Pen or Mouse. -
                Simple drag -events

                In order for the FEP control to receive drag events occurring -in its window, all that is needed is to call EnableDragEvents() in -the control’s construction routine. Having done that, the control will receive -drag events as calls to its HandlePointerEventL() virtual -function. The iType member of HandlePointerEventL() ’s aPointerEvent parameter -is set to TPointerEvent::EDrag for drag events.

                This -method makes heavy use of IPC (inter-process communication) as the user drags -the mouse/pen around the FEP control’s window, which means that the FEP does -not get drag events at optimum frequency. This may be problematic for something -like handwriting recognition software. If there is a requirement to follow -the path traced by the mouse/pen as closely as possible, another method can -be used, namely buffered drag events.

                -
                Buffered drag -events

                The advantage of buffered drag events over simple drag events -is that the window server client can receive multiple mouse/pen positions -in a single event, which reduces the IPC overhead. To enable this, the following -code needs to be called in the FEP control’s construction routine:

                User::LeaveIfError(DrawableWindow()->AllocPointerMoveBuffer(ENumberOfPointsInBuffer, 0));

                This assumes that ENumberOfPointsInBuffer has been defined -elsewhere; TFEP2Plugin sets this constant to 32. The control -then receives drag events as calls to its HandlePointerBufferReadyL() virtual -function, rather than as calls to HandlePointerEventL(). -To retrieve these drag events, include the following code at the start of -the FEP control’s HandlePointerBufferReadyL() function:

                TPoint arrayOfPoints[ENumberOfPointsInBuffer]; -TPtr8 bufferOfPoints(REINTERPRET_CAST(TUint8*, arrayOfPoints), 0, ENumberOfPointsInBuffer*sizeof(TPoint)); -User::LeaveIfError(DrawableWindow()->RetrievePointerMoveBuffer(bufferOfPoints)); -const TInt numberOfPointsInBuffer=bufferOfPoints.Length()/sizeof(TPoint);

                Having -done that, numberOfPointsInBuffer of arrayOfPoints can -be used for whatever purpose the FEP requires, for example handwriting recognition. -Note that AllocPointerMoveBuffer() ’s counterpart FreePointerMoveBuffer() does -not need to be called in the FEP control’s destructor as this happens automatically -when the control’s window is destroyed.

                -
                Intercepting -pen events anywhere on the screen

                In order to intercept mouse/pen -events anywhere on the screen it is necessary to write a plugin into the window -server (WSERV). This is in addition to the FEP plugin which plugs into the -FEP architecture. TFEP2plugin provides a working example of this (TFEP2be). -The details of how to write a window server plugin DLL are beyond the scope -of this document because the APIs involved belong to the window server. See CAnim and CAnimDll in -the SDK for information on this. The way mouse/pen events can be intercepted -is by returning ETrue from the function overriding MEventHandler::OfferRawEvent() (CAnim derives -from MEventHandler). Events which are handled in this way -will not be sent to the relevant window server client, in other words, the -client who would otherwise have received this event.

                The sprite feature -of the window server (RWsSprite, defined in epoc32\include\W32STD.H) -can be used to display to the user the path on the screen being traced out -by their mouse/pen movements. However, care should be taken when using sprites -for this purpose. Sprites use bitmaps, which in this context would need to -be the size of the screen. Because each running application has its own FEP, -which would have its own sprite, which in turn would have its own screen-sized -bitmap, it becomes apparent that some optimization must be done to avoid huge -amounts of memory being consumed. TFEP2Plugin solves this problem by using -a single bitmap shared between each sprite. It uses the 4 byte thread-local -storage of the window server plugin DLL to store the identifier of this bitmap. -The code which constructs the sprite is protected by a mutex (RMutex, -defined in epoc32\include\E32STD.H) as it tests to see -if the bitmap to be used by the sprite has already been created by a FEP running -the same code in another thread. If it has then it merely calls CFbsBitmap::Duplicate() which -simply increments the existing bitmap’s reference count, thus only one large -bitmap is created rather than one per running application.

                Intercepting -mouse/pen events anywhere on the screen is likely to be most useful to handwriting-interpreting -FEPs. Given that using this feature involves two polymorphic DLLs (plugging -into different frameworks) running in two separate threads in separate processes, -there is a choice regarding where the bulk of the FEP’s processing is done. -The advantage of the processing being done outside of the window server process -(in other words, in the FEP architecture plugin) is that bugs in the processing -code (for instance crashing or hanging) do not affect the whole machine. The -advantage of the processing being done inside the window server process (in -other words, in the window server plugin) is that the long lists of screen -positions (tracing out the path of where the user has dragged the mouse/pen) -do not need to be communicated between processes.

                -                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A7E39E45-02BA-58F4-8807-EFABB8F6E5D0-GENID-1-8-1-6-1-1-4-1-8-1-4-1-7-1.dita --- a/Symbian3/SDK/Source/GUID-A7E39E45-02BA-58F4-8807-EFABB8F6E5D0-GENID-1-8-1-6-1-1-4-1-8-1-4-1-7-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,84 +0,0 @@ - - - - - -Processing -pen eventsThis topic describes various events processed by Pen or Mouse. -
                Simple drag -events

                In order for the FEP control to receive drag events occurring -in its window, all that is needed is to call EnableDragEvents() in -the control’s construction routine. Having done that, the control will receive -drag events as calls to its HandlePointerEventL() virtual -function. The iType member of HandlePointerEventL() ’s aPointerEvent parameter -is set to TPointerEvent::EDrag for drag events.

                This -method makes heavy use of IPC (inter-process communication) as the user drags -the mouse/pen around the FEP control’s window, which means that the FEP does -not get drag events at optimum frequency. This may be problematic for something -like handwriting recognition software. If there is a requirement to follow -the path traced by the mouse/pen as closely as possible, another method can -be used, namely buffered drag events.

                -
                Buffered drag -events

                The advantage of buffered drag events over simple drag events -is that the window server client can receive multiple mouse/pen positions -in a single event, which reduces the IPC overhead. To enable this, the following -code needs to be called in the FEP control’s construction routine:

                User::LeaveIfError(DrawableWindow()->AllocPointerMoveBuffer(ENumberOfPointsInBuffer, 0));

                This assumes that ENumberOfPointsInBuffer has been defined -elsewhere; TFEP2Plugin sets this constant to 32. The control -then receives drag events as calls to its HandlePointerBufferReadyL() virtual -function, rather than as calls to HandlePointerEventL(). -To retrieve these drag events, include the following code at the start of -the FEP control’s HandlePointerBufferReadyL() function:

                TPoint arrayOfPoints[ENumberOfPointsInBuffer]; -TPtr8 bufferOfPoints(REINTERPRET_CAST(TUint8*, arrayOfPoints), 0, ENumberOfPointsInBuffer*sizeof(TPoint)); -User::LeaveIfError(DrawableWindow()->RetrievePointerMoveBuffer(bufferOfPoints)); -const TInt numberOfPointsInBuffer=bufferOfPoints.Length()/sizeof(TPoint);

                Having -done that, numberOfPointsInBuffer of arrayOfPoints can -be used for whatever purpose the FEP requires, for example handwriting recognition. -Note that AllocPointerMoveBuffer() ’s counterpart FreePointerMoveBuffer() does -not need to be called in the FEP control’s destructor as this happens automatically -when the control’s window is destroyed.

                -
                Intercepting -pen events anywhere on the screen

                In order to intercept mouse/pen -events anywhere on the screen it is necessary to write a plugin into the window -server (WSERV). This is in addition to the FEP plugin which plugs into the -FEP architecture. TFEP2plugin provides a working example of this (TFEP2be). -The details of how to write a window server plugin DLL are beyond the scope -of this document because the APIs involved belong to the window server. See CAnim and CAnimDll in -the SDK for information on this. The way mouse/pen events can be intercepted -is by returning ETrue from the function overriding MEventHandler::OfferRawEvent() (CAnim derives -from MEventHandler). Events which are handled in this way -will not be sent to the relevant window server client, in other words, the -client who would otherwise have received this event.

                The sprite feature -of the window server (RWsSprite, defined in epoc32\include\W32STD.H) -can be used to display to the user the path on the screen being traced out -by their mouse/pen movements. However, care should be taken when using sprites -for this purpose. Sprites use bitmaps, which in this context would need to -be the size of the screen. Because each running application has its own FEP, -which would have its own sprite, which in turn would have its own screen-sized -bitmap, it becomes apparent that some optimization must be done to avoid huge -amounts of memory being consumed. TFEP2Plugin solves this problem by using -a single bitmap shared between each sprite. It uses the 4 byte thread-local -storage of the window server plugin DLL to store the identifier of this bitmap. -The code which constructs the sprite is protected by a mutex (RMutex, -defined in epoc32\include\E32STD.H) as it tests to see -if the bitmap to be used by the sprite has already been created by a FEP running -the same code in another thread. If it has then it merely calls CFbsBitmap::Duplicate() which -simply increments the existing bitmap’s reference count, thus only one large -bitmap is created rather than one per running application.

                Intercepting -mouse/pen events anywhere on the screen is likely to be most useful to handwriting-interpreting -FEPs. Given that using this feature involves two polymorphic DLLs (plugging -into different frameworks) running in two separate threads in separate processes, -there is a choice regarding where the bulk of the FEP’s processing is done. -The advantage of the processing being done outside of the window server process -(in other words, in the FEP architecture plugin) is that bugs in the processing -code (for instance crashing or hanging) do not affect the whole machine. The -advantage of the processing being done inside the window server process (in -other words, in the window server plugin) is that the long lists of screen -positions (tracing out the path of where the user has dragged the mouse/pen) -do not need to be communicated between processes.

                -                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A7E39E45-02BA-58F4-8807-EFABB8F6E5D0.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-A7E39E45-02BA-58F4-8807-EFABB8F6E5D0.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,84 @@ + + + + + +Processing +pen eventsThis topic describes various events processed by Pen or Mouse. +
                Simple drag +events

                In order for the FEP control to receive drag events occurring +in its window, all that is needed is to call EnableDragEvents() in +the control’s construction routine. Having done that, the control will receive +drag events as calls to its HandlePointerEventL() virtual +function. The iType member of HandlePointerEventL() ’s aPointerEvent parameter +is set to TPointerEvent::EDrag for drag events.

                This +method makes heavy use of IPC (inter-process communication) as the user drags +the mouse/pen around the FEP control’s window, which means that the FEP does +not get drag events at optimum frequency. This may be problematic for something +like handwriting recognition software. If there is a requirement to follow +the path traced by the mouse/pen as closely as possible, another method can +be used, namely buffered drag events.

                +
                Buffered drag +events

                The advantage of buffered drag events over simple drag events +is that the window server client can receive multiple mouse/pen positions +in a single event, which reduces the IPC overhead. To enable this, the following +code needs to be called in the FEP control’s construction routine:

                User::LeaveIfError(DrawableWindow()->AllocPointerMoveBuffer(ENumberOfPointsInBuffer, 0));

                This assumes that ENumberOfPointsInBuffer has been defined +elsewhere; TFEP2Plugin sets this constant to 32. The control +then receives drag events as calls to its HandlePointerBufferReadyL() virtual +function, rather than as calls to HandlePointerEventL(). +To retrieve these drag events, include the following code at the start of +the FEP control’s HandlePointerBufferReadyL() function:

                TPoint arrayOfPoints[ENumberOfPointsInBuffer]; +TPtr8 bufferOfPoints(REINTERPRET_CAST(TUint8*, arrayOfPoints), 0, ENumberOfPointsInBuffer*sizeof(TPoint)); +User::LeaveIfError(DrawableWindow()->RetrievePointerMoveBuffer(bufferOfPoints)); +const TInt numberOfPointsInBuffer=bufferOfPoints.Length()/sizeof(TPoint);

                Having +done that, numberOfPointsInBuffer of arrayOfPoints can +be used for whatever purpose the FEP requires, for example handwriting recognition. +Note that AllocPointerMoveBuffer() ’s counterpart FreePointerMoveBuffer() does +not need to be called in the FEP control’s destructor as this happens automatically +when the control’s window is destroyed.

                +
                Intercepting +pen events anywhere on the screen

                In order to intercept mouse/pen +events anywhere on the screen it is necessary to write a plugin into the window +server (WSERV). This is in addition to the FEP plugin which plugs into the +FEP architecture. TFEP2plugin provides a working example of this (TFEP2be). +The details of how to write a window server plugin DLL are beyond the scope +of this document because the APIs involved belong to the window server. See CAnim and CAnimDll in +the SDK for information on this. The way mouse/pen events can be intercepted +is by returning ETrue from the function overriding MEventHandler::OfferRawEvent() (CAnim derives +from MEventHandler). Events which are handled in this way +will not be sent to the relevant window server client, in other words, the +client who would otherwise have received this event.

                The sprite feature +of the window server (RWsSprite, defined in epoc32\include\W32STD.H) +can be used to display to the user the path on the screen being traced out +by their mouse/pen movements. However, care should be taken when using sprites +for this purpose. Sprites use bitmaps, which in this context would need to +be the size of the screen. Because each running application has its own FEP, +which would have its own sprite, which in turn would have its own screen-sized +bitmap, it becomes apparent that some optimization must be done to avoid huge +amounts of memory being consumed. TFEP2Plugin solves this problem by using +a single bitmap shared between each sprite. It uses the 4 byte thread-local +storage of the window server plugin DLL to store the identifier of this bitmap. +The code which constructs the sprite is protected by a mutex (RMutex, +defined in epoc32\include\E32STD.H) as it tests to see +if the bitmap to be used by the sprite has already been created by a FEP running +the same code in another thread. If it has then it merely calls CFbsBitmap::Duplicate() which +simply increments the existing bitmap’s reference count, thus only one large +bitmap is created rather than one per running application.

                Intercepting +mouse/pen events anywhere on the screen is likely to be most useful to handwriting-interpreting +FEPs. Given that using this feature involves two polymorphic DLLs (plugging +into different frameworks) running in two separate threads in separate processes, +there is a choice regarding where the bulk of the FEP’s processing is done. +The advantage of the processing being done outside of the window server process +(in other words, in the FEP architecture plugin) is that bugs in the processing +code (for instance crashing or hanging) do not affect the whole machine. The +advantage of the processing being done inside the window server process (in +other words, in the window server plugin) is that the long lists of screen +positions (tracing out the path of where the user has dragged the mouse/pen) +do not need to be communicated between processes.

                +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A83DBB85-EBA0-44CB-8903-69F5E0C08191.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-A83DBB85-EBA0-44CB-8903-69F5E0C08191.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,15 @@ + + + + + +Extended +Connection Preference API- TutorialsThe Extended Connection Preference API allows the application to +set preferences prior to connection establishment. These preferences enable +and manage connections efficiently. \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A869BA79-5916-5B60-A02B-EF7D7CCA8C45.dita --- a/Symbian3/SDK/Source/GUID-A869BA79-5916-5B60-A02B-EF7D7CCA8C45.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-A869BA79-5916-5B60-A02B-EF7D7CCA8C45.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,16 +1,16 @@ - - - - - -How to control Application Level Roaming for SIP Profiles

                Application Level Roaming (ALR) is a facility which allows a SIP Profile to switch between service providers by using Internet Access Points (IAPs). By default, all SIP clients allow the SIP profiles they are using to roam across IAPs.

                To restrict roaming for a SIP profile to a set of IAPs, configure the profile with a Service Network Access Point (SNAP) ID. A SNAP ID is a unique identifier for a set of IAPs. The SIP profile store must include the SNAP ID that can be used by the SIP profile while roaming.

                Use the CSipProfileAlrController and MSipProfileAlrObserver classes to control ALR.

                To register for ALR events, use an instance of the CSipProfileAlrController class and implement the MSipProfileAlrObserver interface to register for ALR events. When registered for the ALR event, the MSipProfileAlrObserver interface notifies the client when a SIP profile used by the client tries to migrate to another IAP. Then the client can allow or disallow the migration request using the CSipProfileAlrController::AllowMigrationL() or CSipProfileAlrController::DisallowMigrationL() functions.

                The following illustration shows the call flow of enabling a SIP profile configured with a SNAP ID.

                - Call flow of enabling a SIP profile with a SNAP ID -

                When the SIP profile is registered with a SNAP ID, you can allow the SIP profile to migrate to another IAP within the SNAP.

                In the following illustration, the SIP profile is deregistered after migrating to another IAP. To use it again, you must register the profile again.

                The following illustration shows the call flow of SIP profile migration.

                - Call flow of migrating a SIP profile to another IAP -                 \ No newline at end of file + + + + + +How to control Application Level Roaming for SIP Profiles

                Application Level Roaming (ALR) is a facility which allows a SIP Profile to switch between service providers by using Internet Access Points (IAPs). By default, all SIP clients allow the SIP profiles they are using to roam across IAPs.

                To restrict roaming for a SIP profile to a set of IAPs, configure the profile with a Service Network Access Point (SNAP) ID. A SNAP ID is a unique identifier for a set of IAPs. The SIP profile store must include the SNAP ID that can be used by the SIP profile while roaming.

                Use the CSipProfileAlrController and MSipProfileAlrObserver classes to control ALR.

                To register for ALR events, use an instance of the CSipProfileAlrController class and implement the MSipProfileAlrObserver interface to register for ALR events. When registered for the ALR event, the MSipProfileAlrObserver interface notifies the client when a SIP profile used by the client tries to migrate to another IAP. Then the client can allow or disallow the migration request using the CSipProfileAlrController::AllowMigrationL() or CSipProfileAlrController::DisallowMigrationL() functions.

                The following illustration shows the call flow of enabling a SIP profile configured with a SNAP ID.

                + Call flow of enabling a SIP profile with a SNAP ID +

                When the SIP profile is registered with a SNAP ID, you can allow the SIP profile to migrate to another IAP within the SNAP.

                In the following illustration, the SIP profile is deregistered after migrating to another IAP. To use it again, you must register the profile again.

                The following illustration shows the call flow of SIP profile migration.

                + Call flow of migrating a SIP profile to another IAP +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A87610FF-2FBC-4BA3-8F6B-0BBB441F8066.dita --- a/Symbian3/SDK/Source/GUID-A87610FF-2FBC-4BA3-8F6B-0BBB441F8066.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-A87610FF-2FBC-4BA3-8F6B-0BBB441F8066.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,100 +1,100 @@ - - - - - -Hardware -Resource Manager OverviewIntroduction to topic for overview page or search -

                Hardware Resource Manager (HWRM) is a client-server solution, which utilizes -ECom plug-ins to achieve device independency. ECom plug-ins convert the client -requests into the hardware control commands.

                -
                Purpose

                HWRM performs the following functions:

                  -

                • Provide client APIs -to control lights, vibra.

                  • -

                • Retrieve battery information -of the device.

                  • -

                • Publish certain power-state -related Publish and Subscribe properties.

                  • -

                • Enable clients to retrieve -status information on the hardware elements such as light, vibration, power.

                  • -
                -
                Required background

                Knowledge of the client-server -architecture, asynchronous processing, and active objects feature of the Symbian -system model architecture.

                -
                HWRM architecture

                HWRM is made up of the following -components:

                  -

                • Client APIs

                  • -

                • HWRM Server

                  • -
                - Hardware Resource Manager's Architectural Relationships - - -

                Client APIs

                HWRM provides client APIs that can control -various hardware elements. It also provides callback pointers, so that the -client applications can register to receive notification on the hardware status -changes. Refer to the tutorials for -information on how to use client APIs. Client APIs are useful for both application -developers and the handset manufacturers.

                HWRM server

                HWRM -server uses plug-in handlers to forward the client API requests to appropriate -plug-ins. The client application communicates with HWRM server through the -client APIs (Light API, Vibra API, and Power API). HWRM server defines the -observer classes, which provide the callback pointers.

                The server -calls CHWRMPluginService::ProcessCommandL() function to -forward the client requests to plug-ins. An ongoing ProcessCommandL() is -cancelled by HWRM server using CHWRMPluginService::CancelCommandL(). -The plug-ins process the server's request and pass the response by calling CHWRMPluginCallback::ProcessResponseL() function. -The MHWRMPluginCallback::EventL() method is used to communicate -various events that takes place in the plug-ins.

                HWRM uses the central -repository to store the various values and settings such as the light intensity, -duration and delays.

                -
                APIs

                The HWRM provides the following client APIs -and plug-in APIs:

                - - - - - -Class -Description - - - - -

                CHWRMLight

                -

                Abstract class defining Lights client API.

                -                 - -

                CHWRMExtendedLight

                 -

                Abstract class defining Extended Lights client API.

                 -                 - -

                CHWRMVibra

                -

                Abstract class defining Vibra client API.

                -                 - -

                CHWRMPower

                -

                Class defining Power client API.

                -                 - - -
                -
                Typical use cases

                HWRM is used for the following:

                  -

                • Used to configure a plug-in.

                  • -

                • Start/stop device vibra.

                  • -

                • Release the reserved -lights

                  • -

                • Retrieve the supported -light targets of the device, current light status, vibra settings and status.

                  • -

                • Reserve light targets, -device vibra.

                  • -

                • Switch ON/OFF the lights.

                  • -

                • Request for tactile -vibration pulse.

                  • -
                + + + + + +Hardware +Resource Manager OverviewIntroduction to topic for overview page or search +

                Hardware Resource Manager (HWRM) is a client-server solution, which utilizes +ECom plug-ins to achieve device independency. ECom plug-ins convert the client +requests into the hardware control commands.

                +
                Purpose

                HWRM performs the following functions:

                  +

                • Provide client APIs +to control lights, vibra.

                  • +

                • Retrieve battery information +of the device.

                  • +

                • Publish certain power-state +related Publish and Subscribe properties.

                  • +

                • Enable clients to retrieve +status information on the hardware elements such as light, vibration, power.

                  • +
                +
                Required background

                Knowledge of the client-server +architecture, asynchronous processing, and active objects feature of the Symbian +system model architecture.

                +
                HWRM architecture

                HWRM is made up of the following +components:

                  +

                • Client APIs

                  • +

                • HWRM Server

                  • +
                + Hardware Resource Manager's Architectural Relationships + + +

                Client APIs

                HWRM provides client APIs that can control +various hardware elements. It also provides callback pointers, so that the +client applications can register to receive notification on the hardware status +changes. Refer to the tutorials for +information on how to use client APIs. Client APIs are useful for both application +developers and the handset manufacturers.

                HWRM server

                HWRM +server uses plug-in handlers to forward the client API requests to appropriate +plug-ins. The client application communicates with HWRM server through the +client APIs (Light API, Vibra API, and Power API). HWRM server defines the +observer classes, which provide the callback pointers.

                The server +calls CHWRMPluginService::ProcessCommandL() function to +forward the client requests to plug-ins. An ongoing ProcessCommandL() is +cancelled by HWRM server using CHWRMPluginService::CancelCommandL(). +The plug-ins process the server's request and pass the response by calling CHWRMPluginCallback::ProcessResponseL() function. +The MHWRMPluginCallback::EventL() method is used to communicate +various events that takes place in the plug-ins.

                HWRM uses the central +repository to store the various values and settings such as the light intensity, +duration and delays.

                +
                APIs

                The HWRM provides the following client APIs +and plug-in APIs:

                + + + + + +Class +Description + + + + +

                CHWRMLight

                +

                Abstract class defining Lights client API.

                +                 + +

                CHWRMExtendedLight

                 +

                Abstract class defining Extended Lights client API.

                 +                 + +

                CHWRMVibra

                +

                Abstract class defining Vibra client API.

                +                 + +

                CHWRMPower

                +

                Class defining Power client API.

                +                 + + +
                +
                Typical use cases

                HWRM is used for the following:

                  +

                • Used to configure a plug-in.

                  • +

                • Start/stop device vibra.

                  • +

                • Release the reserved +lights

                  • +

                • Retrieve the supported +light targets of the device, current light status, vibra settings and status.

                  • +

                • Reserve light targets, +device vibra.

                  • +

                • Switch ON/OFF the lights.

                  • +

                • Request for tactile +vibration pulse.

                  • +
                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A89A50B6-2A3B-54E1-8157-6CC86AFE4A57_d0e357640_href.png Binary file Symbian3/SDK/Source/GUID-A89A50B6-2A3B-54E1-8157-6CC86AFE4A57_d0e357640_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A89A50B6-2A3B-54E1-8157-6CC86AFE4A57_d0e363720_href.png Binary file Symbian3/SDK/Source/GUID-A89A50B6-2A3B-54E1-8157-6CC86AFE4A57_d0e363720_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A8C80AA1-42CF-5866-B223-FCE1AEC9DF63_d0e304305_href.jpg Binary file Symbian3/SDK/Source/GUID-A8C80AA1-42CF-5866-B223-FCE1AEC9DF63_d0e304305_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A8C80AA1-42CF-5866-B223-FCE1AEC9DF63_d0e310320_href.jpg Binary file Symbian3/SDK/Source/GUID-A8C80AA1-42CF-5866-B223-FCE1AEC9DF63_d0e310320_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A92CE0FF-113F-55BE-B5EF-7E5C629A4557_d0e169220_href.jpg Binary file Symbian3/SDK/Source/GUID-A92CE0FF-113F-55BE-B5EF-7E5C629A4557_d0e169220_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A92CE0FF-113F-55BE-B5EF-7E5C629A4557_d0e175821_href.jpg Binary file Symbian3/SDK/Source/GUID-A92CE0FF-113F-55BE-B5EF-7E5C629A4557_d0e175821_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A947B5A8-9138-4FA2-B8D8-2850AEB2F38C.dita --- a/Symbian3/SDK/Source/GUID-A947B5A8-9138-4FA2-B8D8-2850AEB2F38C.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-A947B5A8-9138-4FA2-B8D8-2850AEB2F38C.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,23 +1,23 @@ - - - - - -Battery -pane -

                Battery pane displays the remaining energy level of the battery, using -a graphical indicator. It also acts as a charging indicator. The battery indicator -is visible in all applications.

                - -Battery pane - - -

                The battery pane is not accessible -to applications.

                + + + + + +Battery +pane +

                Battery pane displays the remaining energy level of the battery, using +a graphical indicator. It also acts as a charging indicator. The battery indicator +is visible in all applications.

                + +Battery pane + + +

                The battery pane is not accessible +to applications.

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A950288B-D9D8-59E3-9F4C-0AEE2FC77E38_d0e276053_href.jpg Binary file Symbian3/SDK/Source/GUID-A950288B-D9D8-59E3-9F4C-0AEE2FC77E38_d0e276053_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A950288B-D9D8-59E3-9F4C-0AEE2FC77E38_d0e279739_href.jpg Binary file Symbian3/SDK/Source/GUID-A950288B-D9D8-59E3-9F4C-0AEE2FC77E38_d0e279739_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A95CDFDE-285F-5DE2-AADE-29B2B9663757.dita --- a/Symbian3/SDK/Source/GUID-A95CDFDE-285F-5DE2-AADE-29B2B9663757.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-A95CDFDE-285F-5DE2-AADE-29B2B9663757.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,12 +1,12 @@ - - - - - -The object index

                An object index is used to generate handle-numbers for reference counting objects.

                An object index is an instance of a CObjectIx class.

                An object index acts as a collector of reference counting objects but, unlike an object container, it does not act as a container for them. The difference is emphasised by the fact that removing a reference counting object from its object container causes that reference counting object to be destroyed, while removing it from an object index causes it to be closed.

                An object index can hold reference counting objects which belong to different object containers. The same reference counting object can also be added to an object index any number of times; each is regarded as a different instance of that object and each instance generates a different handle-number.

                CObjectIx::AddL() adds a reference counting object to an object index, and is the way in which a unique handle-number can be generated for that object. A handle-number is the way in which an object which is owned or managed by another thread or process can be identified. For example, on the server side, the object representing a thread (a DThread) maintains an object index for all objects which are open in that thread. Semaphores, mutexes and other threads are examples. Typically, user code running in that thread will have handles, RHandleBase derived types, open on those objects.

                The following drawing shows the idea.

                An object index is implemented as an array where each element of the array contains a pointer to the reference counting object. An object index can index up to 32,768 (0x8000) reference counting objects.

                See also:

                • CObjectIx

                • CObjectConIx

                • CObjectCon

                • CObject

                \ No newline at end of file + + + + + +The object index

                An object index is used to generate handle-numbers for reference counting objects.

                An object index is an instance of a CObjectIx class.

                An object index acts as a collector of reference counting objects but, unlike an object container, it does not act as a container for them. The difference is emphasised by the fact that removing a reference counting object from its object container causes that reference counting object to be destroyed, while removing it from an object index causes it to be closed.

                An object index can hold reference counting objects which belong to different object containers. The same reference counting object can also be added to an object index any number of times; each is regarded as a different instance of that object and each instance generates a different handle-number.

                CObjectIx::AddL() adds a reference counting object to an object index, and is the way in which a unique handle-number can be generated for that object. A handle-number is the way in which an object which is owned or managed by another thread or process can be identified. For example, on the server side, the object representing a thread (a DThread) maintains an object index for all objects which are open in that thread. Semaphores, mutexes and other threads are examples. Typically, user code running in that thread will have handles, RHandleBase derived types, open on those objects.

                The following drawing shows the idea.

                An object index is implemented as an array where each element of the array contains a pointer to the reference counting object. An object index can index up to 32,768 (0x8000) reference counting objects.

                See also:

                • CObjectIx

                • CObjectConIx

                • CObjectCon

                • CObject

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A95FEDD4-106A-5E14-8B64-3E2882C76666_d0e246388_href.png Binary file Symbian3/SDK/Source/GUID-A95FEDD4-106A-5E14-8B64-3E2882C76666_d0e246388_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A95FEDD4-106A-5E14-8B64-3E2882C76666_d0e250125_href.png Binary file Symbian3/SDK/Source/GUID-A95FEDD4-106A-5E14-8B64-3E2882C76666_d0e250125_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A97AD7EB-43C2-545A-9756-57D65A4905D9-GENID-1-8-1-3-1-1-4-1-4-1.dita --- a/Symbian3/SDK/Source/GUID-A97AD7EB-43C2-545A-9756-57D65A4905D9-GENID-1-8-1-3-1-1-4-1-4-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,41 +0,0 @@ - - - - - -How to create a basic animation

                The animation framework provides a concrete implementation of the CAnimation class called CBasicAnimation class to create a basic client-side animation. A basic client-side animation needs data, which can range from a simple file to a complex data structure. The data provider is responsible for handling this data and cater to the needs of the animation whenever required. The CICLAnimationDataProvider class acts as a data provider and handles the data needed for any type of animation.

                To create a basic client-side animation, create an object of the CICLAnimationDataProvider class. Associate the data required for the animation with the data provider object. In the example used below, the data needed for the animation is a simple animated GIF file.

                The following code shows how to create a data provider object and associate a GIF file with it:

                //Path to the GIF file -_LIT(KAnimExGuitarPlayer,"Z:\\resource\\apps\\AnimExample\\GuitarPlayer.gif"); - -//Creating the data provider object and setting the GIF file using the string literal created above. -//The iEikonEnv macro is used to open a session with the file system, before setting the GIF file to the data provider. -CICLAnimationDataProvider* basicDataProvider = new (ELeave)CICLAnimationDataProvider; -basicDataProvider->SetFileL(iEikonEnv->FsSession(), KAnimExGuitarPlayer());

                Now that the data provider object is ready with the required data, you can create an object of CBasicAnimation class. The control and behaviour for the animation is defined using the TAnimationConfig class. You should create such an object and provide it to the animation. The behaviour of the animation can be set to any of the following:

                • Play in a loop: Set the iFlags variable of the TAnimationConfig class to ELoop, and set the number of cycles the animation should complete using the iData variable. If you want the animation to be played for an indefinite number of cycles, set iData to -1.

                • Play immediately: Set the iFlags variable of the TAnimationConfig class to EStartImmediately. By default, the animations will wait till the data is loaded completely.

                • Play only specified number of frames: Set the iFlags variable of the TAnimationConfig class to ECountFrames, and set the number of frames the animation should play using the iData variable.

                • Stop the animation at the last frame: Set the iFlags variable of the TAnimationConfig class to EEndOnLastFrame. By default, when animations stop they return to the first frame.

                In this case, the animation is configured to play in an infinite loop.

                The following code shows how to create and start a basic client-side animation. It loads an animated GIF file and plays it in an infinite loop :

                //Integer constant defining the X and Y co-ordinates of the animation -const TInt KAnimExBasicPositionX = 300; -const TInt KAnimExBasicPositionY = 100; -TPoint position = TPoint(KAnimExBasicPositionX, KAnimExBasicPositionY); - -//configure the animation to play in an infinite loop -TAnimationConfig config; -config.iFlags = TAnimationConfig::ELoop; -config.iData = -1; - -//Creating the basic animation object using the data provider object and the X and Y coordinates defined above -iBasicAnim = CBasicAnimation::NewL(basicDataProvider,position, iEikonEnv->WsSession(), Window()); - -//Starting the animation using the configuration created above -iBasicAnim->Start(config);

                The animation will be visible only when it is rendered to the window. To do so, implement a private virtual member function of CCoeControl class called Draw() in your client application view class. This function should in-turn call the CBasicAnimation::Draw function by passing the windows graphics context as an argument.

                The following code shows how to draw the animation to the window:

                void CClientAppView::Draw(const TRect&) const -{ - - CWindowGc& gc = SystemGc(); - if( iBasicAnim ) - { - iBasicAnim->Draw( gc ); - } -}

                Note that you should include proper error checks in the given code before using it for production.

                When a new frame is required for the animation, the entire window or an area within in the window need to be redrawn using the RWindow::Invalidate() function. This function will force a client redraw.

                This code creates a client-side animation which loads an animated GIF file and plays it in an infinite loop.

                Animation - overview                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A97AD7EB-43C2-545A-9756-57D65A4905D9-GENID-1-8-1-6-1-1-4-1-3-1-4-1.dita --- a/Symbian3/SDK/Source/GUID-A97AD7EB-43C2-545A-9756-57D65A4905D9-GENID-1-8-1-6-1-1-4-1-3-1-4-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,41 +0,0 @@ - - - - - -How to create a basic animation

                The animation framework provides a concrete implementation of the CAnimation class called CBasicAnimation class to create a basic client-side animation. A basic client-side animation needs data, which can range from a simple file to a complex data structure. The data provider is responsible for handling this data and cater to the needs of the animation whenever required. The CICLAnimationDataProvider class acts as a data provider and handles the data needed for any type of animation.

                To create a basic client-side animation, create an object of the CICLAnimationDataProvider class. Associate the data required for the animation with the data provider object. In the example used below, the data needed for the animation is a simple animated GIF file.

                The following code shows how to create a data provider object and associate a GIF file with it:

                //Path to the GIF file -_LIT(KAnimExGuitarPlayer,"Z:\\resource\\apps\\AnimExample\\GuitarPlayer.gif"); - -//Creating the data provider object and setting the GIF file using the string literal created above. -//The iEikonEnv macro is used to open a session with the file system, before setting the GIF file to the data provider. -CICLAnimationDataProvider* basicDataProvider = new (ELeave)CICLAnimationDataProvider; -basicDataProvider->SetFileL(iEikonEnv->FsSession(), KAnimExGuitarPlayer());

                Now that the data provider object is ready with the required data, you can create an object of CBasicAnimation class. The control and behaviour for the animation is defined using the TAnimationConfig class. You should create such an object and provide it to the animation. The behaviour of the animation can be set to any of the following:

                • Play in a loop: Set the iFlags variable of the TAnimationConfig class to ELoop, and set the number of cycles the animation should complete using the iData variable. If you want the animation to be played for an indefinite number of cycles, set iData to -1.

                • Play immediately: Set the iFlags variable of the TAnimationConfig class to EStartImmediately. By default, the animations will wait till the data is loaded completely.

                • Play only specified number of frames: Set the iFlags variable of the TAnimationConfig class to ECountFrames, and set the number of frames the animation should play using the iData variable.

                • Stop the animation at the last frame: Set the iFlags variable of the TAnimationConfig class to EEndOnLastFrame. By default, when animations stop they return to the first frame.

                In this case, the animation is configured to play in an infinite loop.

                The following code shows how to create and start a basic client-side animation. It loads an animated GIF file and plays it in an infinite loop :

                //Integer constant defining the X and Y co-ordinates of the animation -const TInt KAnimExBasicPositionX = 300; -const TInt KAnimExBasicPositionY = 100; -TPoint position = TPoint(KAnimExBasicPositionX, KAnimExBasicPositionY); - -//configure the animation to play in an infinite loop -TAnimationConfig config; -config.iFlags = TAnimationConfig::ELoop; -config.iData = -1; - -//Creating the basic animation object using the data provider object and the X and Y coordinates defined above -iBasicAnim = CBasicAnimation::NewL(basicDataProvider,position, iEikonEnv->WsSession(), Window()); - -//Starting the animation using the configuration created above -iBasicAnim->Start(config);

                The animation will be visible only when it is rendered to the window. To do so, implement a private virtual member function of CCoeControl class called Draw() in your client application view class. This function should in-turn call the CBasicAnimation::Draw function by passing the windows graphics context as an argument.

                The following code shows how to draw the animation to the window:

                void CClientAppView::Draw(const TRect&) const -{ - - CWindowGc& gc = SystemGc(); - if( iBasicAnim ) - { - iBasicAnim->Draw( gc ); - } -}

                Note that you should include proper error checks in the given code before using it for production.

                When a new frame is required for the animation, the entire window or an area within in the window need to be redrawn using the RWindow::Invalidate() function. This function will force a client redraw.

                This code creates a client-side animation which loads an animated GIF file and plays it in an infinite loop.

                Animation - overview                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A97AD7EB-43C2-545A-9756-57D65A4905D9.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-A97AD7EB-43C2-545A-9756-57D65A4905D9.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,41 @@ + + + + + +How to create a basic animation

                The animation framework provides a concrete implementation of the CAnimation class called CBasicAnimation class to create a basic client-side animation. A basic client-side animation needs data, which can range from a simple file to a complex data structure. The data provider is responsible for handling this data and cater to the needs of the animation whenever required. The CICLAnimationDataProvider class acts as a data provider and handles the data needed for any type of animation.

                To create a basic client-side animation, create an object of the CICLAnimationDataProvider class. Associate the data required for the animation with the data provider object. In the example used below, the data needed for the animation is a simple animated GIF file.

                The following code shows how to create a data provider object and associate a GIF file with it:

                //Path to the GIF file +_LIT(KAnimExGuitarPlayer,"Z:\\resource\\apps\\AnimExample\\GuitarPlayer.gif"); + +//Creating the data provider object and setting the GIF file using the string literal created above. +//The iEikonEnv macro is used to open a session with the file system, before setting the GIF file to the data provider. +CICLAnimationDataProvider* basicDataProvider = new (ELeave)CICLAnimationDataProvider; +basicDataProvider->SetFileL(iEikonEnv->FsSession(), KAnimExGuitarPlayer());

                Now that the data provider object is ready with the required data, you can create an object of CBasicAnimation class. The control and behaviour for the animation is defined using the TAnimationConfig class. You should create such an object and provide it to the animation. The behaviour of the animation can be set to any of the following:

                • Play in a loop: Set the iFlags variable of the TAnimationConfig class to ELoop, and set the number of cycles the animation should complete using the iData variable. If you want the animation to be played for an indefinite number of cycles, set iData to -1.

                • Play immediately: Set the iFlags variable of the TAnimationConfig class to EStartImmediately. By default, the animations will wait till the data is loaded completely.

                • Play only specified number of frames: Set the iFlags variable of the TAnimationConfig class to ECountFrames, and set the number of frames the animation should play using the iData variable.

                • Stop the animation at the last frame: Set the iFlags variable of the TAnimationConfig class to EEndOnLastFrame. By default, when animations stop they return to the first frame.

                In this case, the animation is configured to play in an infinite loop.

                The following code shows how to create and start a basic client-side animation. It loads an animated GIF file and plays it in an infinite loop :

                //Integer constant defining the X and Y co-ordinates of the animation +const TInt KAnimExBasicPositionX = 300; +const TInt KAnimExBasicPositionY = 100; +TPoint position = TPoint(KAnimExBasicPositionX, KAnimExBasicPositionY); + +//configure the animation to play in an infinite loop +TAnimationConfig config; +config.iFlags = TAnimationConfig::ELoop; +config.iData = -1; + +//Creating the basic animation object using the data provider object and the X and Y coordinates defined above +iBasicAnim = CBasicAnimation::NewL(basicDataProvider,position, iEikonEnv->WsSession(), Window()); + +//Starting the animation using the configuration created above +iBasicAnim->Start(config);

                The animation will be visible only when it is rendered to the window. To do so, implement a private virtual member function of CCoeControl class called Draw() in your client application view class. This function should in-turn call the CBasicAnimation::Draw function by passing the windows graphics context as an argument.

                The following code shows how to draw the animation to the window:

                void CClientAppView::Draw(const TRect&) const +{ + + CWindowGc& gc = SystemGc(); + if( iBasicAnim ) + { + iBasicAnim->Draw( gc ); + } +}

                Note that you should include proper error checks in the given code before using it for production.

                When a new frame is required for the animation, the entire window or an area within in the window need to be redrawn using the RWindow::Invalidate() function. This function will force a client redraw.

                This code creates a client-side animation which loads an animated GIF file and plays it in an infinite loop.

                Animation + overview                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A9BFB95C-E2B0-5CD0-8B39-C448E3C81400_d0e333278_href.png Binary file Symbian3/SDK/Source/GUID-A9BFB95C-E2B0-5CD0-8B39-C448E3C81400_d0e333278_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A9BFB95C-E2B0-5CD0-8B39-C448E3C81400_d0e339435_href.png Binary file Symbian3/SDK/Source/GUID-A9BFB95C-E2B0-5CD0-8B39-C448E3C81400_d0e339435_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A9E610B7-505C-41C4-9079-BC83C094982E_d0e10566_href.png Binary file Symbian3/SDK/Source/GUID-A9E610B7-505C-41C4-9079-BC83C094982E_d0e10566_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-A9E610B7-505C-41C4-9079-BC83C094982E_d0e11841_href.png Binary file Symbian3/SDK/Source/GUID-A9E610B7-505C-41C4-9079-BC83C094982E_d0e11841_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-AA820231-5C46-46A1-A310-ABBA45593B1F_d0e143085_href.png Binary file Symbian3/SDK/Source/GUID-AA820231-5C46-46A1-A310-ABBA45593B1F_d0e143085_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-AA820231-5C46-46A1-A310-ABBA45593B1F_d0e149619_href.png Binary file Symbian3/SDK/Source/GUID-AA820231-5C46-46A1-A310-ABBA45593B1F_d0e149619_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-AB35BA46-87DB-59F0-9342-75550AD338B7_d0e184946_href.png Binary file Symbian3/SDK/Source/GUID-AB35BA46-87DB-59F0-9342-75550AD338B7_d0e184946_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-AB35BA46-87DB-59F0-9342-75550AD338B7_d0e191542_href.png Binary file Symbian3/SDK/Source/GUID-AB35BA46-87DB-59F0-9342-75550AD338B7_d0e191542_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-AB69D251-7635-4325-BBCE-92F7AFC86DC2.dita --- a/Symbian3/SDK/Source/GUID-AB69D251-7635-4325-BBCE-92F7AFC86DC2.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-AB69D251-7635-4325-BBCE-92F7AFC86DC2.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,198 +1,157 @@ - - - - - -New -C++ APIs in Symbian^3The following new C++ APIs are introduced in Symbian^3. - - - -API -Description - - - - - - -

                Beagle Variant Header APIs

                 -

                Provides variant layer headers for the Beagle platform. For more -information, see Beagle.

                 -                 - - - - - - - - - - -

                E-mail Widget API

                 -

                ECom plugin API that Third-party e-mail solutions implement to publish -e-mail data to Home Screen widget.

                -                 - -

                exFAT File System APIs

                 -

                Provides the "exFAT" file system. For more information, see TVolFormatParam_exFAT.

                -                 - -

                Extended Content Publisher API

                 -

                Provides interfaces for Home Screen content publisher plug-ins.

                 -                 - -

                EUser High Level (EUserHL) Library APIs

                 -

                Provides APIs to improve string handling, object creation and resource -management. For more information, see EUser -High Level Library.

                 -                 - - - - -

                Gstreamer Library APIs

                 -

                Provides a development framework (Open source Multimedia Framework) for creating applications -like media player, streaming media broadcasters and video editors. For more -information, see Gstreamer -Overview.

                 -                 - -

                Haptics APIs

                 -

                Provides methods for controlling the haptics feature of the Symbian -device. Both synchronous and asynchronous versions are provided for playing -various types of effects. Only synchronous methods are provided for other -functionalities, such as opening and closing an actuator, reserving and releasing -the haptics feature, and for getting various state and system information -from the haptics. For more information, see CHWRMHaptics.

                 -                 - -

                Home Screen Widget Publisher API

                 -

                Provides support for publishing logo and description of a widget.

                 -                 - - -

                Libxm2 Library APIs

                 -

                Provides APIs for XML processing, parsing and validation. For more -information, see Libxml2 -Overview.

                 -                 - -

                Location Centre Utility APIs

                 -

                Provides the application, service and file launching services to -Location Centre. For more information, see CLcAppLauncher.

                 -                 - - - - - -

                NFC Discovery API

                 -

                Used for subscribing and discovering Tags and NDEF -messages.

                 -                 - -

                NFC Tag Extension API

                 -

                Provides implementation and access (read/write) -methods for different types of NFC targets.

                 -                 - -

                NDEF API

                 -

                Used for handling NDEF messages and accessing NDEF -messages on Tags.

                -                 - -

                NFC Peer-to-Peer API

                 -

                Provides LLCP (Logical Link Control Protocol) API -for peer to peer communication between NFC devices.

                 -                 - -

                NFC Content Handler API

                 -

                ECOM plug-in interface for subscribing and receiving -NDEF messages.

                 -                 - - - - -

                OpenWF Composition APIs

                 -

                Supports the open standard for layered graphics composition developed -by the Khronos Group. -For more information, see OpenWF -Composition Interface Overview.

                 -                 - -

                OpenWF Support APIs

                 -

                Provides a Symbian-specific implementation of platform-specific -elements of the OpenWF-C specification and abstracts communication between -the OpenWF-C Engine and other Symbian graphics components. For more information, -see OpenWF Support -Component Overview.

                 -                 - -

                Puny Code Converter APIs

                 -

                Provides support for converting the Unicode formatted domain names -to ASCII format that can be resolved by the external DNS server. For more -information, see TPunyCodeDndName.

                 -                 - - -

                SQLite 3 APIs

                 -

                Provides an implementation of the native SQLite C APIs. For more -information, see SQLite -3.

                 -                 - - -

                Standard C++ Library (STLport v5) APIs

                 -

                Provides a Standard C++ environment with IOStream and STL (Standard -Template Library) libraries that enable you to develop or port Standard C++ -applications or libraries quickly and easily onto the Symbian platform. For -more information, see Standard -C++ Library (STLport v5).

                 -                 - - - - - -

                System State Manager Mapper Utility APIs

                 -

                Provides a utility class for mapping UIDs, getting feature and system -states and cenrep values. For more information, see CSsmMapperUtility.

                 -                 - - - - - - -

                User Prompt Service APIs

                 -

                Allows device creators to choose whether security decisions (for -example, allowing an application to make a network connection) are processed -silently or require the user to be prompted. For more information, see User Prompt Service.

                 -                 - - -

                XML DOM Engine and XPath APIs

                 -

                Implements the standard DOM API (tree-based XML parsing and editing), -including XPath and serialization extensions. For more information, see XML DOM Engine.

                 -                 - - -
                 - -Introduction -to Symbian^3 -What's new -in Symbian^3 -Porting applications -to Symbian^3 - + + + + + +New C++ APIs in Symbian^3The following new C++ APIs are introduced in Symbian^3. + + + +API +Description + + + + + + +

                Beagle Variant Header APIs

                 +

                Provides variant layer headers for the Beagle platform. +For more information on Beagle plaform, see http://beagleboard.org/.

                 +                 + + + + + + + + + + +

                E-mail Widget API

                 +

                ECom plugin API that Third-party e-mail solutions implement +to publish e-mail data to Home Screen widget.

                +                 + +

                exFAT File System APIs

                 +

                Provides the "exFAT" file system. For more information, +see FileSystem_EXFAT::TVolFormatParam_exFAT.

                +                 + +

                Extended Content Publisher API

                 +

                Provides interfaces for Home Screen content publisher plug-ins.

                 +                 + +

                EUser High Level (EUserHL) Library APIs

                 +

                Provides APIs to improve string handling, object creation +and resource management. For more information, see EUser High Level +Library.

                 +                 + + + + +

                Haptics APIs

                 +

                Provides methods for controlling the haptics feature of +the Symbian device. Both synchronous and asynchronous versions are +provided for playing various types of effects. Only synchronous methods +are provided for other functionalities, such as opening and closing +an actuator, reserving and releasing the haptics feature, and for +getting various state and system information from the haptics. For +more information, see CHWRMHaptics.

                 +                 + +

                Home Screen Widget Publisher API

                 +

                Provides support for publishing logo and description of +a widget.

                 +                 + + +

                Libxm2 Library APIs

                 +

                Provides APIs for XML processing, parsing and validation. +For more information, see Libxml2 Overview.

                 +                 + + + + + + + +

                OpenWF Composition APIs

                 +

                Supports the open standard for layered graphics composition +developed by the Khronos Group. For more information, see OpenWF Composition +Interface Overview.

                 +                 + +

                OpenWF Support APIs

                 +

                Provides a Symbian-specific implementation of platform-specific +elements of the OpenWF-C specification and abstracts communication +between the OpenWF-C Engine and other Symbian graphics components. +For more information, see OpenWF Support Component +Overview.

                 +                 + +

                Puny Code Converter APIs

                 +

                Provides support for converting the Unicode formatted domain +names to ASCII format that can be resolved by the external DNS server. +For more information, see TPunyCodeDndName.

                 +                 + + +

                SQLite 3 APIs

                 +

                Provides an implementation of the native SQLite C APIs. +For more information, see SQLite 3.

                 +                 + +

                Standard C++ Library (STLport v5) APIs

                 +

                Provides a Standard C++ environment with IOStream and STL +(Standard Template Library) libraries that enable you to develop or +port Standard C++ applications or libraries quickly and easily onto +the Symbian platform. For more information, see Standard C++ Library +(STLport v5).

                STLport v4 is also supported +on Symbian^3. For more information STLport v4, see C++ Standard Library +(STLport v4).                 +                 + + + + + + + + + + +

                User Prompt Service APIs

                 +

                Allows device creators to choose whether security decisions +(for example, allowing an application to make a network connection) +are processed silently or require the user to be prompted. For more +information, see User Prompt Service.

                 +                 + + +

                XML DOM Engine and XPath APIs

                 +

                Implements the standard DOM API (tree-based XML parsing +and editing), including XPath and serialization extensions. For more +information, see XML DOM Engine.

                 +                 + + +
                 + +Introduction +to Symbian^3 +What's +new in Symbian^3 +Porting +applications to Symbian^3 +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-AB9A3EA2-2B99-4502-A161-8EE5BF477D41.dita --- a/Symbian3/SDK/Source/GUID-AB9A3EA2-2B99-4502-A161-8EE5BF477D41.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-AB9A3EA2-2B99-4502-A161-8EE5BF477D41.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,87 +1,98 @@ - - - - - -Capturing -a video clip -

                To record video data to a file, descriptor, or an URL, use the video -recorder utility of the Multimedia Framework (MMF) to develop your application. -To make use of the onboard camera to capture a video clip, the application -needs to repeat the steps described in the illustration below.

                -The steps required to capture a video clip -

                Important implementation considerations include:

                -
                  -

                • To open a file for recording the CVideoRecorderUtility class requires the MMF Controller Framework API to specify controller and -format UIDs.

                  • -

                • If you need to use the display of the device as a viewfinder -for your video application, request viewfinder frames using the CCamera class, and draw them yourself. For more information, see step -3 in .

                  -
                  • -

                • The settings you can use in your application depend on what -the camera hardware on the device supports.

                  • -
                -
                To capture a -video clip -

                Use the methods of the CVideoRecorderUtility class to construct your application.

                -
                  -

                1. Initialize -the video recorder.

                  -
                    -

                  • Create a video recorder object using the CVideoRecorderUtility::NewL method.

                    -
                    • -

                  • Resolve the supported video format and retrieve a list of -controllers using the CMMFControllerPluginSelectionParameters and CMMFFormatSelectionParameters classes, and the respective type definitions RMMFControllerImplInfoArray and RMMFFormatImplInfoArray.

                    • -

                  • Open a file, descriptor or an URL to store the video clip -in using the respective CVideoRecorderUtility::OpenFileL, CVideoRecorderUtility::OpenDesL, or CVideoRecorderUtility::OpenUrlL method.

                    -
                    • -

                  • Set the maximum video clip size using the CVideoRecorderUtility::SetMaxClipSizeL() method.

                    -
                    • -

                  • Prepare the record controller using the CVideoRecorderUtility::Prepare() method. MVideoRecorderUtilityObserver::MvruoPrepareComplete is -called upon completion.

                    • -
                  -
                  2. -

                2. Configure -the audio and video settings.

                  You can check and set, for example, -the recording priority, audio track, video frame size and frame rate, audio -and video codecs and bit rates, and recording gain of the video clip. For -more information on the options, see the CVideoRecorderUtility class.

                  3. -

                3. Capture the -video clip.

                  -
                    -

                  • Start recording a video using the CVideoRecorderUtility::Record() method.

                    • -

                  • Pause recording using the CVideoRecorderUtility::PauseL() method.

                    • -

                  • Stop recording using the CVideoRecorderUtility::Stop() method.

                    • -
                  -
                  4. -

                4. To exit the -application or to switch it to the background, close audio and video controllers -using the CVideoRecorderUtility::Close() method.

                  -
                  5. -

                5. Include VideoRecorder.h and mmfcontrollerpluginresolver.h header files in the appropriate class files.

                  6. -

                6. Make sure -you have correct capabilities information -set for your application. You need at least the UserEnvironment capability. -If you want to set the recording priority for the video and audio device, -you need the MultimediaDD capability.

                  7. -

                7. Make sure mediaclientvideo.lib and mmfcontrollerframework.lib are accessible to your linker when compiling your application by including -it in your mmp file or by editing the project properties -in your IDE, depending on your build environment.

                  8. -
                -
                -
                Additional information -on capturing a video -

                For a reference example, see the Camera -Example: Capturing and controlling the images using Camera.

                -

                For more information on CVideoRecorderUtility, see Multimedia -recipes at the Symbian Foundation.

                -

                For more information on CVideoRecorderUtility see the Recording Video Data tutorial -in the Video Client library.

                -
                + + + + + +Capturing +a Video Clip +

                To record video data to a file, descriptor, or an URL, use the video +recorder utility of the Multimedia Framework (MMF) to develop your application. +To make use of the onboard camera to capture a video clip, the application +needs to repeat the steps described in the illustration below.

                +The steps required to capture a video clip +

                Important implementation considerations include:

                +
                  +

                • Make sure you include the VideoRecorder.h and mmfcontrollerpluginresolver.h header +files in the appropriate class files.

                  • +

                • Make sure you have correct capabilities information +set for your application. You need at least the UserEnvironment capability. +If you want to set the recording priority for the video and audio device, +you need the MultimediaDD capability.

                  • +

                • Make sure mediaclientvideo.lib and mmfcontrollerframework.lib are +accessible to your linker when compiling your application by including it +in your mmp file or by editing the project properties in +your IDE, depending on your build environment.

                  • +

                • To open a file for recording the CVideoRecorderUtility class +requires the MMF Controller Framework API to specify controller and format +UIDs.

                  • +

                • If you need to use the display of the device as a viewfinder +for your video application, request viewfinder frames using the CCamera class, +and draw them yourself. For more information, see step 3 in To capture still images on a mobile device .

                  • +

                • The settings you can use in your application depend on what +the camera hardware on the device supports.

                  • +
                +
                To capture a +video clip +

                Use the methods of the CVideoRecorderUtility class +to construct your application.

                +
                  +

                1. Initialize +the video recorder.

                  +
                    +

                  • Create a video recorder object using the CVideoRecorderUtility::NewL method.

                    +
                    • +

                  • Resolve the supported video format and retrieve a list of +controllers using the CMMFControllerPluginSelectionParameters and CMMFFormatSelectionParameters classes, +and the respective type definitions RMMFControllerImplInfoArray and RMMFFormatImplInfoArray.

                    +
                    • +

                  • Open a file, descriptor or an URL to store the video clip +in using the respective CVideoRecorderUtility::OpenFileL, CVideoRecorderUtility::OpenDesL, +or CVideoRecorderUtility::OpenUrlL method.

                    • +

                  • Set the maximum video clip size using the CVideoRecorderUtility::SetMaxClipSizeL() method.

                    +
                    • +

                  • Prepare the record controller using the CVideoRecorderUtility::Prepare() method. MVideoRecorderUtilityObserver::MvruoPrepareComplete is called upon completion.

                    • +
                  +
                  2. +

                2. Configure +the audio and video settings.

                  You can check and set, for example, +the recording priority, audio track, video frame size and frame rate, audio +and video codecs and bit rates, and recording gain of the video clip. For +more information on the options, see the CVideoRecorderUtility class.

                  +
                  3. +

                3. Capture the +video clip.

                  +
                    +

                  • Start recording a video using the CVideoRecorderUtility::Record() method.

                    +
                    • +

                  • Pause recording using the CVideoRecorderUtility::PauseL() method.

                    +
                    • +

                  • Stop recording using the CVideoRecorderUtility::Stop() method.

                    +
                    • +
                  +
                  4. +

                4. To exit the +application or to switch it to the background, close audio and video controllers +using the CVideoRecorderUtility::Close() method.

                  5. +
                +
                +
                Additional information +on capturing a video +

                For a reference example, see the Camera +Example: Capturing and controlling the images using Camera.

                +

                For more information on CVideoRecorderUtility, see:

                +
                  +

                • Video +Client Overview

                  • +

                • Multimedia +recipes at the Symbian Foundation

                  • +
                +

                For information on using encoded H264 video frames, see Using +the Encoded H264 Video Frames to Capture Video.

                +
                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-AB9D7D52-BCF0-5E89-8A99-A6590FAD7AF6.dita --- a/Symbian3/SDK/Source/GUID-AB9D7D52-BCF0-5E89-8A99-A6590FAD7AF6.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-AB9D7D52-BCF0-5E89-8A99-A6590FAD7AF6.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,38 +1,37 @@ - - - - - -Recognizer: -Data Recognizer exampleShows how to implement a data recogniser. -
                Purpose

                This -example shows how to implement a data recogniser. For more information about -this example, see the Data -Recogniser tutorial.

                -
                Download

                Click -on the following link to download the example: ExampleRecognizer.zip

                Click: browse to view the example code.

                -
                Class Summary

                CApaDataRecognizerType

                RApaLsSession

                -
                Building and -configuring

                To build the example:

                  -

                • You can build the example -from your IDE or the command line.

                  If you use an IDE, import the bld.inf file -of the example into your IDE, and use the build command of the IDE.

                  If -you use the command line, open a command prompt, and set the current directory -to the source code directory of the example. You can then build the example -with the SBSv1 build tools with the following commands:

                  bldmake -bldfiles

                  abld build

                  How to use bldmake and How to use abld describe -how to use the SBSv1 build tools.

                  • -

                • For the emulator, the -example builds an dll called examplerecognizer.dll in -the epoc32\release\winscw\<udeb or urel>\ folder.

                  • -
                -                 -Data Recognizer -Tutorial + + + + + +Recognizer: Data Recognizer exampleShows how to implement a data recogniser. +
                Purpose

                This example shows how to implement a data recogniser. For more +information about this example, see the Data Recogniser tutorial.

                +
                Download

                Click on the following link to download the example: ExampleRecognizer.zip

                Click: browse to view the example code.

                +
                Class Summary
                  +

                • CApaDataRecognizerType

                  • +

                • RApaLsSession

                  • +
                +
                Building +and configuring

                To build the example:

                  +

                • You can build +the example from your IDE or the command line.

                  If you use +an IDE, import the bld.inf file of the example +into your IDE, and use the build command of the IDE.

                  If you +use the command line, open a command prompt, and set the current directory +to the source code directory of the example. You can then build the +example with the SBSv1 build tools with the following commands:

                  bldmake bldfiles

                  abld +build

                  How to use bldmake and How to +use abld describe how to use the SBSv1 build tools.

                  • +

                • For the emulator, +the example builds an dll called examplerecognizer.dll in the epoc32\release\winscw\<udeb or urel>\ folder.

                  • +
                +                 +Data +Recognizer Tutorial                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-ABC01315-D65D-55EA-9D42-4DE6384D517D.dita --- a/Symbian3/SDK/Source/GUID-ABC01315-D65D-55EA-9D42-4DE6384D517D.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-ABC01315-D65D-55EA-9D42-4DE6384D517D.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,14 +1,14 @@ - - - - - -Position data and info classesThis document describes the basic and extended classes that hold position data.

                The Location Acquisition API defines a set of position data classes. Some of these classes store the co-ordinates of a location fix and others store information about course and positioning satellites. The API also defines position info classes that wrap the position data classes. These classes are used to pass data across the Location Acquisition API. Figure 1 illustrates the position data and position info classes with some of the most important methods.

                - Figure 1 Position data and info classes -
                The position data classes

                • TCoordinate is the base class for all the position data classes. It holds latitude, longitude and altitude data. All positioning modules must provide latitude and longitude information, but not all modules are guaranteed to provide altitude information.

                • TLocality adds accuracy information to co-ordinates.

                • TPosition adds the time at which the location fix was obtained and also allows the average speed between two positions to be calculated.

                There are two additional position data classes that are not part of this position data class inheritance hierarchy.

                • TCourse holds bearing and current speed data.

                • TSatelliteData holds information on one of the satellites used to obtain the location fix.

                Note that it is a position info object and not a position data object that is passed across the Location Acquisition API. Client applications extract the position data object from the wrapper position info object.

                See Position data for a description of how the location data is represented inside the position data classes.

                The position info classes

                Client applications use three position info classes that wrap the position data classes:

                • TPositionInfo wraps a TPosition class

                • TPositionCourseInfo wraps a TCourse class

                • TPositionSatelliteInfo wraps a TSatelliteData class

                To get location information, a reference to an object of a class derived from TPositionInfoBase is passed in a call to RPositioner::NotifyPositionUpdate() or RPositioner::GetLastKnownPosition(). The position info class hierarchy allows simple location information (TPositionInfo), course information (TCourse Info) or satellite information (TSatelliteInfo) to be obtained via the same calls to the Location Acquisition API.

                HPositionGenericInfo

                HPositionGenericInfo is an extended position info class that allocates memory on the heap. Applications can use the class to retrieve additional position information from positioning hardware that can provide it (such as NMEA strings provided by Bluetooth GPS hardware).

                HPositionGenericInfo is only supported by the Location Server eposserver.exe. It can only be used by applications that link with lbs.lib. Not all PSYs support this class.

                See also

                Position data

                \ No newline at end of file + + + + + +Position data and info classesThis document describes the basic and extended classes that hold position data.

                The Location Acquisition API defines a set of position data classes. Some of these classes store the co-ordinates of a location fix and others store information about course and positioning satellites. The API also defines position info classes that wrap the position data classes. These classes are used to pass data across the Location Acquisition API. Figure 1 illustrates the position data and position info classes with some of the most important methods.

                + Figure 1 Position data and info classes +
                The position data classes

                • TCoordinate is the base class for all the position data classes. It holds latitude, longitude and altitude data. All positioning modules must provide latitude and longitude information, but not all modules are guaranteed to provide altitude information.

                • TLocality adds accuracy information to co-ordinates.

                • TPosition adds the time at which the location fix was obtained and also allows the average speed between two positions to be calculated.

                There are two additional position data classes that are not part of this position data class inheritance hierarchy.

                • TCourse holds bearing and current speed data.

                • TSatelliteData holds information on one of the satellites used to obtain the location fix.

                Note that it is a position info object and not a position data object that is passed across the Location Acquisition API. Client applications extract the position data object from the wrapper position info object.

                See Position data for a description of how the location data is represented inside the position data classes.

                The position info classes

                Client applications use three position info classes that wrap the position data classes:

                • TPositionInfo wraps a TPosition class

                • TPositionCourseInfo wraps a TCourse class

                • TPositionSatelliteInfo wraps a TSatelliteData class

                To get location information, a reference to an object of a class derived from TPositionInfoBase is passed in a call to RPositioner::NotifyPositionUpdate() or RPositioner::GetLastKnownPosition(). The position info class hierarchy allows simple location information (TPositionInfo), course information (TCourse Info) or satellite information (TSatelliteInfo) to be obtained via the same calls to the Location Acquisition API.

                HPositionGenericInfo

                HPositionGenericInfo is an extended position info class that allocates memory on the heap. Applications can use the class to retrieve additional position information from positioning hardware that can provide it (such as NMEA strings provided by Bluetooth GPS hardware).

                HPositionGenericInfo is only supported by the Location Server eposserver.exe. It can only be used by applications that link with lbs.lib. Not all PSYs support this class.

                See also

                Position data

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-ABD741AE-7F66-564C-895C-6E4682308CEA.dita --- a/Symbian3/SDK/Source/GUID-ABD741AE-7F66-564C-895C-6E4682308CEA.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,12 +0,0 @@ - - - - - -Example Code

                The list of example applications that demonstrates the use of the Imaging Frameworks is shown below:

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-ABE77283-EED8-5A33-B574-3B771EF11086.dita --- a/Symbian3/SDK/Source/GUID-ABE77283-EED8-5A33-B574-3B771EF11086.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-ABE77283-EED8-5A33-B574-3B771EF11086.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,156 +1,156 @@ - - - - - -How -to Use ULogger with Comms -

                This tutorial summarises one approach for enabling, retrieving and post-processing -the ULogger logs -for Comms. ULogger is part of the Unified Trace framework which replaces other -logging mechanisms for Symbian platform including Flogger and -CDU.

                -

                The Unified Trace framework has greater flexibility and speed compared -to Flogger and CDU.

                -
                Introduction

                The Comms logging which has been migrated -to ULogger is as follows:

                  -

                • Comms Framework Node -messages - creation and destruction of Nodes and messages between Nodes.

                  • -

                • Mesh Machine messages

                  • -

                • data to support the -SVG generation

                  • -

                This logging replaces some of what was logged through the "LOG -CFNode * ", "LOG Mesh * " and "LOG ESock -* " tags. In the case of the ESock tag, the logging -which is written to ULogger is also written to CDU.

                This usage description -assumes that the development tools already include ULogger support.

                -
                Procedure - Using ULogger

                Requirements

                - For this tutorial, the code under observation must be run from EShell.

                - The following binaries must include logging:

                  -

                • nodemessages.dll -

                  • -

                • meshmachine.dll -

                  • -

                • commsfw.dll

                  • -

                • serverden.dll

                  • -

                • esocksvr.dll

                  • -

                To enable logging for a binary either use the UDEB version of the - binary or rebuild the binary with the SYMBIAN_TRACE_ENABLED macro -defined.

                -
                Steps
                  -

                1. Start -Eshell - ULogger only supports asynchronous logging, so -from EShell start a second instance of EShell.

                  start eshell

                  - This allows ULogger to be stopped even if the code under - observation does not exit normally.

                  2. -

                2. Set -the ULogger Filters - To allow Comms logging enable the -following filters:

                  - - - -Level -Description - - - - -

                  194

                  -

                  Node Messages

                  -                   - -

                  195

                  -

                  Mesh Machine

                  -                   - -

                  196

                  -

                  SVG Logging - provides extra logging so -that 194 and 195 can be displayed in an SVG file -

                  -                   - - -

                  The following filter is also useful: -

                  - - - -Level -Description - - - - -

                  3

                   -

                  Kernel Thread ID's - Thread and process -creation

                  -                   - - -

                  Set these filters with the following command: -

                  ulogger -efv 194 195 3 196 -
                  3. -

                3. Start -ULogger - The following command starts ULogger with the -filter:

                  - -ulogger -rv
                  4. -

                4. Run -the code under observation - In the first Eshell session, -run the code to be tested or debugged.

                  5. -

                5. Stop -ULogger - To stop ULogger and generate the logs, use the -command:

                  ulogger -qv
                  6. -

                6. Process -the binary logs into text - The log file created by ULogger -is in a binary format and is located in the c:\logs folder -on the device.

                  To use the log file, -the file must be converted to a text format. -

                  The Comms software has a decoder to interpret the -ULogger output for Comms. This decoder is an MS Windows-compatible -application and is located in …\os\commsfw\commsfwtools\. -

                  An example command to run the decoder -is:

                  utracedecoder - -message-def esockmessages.definition.txt ulogger.log > log.txt

                  - The decoder uses a definition file to decipher the binary data -in the log, and the decoder has definition files configured -for the current scope of Comms logging. This example uses -the ESock messages definition file, which is located in - …\os\commsfw\commsfwtools\commstools\utracedecoder\data\esockmessages.definition.txt. -

                  The output in log.txt -contains an interpretation of the original binary logs. -

                  7. -

                7. Generating -the SVG diagram - The exchange of messages between Nodes -can be rendered into a diagram.

                  From …\os\commsfw\commsfwtools\commstools\svg run - parseit.bat specifying the path to the -generated log.txt file:

                  parseit.bat /log M:\path_to_log_file\log.txt -Example SVG output from the Message Sequence Display Tool - -

                  Key to the SVG diagram:

                    -

                  1. - Vertical black lines are tagged with names to represent node - lifetimes. For example: IPCpr -

                    2. -

                  2. - Vertical lines forking from the node lifetime lines are - MeshMachine activity lifetimes.

                    3. -

                  3. - Black horizontal lines are message deliveries.

                    4. -

                  4. - Green horizontal lines are message postings.

                    5. -

                  New message types can be added to the definition -files. See the documentation with the utracedecoder component. -

                  8. -
                -                 -Unified Trace -Solution -How to Use -the ULogger Configuration File + + + + + +How +to Use ULogger with Comms +

                This tutorial summarises one approach for enabling, retrieving and post-processing +the ULogger logs +for Comms. ULogger is part of the Unified Trace framework which replaces other +logging mechanisms for Symbian platform including Flogger and +CDU.

                +

                The Unified Trace framework has greater flexibility and speed compared +to Flogger and CDU.

                +
                Introduction

                The Comms logging which has been migrated +to ULogger is as follows:

                  +

                • Comms Framework Node +messages - creation and destruction of Nodes and messages between Nodes.

                  • +

                • Mesh Machine messages

                  • +

                • data to support the +SVG generation

                  • +

                This logging replaces some of what was logged through the "LOG +CFNode * ", "LOG Mesh * " and "LOG ESock +* " tags. In the case of the ESock tag, the logging +which is written to ULogger is also written to CDU.

                This usage description +assumes that the development tools already include ULogger support.

                +
                Procedure - Using ULogger

                Requirements

                + For this tutorial, the code under observation must be run from EShell.

                + The following binaries must include logging:

                  +

                • nodemessages.dll +

                  • +

                • meshmachine.dll +

                  • +

                • commsfw.dll

                  • +

                • serverden.dll

                  • +

                • esocksvr.dll

                  • +

                To enable logging for a binary either use the UDEB version of the + binary or rebuild the binary with the SYMBIAN_TRACE_ENABLED macro +defined.

                +
                Steps
                  +

                1. Start +Eshell - ULogger only supports asynchronous logging, so +from EShell start a second instance of EShell.

                  start eshell

                  + This allows ULogger to be stopped even if the code under + observation does not exit normally.

                  2. +

                2. Set +the ULogger Filters - To allow Comms logging enable the +following filters:

                  + + + +Level +Description + + + + +

                  194

                  +

                  Node Messages

                  +                   + +

                  195

                  +

                  Mesh Machine

                  +                   + +

                  196

                  +

                  SVG Logging - provides extra logging so +that 194 and 195 can be displayed in an SVG file +

                  +                   + + +

                  The following filter is also useful: +

                  + + + +Level +Description + + + + +

                  3

                   +

                  Kernel Thread ID's - Thread and process +creation

                  +                   + + +

                  Set these filters with the following command: +

                  ulogger -efv 194 195 3 196 +
                  3. +

                3. Start +ULogger - The following command starts ULogger with the +filter:

                  + +ulogger -rv
                  4. +

                4. Run +the code under observation - In the first Eshell session, +run the code to be tested or debugged.

                  5. +

                5. Stop +ULogger - To stop ULogger and generate the logs, use the +command:

                  ulogger -qv
                  6. +

                6. Process +the binary logs into text - The log file created by ULogger +is in a binary format and is located in the c:\logs folder +on the device.

                  To use the log file, +the file must be converted to a text format. +

                  The Comms software has a decoder to interpret the +ULogger output for Comms. This decoder is an MS Windows-compatible +application and is located in …\os\commsfw\commsfwtools\. +

                  An example command to run the decoder +is:

                  utracedecoder - -message-def esockmessages.definition.txt ulogger.log > log.txt

                  + The decoder uses a definition file to decipher the binary data +in the log, and the decoder has definition files configured +for the current scope of Comms logging. This example uses +the ESock messages definition file, which is located in + …\os\commsfw\commsfwtools\commstools\utracedecoder\data\esockmessages.definition.txt. +

                  The output in log.txt +contains an interpretation of the original binary logs. +

                  7. +

                7. Generating +the SVG diagram - The exchange of messages between Nodes +can be rendered into a diagram.

                  From …\os\commsfw\commsfwtools\commstools\svg run + parseit.bat specifying the path to the +generated log.txt file:

                  parseit.bat /log M:\path_to_log_file\log.txt +Example SVG output from the Message Sequence Display Tool + +

                  Key to the SVG diagram:

                    +

                  1. + Vertical black lines are tagged with names to represent node + lifetimes. For example: IPCpr +

                    2. +

                  2. + Vertical lines forking from the node lifetime lines are + MeshMachine activity lifetimes.

                    3. +

                  3. + Black horizontal lines are message deliveries.

                    4. +

                  4. + Green horizontal lines are message postings.

                    5. +

                  New message types can be added to the definition +files. See the documentation with the utracedecoder component. +

                  8. +
                +                 +Unified Trace +Solution +How to Use +the ULogger Configuration File                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-AC3F5010-ECA6-4257-98B5-77FB26B4987F_d0e3955_href.png Binary file Symbian3/SDK/Source/GUID-AC3F5010-ECA6-4257-98B5-77FB26B4987F_d0e3955_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-AC3F5010-ECA6-4257-98B5-77FB26B4987F_d0e5230_href.png Binary file Symbian3/SDK/Source/GUID-AC3F5010-ECA6-4257-98B5-77FB26B4987F_d0e5230_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-AC5ADA77-EBA1-597E-A6B7-80157E9DE2B2_d0e184188_href.png Binary file Symbian3/SDK/Source/GUID-AC5ADA77-EBA1-597E-A6B7-80157E9DE2B2_d0e184188_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-AC5ADA77-EBA1-597E-A6B7-80157E9DE2B2_d0e190784_href.png Binary file Symbian3/SDK/Source/GUID-AC5ADA77-EBA1-597E-A6B7-80157E9DE2B2_d0e190784_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-AC7069ED-8CA5-55FC-9DF6-595C0505C672.dita --- a/Symbian3/SDK/Source/GUID-AC7069ED-8CA5-55FC-9DF6-595C0505C672.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-AC7069ED-8CA5-55FC-9DF6-595C0505C672.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,15 +1,15 @@ - - - - - -Positioning Module StatusThis document describes positioning technology module status, which applications access through the Location Acquisition API.
                Purpose

                This document describes Positioning Module status, which applications access through the Location Acquisition API.

                Positioning Module status

                A Positioning Module has a status which is represented by a TPositionModuleStatus object. The status describes the low-level state of a Positioning Module, such as whether it is disabled, initialising, or ready to retrieve location data, as well as its data quality status.

                A change in Positioning Module status is indicated by a status event. Details of the event are held in a TPositionModuleStatusEvent object. Client applications can receive notification of status events from the location server.

                Figure 1 illustrates Positioning Module status and event classes.

                - Figure 1. TPositionModuleStatus and - TPositionModuleStatusEvent classes -

                TPositionModuleStatus

                TPositionModuleStatus describes the status of a Positioning Module. An application gets information about a Positioning Module's current status by calling RPositionServer::GetModuleStatus(). There are two status types - device status and data quality status.

                Device status

                Device status is the status of the hardware device utilised by a Positioning Module, such as the chipset used by an A-GPS Positioning Module.

                TPositionModuleStatus::DeviceStatus() returns the device status as a TPositionModuleStatus::TDeviceStatus value. The value returned can indicate a transient device status, such as whether the hardware is disabled, initialising, or ready. It can also indicate a more serious device error state.

                Data quality status

                Data quality status describes the accuracy of the location data that a Positioning Module is able to provide at a point in time.

                TPositionModuleStatus::DataQualityStatus() returns the data quality status as a TPositionModuleStatus::TDataQualityStatus value. This value indicates whether the quality of location data is normal (the ideal condition), partially degraded or completely degraded. Location data quality can become degraded because the mobile device has moved out of range of any base stations or is in a position where it cannot receive signals from positioning satellites. Note that loss of information quality does not indicate a device error, which would be flagged by a change in the device status.

                Positioning Module status events

                When a Positioning Module's status changes, a Positioning Module status event occurs.

                There are three types of Positioning Module status events:

                • Device status events

                • Data quality status events

                • System level events. These events indicate that a Positioning Module has been added or removed in the system.

                TPositionModuleStatusEvent

                An object of class TPositionModuleStatusEvent has two functions:

                • As the object on which an application defines the types of Positioning Module status events for which it requests notification. These are set by calling TPositionModuleStatusEvent::SetRequestedEvents() passing a TPositionModuleStatusEventBase::TModuleEvent bitmask value as a parameter to define the combination of events

                • As the object on which the location framework sets the type of events that have occurred. These are retrieved by calling TPositionModuleStatusEvent::OccurredEvents() and checking the returned TPositionModuleStatusEventBase::TModuleEvent value.

                Event notification

                An application calls RPositionServer::NotifyModuleStatusEvent() to receive notification of Positioning Module status changes, passing a reference to a TPositionModuleStatusEvent object on which it has set the requested events. An application also supplies a TRequestStatus object and optionally a TPositionModuleId object if status changes from only one Positioning Module are required.

                When the status of a Positioning Module changes, the client application is notified. The TPositionModuleStatusEvent object that was supplied to the location server now also contains details of the events that have occurred and these are obtained by calling TPositionModuleStatusEvent::OccurredEvents().

                The Positioning Module status is obtained by calling TPositionModuleStatusEvent::GetModuleStatus() providing a TPositionModuleStatus reference as a parameter.

                See How to Get Positioning Module Status Changes for an example.

                Uses of Positioning Module status

                Quality status events are useful for applications that need to modify their behaviour based on the quality of location information that can be received. For example, an application may need to show a message when a user moves into an area where the accuracy of location information is degraded to a lower quality than is required because of distance from a base station or inability to receive satellite signals.

                Device status events and system Positioning Module events are most useful to software components that perform administrative operations, such as taking a Positioning Module online or offline. The events can be used to notify when such an administrative operation is complete.

                Device status events can also be used to keep a user informed as to the status of a particular Positioning Module. For example, a phone status bar could be updated to show that GPS is active when location information is being received.

                See also

                Positioning Modules

                \ No newline at end of file + + + + + +Positioning Module StatusThis document describes positioning technology module status, which applications access through the Location Acquisition API.
                Purpose

                This document describes Positioning Module status, which applications access through the Location Acquisition API.

                Positioning Module status

                A Positioning Module has a status which is represented by a TPositionModuleStatus object. The status describes the low-level state of a Positioning Module, such as whether it is disabled, initialising, or ready to retrieve location data, as well as its data quality status.

                A change in Positioning Module status is indicated by a status event. Details of the event are held in a TPositionModuleStatusEvent object. Client applications can receive notification of status events from the location server.

                Figure 1 illustrates Positioning Module status and event classes.

                + Figure 1. TPositionModuleStatus and + TPositionModuleStatusEvent classes +

                TPositionModuleStatus

                TPositionModuleStatus describes the status of a Positioning Module. An application gets information about a Positioning Module's current status by calling RPositionServer::GetModuleStatus(). There are two status types - device status and data quality status.

                Device status

                Device status is the status of the hardware device utilised by a Positioning Module, such as the chipset used by an A-GPS Positioning Module.

                TPositionModuleStatus::DeviceStatus() returns the device status as a TPositionModuleStatus::TDeviceStatus value. The value returned can indicate a transient device status, such as whether the hardware is disabled, initialising, or ready. It can also indicate a more serious device error state.

                Data quality status

                Data quality status describes the accuracy of the location data that a Positioning Module is able to provide at a point in time.

                TPositionModuleStatus::DataQualityStatus() returns the data quality status as a TPositionModuleStatus::TDataQualityStatus value. This value indicates whether the quality of location data is normal (the ideal condition), partially degraded or completely degraded. Location data quality can become degraded because the mobile device has moved out of range of any base stations or is in a position where it cannot receive signals from positioning satellites. Note that loss of information quality does not indicate a device error, which would be flagged by a change in the device status.

                Positioning Module status events

                When a Positioning Module's status changes, a Positioning Module status event occurs.

                There are three types of Positioning Module status events:

                • Device status events

                • Data quality status events

                • System level events. These events indicate that a Positioning Module has been added or removed in the system.

                TPositionModuleStatusEvent

                An object of class TPositionModuleStatusEvent has two functions:

                • As the object on which an application defines the types of Positioning Module status events for which it requests notification. These are set by calling TPositionModuleStatusEvent::SetRequestedEvents() passing a TPositionModuleStatusEventBase::TModuleEvent bitmask value as a parameter to define the combination of events

                • As the object on which the location framework sets the type of events that have occurred. These are retrieved by calling TPositionModuleStatusEvent::OccurredEvents() and checking the returned TPositionModuleStatusEventBase::TModuleEvent value.

                Event notification

                An application calls RPositionServer::NotifyModuleStatusEvent() to receive notification of Positioning Module status changes, passing a reference to a TPositionModuleStatusEvent object on which it has set the requested events. An application also supplies a TRequestStatus object and optionally a TPositionModuleId object if status changes from only one Positioning Module are required.

                When the status of a Positioning Module changes, the client application is notified. The TPositionModuleStatusEvent object that was supplied to the location server now also contains details of the events that have occurred and these are obtained by calling TPositionModuleStatusEvent::OccurredEvents().

                The Positioning Module status is obtained by calling TPositionModuleStatusEvent::GetModuleStatus() providing a TPositionModuleStatus reference as a parameter.

                See How to Get Positioning Module Status Changes for an example.

                Uses of Positioning Module status

                Quality status events are useful for applications that need to modify their behaviour based on the quality of location information that can be received. For example, an application may need to show a message when a user moves into an area where the accuracy of location information is degraded to a lower quality than is required because of distance from a base station or inability to receive satellite signals.

                Device status events and system Positioning Module events are most useful to software components that perform administrative operations, such as taking a Positioning Module online or offline. The events can be used to notify when such an administrative operation is complete.

                Device status events can also be used to keep a user informed as to the status of a particular Positioning Module. For example, a phone status bar could be updated to show that GPS is active when location information is being received.

                See also

                Positioning Modules

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-AC8439C7-7E57-4829-AB4B-70BC394DD66F.dita --- a/Symbian3/SDK/Source/GUID-AC8439C7-7E57-4829-AB4B-70BC394DD66F.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-AC8439C7-7E57-4829-AB4B-70BC394DD66F.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,105 +1,105 @@ - - - - - -Hiding -item-specific commands in menusThe item-specific commands and item-action commands in options -menu must be flagged with the EEikMenuItemSpecific and EEikMenuItemAction flags -introduced in Symbian^3. This enables the UI framework to hide them in the -options menu and display them only in the stylus pop-up menu. The touch down -and hold action opens the stylus pop-up menu. Touch down and release performs -an action. -

                Actions like opening -a radio button list and virtual input are performed on the first tap. These -actions are normally handled by the UI framework. However, if your application -contains an implementation of its own for handling these actions (for example, -opening a custom component on the second tap) it must be changed to follow -the single-tap style.

                 - -Add the EEikMenuItemAction flag -to all item-action commands in your options menu resource definitions. Menu -item-action commands are functions that are called during touch down and release -on an item (for example, Open action). -

                For example,

                /** - *AppList View menuitems (Counters) - */ -RESOURCE MENU_PANE r_logs_applist_menu -{ - items = - { - MENU_ITEM - { - command = ELogsCmdMenuOpen; - txt = qtn_logs_cmd_open; - //--------------------------------------------------------------- -// Include the following line to the list-item action commands - flags =EEikMenuItemAction; - -//---------------------------------------------------------------- - } - }; -}                 -                 -Add the EEikMenuItemSpecific flag -to all (other than item-action) item-specific commands in options menu resource -definitions. -

                For example,

                RESOURCE MENU_PANE r_common_event_menu_send_events -{ - items = - { - MENU_ITEM /* Send */ - { - command = ELogsCmdMenuSendUi; - txt = qtn_stm_om_send; -//------------------------------------------------------------------------- -//Add the following line to the list item-specific commands - flags = EEikMenuItemSpecific; -//------------------------------------------------------------------------- - - }, - MENU_ITEM /* Clear list */ - { command = ELogsCmdMenuDeleteAll; - txt = qtn_stm_om_delete_all; } - }; -}                 - An application view containing forms need -not flag item-specific commands, as forms are always highlighted. -                 -If your application -code dynamically adds or removes menu items, you must change -the flag value of the menu pane using the CEikMenuPane::SetItemSpecific() function. -

                For example,

                /* Add send message item to menu above position pos */ -TInt pos = 0; - -/* Returns pointer to menu item */ -aMenuPane->ItemAndPos(ELogsCmdMenuSendUi, pos); - -/* Delete marker item from menu */ -aMenuPane->DeleteMenuItem(ELogsCmdMenuSendUi); - -/* No need here yet to tailor subitems in SendUi menu */ -TSendingCapabilities capabilities(0, 0, 0); -LogsAppUi() --> -SendUiL() -->AddSendMenuItemL - ( - *aMenuPane, pos, /* Position in menupane */ ELogsCmdMenuSendUi, /* Command id to be used for "Send" menu item */ - capabilities - ); -aMenuPane->SetItemTextL(ELogsCmdMenuSendUi, iSendUiText->Des()); -//------------------------------------------------------------- -// Include the following line to dynamically change the flag value - -aMenuPane->SetItemSpecific(ELogsCmdMenuSendUi, ETrue); -//-----------------------------------------------------------------                 -                 -                 + + + + + +Hiding +item-specific commands in menusThe item-specific commands and item-action commands in options +menu must be flagged with the EEikMenuItemSpecific and EEikMenuItemAction flags +introduced in Symbian^3. This enables the UI framework to hide them in the +options menu and display them only in the stylus pop-up menu. The touch down +and hold action opens the stylus pop-up menu. Touch down and release performs +an action. +

                Actions like opening +a radio button list and virtual input are performed on the first tap. These +actions are normally handled by the UI framework. However, if your application +contains an implementation of its own for handling these actions (for example, +opening a custom component on the second tap) it must be changed to follow +the single-tap style.

                 + +Add the EEikMenuItemAction flag +to all item-action commands in your options menu resource definitions. Menu +item-action commands are functions that are called during touch down and release +on an item (for example, Open action). +

                For example,

                /** + *AppList View menuitems (Counters) + */ +RESOURCE MENU_PANE r_logs_applist_menu +{ + items = + { + MENU_ITEM + { + command = ELogsCmdMenuOpen; + txt = qtn_logs_cmd_open; + //--------------------------------------------------------------- +// Include the following line to the list-item action commands + flags =EEikMenuItemAction; + +//---------------------------------------------------------------- + } + }; +}                 +                 +Add the EEikMenuItemSpecific flag +to all (other than item-action) item-specific commands in options menu resource +definitions. +

                For example,

                RESOURCE MENU_PANE r_common_event_menu_send_events +{ + items = + { + MENU_ITEM /* Send */ + { + command = ELogsCmdMenuSendUi; + txt = qtn_stm_om_send; +//------------------------------------------------------------------------- +//Add the following line to the list item-specific commands + flags = EEikMenuItemSpecific; +//------------------------------------------------------------------------- + + }, + MENU_ITEM /* Clear list */ + { command = ELogsCmdMenuDeleteAll; + txt = qtn_stm_om_delete_all; } + }; +}                 + An application view containing forms need +not flag item-specific commands, as forms are always highlighted. +                 +If your application +code dynamically adds or removes menu items, you must change +the flag value of the menu pane using the CEikMenuPane::SetItemSpecific() function. +

                For example,

                /* Add send message item to menu above position pos */ +TInt pos = 0; + +/* Returns pointer to menu item */ +aMenuPane->ItemAndPos(ELogsCmdMenuSendUi, pos); + +/* Delete marker item from menu */ +aMenuPane->DeleteMenuItem(ELogsCmdMenuSendUi); + +/* No need here yet to tailor subitems in SendUi menu */ +TSendingCapabilities capabilities(0, 0, 0); +LogsAppUi() +-> +SendUiL() +->AddSendMenuItemL + ( + *aMenuPane, pos, /* Position in menupane */ ELogsCmdMenuSendUi, /* Command id to be used for "Send" menu item */ + capabilities + ); +aMenuPane->SetItemTextL(ELogsCmdMenuSendUi, iSendUiText->Des()); +//------------------------------------------------------------- +// Include the following line to dynamically change the flag value + +aMenuPane->SetItemSpecific(ELogsCmdMenuSendUi, ETrue); +//-----------------------------------------------------------------                 +                 +                                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-ACA2AFE8-4872-42FA-A871-34EB80197495_d0e148518_href.png Binary file Symbian3/SDK/Source/GUID-ACA2AFE8-4872-42FA-A871-34EB80197495_d0e148518_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-ACA2AFE8-4872-42FA-A871-34EB80197495_d0e155039_href.png Binary file Symbian3/SDK/Source/GUID-ACA2AFE8-4872-42FA-A871-34EB80197495_d0e155039_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-ACC71D0D-32C4-5DAF-B4D9-66013A073FD4-GENID-1-8-1-3-1-1-9-1-4-1-8-1.dita --- a/Symbian3/SDK/Source/GUID-ACC71D0D-32C4-5DAF-B4D9-66013A073FD4-GENID-1-8-1-3-1-1-9-1-4-1-8-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,50 +0,0 @@ - - - - - -Synchronising -FEP InstantiationsThis topic describes how to synchronize settings across different -instances of the same FEP. -

                As mentioned previously, the FEP architecture has been designed so that -each running application has its own instance of the current FEP. CCoeFep provides -support for synchronizing attributes across all of these instances, so that -when one instance changes the value of an attribute, the others are automatically -updated. In order for this to happen, the FEP has to do several things.

                -
                  -

                • Override the four pure -virtual functions that CCoeFep inherits from MFepAttributeStore: NumberOfAttributes(), AttributeAtIndex(), WriteAttributeDataToStreamL() and ReadAttributeDataFromStreamL(). NumberOfAttributes() should return the number of attributes that are to be synchronized across -all instances of the FEP, AttributeAtIndex() should return -the UID of the specified attribute, and WriteAttributeDataToStreamL() and ReadAttributeDataFromStreamL() should -write/read the specified attribute’s data to/from the provided stream.

                  • -

                • When the object of the CCoeFep -derived -class has been fully constructed, call CCoeFep::ReadAllAttributesL(). -This calls the ReadAttributeDataFromStreamL() virtual function -for each of the UIDs that the FEP requires to be synchronized (as specified -by NumberOfAttributes() and AttributeAtIndex()).

                  • -

                • After internally changing -the value of an attribute that is to be synchronized, call CCoeFep::WriteAttributeDataAndBroadcastL() to -propagate that change to all the other instances of the FEP. The parameter -identifies the attributes that are to be synchronized, using UIDs. See the -Symbian website for information on how to be allocated UIDs.

                  • -
                -

                The purpose of the SynchronouslyExecuteSettingsDialogL() exported -function, which the FEP must provide, is to launch a dialog that allows the -user to change any settings specific to that FEP. As mentioned above, there -is no guarantee that any instance of that particular FEP exists when this -function is called. In order for the dialog launched by SynchronouslyExecuteSettingsDialogL() to -be able to edit settings that are required to be synchronized across all running -applications, the dialog class must derive from MFepAttributeStorer. -The dialog class’ implementation of MFepAttributeStorer ’s -virtual functions should be the same as the CCoeFep -derived -class’ implementation of them. For an example of this, see TFEP1Plugin. When -the dialog is launched it needs to call MFepAttributeStorer::ReadAllAttributesL() to -correctly initialize all the settings. Conversely, the settings in the dialog -are committed by calling MFepAttributeStorer::WriteAttributeDataAndBroadcastL().

                -                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-ACC71D0D-32C4-5DAF-B4D9-66013A073FD4-GENID-1-8-1-6-1-1-4-1-8-1-4-1-8-1.dita --- a/Symbian3/SDK/Source/GUID-ACC71D0D-32C4-5DAF-B4D9-66013A073FD4-GENID-1-8-1-6-1-1-4-1-8-1-4-1-8-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,50 +0,0 @@ - - - - - -Synchronising -FEP InstantiationsThis topic describes how to synchronize settings across different -instances of the same FEP. -

                As mentioned previously, the FEP architecture has been designed so that -each running application has its own instance of the current FEP. CCoeFep provides -support for synchronizing attributes across all of these instances, so that -when one instance changes the value of an attribute, the others are automatically -updated. In order for this to happen, the FEP has to do several things.

                -
                  -

                • Override the four pure -virtual functions that CCoeFep inherits from MFepAttributeStore: NumberOfAttributes(), AttributeAtIndex(), WriteAttributeDataToStreamL() and ReadAttributeDataFromStreamL(). NumberOfAttributes() should return the number of attributes that are to be synchronized across -all instances of the FEP, AttributeAtIndex() should return -the UID of the specified attribute, and WriteAttributeDataToStreamL() and ReadAttributeDataFromStreamL() should -write/read the specified attribute’s data to/from the provided stream.

                  • -

                • When the object of the CCoeFep -derived -class has been fully constructed, call CCoeFep::ReadAllAttributesL(). -This calls the ReadAttributeDataFromStreamL() virtual function -for each of the UIDs that the FEP requires to be synchronized (as specified -by NumberOfAttributes() and AttributeAtIndex()).

                  • -

                • After internally changing -the value of an attribute that is to be synchronized, call CCoeFep::WriteAttributeDataAndBroadcastL() to -propagate that change to all the other instances of the FEP. The parameter -identifies the attributes that are to be synchronized, using UIDs. See the -Symbian website for information on how to be allocated UIDs.

                  • -
                -

                The purpose of the SynchronouslyExecuteSettingsDialogL() exported -function, which the FEP must provide, is to launch a dialog that allows the -user to change any settings specific to that FEP. As mentioned above, there -is no guarantee that any instance of that particular FEP exists when this -function is called. In order for the dialog launched by SynchronouslyExecuteSettingsDialogL() to -be able to edit settings that are required to be synchronized across all running -applications, the dialog class must derive from MFepAttributeStorer. -The dialog class’ implementation of MFepAttributeStorer ’s -virtual functions should be the same as the CCoeFep -derived -class’ implementation of them. For an example of this, see TFEP1Plugin. When -the dialog is launched it needs to call MFepAttributeStorer::ReadAllAttributesL() to -correctly initialize all the settings. Conversely, the settings in the dialog -are committed by calling MFepAttributeStorer::WriteAttributeDataAndBroadcastL().

                -                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-ACC71D0D-32C4-5DAF-B4D9-66013A073FD4.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-ACC71D0D-32C4-5DAF-B4D9-66013A073FD4.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,50 @@ + + + + + +Synchronising +FEP InstantiationsThis topic describes how to synchronize settings across different +instances of the same FEP. +

                As mentioned previously, the FEP architecture has been designed so that +each running application has its own instance of the current FEP. CCoeFep provides +support for synchronizing attributes across all of these instances, so that +when one instance changes the value of an attribute, the others are automatically +updated. In order for this to happen, the FEP has to do several things.

                +
                  +

                • Override the four pure +virtual functions that CCoeFep inherits from MFepAttributeStore: NumberOfAttributes(), AttributeAtIndex(), WriteAttributeDataToStreamL() and ReadAttributeDataFromStreamL(). NumberOfAttributes() should return the number of attributes that are to be synchronized across +all instances of the FEP, AttributeAtIndex() should return +the UID of the specified attribute, and WriteAttributeDataToStreamL() and ReadAttributeDataFromStreamL() should +write/read the specified attribute’s data to/from the provided stream.

                  • +

                • When the object of the CCoeFep -derived +class has been fully constructed, call CCoeFep::ReadAllAttributesL(). +This calls the ReadAttributeDataFromStreamL() virtual function +for each of the UIDs that the FEP requires to be synchronized (as specified +by NumberOfAttributes() and AttributeAtIndex()).

                  • +

                • After internally changing +the value of an attribute that is to be synchronized, call CCoeFep::WriteAttributeDataAndBroadcastL() to +propagate that change to all the other instances of the FEP. The parameter +identifies the attributes that are to be synchronized, using UIDs. See the +Symbian website for information on how to be allocated UIDs.

                  • +
                +

                The purpose of the SynchronouslyExecuteSettingsDialogL() exported +function, which the FEP must provide, is to launch a dialog that allows the +user to change any settings specific to that FEP. As mentioned above, there +is no guarantee that any instance of that particular FEP exists when this +function is called. In order for the dialog launched by SynchronouslyExecuteSettingsDialogL() to +be able to edit settings that are required to be synchronized across all running +applications, the dialog class must derive from MFepAttributeStorer. +The dialog class’ implementation of MFepAttributeStorer ’s +virtual functions should be the same as the CCoeFep -derived +class’ implementation of them. For an example of this, see TFEP1Plugin. When +the dialog is launched it needs to call MFepAttributeStorer::ReadAllAttributesL() to +correctly initialize all the settings. Conversely, the settings in the dialog +are committed by calling MFepAttributeStorer::WriteAttributeDataAndBroadcastL().

                +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-ACD9E338-DF75-5811-B696-C3900B498218.dita --- a/Symbian3/SDK/Source/GUID-ACD9E338-DF75-5811-B696-C3900B498218.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-ACD9E338-DF75-5811-B696-C3900B498218.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,64 +1,64 @@ - - - - - -Privacy -Requester ClassesThis document describes the classes that were used in earlier versions -of the Symbian platform to identify the requester of location information -to the LBS subsystem. -

                Use of these classes is now optional. It is recommended that you still -use them if your LBS applications must run on devices based on earlier versions -of Symbian.

                -
                Purpose

                The privacy requester classes were defined -as part of the Location Acquisition API before platform security was introduced -in Symbian OS v9. On all platforms based on Symbian OS v9 and later, client -applications are required to have the Location capability -to use the Location Acquisition API. Platform security checks fulfil much -of the role of the privacy requester classes.

                -
                Privacy requester classes

                This section describes -the privacy requester classes.

                Class -description

                Figure 1 shows the Privacy classes provided by the -Location Acquisition API.

                - Figure 1. Location Acquisition API privacy classes. - - -

                A requester is defined as an agent -that requests location information. There are two requester types:

                  -

                • Service requesters

                  A -service requester represents any terminal or network application or service.

                  • -

                • Contact requesters

                  A -contact requester represents an individual person requesting the location.

                  • -

                CRequestor::RequestorType() defines the type -of the requester. The requester information is sent to Location Server before -requesting location estimates.

                Defining -requesters

                Requesters may be defined in one of two ways:

                Defining a single requester

                A single requester is defined by -calling RPositioner::SetRequestorL(). The method signature -is: TInt SetRequestor(CRequestor::TRequestorType aType, - CRequestor::TRequestorFormat aFormat, const TDesC& - aData).

                The requester is defined directly by the values -supplied to the function’s parameters. This case is used by applications or -services if they are the only request source.

                CRequestor::TRequestorType defines -the type of requester: a service or contact.

                CRequestor::TRequestorFormat defines -the format of the requester identifier passed in aData: an -application name, contact, email address etc.

                Defining a stack of requesters

                If an application requests -location information on behalf of another agent or agents, it can specify -the chain of requesters by calling a second variant of RPositioner::SetRequestorL(). -The method signature is: TInt SetRequestor(const RRequestorStack& -aRequestorStack)

                RRequestorStack is -a container for a list of the requesters on behalf of which the request is -made. Each requester in the stack is represented by a CRequestor class.

                Note: Regardless of the number of requesters, there is always one service -requester, because the application executing the location request must be -always shown, even if it made the request on behalf of a contact requester. -For this reason, the last item in the requester stack must always be a service -requester (type CRequestorBase::ERequestorService).

                -                 -Position -Area Data Classes + + + + + +Privacy +Requester ClassesThis document describes the classes that were used in earlier versions +of the Symbian platform to identify the requester of location information +to the LBS subsystem. +

                Use of these classes is now optional. It is recommended that you still +use them if your LBS applications must run on devices based on earlier versions +of Symbian.

                +
                Purpose

                The privacy requester classes were defined +as part of the Location Acquisition API before platform security was introduced +in Symbian OS v9. On all platforms based on Symbian OS v9 and later, client +applications are required to have the Location capability +to use the Location Acquisition API. Platform security checks fulfil much +of the role of the privacy requester classes.

                +
                Privacy requester classes

                This section describes +the privacy requester classes.

                Class +description

                Figure 1 shows the Privacy classes provided by the +Location Acquisition API.

                + Figure 1. Location Acquisition API privacy classes. + + +

                A requester is defined as an agent +that requests location information. There are two requester types:

                  +

                • Service requesters

                  A +service requester represents any terminal or network application or service.

                  • +

                • Contact requesters

                  A +contact requester represents an individual person requesting the location.

                  • +

                CRequestor::RequestorType() defines the type +of the requester. The requester information is sent to Location Server before +requesting location estimates.

                Defining +requesters

                Requesters may be defined in one of two ways:

                Defining a single requester

                A single requester is defined by +calling RPositioner::SetRequestorL(). The method signature +is: TInt SetRequestor(CRequestor::TRequestorType aType, + CRequestor::TRequestorFormat aFormat, const TDesC& + aData).

                The requester is defined directly by the values +supplied to the function’s parameters. This case is used by applications or +services if they are the only request source.

                CRequestor::TRequestorType defines +the type of requester: a service or contact.

                CRequestor::TRequestorFormat defines +the format of the requester identifier passed in aData: an +application name, contact, email address etc.

                Defining a stack of requesters

                If an application requests +location information on behalf of another agent or agents, it can specify +the chain of requesters by calling a second variant of RPositioner::SetRequestorL(). +The method signature is: TInt SetRequestor(const RRequestorStack& +aRequestorStack)

                RRequestorStack is +a container for a list of the requesters on behalf of which the request is +made. Each requester in the stack is represented by a CRequestor class.

                Note: Regardless of the number of requesters, there is always one service +requester, because the application executing the location request must be +always shown, even if it made the request on behalf of a contact requester. +For this reason, the last item in the requester stack must always be a service +requester (type CRequestorBase::ERequestorService).

                +                 +Position +Area Data Classes                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-ACF69260-D643-4709-8DAB-33FD92940F86.dita --- a/Symbian3/SDK/Source/GUID-ACF69260-D643-4709-8DAB-33FD92940F86.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,36 +0,0 @@ - - - - - -Hierarchical -application structures -

                When browsing within a hierarchical application structure, the Symbian -user interface offers direct access from one folder to another (sibling) folder -in the same level. The Arrow left and Arrow right keys are used to accomplish -this. The Navi pane displays the sibling folders as tabs.

                - -In this example, each displayed state is a folder containing a list -of items. State 1 contains three folders (1-1, 1-2, 1-3). When the user has -opened one of these, there is a possibility to move directly into the other -two folders without first going back to state 1. Folder 1-1 contains two sub-folders -and folder 1-2 contains one. - - -

                This additional navigation feature can be interpreted as a shortcut between -sibling folders. For navigating hierarchical application structures, the basic -navigation rules are applied, noticing the following:

                -
                  -

                • Moving from one folder to another has no effect on the function of -the Back softkey in these views: from all of them, the Back function leads -to the previous hierarchy level.

                  • -

                • The navigation shortcuts can only be applied when there is no other -use for the Arrow left and Arrow right keys in the state.

                  • -
                -                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-AD5F35EC-4459-589F-9C46-94901562E05F-GENID-1-8-1-3-1-1-6-1.dita --- a/Symbian3/SDK/Source/GUID-AD5F35EC-4459-589F-9C46-94901562E05F-GENID-1-8-1-3-1-1-6-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,12 +0,0 @@ - - - - - -ClockThis section explains how to display digital and analogue clocks. \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-AD5F35EC-4459-589F-9C46-94901562E05F-GENID-1-8-1-6-1-1-4-1-5-1.dita --- a/Symbian3/SDK/Source/GUID-AD5F35EC-4459-589F-9C46-94901562E05F-GENID-1-8-1-6-1-1-4-1-5-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,12 +0,0 @@ - - - - - -ClockThis section explains how to display digital and analogue clocks. \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-AD5F35EC-4459-589F-9C46-94901562E05F.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-AD5F35EC-4459-589F-9C46-94901562E05F.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,12 @@ + + + + + +ClockThis section explains how to display digital and analogue clocks. \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-AD95D78A-9323-5E97-96C4-FB4872B66755_d0e144346_href.png Binary file Symbian3/SDK/Source/GUID-AD95D78A-9323-5E97-96C4-FB4872B66755_d0e144346_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-AD95D78A-9323-5E97-96C4-FB4872B66755_d0e150880_href.png Binary file Symbian3/SDK/Source/GUID-AD95D78A-9323-5E97-96C4-FB4872B66755_d0e150880_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-ADA36DA0-4E5D-483D-8AA7-C10A8E55ADD2_d0e68734_href.png Binary file Symbian3/SDK/Source/GUID-ADA36DA0-4E5D-483D-8AA7-C10A8E55ADD2_d0e68734_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-ADA36DA0-4E5D-483D-8AA7-C10A8E55ADD2_d0e73877_href.png Binary file Symbian3/SDK/Source/GUID-ADA36DA0-4E5D-483D-8AA7-C10A8E55ADD2_d0e73877_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-ADB3FA27-1DC0-4A04-A443-A174EDADF49D_d0e40470_href.png Binary file Symbian3/SDK/Source/GUID-ADB3FA27-1DC0-4A04-A443-A174EDADF49D_d0e40470_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-ADB3FA27-1DC0-4A04-A443-A174EDADF49D_d0e46030_href.png Binary file Symbian3/SDK/Source/GUID-ADB3FA27-1DC0-4A04-A443-A174EDADF49D_d0e46030_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-ADCDEFF9-4B1D-5E46-A63B-808192123E15_d0e168926_href.jpg Binary file Symbian3/SDK/Source/GUID-ADCDEFF9-4B1D-5E46-A63B-808192123E15_d0e168926_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-ADCDEFF9-4B1D-5E46-A63B-808192123E15_d0e175527_href.jpg Binary file Symbian3/SDK/Source/GUID-ADCDEFF9-4B1D-5E46-A63B-808192123E15_d0e175527_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-AE69AA42-E633-5B7A-BAA1-6896950E0E19_d0e429673_href.png Binary file Symbian3/SDK/Source/GUID-AE69AA42-E633-5B7A-BAA1-6896950E0E19_d0e429673_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-AE69AA42-E633-5B7A-BAA1-6896950E0E19_d0e429835_href.png Binary file Symbian3/SDK/Source/GUID-AE69AA42-E633-5B7A-BAA1-6896950E0E19_d0e429835_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-AE6F03EB-1430-4526-B4D0-57BC6C6029D4.dita --- a/Symbian3/SDK/Source/GUID-AE6F03EB-1430-4526-B4D0-57BC6C6029D4.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-AE6F03EB-1430-4526-B4D0-57BC6C6029D4.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,54 +1,53 @@ - - - - - -Touch -UI -

                When designing a Symbian application, the UI must be designed so that all -tasks can be performed with touch. Therefore, the design must not rely on -hardware keys (except for turning the power ON and OFF).

                -

                The touch UI in the Symbian platform involves various specific touch components, -component and UI behavior changes, layout changes and additions to the user experience. The -main differences or additions in touch UI include the following:

                -
                  -

                • Resistive touch screen (HW).

                  For more information, see Designing applications for -touch UI

                  • -

                • Capacitive touch screen (HW).

                  For more information, see Designing applications for -touch UI

                  • -

                • Single tap. For more information, see Single -tap.

                  • -

                • Multi-touch

                  .

                  For more information, see Multi-touch.

                  • - -

                • Toolbar component in touch UI

                  For -more information, see Toolbar.

                  • -

                • Touch input component (virtual keyboard, hand-writing recognition and -virtual ITU-T)

                  For more information, -see Text -input.

                  • -

                • Stylus pop-up menu component

                  For -more information, see Stylus -pop-up menu.

                  • -

                • On-screen dialer application

                  • -

                • Additional touch functionality to some components (for example, Preview -pop-up)

                  For more information, -see Preview -pop-up.

                  • -

                • Touch-enabled components

                  For -more information, see Touch -support for UI components.

                  • -
                -

                There are two generic layouts for touch UI -portrait orientation and landscape -orientation, see the following figure. The Status -pane in Touch UI has three variants: extended, flat and small.

                - -Default Symbian Touch UI layouts for portrait and landscape - - + + + + + +Touch +UI +

                When designing a Symbian application, the UI must be designed so that all +tasks can be performed with touch. Therefore, the design must not rely on +hardware keys (except for turning the power ON and OFF).

                +

                The touch UI in the Symbian platform involves various specific touch components, +component and UI behavior changes, layout changes and additions to the user experience. The +main differences or additions in touch UI include the following:

                +
                  +

                • Resistive touch screen (HW).

                  For more information, see Designing applications for +touch UI

                  • +

                • Capacitive touch screen (HW).

                  For more information, see Designing applications for +touch UI

                  • +

                • Single tap. For more information, see Single +tap.

                  • +

                • Multi-touch.

                  For more information, see Multi-touch.

                  • + +

                • Toolbar component in touch UI

                  For +more information, see Toolbar.

                  • +

                • Touch input component (virtual keyboard, hand-writing recognition and +virtual ITU-T)

                  For more information, +see Text +input.

                  • +

                • Stylus pop-up menu component

                  For +more information, see Stylus +pop-up menu.

                  • +

                • On-screen dialer application

                  • +

                • Additional touch functionality to some components (for example, Preview +pop-up)

                  For more information, +see Preview +pop-up.

                  • +

                • Touch-enabled components

                  For +more information, see Touch support for UI components.

                  • +
                +

                There are two generic layouts for touch UI -portrait orientation and landscape +orientation, see the following figure. The Status +pane in Touch UI has three variants: extended, flat and small.

                + +Default Symbian Touch UI layouts for portrait and landscape + +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-AE85751A-77CA-5C41-AF61-C9C9D776B066_d0e160811_href.png Binary file Symbian3/SDK/Source/GUID-AE85751A-77CA-5C41-AF61-C9C9D776B066_d0e160811_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-AE85751A-77CA-5C41-AF61-C9C9D776B066_d0e167412_href.png Binary file Symbian3/SDK/Source/GUID-AE85751A-77CA-5C41-AF61-C9C9D776B066_d0e167412_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-AE8D314A-5381-5576-9B17-94BA029A7FEA_d0e287887_href.jpg Binary file Symbian3/SDK/Source/GUID-AE8D314A-5381-5576-9B17-94BA029A7FEA_d0e287887_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-AE8D314A-5381-5576-9B17-94BA029A7FEA_d0e291520_href.jpg Binary file Symbian3/SDK/Source/GUID-AE8D314A-5381-5576-9B17-94BA029A7FEA_d0e291520_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-AE96F25E-45A2-5C00-9F27-BB3E17C8E6E5.dita --- a/Symbian3/SDK/Source/GUID-AE96F25E-45A2-5C00-9F27-BB3E17C8E6E5.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-AE96F25E-45A2-5C00-9F27-BB3E17C8E6E5.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,291 +1,291 @@ - - - - - -Certificate -and Key Management Overview

                The Certificate and Key Management component provides authentication -services for Public -Key Cryptography.

                 -
                Purpose

                The main purpose of the Certificate and -Key Management component is to provide validation services according to the -Public Key Infrastructure (PKI) for X.509 Certificates.

                The -Certificate and Key Management component provides interfaces for the following:

                  -

                • Storage and retrieval -of certificates

                  • -

                • Assignment of trust -status to a certificate on an application-by-application basis

                  • -

                • Certificate chain construction -and validation

                  • -

                • Verification of trust -of a certificate

                  • -

                • Generation of asymmetric -key pairs

                  • -

                • Protected storage of -keys

                  • -

                • Key import and export

                  • -

                • Authenticated execution -of private key operations

                  • -
                -
                Required background

                To understand Certificate and -Key Management in detail, you need to have a basic understanding of the following:

                  -

                • Public -Key Cryptography

                  • -

                • Certificates

                  • -

                • Digital -Signatures

                  • -
                -
                Key concepts and terms
                - -
                Certificate
                -

                A certificate is an electronic document that binds an identity to a -particular public or private key pair. It is commonly used to authenticate -cryptographic public keys.

                Certificates are issued by a Certification -Authority (CA). They usually include information such as a label, serial number, -validity period, certificate format (for example, X.509) and algorithm type -(for example, MD2RSA).

                -                 - -
                Key
                -

                A cryptography key is a constant value applied using a cryptographic -algorithm to encrypt text or to decrypt encrypted text.

                Keys are classified -as symmetric and asymmetric based on the type of algorithm applied. If the -same key is used for both encryption and decryption, it is symmetric. If different -keys are used for encryption and decryption, they are asymmetric. Asymmetric -keys exist in the form of a public and private key pair, where the public -key is used for encryption and the private key is used for decryption.

                -                 - -
                Certificate Store
                -

                A certificate store is a database or a file that stores and manipulates -certificates.

                The certificate store provides the following functionality:

                  -

                • Generation, storage -and retrieval certificates

                  • -

                • Assignment of trust -status to certificates

                  • -

                • Retrieval of list of -applications trusting a certificate

                  • -
                -                 - -
                Key Store
                -

                A key store is a repository of keys that can be retrieved and used -to accomplish a variety of tasks.

                The key store provides the following -functionality:

                  -

                • Generation, import and -export of RSA, DSA, and DH key pairs

                  • -

                • Listing of stored keys

                  • -

                • Authentication of users

                  • -

                • Private key operations -for authenticated users

                  • -
                -                 - -
                Token
                -

                A token is a physical instantiation of an object, such as a certificate -or a key, stored in a phone. Each token belongs to a group of tokens called -a token type. For example, an X.509 certificate is a token which belongs to -the X.509 token type.

                -                 -
                -
                Architecture

                The following diagram shows the basic -architecture of the Certificate and Key Management component. The blocks in -blue are internal to the component.

                - -

                The various blocks in the basic architecture diagram of the Certificate -and Key Management component are explained as follows:

                  -

                • Client Application: -This is a typical application that accesses the certificates or the keys of -the device through Certificate and Key Management component.

                  For example, -a web browser that wishes to load a bank's web page to perform a money-transfer -operation (in a secured mode using an https connection) first -checks the device's certificate store for a certificate that trusts the bank's -server and then loads the particular page.

                  • -

                • Unified Stores: -The Unified Stores APIs -form the primary access point for client applications to use certificates -or keys stored in the device. The Unified -Certificate Store provides a unified view of all the certificates in -the device while the Unified -Key Store provides a similar view of all the keys in the device.

                  • -

                • Generic Certificate -and Key Stores: These are the various certificate and key stores in the -device.

                  • -

                • File-Based Store -Implementation: The certificate and key stores use Symbian's file-based -store implementation. Based on the operations to be performed on the -keys and certificates, the file-based implementation updates the physical -certificate and key store files.

                  • -
                -
                APIs

                The following table lists the key APIs of -the Certificate and Key Management component. The table lists APIs that perform -the following tasks:

                  -

                • Provide implementation -for certificate and key stores, and for manipulating various types of certificates.

                  • -

                • Perform different types -of ASN.1 (Abstract Syntax Notation One) encoding.

                  • -
                - - - -API -Description - - - - -

                Unified Store APIs

                -                 - -

                CUnifiedCertStore

                -

                Provides a common implementation for all certificate stores in the -device.

                -                 - -

                CUnifiedKeyStore

                -

                Provides a common implementation for all key stores in the device.

                -                 - -

                Certificate APIs

                -                 - -

                CX500DistinguishedName

                -

                Provides implementation for parsing and matching the X.500 distinguished -names.

                -                 - -

                CX520AttributeTypeAndValue

                -

                Provides implementation for parsing and matching attribute types -and values, as defined by the X.520 standard.

                -                 - -

                CX509GeneralName

                -

                Provides implementation for manipulation of X.509 certificates.

                -                 - -

                CX509CertChain

                -

                Provides implementation for X.509 certificate chain validation.

                -                 - -

                CX509RSAPublicKey

                -

                Provides APIs for encoding and decoding of RSA public keys.

                -                 - -

                CX509ExtensionBase

                -

                Provides APIs for manipulating various X.509 certificate extensions.

                -                 - -

                CWTLSCertificate

                -

                Provides implementation for construction and manipulation of WTLS (Wireless Transport -Layer Security) certificates.

                -                 - -

                CWTLSName

                -

                Provides implementation for manipulation of WTLS names.

                -                 - -

                CWTLSRSAPublicKey

                -

                Provides implementation for manipulation of RSA public keys associated -with WTLS certificates.

                -                 - -

                CWTLSCertChain

                -

                Provides implementation for validation of WTLS certificate chains.

                -                 - -

                ASN.1 Encoding APIs

                -                 - -

                CASN1EncBigInt

                -

                Encodes Big Integer objects.

                -                 - -

                CASN1EncBitString

                -

                Encodes bit strings (for example, keys).

                -                 - -

                CASN1EncBoolean

                -

                Encodes Boolean values.

                -                 - -

                CASN1EncEncoding

                -

                Encapsulates already encoded information.

                -                 - -

                CASN1EncExplicitTag

                -

                Wraps other encoding objects and provides them with an explicit -tag.

                -                 - -

                CASN1EncGeneralizedTime

                -

                Encodes time-related objects.

                -                 - -

                CASN1EncInt

                -

                Encodes TInt objects.

                -                 - -

                CASN1EncNull

                -

                Encodes NULL values.

                -                 - -

                CASN1EncObjectIdentifier

                -

                Encodes object identifiers.

                -                 - -

                CASN1EncOctetString

                -

                Encodes octet strings.

                -                 - -

                CASN1EncPrimitive

                -

                All ASN.1 primitive type encoding classes derive from this class.

                -                 - -

                CASN1EncPrintableString

                -

                Encodes printable strings.

                -                 - -

                CASN1EncSequence

                -

                Encodes the SEQUENCE and SEQUENCE-OF data types.

                -                 - -

                CASN1EncSet

                -

                Encodes the SET and SET-OF data types.

                -                 - - -
                -
                Typical uses

                The Certificate and Key Management -component performs the following tasks:

                  -

                • Validating certificates -in PKIX

                  • -

                • Adding certificates

                  • -

                • Finding certificates

                  • -

                • Managing applicability -and trust settings

                  • -

                • Removing certificates

                  • -

                • Retrieving certificates

                  • -

                • Creating keys

                  • -

                • Importing keys

                  • -

                • Exporting keys

                  • -

                • Retrieving keys

                  • -

                • Deleting keys

                  • -

                • Signing keys

                  • -

                • Retrieving key stores

                  • -

                • Setting and retrieving -authentication policies

                  • -

                • Setting use and management -policies

                  • -

                See Unified -Certificate Store Tutorial and Unified -Keystore Tutorials for details of these tasks.

                -                 -OS Security -Concepts + + + + + +Certificate +and Key Management Overview

                The Certificate and Key Management component provides authentication +services for Public +Key Cryptography.

                 +
                Purpose

                The main purpose of the Certificate and +Key Management component is to provide validation services according to the +Public Key Infrastructure (PKI) for X.509 Certificates.

                The +Certificate and Key Management component provides interfaces for the following:

                  +

                • Storage and retrieval +of certificates

                  • +

                • Assignment of trust +status to a certificate on an application-by-application basis

                  • +

                • Certificate chain construction +and validation

                  • +

                • Verification of trust +of a certificate

                  • +

                • Generation of asymmetric +key pairs

                  • +

                • Protected storage of +keys

                  • +

                • Key import and export

                  • +

                • Authenticated execution +of private key operations

                  • +
                +
                Required background

                To understand Certificate and +Key Management in detail, you need to have a basic understanding of the following:

                  +

                • Public +Key Cryptography

                  • +

                • Certificates

                  • +

                • Digital +Signatures

                  • +
                +
                Key concepts and terms
                + +
                Certificate
                +

                A certificate is an electronic document that binds an identity to a +particular public or private key pair. It is commonly used to authenticate +cryptographic public keys.

                Certificates are issued by a Certification +Authority (CA). They usually include information such as a label, serial number, +validity period, certificate format (for example, X.509) and algorithm type +(for example, MD2RSA).

                +                 + +
                Key
                +

                A cryptography key is a constant value applied using a cryptographic +algorithm to encrypt text or to decrypt encrypted text.

                Keys are classified +as symmetric and asymmetric based on the type of algorithm applied. If the +same key is used for both encryption and decryption, it is symmetric. If different +keys are used for encryption and decryption, they are asymmetric. Asymmetric +keys exist in the form of a public and private key pair, where the public +key is used for encryption and the private key is used for decryption.

                +                 + +
                Certificate Store
                +

                A certificate store is a database or a file that stores and manipulates +certificates.

                The certificate store provides the following functionality:

                  +

                • Generation, storage +and retrieval certificates

                  • +

                • Assignment of trust +status to certificates

                  • +

                • Retrieval of list of +applications trusting a certificate

                  • +
                +                 + +
                Key Store
                +

                A key store is a repository of keys that can be retrieved and used +to accomplish a variety of tasks.

                The key store provides the following +functionality:

                  +

                • Generation, import and +export of RSA, DSA, and DH key pairs

                  • +

                • Listing of stored keys

                  • +

                • Authentication of users

                  • +

                • Private key operations +for authenticated users

                  • +
                +                 + +
                Token
                +

                A token is a physical instantiation of an object, such as a certificate +or a key, stored in a phone. Each token belongs to a group of tokens called +a token type. For example, an X.509 certificate is a token which belongs to +the X.509 token type.

                +                 +
                +
                Architecture

                The following diagram shows the basic +architecture of the Certificate and Key Management component. The blocks in +blue are internal to the component.

                + +

                The various blocks in the basic architecture diagram of the Certificate +and Key Management component are explained as follows:

                  +

                • Client Application: +This is a typical application that accesses the certificates or the keys of +the device through Certificate and Key Management component.

                  For example, +a web browser that wishes to load a bank's web page to perform a money-transfer +operation (in a secured mode using an https connection) first +checks the device's certificate store for a certificate that trusts the bank's +server and then loads the particular page.

                  • +

                • Unified Stores: +The Unified Stores APIs +form the primary access point for client applications to use certificates +or keys stored in the device. The Unified +Certificate Store provides a unified view of all the certificates in +the device while the Unified +Key Store provides a similar view of all the keys in the device.

                  • +

                • Generic Certificate +and Key Stores: These are the various certificate and key stores in the +device.

                  • +

                • File-Based Store +Implementation: The certificate and key stores use Symbian's file-based +store implementation. Based on the operations to be performed on the +keys and certificates, the file-based implementation updates the physical +certificate and key store files.

                  • +
                +
                APIs

                The following table lists the key APIs of +the Certificate and Key Management component. The table lists APIs that perform +the following tasks:

                  +

                • Provide implementation +for certificate and key stores, and for manipulating various types of certificates.

                  • +

                • Perform different types +of ASN.1 (Abstract Syntax Notation One) encoding.

                  • +
                + + + +API +Description + + + + +

                Unified Store APIs

                +                 + +

                CUnifiedCertStore

                +

                Provides a common implementation for all certificate stores in the +device.

                +                 + +

                CUnifiedKeyStore

                +

                Provides a common implementation for all key stores in the device.

                +                 + +

                Certificate APIs

                +                 + +

                CX500DistinguishedName

                +

                Provides implementation for parsing and matching the X.500 distinguished +names.

                +                 + +

                CX520AttributeTypeAndValue

                +

                Provides implementation for parsing and matching attribute types +and values, as defined by the X.520 standard.

                +                 + +

                CX509GeneralName

                +

                Provides implementation for manipulation of X.509 certificates.

                +                 + +

                CX509CertChain

                +

                Provides implementation for X.509 certificate chain validation.

                +                 + +

                CX509RSAPublicKey

                +

                Provides APIs for encoding and decoding of RSA public keys.

                +                 + +

                CX509ExtensionBase

                +

                Provides APIs for manipulating various X.509 certificate extensions.

                +                 + +

                CWTLSCertificate

                +

                Provides implementation for construction and manipulation of WTLS (Wireless Transport +Layer Security) certificates.

                +                 + +

                CWTLSName

                +

                Provides implementation for manipulation of WTLS names.

                +                 + +

                CWTLSRSAPublicKey

                +

                Provides implementation for manipulation of RSA public keys associated +with WTLS certificates.

                +                 + +

                CWTLSCertChain

                +

                Provides implementation for validation of WTLS certificate chains.

                +                 + +

                ASN.1 Encoding APIs

                +                 + +

                CASN1EncBigInt

                +

                Encodes Big Integer objects.

                +                 + +

                CASN1EncBitString

                +

                Encodes bit strings (for example, keys).

                +                 + +

                CASN1EncBoolean

                +

                Encodes Boolean values.

                +                 + +

                CASN1EncEncoding

                +

                Encapsulates already encoded information.

                +                 + +

                CASN1EncExplicitTag

                +

                Wraps other encoding objects and provides them with an explicit +tag.

                +                 + +

                CASN1EncGeneralizedTime

                +

                Encodes time-related objects.

                +                 + +

                CASN1EncInt

                +

                Encodes TInt objects.

                +                 + +

                CASN1EncNull

                +

                Encodes NULL values.

                +                 + +

                CASN1EncObjectIdentifier

                +

                Encodes object identifiers.

                +                 + +

                CASN1EncOctetString

                +

                Encodes octet strings.

                +                 + +

                CASN1EncPrimitive

                +

                All ASN.1 primitive type encoding classes derive from this class.

                +                 + +

                CASN1EncPrintableString

                +

                Encodes printable strings.

                +                 + +

                CASN1EncSequence

                +

                Encodes the SEQUENCE and SEQUENCE-OF data types.

                +                 + +

                CASN1EncSet

                +

                Encodes the SET and SET-OF data types.

                +                 + + +
                +
                Typical uses

                The Certificate and Key Management +component performs the following tasks:

                  +

                • Validating certificates +in PKIX

                  • +

                • Adding certificates

                  • +

                • Finding certificates

                  • +

                • Managing applicability +and trust settings

                  • +

                • Removing certificates

                  • +

                • Retrieving certificates

                  • +

                • Creating keys

                  • +

                • Importing keys

                  • +

                • Exporting keys

                  • +

                • Retrieving keys

                  • +

                • Deleting keys

                  • +

                • Signing keys

                  • +

                • Retrieving key stores

                  • +

                • Setting and retrieving +authentication policies

                  • +

                • Setting use and management +policies

                  • +

                See Unified +Certificate Store Tutorial and Unified +Keystore Tutorials for details of these tasks.

                +                 +OS Security +Concepts                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-AE979B97-5610-42F3-99A7-5A3D66D3C2E6.dita --- a/Symbian3/SDK/Source/GUID-AE979B97-5610-42F3-99A7-5A3D66D3C2E6.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,48 +0,0 @@ - - - - - -Sensor -interaction -

                The following types of interaction are enabled by using the sensors on -the device:

                -
                  -

                1. Tapping the device (for -example, double tap) to perform a given function. Tapping interaction -is not recommended for touch devices since the tap might also be interpreted -as a touch action if you tap on the touch screen area.

                  2. -

                2. Changing the screen -orientation on the device from portrait to landscape as the device is rotated.

                  3. -

                3. Silencing an incoming -call when the device orientation is changed from screen down (for example -on a table) to screen up and back again).

                  4. -

                4. Changing application -settings based on the ambient light conditions, e.g. bright sunshine or night -time.

                  5. -

                5. In a map application, -changing the orientation of a map based on the device's compass orientation.

                  6. -

                6. Allowing movement gestures, -such as device rotation, to trigger an action.

                  7. -

                7. Trigger an action when -the device comes in close proximity to the user's hand or head.

                  8. -
                -

                The supported sensor interactions are configurable on the device. The users -should be given the option to set their desired interactions.

                -

                Apart from sensing actions, the device can give tactile (vibrating) feedback -to acknowledge that the interaction has been successful.

                -
                Using -sensor interaction in C++ applications

                The APIs to use for sensor -interaction are the Sensor channel API and the Sensor definitions API.

                For -implementation information and description of the APIs, see the API specification for -the sensor APIs.

                Sensors channels come in three types based on the kind -of data that is delivered on the sensor channel: event, status, and continuous -data. For more information, see Definitions -for the sensor APIs.

                -                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-AEBB7F5D-E18E-4E1F-ADE0-C984084AC108_d0e11400_href.png Binary file Symbian3/SDK/Source/GUID-AEBB7F5D-E18E-4E1F-ADE0-C984084AC108_d0e11400_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-AEBB7F5D-E18E-4E1F-ADE0-C984084AC108_d0e12675_href.png Binary file Symbian3/SDK/Source/GUID-AEBB7F5D-E18E-4E1F-ADE0-C984084AC108_d0e12675_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-AFAD0F36-330B-50BD-B810-85BE7FA21179.dita --- a/Symbian3/SDK/Source/GUID-AFAD0F36-330B-50BD-B810-85BE7FA21179.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-AFAD0F36-330B-50BD-B810-85BE7FA21179.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,103 +1,103 @@ - - - - - -HTTP -Utilities Library (InetProtUtils) Example -
                Download

                Click -on the following link to download the example: ExampleInetProtUtil.zip

                Click: browse to view the example code.

                -
                Description

                This example code demonstrates -the usage of utilities provided by the InetProtUtil API. The users should -have a prior knowledge of concepts associated with it, such as URLs and URI -components.

                The central class is CExampleInetProtUtil, -which demonstrates the following functionality:

                  -

                • Creating a URI

                  • -

                • Modifying a URI

                  • -

                • Resolving a URI

                  • -

                • Parsing a URI

                  • -

                • Validating a URI

                  • -

                • Extracting URI components

                  • -

                • Retrieving a filename from a URI

                  • -

                • Adding and removing delimiters from a URI

                  • -

                • Removing whitespace from a URI

                  • -

                • Escape encoding and decoding a URI

                  • -

                Creating a URI

                void CExampleInetProtUtil::CreateUri();

                Creates -a URI with respect to the physical path of a given file.

                For example, -the physical path of the file:

                K:/ws/direct/direct.mmp

                gives -the following URI file:

                ///k/ws/direct/direct.mmp

                The -screen output from this example is:

                - -

                Modifying a URI

                void CExampleInetProtUtil::ModifyUriComponents();

                Modifies -URI components, which involves:

                  -

                1. Adding URI components, -where it constructs the URI component by component. For example, you can add -the following components:

                    -

                  • scheme: http

                    • -

                  • host: waterlang.org

                    • -

                  • path: main_page.html

                    • -

                  • port: 8080

                    • -

                  to get the complete URI:

                  http://waterlang.org:8080/main_page.html

                  The -screen output from this example is:

                  - -
                  2. -

                2. Removing the specific -URI component(s) from a constructed URI. For example, the above URI with the -port number removed:

                  http://waterlang.org/main_page.html

                  The -screen output from this example is:

                  - -
                  3. -

                Resolving a URI

                void CExampleInetProtUtil::ResolveUri();

                Resolves -the URI, which involves creation of an absolute CUri object -from a given reference URI.

                The screen output from this example is:

                - -

                Parsing a URI

                void CExampleInetProtUtil::ParseUri();

                Parses -the URI into its components (as given in RFC2396). The five URI components are:

                  -

                • scheme

                  • -

                • authority

                  • -

                • path

                  • -

                • query

                  • -

                • fragment.

                  • -

                The screen output from this example is:

                - -

                Validating a URI

                void CExampleInetProtUtil::ValidateUriComponents();

                Validates -a given URI. This function is usually used for URIs with SIP as the scheme.

                The -screen output from this example is:

                - -

                Extracting URI -components

                void CExampleInetProtUtil::ExtractUriComponents();

                Extracts -URI components from the given URI.

                The screen output from this example -is:

                - -

                Retrieving a filename -from a URI

                void CExampleInetProtUtil::RetrieveFileName();

                Extracts -the actual physical location of the file from its URI.

                The screen -output from this example is:

                - -

                Adding and removing -delimiters from a URI

                void CExampleInetProtUtil::ModifyDelimiter();

                Adds the delimiters to and removes the delimiters from a URI. Before -doing this ensure that:

                  -

                • the delimiter is set -using SetDelimiter()

                  • -

                • the URI has already -been parsed.

                  • -

                The screen output from this example is:

                - -

                Removing whitespace -from a URI

                void CExampleInetProtUtil::WhiteSpaceRemover();

                Removes -the whitespace from the given URI and returns the number of white spaces that -were removed.

                The screen output from this example is:

                - -

                Escape encoding -and decoding a URI

                void CExampleInetProtUtil::EscapeEncodeDecode();

                Escape encodes the characters in a given URI as escape triplets and decodes -it to the original one.

                The screen output from this example is:

                - -
                -
                Class Summary

                CUri8

                TUriParser8

                EscapeUtils

                TDelimitedParserBase8

                InetProtTextUtils

                + + + + + +HTTP +Utilities Library (InetProtUtils) Example +
                Download

                Click +on the following link to download the example: ExampleInetProtUtil.zip

                Click: browse to view the example code.

                +
                Description

                This example code demonstrates +the usage of utilities provided by the InetProtUtil API. The users should +have a prior knowledge of concepts associated with it, such as URLs and URI +components.

                The central class is CExampleInetProtUtil, +which demonstrates the following functionality:

                  +

                • Creating a URI

                  • +

                • Modifying a URI

                  • +

                • Resolving a URI

                  • +

                • Parsing a URI

                  • +

                • Validating a URI

                  • +

                • Extracting URI components

                  • +

                • Retrieving a filename from a URI

                  • +

                • Adding and removing delimiters from a URI

                  • +

                • Removing whitespace from a URI

                  • +

                • Escape encoding and decoding a URI

                  • +

                Creating a URI

                void CExampleInetProtUtil::CreateUri();

                Creates +a URI with respect to the physical path of a given file.

                For example, +the physical path of the file:

                K:/ws/direct/direct.mmp

                gives +the following URI file:

                ///k/ws/direct/direct.mmp

                The +screen output from this example is:

                + +

                Modifying a URI

                void CExampleInetProtUtil::ModifyUriComponents();

                Modifies +URI components, which involves:

                  +

                1. Adding URI components, +where it constructs the URI component by component. For example, you can add +the following components:

                    +

                  • scheme: http

                    • +

                  • host: waterlang.org

                    • +

                  • path: main_page.html

                    • +

                  • port: 8080

                    • +

                  to get the complete URI:

                  http://waterlang.org:8080/main_page.html

                  The +screen output from this example is:

                  + +
                  2. +

                2. Removing the specific +URI component(s) from a constructed URI. For example, the above URI with the +port number removed:

                  http://waterlang.org/main_page.html

                  The +screen output from this example is:

                  + +
                  3. +

                Resolving a URI

                void CExampleInetProtUtil::ResolveUri();

                Resolves +the URI, which involves creation of an absolute CUri object +from a given reference URI.

                The screen output from this example is:

                + +

                Parsing a URI

                void CExampleInetProtUtil::ParseUri();

                Parses +the URI into its components (as given in RFC2396). The five URI components are:

                  +

                • scheme

                  • +

                • authority

                  • +

                • path

                  • +

                • query

                  • +

                • fragment.

                  • +

                The screen output from this example is:

                + +

                Validating a URI

                void CExampleInetProtUtil::ValidateUriComponents();

                Validates +a given URI. This function is usually used for URIs with SIP as the scheme.

                The +screen output from this example is:

                + +

                Extracting URI +components

                void CExampleInetProtUtil::ExtractUriComponents();

                Extracts +URI components from the given URI.

                The screen output from this example +is:

                + +

                Retrieving a filename +from a URI

                void CExampleInetProtUtil::RetrieveFileName();

                Extracts +the actual physical location of the file from its URI.

                The screen +output from this example is:

                + +

                Adding and removing +delimiters from a URI

                void CExampleInetProtUtil::ModifyDelimiter();

                Adds the delimiters to and removes the delimiters from a URI. Before +doing this ensure that:

                  +

                • the delimiter is set +using SetDelimiter()

                  • +

                • the URI has already +been parsed.

                  • +

                The screen output from this example is:

                + +

                Removing whitespace +from a URI

                void CExampleInetProtUtil::WhiteSpaceRemover();

                Removes +the whitespace from the given URI and returns the number of white spaces that +were removed.

                The screen output from this example is:

                + +

                Escape encoding +and decoding a URI

                void CExampleInetProtUtil::EscapeEncodeDecode();

                Escape encodes the characters in a given URI as escape triplets and decodes +it to the original one.

                The screen output from this example is:

                + +
                +
                Class Summary

                CUri8

                TUriParser8

                EscapeUtils

                TDelimitedParserBase8

                InetProtTextUtils

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-AFC49653-78E6-5639-911C-E02AEB08AFFC_d0e185333_href.png Binary file Symbian3/SDK/Source/GUID-AFC49653-78E6-5639-911C-E02AEB08AFFC_d0e185333_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-AFC49653-78E6-5639-911C-E02AEB08AFFC_d0e191929_href.png Binary file Symbian3/SDK/Source/GUID-AFC49653-78E6-5639-911C-E02AEB08AFFC_d0e191929_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-AFE7F3DA-6D61-5A4C-A08F-C998C8805A06.dita --- a/Symbian3/SDK/Source/GUID-AFE7F3DA-6D61-5A4C-A08F-C998C8805A06.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-AFE7F3DA-6D61-5A4C-A08F-C998C8805A06.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,81 +1,81 @@ - - - - - -How -the target Client is Resolved using CSIPResolvedClient2 -

                The SIP Client Resolver determines the target clients by comparing the -Request-URI of the incoming SIP request to the information stored in SIP Client -Resolver mapping table in the Central Repository. The information required -to access the map table in the Central Repository is defined in the sipclientresolverconfigcrkey.h file. -The incoming SIP request compares with the Request-URI’s user part in the -Central Repository mapping table.

                -

                If a match is found, the related ECOM plug-in is loaded by its UID. The -loaded plug-in matches the incoming SIP requests based on their fields. If -the request matches, the plug-in returns the UID of the matching client. SIP -Client Resolver requests the resolved ECom plug-in to connect to the Symbian -platform server that uses SIP.

                -

                The resource (.rss) file contains the information -in the Central Repository and also the following information:

                -
                  -

                • dll_uid and implementation_uid: -These UIDs are obtained from Symbian -Signed.

                  Note: Both these UIDs can be the same.

                  • -

                • The interface_uid must -be 0x10282EE5.

                  • -
                -
                Resolving the target client using CSIPResolvedClient2

                The -following illustration shows how the SIP Client Resolver subsystem resolves -the target client implementing CSIPResolvedClient2 and -requests the resolved client to connect to the SIP implementation.

                - Call flow of resolving a target client implementation -using CSIPResolvedClient2 - -

                The target clients must implement the CSIPResolvedClient2 interface -to receive SIP requests including SIP dialogs and enable the client resolution -mechanism. Note: The channel UIDs must be unique across all -SIP clients. For example clients may use UIDs assigned for binaries.

                The -SIP stack uses the plug-ins that implement the CSIPResolvedClient2 interface -as follows:

                  -

                1. If the SIP request does -not contain an Accept-Contact-header, go to step 2. If it does, the SIP stack -calls CSIPResolvedClient2::MatchAcceptContactsL for all the -plug-ins and applies the following logic:

                    -

                  • If none of the clients -match, go to step 2

                    • -

                  • If one of the client -match, the SIP request is sent to the matching client

                    • -

                  • If more than one of -the clients match, go to step 2

                    • -
                  2. -

                2. If the SIP request does -not contain an Event-header go to step 3. If it does, the SIP stack calls CSIPResolvedClient2::MatchEventL for -all the plug-ins and applies the following logic:

                    -

                  • If none of the clients -match, go to step 3

                    • -

                  • If one of the client -match, the SIP request is sent to the matching client

                    • -

                  • If more than one of -the clients match, go to step 3

                    • -
                  3. -

                3. The SIP stack calls CSIPResolvedClient2::MatchRequestL for -all the plug-ins and applies the following logic:

                    -

                  • If none of the clients -match, the SIP generates an error response

                    • -

                  • If one of the client -match, the SIP request is sent to the matching client

                    • -

                  • If more than one of -the clients match, SIP selects one of these clients randomly and sends the -request to it. The ROM-based clients are preferred.

                    • -
                  4. -
                -
                See also

                Example -of a SIP Client Resolver Plug-in

                + + + + + +How +the target Client is Resolved using CSIPResolvedClient2 +

                The SIP Client Resolver determines the target clients by comparing the +Request-URI of the incoming SIP request to the information stored in SIP Client +Resolver mapping table in the Central Repository. The information required +to access the map table in the Central Repository is defined in the sipclientresolverconfigcrkey.h file. +The incoming SIP request compares with the Request-URI’s user part in the +Central Repository mapping table.

                +

                If a match is found, the related ECOM plug-in is loaded by its UID. The +loaded plug-in matches the incoming SIP requests based on their fields. If +the request matches, the plug-in returns the UID of the matching client. SIP +Client Resolver requests the resolved ECom plug-in to connect to the Symbian +platform server that uses SIP.

                +

                The resource (.rss) file contains the information +in the Central Repository and also the following information:

                +
                  +

                • dll_uid and implementation_uid: +These UIDs are obtained from Symbian +Signed.

                  Note: Both these UIDs can be the same.

                  • +

                • The interface_uid must +be 0x10282EE5.

                  • +
                +
                Resolving the target client using CSIPResolvedClient2

                The +following illustration shows how the SIP Client Resolver subsystem resolves +the target client implementing CSIPResolvedClient2 and +requests the resolved client to connect to the SIP implementation.

                + Call flow of resolving a target client implementation +using CSIPResolvedClient2 + +

                The target clients must implement the CSIPResolvedClient2 interface +to receive SIP requests including SIP dialogs and enable the client resolution +mechanism. Note: The channel UIDs must be unique across all +SIP clients. For example clients may use UIDs assigned for binaries.

                The +SIP stack uses the plug-ins that implement the CSIPResolvedClient2 interface +as follows:

                  +

                1. If the SIP request does +not contain an Accept-Contact-header, go to step 2. If it does, the SIP stack +calls CSIPResolvedClient2::MatchAcceptContactsL for all the +plug-ins and applies the following logic:

                    +

                  • If none of the clients +match, go to step 2

                    • +

                  • If one of the client +match, the SIP request is sent to the matching client

                    • +

                  • If more than one of +the clients match, go to step 2

                    • +
                  2. +

                2. If the SIP request does +not contain an Event-header go to step 3. If it does, the SIP stack calls CSIPResolvedClient2::MatchEventL for +all the plug-ins and applies the following logic:

                    +

                  • If none of the clients +match, go to step 3

                    • +

                  • If one of the client +match, the SIP request is sent to the matching client

                    • +

                  • If more than one of +the clients match, go to step 3

                    • +
                  3. +

                3. The SIP stack calls CSIPResolvedClient2::MatchRequestL for +all the plug-ins and applies the following logic:

                    +

                  • If none of the clients +match, the SIP generates an error response

                    • +

                  • If one of the client +match, the SIP request is sent to the matching client

                    • +

                  • If more than one of +the clients match, SIP selects one of these clients randomly and sends the +request to it. The ROM-based clients are preferred.

                    • +
                  4. +
                +
                See also

                Example +of a SIP Client Resolver Plug-in

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B015C4A3-469E-5AC4-B9B9-A24AF7444E65.dita --- a/Symbian3/SDK/Source/GUID-B015C4A3-469E-5AC4-B9B9-A24AF7444E65.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-B015C4A3-469E-5AC4-B9B9-A24AF7444E65.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,97 +1,97 @@ - - - - - -SendAs -Overview -

                This section describes the overview and functions provided by the SendAs -component.

                -
                Purpose

                The SendAs component provides a high-level -APIs for client applications that wish to include a SendAs menu to -allow users to send content through any of the supported message types. It -acts as a wrapper that allows access to the common functionality of email, -SMS, and OBEX components.

                For example, SendAs allows a word processor -document to be sent as an email, or a contact as a vCard (either attached -to an email or as an SMS).

                -
                Key terms
                - -
                SendAs Server
                -

                The server that maintains and controls access to all the SendAs entries.

                -                 - -
                Message Type Module (MTM)
                -

                A group of components that together provide message handling functionality -for a particular protocol.

                -                 -
                -
                Architecture

                The main client-side API is the RSendAs class. -Client applications use this to connect to the SendAs Server.

                Client -applications create messages using the RSendAsMessage API. -Opening an RSendAsMessage object on SendAs Server session -creates a SendAs message in the SendAs Server. This allows client applications -to create multiple messages concurrently.

                Important: There -is no exposure to Message Server APIs on the client-side. The SendAs Server -encapsulates the Message Server completely.

                - SendAs architecture - -
                -
                SendAs Server

                The SendAs Server maintains -all SendAs entries and controls the access to a Message Store. It allows client -applications to create messages in the Drafts folder of a Message Store. The -SendAs APIs also allow a client application to launch an appropriate message -editor for a given message type. They support two methods of sending messages: -confirmed or unconfirmed send. A confirmed send requires a confirmation by -the UI MTM; typically it queries the phone user. An unconfirmed send does -not require confirmation by the UI MTM.

                The following are the key -functions of SendAs Server :

                  -

                • Get a list of the names -of the MTMs that have the required capabilities.

                  • -

                • Get a list of the services -that can be used with the chosen MTM.

                  • -

                • Create a message, define -the body and attachments for that message, without forcing the client application -to start any message-specific user interface.

                  • -

                • Store the message so -that it is ready for sending from the device next time it is connected to -the appropriate service.

                  • -

                • Send the message.

                  • -

                • Start the editor for -the message type.

                  • -

                • Allow client applications -to query the message type.

                  • -
                -
                API summary

                The following are the two main SendAs -Server classes:

                  -

                • The RSendAs class -is the main interface to the SendAs Server.

                  • -

                • The RSendAsMessage class -encapsulates creating and sending a message. It requires a connected RSendAs session.

                  • -
                -
                Typical use cases

                The RSendAs class -is used for the following tasks:

                  -

                • Connecting to and disconnecting -from the SendAs Server

                  • -

                • Querying the message -type registry

                  • -

                The RSendAsMessage class is used for the following -tasks:

                  -

                • Creating and managing -a SendAs message

                  • -

                • Launching a message -editor for the created SendAs message

                  • -

                • Modifying a SendAs message

                  • -

                • Sending a SendAs message

                  • -
                -                 -SendAs Server - -SendAs Example -Code + + + + + +SendAs +Overview +

                This section describes the overview and functions provided by the SendAs +component.

                +
                Purpose

                The SendAs component provides a high-level +APIs for client applications that wish to include a SendAs menu to +allow users to send content through any of the supported message types. It +acts as a wrapper that allows access to the common functionality of email, +SMS, and OBEX components.

                For example, SendAs allows a word processor +document to be sent as an email, or a contact as a vCard (either attached +to an email or as an SMS).

                +
                Key terms
                + +
                SendAs Server
                +

                The server that maintains and controls access to all the SendAs entries.

                +                 + +
                Message Type Module (MTM)
                +

                A group of components that together provide message handling functionality +for a particular protocol.

                +                 +
                +
                Architecture

                The main client-side API is the RSendAs class. +Client applications use this to connect to the SendAs Server.

                Client +applications create messages using the RSendAsMessage API. +Opening an RSendAsMessage object on SendAs Server session +creates a SendAs message in the SendAs Server. This allows client applications +to create multiple messages concurrently.

                Important: There +is no exposure to Message Server APIs on the client-side. The SendAs Server +encapsulates the Message Server completely.

                + SendAs architecture + +
                +
                SendAs Server

                The SendAs Server maintains +all SendAs entries and controls the access to a Message Store. It allows client +applications to create messages in the Drafts folder of a Message Store. The +SendAs APIs also allow a client application to launch an appropriate message +editor for a given message type. They support two methods of sending messages: +confirmed or unconfirmed send. A confirmed send requires a confirmation by +the UI MTM; typically it queries the phone user. An unconfirmed send does +not require confirmation by the UI MTM.

                The following are the key +functions of SendAs Server :

                  +

                • Get a list of the names +of the MTMs that have the required capabilities.

                  • +

                • Get a list of the services +that can be used with the chosen MTM.

                  • +

                • Create a message, define +the body and attachments for that message, without forcing the client application +to start any message-specific user interface.

                  • +

                • Store the message so +that it is ready for sending from the device next time it is connected to +the appropriate service.

                  • +

                • Send the message.

                  • +

                • Start the editor for +the message type.

                  • +

                • Allow client applications +to query the message type.

                  • +
                +
                API summary

                The following are the two main SendAs +Server classes:

                  +

                • The RSendAs class +is the main interface to the SendAs Server.

                  • +

                • The RSendAsMessage class +encapsulates creating and sending a message. It requires a connected RSendAs session.

                  • +
                +
                Typical use cases

                The RSendAs class +is used for the following tasks:

                  +

                • Connecting to and disconnecting +from the SendAs Server

                  • +

                • Querying the message +type registry

                  • +

                The RSendAsMessage class is used for the following +tasks:

                  +

                • Creating and managing +a SendAs message

                  • +

                • Launching a message +editor for the created SendAs message

                  • +

                • Modifying a SendAs message

                  • +

                • Sending a SendAs message

                  • +
                +                 +SendAs Server + +SendAs Example +Code                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B02C762B-C452-4184-ABEA-4753E6CD47D2.dita --- a/Symbian3/SDK/Source/GUID-B02C762B-C452-4184-ABEA-4753E6CD47D2.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-B02C762B-C452-4184-ABEA-4753E6CD47D2.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,53 +1,53 @@ - - - - - -Scalability -

                The term scalability refers to the ability of an application -UI to function as designed in mobile devices with different screen resolutions -or orientations. For example, in the figure below, the UI scales to fit both -portrait and landscape orientations.

                -Scaling -

                When you enable scaling in your application, you allow your application -to support the different display sizes, resolutions, and layouts for different -devices based on the Symbian platform. The Symbian platform provides APIs -and other support to enable scaling in applications. Some scaling issues are -handled by the application framework if support is enabled, while other issues -need to be handled by the application. The details of what can be handled -where depend on the nature of your UI architecture. A general rule of thumb -is that the greater the degree of customization in your application, the more -you need to handle scalability issues in the application.

                -

                You are not required to enable scaling in your applications, although -it is recommended as it enhances usability for mobile device users.

                -

                The following issues should be kept in mind when enabling your application -for scaling:

                -
                  -

                • Layout information should not be hard-coded.

                  - -

                  The Symbian platform provides the AknLayoutUtils class -for building layouts from resource files.

                  -

                  Note that you also need to override CCoeControl::HandleResourceChange() and CEikAppUi::HandleResourceChangeL() in your -application to draw your application again in the event that the orientation -of the display changes.

                  -                   -
                  • -

                • Scalable fonts should be used.

                  - -

                  The Symbian platform provides methods in the AknLayoutUtils for -using logical fonts from an enumeration in the avkon.hrh file.

                  -                   -
                  • -

                • Scalable icons should be used.

                  - -

                  Scalable icons are based on SVG Tiny (SVG-T) format graphics.

                  -                   -
                  • -
                + + + + + +Scalability +

                The term scalability refers to the ability of an application +UI to function as designed in mobile devices with different screen resolutions +or orientations. For example, in the figure below, the UI scales to fit both +portrait and landscape orientations.

                +Scaling +

                When you enable scaling in your application, you allow your application +to support the different display sizes, resolutions, and layouts for different +devices based on the Symbian platform. The Symbian platform provides APIs +and other support to enable scaling in applications. Some scaling issues are +handled by the application framework if support is enabled, while other issues +need to be handled by the application. The details of what can be handled +where depend on the nature of your UI architecture. A general rule of thumb +is that the greater the degree of customization in your application, the more +you need to handle scalability issues in the application.

                +

                You are not required to enable scaling in your applications, although +it is recommended as it enhances usability for mobile device users.

                +

                The following issues should be kept in mind when enabling your application +for scaling:

                +
                  +

                • Layout information should not be hard-coded.

                  + +

                  The Symbian platform provides the AknLayoutUtils class +for building layouts from resource files.

                  +

                  Note that you also need to override CCoeControl::HandleResourceChange() and CEikAppUi::HandleResourceChangeL() in your +application to draw your application again in the event that the orientation +of the display changes.

                  +                   +
                  • +

                • Scalable fonts should be used.

                  + +

                  The Symbian platform provides methods in the AknLayoutUtils for +using logical fonts from an enumeration in the avkon.hrh file.

                  +                   +
                  • +

                • Scalable icons should be used.

                  + +

                  Scalable icons are based on SVG Tiny (SVG-T) format graphics.

                  +                   +
                  • +
                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B0391618-0681-5E4E-94BE-C0E24B862AEF_d0e213571_href.png Binary file Symbian3/SDK/Source/GUID-B0391618-0681-5E4E-94BE-C0E24B862AEF_d0e213571_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B0391618-0681-5E4E-94BE-C0E24B862AEF_d0e217308_href.png Binary file Symbian3/SDK/Source/GUID-B0391618-0681-5E4E-94BE-C0E24B862AEF_d0e217308_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B0449B60-B78E-5CC1-8FAF-E5EE24D88EB2.dita --- a/Symbian3/SDK/Source/GUID-B0449B60-B78E-5CC1-8FAF-E5EE24D88EB2.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-B0449B60-B78E-5CC1-8FAF-E5EE24D88EB2.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,16 +1,16 @@ - - - - - -Advanced Audio Adaptation Framework Technology Guide

                This document provides additional information about the Advanced Audio Adaptation Framework.

                Purpose

                The Advanced Audio Adaptation Framework (A3F) provides a common interface for accessing audio resources, playing tones, and configuring audio for playing and recording.

                Understanding A3F

                A3F functionality is provided by the CAudioContextFactory class. CAudioContextFactory is responsible for creating audio contexts. The Audio Context API (MAudioContext) maintains all audio components created in a context, where audio components are instances of the MAudioStream and MAudioProcessingUnit classes.

                An MAudioProcessingUnit is created in a context by giving the type of the processing unit such as codec and source sink. MAudioProcessingUnit allows extension interfaces to set additional audio processing unit settings.

                The Audio Stream API (MAudioStream) is an audio component that links together processing units into an audio stream. MAudioStream manages the audio processing state requested by the client and interacts with the audio processing units added to the stream. MAudioStream provides runtime control over a stream's (composite) behaviour and lifetime management of the entities in a stream (whether the state of the stream is uninitialized, initialized, idle, primed, active or dead). For more information, see Stream States.

                The Audio Context API allows a grouping notion for multimedia allocations. MAudioContext groups component actions made inside a context. This means any allocation or loss of resources which occurs in any single audio component affects all of the components grouped in the context.

                The Commit Cycle

                Changes made to an audio stream are handled in a transactional manner. If changes fail to be applied, then any other changes made to the stream are considered to fail also. The application of changes is dependent on a successful commit cycle. If there is a failure, a “rollback" mechanism is executed and the stream states are reverted to their previous state.

                The client requests changes through various Set() calls and then calls the MAudioContext::Commit() function. The platform-specific implementation then decides whether the Commit() request is allowed, possibly dictates new values if needed, and then applies the changes. If successful, the client is informed through callbacks. If there is a need to modify the context because resources are needed in another context, then the platform-specific implementation can take the resources by pre-empting the context. In this case, the client is informed about the pre-emption.

                The following diagram shows this behaviour:

                - A3F Commit / Pre-emption Cycle -

                Observers

                Most of the A3F API functions are asynchronous. For example, the functions Foo() or SetFoo() are followed with FooComplete(Tint aError) or FooSet(Tint aError).

                The following A3F observers are defined:

                • MAudioContextObserver

                  Informs with ContextEvent() about the commit cycle. Note that ContextEvent() is in the same thread context as the A3F client.

                • MAudioStreamObserver

                  Informs with StateEvent() about state changes

                • MAudioCodecObserver

                  Informs about completion of setters and getters.

                • MAudioGainControlObserver

                  Informs about changes in gain or changes in maximum gain values.

                • MAudioProcessingUnitObserver

                  Informs about any additional errors in audio processing units.

                • MMMFAudioDataConsumer

                  Informs about recorded buffer to be ready for storing. Also informs the client if there is a buffer to be ignored.

                • MMMFAudioDataSupplier

                  Informs about new buffer ready to be filled with audio data. Also informs the client if any requested buffer should be ignored.

                Stream States

                Clients using A3F should be aware that requested audio resources can be lost at any time while they are being used. A client with a higher importance can cause requests for resources to be denied or available resources to become unavailable. In these cases, the commit cycle informs the client through pre-emption events and the resulted stream state is usually demoted to the highest non-disturbing state.

                The possible audio stream states are described in the following table:

                State Description

                EUninitialized

                This is the state of the chain before it is initialized. However, the settings in the logical chain cannot be related to the adaptation because no adaptation has been selected yet.

                EInitialized

                This state is set after a successful initialization request.

                The physical adaptation has been selected but may not be fully allocated.

                There should be no externally visible buffers allocated at this point

                Note: For zero copy and shared chunk buffers, a stream in the EInitialized state should not require buffer consumption. This is an important issue if the base port only has 16 addressable chunks per process.

                In terms of DevSound compatibility, some custom interfaces are available at this point (although others may require further construction before they are available).

                EIdle

                All the chain resources are allocated. However, no processing time (other than that expended to put the chain into the EIdle state) is consumed in this phase.

                In the EIdle state, any existing allocated buffers continue to exist.

                The codec is allocated in terms of hardware memory consumption.

                A stream in the EIdle state can be ‘mid-file position’. There is no implied reset of position or runtime settings (that is, time played) by returning to EIdle.

                EPrimed

                This state is the same as EIdle but the stream can consume processing time by filling its buffers. The purpose of this state is to prepare a stream such that it is ready to play in as short a time as possible (for example, low-latency for audio chains which can be pre-buffered).

                Note that once the buffer is full, the stream may continue to use some processing time.

                There will not be an automatic transition to the EIdle state when the buffer is full. If such behaviour is desired, the client must request it.

                There will not be an automatic transition to EActive when the buffer is full. If such behaviour is desired, the client must request it.

                EActive

                The chain has the resources as EIdle and EPrimed but also has started to process the actions requested by the client.

                Note: A chain can be in the EActive state and performing a wide range of operations. However the semantics are that it is processing the stream and that it is consuming both processing and memory resources.

                EDead

                The stream can no longer function due to a fatal error. The logical chain still exists, but any physical resources should be reclaimed by the adaptation.

                The following diagram shows the stream states:

                - A3F State Machine -
                A3F Tutorials

                The following tutorials are provided to help you create A3F solutions:

                • Audio Component Framework Tutorial

                • Audio Processing Tutorial

                See Also

                Advanced Audio Adaptation Framework Overview

                Sound Device Overview

                \ No newline at end of file + + + + + +Advanced Audio Adaptation Framework Technology Guide

                This document provides additional information about the Advanced Audio Adaptation Framework.

                Purpose

                The Advanced Audio Adaptation Framework (A3F) provides a common interface for accessing audio resources, playing tones, and configuring audio for playing and recording.

                Understanding A3F

                A3F functionality is provided by the CAudioContextFactory class. CAudioContextFactory is responsible for creating audio contexts. The Audio Context API (MAudioContext) maintains all audio components created in a context, where audio components are instances of the MAudioStream and MAudioProcessingUnit classes.

                An MAudioProcessingUnit is created in a context by giving the type of the processing unit such as codec and source sink. MAudioProcessingUnit allows extension interfaces to set additional audio processing unit settings.

                The Audio Stream API (MAudioStream) is an audio component that links together processing units into an audio stream. MAudioStream manages the audio processing state requested by the client and interacts with the audio processing units added to the stream. MAudioStream provides runtime control over a stream's (composite) behaviour and lifetime management of the entities in a stream (whether the state of the stream is uninitialized, initialized, idle, primed, active or dead). For more information, see Stream States.

                The Audio Context API allows a grouping notion for multimedia allocations. MAudioContext groups component actions made inside a context. This means any allocation or loss of resources which occurs in any single audio component affects all of the components grouped in the context.

                The Commit Cycle

                Changes made to an audio stream are handled in a transactional manner. If changes fail to be applied, then any other changes made to the stream are considered to fail also. The application of changes is dependent on a successful commit cycle. If there is a failure, a “rollback" mechanism is executed and the stream states are reverted to their previous state.

                The client requests changes through various Set() calls and then calls the MAudioContext::Commit() function. The platform-specific implementation then decides whether the Commit() request is allowed, possibly dictates new values if needed, and then applies the changes. If successful, the client is informed through callbacks. If there is a need to modify the context because resources are needed in another context, then the platform-specific implementation can take the resources by pre-empting the context. In this case, the client is informed about the pre-emption.

                The following diagram shows this behaviour:

                + A3F Commit / Pre-emption Cycle +

                Observers

                Most of the A3F API functions are asynchronous. For example, the functions Foo() or SetFoo() are followed with FooComplete(Tint aError) or FooSet(Tint aError).

                The following A3F observers are defined:

                • MAudioContextObserver

                  Informs with ContextEvent() about the commit cycle. Note that ContextEvent() is in the same thread context as the A3F client.

                • MAudioStreamObserver

                  Informs with StateEvent() about state changes

                • MAudioCodecObserver

                  Informs about completion of setters and getters.

                • MAudioGainControlObserver

                  Informs about changes in gain or changes in maximum gain values.

                • MAudioProcessingUnitObserver

                  Informs about any additional errors in audio processing units.

                • MMMFAudioDataConsumer

                  Informs about recorded buffer to be ready for storing. Also informs the client if there is a buffer to be ignored.

                • MMMFAudioDataSupplier

                  Informs about new buffer ready to be filled with audio data. Also informs the client if any requested buffer should be ignored.

                Stream States

                Clients using A3F should be aware that requested audio resources can be lost at any time while they are being used. A client with a higher importance can cause requests for resources to be denied or available resources to become unavailable. In these cases, the commit cycle informs the client through pre-emption events and the resulted stream state is usually demoted to the highest non-disturbing state.

                The possible audio stream states are described in the following table:

                State Description

                EUninitialized

                This is the state of the chain before it is initialized. However, the settings in the logical chain cannot be related to the adaptation because no adaptation has been selected yet.

                EInitialized

                This state is set after a successful initialization request.

                The physical adaptation has been selected but may not be fully allocated.

                There should be no externally visible buffers allocated at this point

                Note: For zero copy and shared chunk buffers, a stream in the EInitialized state should not require buffer consumption. This is an important issue if the base port only has 16 addressable chunks per process.

                In terms of DevSound compatibility, some custom interfaces are available at this point (although others may require further construction before they are available).

                EIdle

                All the chain resources are allocated. However, no processing time (other than that expended to put the chain into the EIdle state) is consumed in this phase.

                In the EIdle state, any existing allocated buffers continue to exist.

                The codec is allocated in terms of hardware memory consumption.

                A stream in the EIdle state can be ‘mid-file position’. There is no implied reset of position or runtime settings (that is, time played) by returning to EIdle.

                EPrimed

                This state is the same as EIdle but the stream can consume processing time by filling its buffers. The purpose of this state is to prepare a stream such that it is ready to play in as short a time as possible (for example, low-latency for audio chains which can be pre-buffered).

                Note that once the buffer is full, the stream may continue to use some processing time.

                There will not be an automatic transition to the EIdle state when the buffer is full. If such behaviour is desired, the client must request it.

                There will not be an automatic transition to EActive when the buffer is full. If such behaviour is desired, the client must request it.

                EActive

                The chain has the resources as EIdle and EPrimed but also has started to process the actions requested by the client.

                Note: A chain can be in the EActive state and performing a wide range of operations. However the semantics are that it is processing the stream and that it is consuming both processing and memory resources.

                EDead

                The stream can no longer function due to a fatal error. The logical chain still exists, but any physical resources should be reclaimed by the adaptation.

                The following diagram shows the stream states:

                + A3F State Machine +
                A3F Tutorials

                The following tutorials are provided to help you create A3F solutions:

                • Audio Component Framework Tutorial

                • Audio Processing Tutorial

                See Also

                Advanced Audio Adaptation Framework Overview

                Sound Device Overview

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B05B61B8-1217-441F-BAFA-C209C8F123C5.dita --- a/Symbian3/SDK/Source/GUID-B05B61B8-1217-441F-BAFA-C209C8F123C5.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-B05B61B8-1217-441F-BAFA-C209C8F123C5.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,62 +1,64 @@ - - - - - -Toolbar -APIThe Toolbar API is used for enabling quick access to functions -by displaying them in a toolbar. -

                A toolbar contains AVKON buttons. The toolbar supports touch, and can be -with focus or without focus. It contains application-specific buttons (at -least three) that launch application-specific commands. The toolbar content -is application-specific, but you can choose whether the toolbar is displayed -in an application view or not.

                -

                The Toolbar API supports two types of toolbars: a fixed toolbar for touch -UI, and a floating toolbar which can also be used in non-touch UIs.

                - -Fixed toolbar, floating toolbar, and toolbar extension - - -

                The fixed toolbar doesn’t have focus, whereas the floating toolbar owns -the focus and it can be used also with navigation and selection keys. By default, -the floating toolbar owns the CBA buttons (Select and Close) -but the floating toolbar can be defined as not having the CBA buttons with -suitable flags.

                -

                The toolbars are also located differently: a fixed toolbar has a permanent -place in the layout but a floating toolbar can be freely located when it is -defined as having a flexible position.

                -

                The toolbar extension is a toolbar button that expands the fixed or floating -toolbar. When the extension button is pressed, a grid of toolbar items opens -up. The extension items can be used as actual toolbar items.

                -

                The extension button itself looks like an ordinary toolbar button. The -only difference is that there is a default icon for the extension button that -is shown if the application does not change the icon itself.

                -

                For user experience guidelines on the toolbar component, please see the toolbar UI component description.

                -

                For information -on using the API, see Enabling -quick access to functions with a toolbar.

                For the Toolbar API -classes and header files, see Classes and Definitions.

                -
                Constraints

                This -API is valid for all platforms running on Symbian OS v9.3 or later.

                -
                Emulator support

                This -API is supported in the WINS/WINSCW emulator environment, with the following -exception:

                  -

                • Tactile feedback is not supported.

                  • -
                -                 -Related APIs -Generic button -API - for creating toolbar buttons - -Form API - for including editable fields in fixed toolbar extensions - - + + + + + +Toolbar +APIThe Toolbar API is used for enabling quick access to functions +by displaying them in a toolbar. +

                A toolbar contains AVKON buttons. The toolbar supports touch, and can be +with focus or without focus. It contains application-specific buttons (at +least three) that launch application-specific commands. The toolbar content +is application-specific, but you can choose whether the toolbar is displayed +in an application view or not.

                +

                The Toolbar API supports two types of toolbars: a fixed toolbar for touch +UI, and a floating toolbar which can also be used in non-touch UIs.

                + +Fixed toolbar, floating toolbar, and toolbar extension + + +

                The fixed toolbar doesn’t have focus, whereas the floating toolbar owns +the focus and it can be used also with navigation and selection keys. By default, +the floating toolbar owns the CBA buttons (Select and Close) +but the floating toolbar can be defined as not having the CBA buttons with +suitable flags.

                +

                The toolbars are also located differently: a fixed toolbar has a permanent +place in the layout but a floating toolbar can be freely located when it is +defined as having a flexible position.

                +

                The toolbar extension is a toolbar button that expands the fixed or floating +toolbar. When the extension button is pressed, a grid of toolbar items opens +up. The extension items can be used as actual toolbar items.

                +

                The extension button itself looks like an ordinary toolbar button. The +only difference is that there is a default icon for the extension button that +is shown if the application does not change the icon itself.

                +

                For user experience guidelines on the toolbar component, please see the toolbar UI component description.

                +

                For information +on using the API, see Enabling +quick access to functions with a toolbar.

                For the Toolbar API +classes and header files, see Classes and Definitions.

                +
                Changes and release information

                The Toolbar API +is an SDK API and first released in S60 5th Edition.

                +
                Constraints

                This +API is valid for all platforms running on Symbian OS v9.3 or later.

                +
                Emulator support

                This +API is supported in the WINS/WINSCW emulator environment, with the following +exception:

                  +

                • Tactile feedback is not supported.

                  • +
                +                 +Related APIs +Generic button +API + for creating toolbar buttons + +Form API + for including editable fields in fixed toolbar extensions + +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B0797210-4EE3-557B-A5A6-D215D030BA0E_d0e184810_href.png Binary file Symbian3/SDK/Source/GUID-B0797210-4EE3-557B-A5A6-D215D030BA0E_d0e184810_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B0797210-4EE3-557B-A5A6-D215D030BA0E_d0e191406_href.png Binary file Symbian3/SDK/Source/GUID-B0797210-4EE3-557B-A5A6-D215D030BA0E_d0e191406_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B0EF8500-0A49-5EA8-B7FF-8149E5F03693.dita --- a/Symbian3/SDK/Source/GUID-B0EF8500-0A49-5EA8-B7FF-8149E5F03693.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-B0EF8500-0A49-5EA8-B7FF-8149E5F03693.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,22 +1,22 @@ - - - - - -How to use the SIP Client API
                Protocols

                The following sections describe how to do the following:

                • Starting the SIP Client

                • Closing SIP Client

                • Sending a SIP request

                • Receiving a SIP request

                • Receiving a SIP request and creating a session

                • Registration

                • Creating a dialog with INVITE

                • Generating a '100 SIP response'

                • Responding to a CANCEL request

                • Sending a SIP request and responding to a HTTP Digest challenge

                • Notification of a failed refresh

                • Error handling

                • Refreshing a Connection

                Starting the SIP Client

                To start the SIP Client:

                1. Create an instance of the CSIP class. The CSIP class creates a CSIP object and implements the callback functions defined by MSIPObserver. The CSIP object connects the client to a shared server.

                  Note: The server is started if it is not active. This may take a short time while the server side resources are created and initialised.

                2. Create an instance of the CSIPConnection class to use an IAP. The CSIPConnection class must implement the callback functions defined by MSIPConnectionObserver. The CSIPConnection class creates CSIPConnection object. The CSIPConnection object forms a sub-session between the client and the server.

                3. Call the CSIPConnection::NewL() function to create an active connection. The CSIPConnection::EActive state indicates that the object can be used to send SIP messages and create registrations and dialogs. The current state is asked by calling CSIPConnection::State(). The MSIPConnectionObserver::ConnectionStateChanged(CSIPConnection:: - EActive) callback function is called.

                The following illustration shows the sequence of events involved in starting the SIP Client API.

                Closing the SIP Client

                To close the SIP Client:

                • Delete the CSIP object to close the connection to the SIP server.

                • Delete the CSIPConnection object to close the sub-session between the client and the server.

                • When the connection has been closed, operations on objects that depend on the connection fail with the KErrSIPResourceNotAvailable error code.

                For example, if an application has CSIPConnection and CSIPRegistrationBinding objects, and it deletes the CSIPConnection object, then subsequent attempts to use the CSIPRegistrationBinding object fails. This is because CSIPRegistrationBinding cannot communicate with the server side of the SIP stack without the CSIPConnection object.

                The following illustration shows the order for deleting SIP Client API objects.

                Sending a SIP request

                To send a SIP request:

                • Create a CSIPRequestElements object and enter the required fields of the request.

                • Call the CSIPConnection::SendRequestL(CSIPRequestElements*) function to take control of the CSIPRequestElements objects and communicate the request to the server side of the SIP stack.

                  CSIPConnection creates a CSIPClientTransaction object and returns it to the application.

                Note: SendRequestL() starts the server side processing of sending the MESSAGE request. This task takes time as address resolving and socket operations are done only after the SendRequestL() call is returned. If an error occurs after SendRequestL() returns, then the error is communicated to the application through one of the MSIPConnectionObserver::ErrorOccured() callback functions. An example of such a failure is failure to resolve the address. When SendRequestL() returns, the MESSAGE request is not yet sent to the network, and is being processed on the server side of the SIP stack.

                After SendRequestL() returns and the sending of a MESSAGE request is in progress on the shared server, there is no way for the application to cancel that operation. This also applies to other operation types. However the CSIPClientTransaction::CancelL() function is used to send a CANCEL request after the application sends an INVITE request.

                When the SIP response is received from the server side, the CSIPConnection object:

                1. creates a CSIPResponseElements object to represent the SIP response

                2. attaches it to the CSIPClientTransaction object

                3. notifies the application through a call to one of the MSIPConnectionObserver:: IncomingResponse() callback functions.

                The application determines the kind of response received by accessing the CSIPResponseElements object through CSIPClientTransaction. As the response is provisional, the application does not delete the CSIPClientTransaction object. A '200 response' is received later, and the application then deletes the CSIPClientTransaction object.

                Then, create a CSIPResponseElements object to represent the SIP response, attach it to CSIPClientTransaction and notify the application with MSIPConnectionObserver:: - IncomingResponse.

                The following illustration shows the sequence of events involved in sending a MESSAGE request and receiving two responses to it.

                Receiving a SIP request

                A standalone SIP request is received through an existing CSIPConnection object. The CSIPConnection creates CSIPRequestElements and CSIPServerTransaction objects before notifying the application through the MSIPConnectionObserver::IncomingRequest() callback function. The CSIPRequestElements and CSIPServerTransaction represent the incoming SIP request

                The CSIPServerTransaction object is passed to the CSIPRequestElements object through the callback function. The application retrieves information about the request from the CSIPServerTransaction object.

                To send a response, the application creates a CSIPResponseElements object and passes it to CSIPServerTransaction::SendResponseL(). This passes the response to the server side for further processing. When SendResponseL() is returned, the application no longer needs the CSIPServerTransaction object and deletes it.

                The following illustration shows the sequence of events involved in receiving a MESSAGE request and sending a response to it.

                Receiving a SIP request and creating a session

                The SIP stack receives a SIP INVITE request from the network acting as a User Agent Server (UAS) and creates an invite server transaction for the received request. The SIP stack sends a '100 SIP response' to the remote UA. After comparing the received request with the stored application capabilities, the SIP stack routes the received INVITE request to the chosen application.

                The application creates a CSIPInviteDialogAssoc object and the SIP stack creates an instance of CSIPDialog. The application sends a '200 SIP response' to the remote UA. The remote UA acknowledges the '200 SIP' response with ACK and creates a SIP session is between the local and remote UA.

                The following illustration shows the sequence of events involved in receiving a SIP request and creating a SIP dialog.

                Registration

                An application creates a CSIPRefresh object to initiate a registration. It then creates a CSIPRegistrationBinding object, passing CSIPRefresh to it.

                Note: It is not mandatory to create a CSIPRefresh object. It is required if the registration is to be refreshed by the SIP stack.

                After the CSIPRegistrationBinding object exists, the application initiates the registration process by calling RegisterL() on the CSIPRegistrationBinding object. CSIPRegistrationBinding forms a REGISTER request and communicates it to the server side of the SIP stack, it instantiates the CSIPClientTransaction object and returns it to the application.

                When the '200 SIP response' is received from the server side, CSIPConnection creates the CSIPResponseElements object to contain the response, and then routes the response to CSIPRegistrationBinding. CSIPRegistrationBinding attaches the response to CSIPClientTransaction. The application is informed about the response through one of the MSIPConnectionObserver::IncomingResponse() callback functions.

                The application does not require the CSIPClientTransaction object and can delete it. The IsContextActive() finds out if the registration is successful.

                The following illustration shows the sequence of events involved in registering with a refresh and receiving a '200 OK response'.

                Configuring the registration

                When registering an SIP connection, applications have two options to configure the registration : outbound proxy caching and expiration value removal. To set each of these options, call CSIPRegistrationBinding::SetProperty() with the corresponding property constant, as explained below.

                The SIP stack resolves the IP address of the outbound proxy during registration. The default behavior is to resolve the address again for each SIP message sent using this registration context. However, you can also cache the address to optimise network traffic. If you set KSIPCacheOutboundProxyIP property to ETrue, the SIP stack reuses the proxy address that was resolved during registration. The proxy address is refreshed by successful REGISTER transactions, which always perform a DNS query.

                By default, the SIP stack sends the expiration value in the REGISTER request. In the '200 OK' answer to a REGISTER message, the registrar returns an expiration value that may be different from the value that was sent. The SIP stack validates the returned expiration value against the minimum and maximum expiration values: if the returned expiration value is out of range, the SIP stack uses the minimum value or the maximum value.

                • The minimum expiration value is 30 seconds, to reduce network activity and battery consumption.

                • The maximum expiration value is the expiration value that you specify for the REGISTER request. By default, the maximum expiration value is 3600 seconds, to protect the application from DOS attacks that provide '200 OK' responses with a very high expiration value.

                If you set KSIPSendWithExpires to EFalse, the SIP stack does not send the application's expiration value in the REGISTER message.

                Creating a dialog with INVITE

                To create a dialog with INVITE an application creates CSIPInviteDialogAssoc and CSIPMessageElements objects. The application must enter the relevant SIP headers in the CSIPMessageElements object before passing it to CSIPInviteDialogAssoc using the CSIPInviteDialogAssoc::SendInviteL() function.

                CSIPInviteDialogAssoc then forms an INVITE request and communicates it to the server side of the SIP stack. It then creates a CSIPClientTransaction object, and returns it to the application.

                When the server sends '180 response', the CSIPConnection creates a CSIPResponseElements object to contain the response, and then routes the response to CSIPDialog. CSIPDialog attaches the response to CSIPClientTransaction. The application is informed about the receipt of the '180 response' through a call to one of the MSIPConnectionObserver:: IncomingResponse() callback functions.

                When the '200 response' is received, processing similar to '180 response' occurs. Then the application responds by sending an ACK request. This is done by invoking the CSIPInviteDialogAssoc::SendAckL() function, which forms the ACK request and sends it to the server side of the SIP stack.

                The INVITE request might fork at a proxy, so the server side of the SIP stack waits for several possible responses. When the forking is does not happen, the server side of the SIP stack sends an InviteCompleted event. The SIP Client API forwards the InviteCompleted event to the application, indicating that the application can now delete the CSIPClientTransaction.

                The following figure shows the sequence of events involved in sending an INVITE, receiving a response and sending an ACK.

                Generating a '100 SIP response'

                The SIP stack generates a '100 response' automatically when it receives an INVITE request from the network. Applications are not allowed to send '100 responses'.

                Responding to a CANCEL request

                When the SIP stack receives a CANCEL request from the network, it automatically responds to it. CANCEL requests are never passed to an application.

                If the SIP stack:

                • does not find a matching transaction for a CANCEL request, it automatically generates a '481 response'.

                • finds a matching transaction for a CANCEL request, it automatically generates a '200 response'.

                • finds a matching INVITE server transaction that is in the Proceeding state (that is a final response is not yet sent), it also automatically generates a '487 response' to the INVITE transaction.

                After these actions are complete, the SIP stack informs the application by calling the MSIPConnectionObserver::InviteCanceled() callback function.

                Sending a SIP request and responding to a HTTP Digest challenge

                A SIP server in the signalling chain challenges any SIP request initiated by the application with an HTTP Digest challenge by responding with a '401 SIP response', '407 SIP response' or a '494 SIP response'. The responses contain details of the challenge. These responses are never passed directly to the application. Instead, they are passed to the application through a call to the callback function MSIPHttpDigestChallengeObserver::ChallengeReceived().

                To enable an application to respond to a challenge, it must:

                • create a CSIPHttpDigest object

                • provide an implementation of the callback function MSIPHttpDigestChallengeObserver::ChallengeReceived() .

                The application can either accept or reject the challenge:

                • If it accepts the challenge, the callback function must call CSIPHttpDigest::SetCredentialsL(), specifying the username, password, and the realm passed to the callback function.

                  Then, SIP stack re-sends the original SIP request with the HTTP Digest response.

                • If it rejects the challenge, the callback function must call CSIPHttpDigest::IgnoreChallenge(), specifying the realm passed to the callback function.

                  Then, SIP stack calls the callback function MSIPConnectionObserver::ErrorOccured(), by passing the error code KErrSIPForbidden.

                If an application does not want to receive the HTTP Digest challenge then it must not create a CSIPHttpDigest object. In this event, the SIP stack calls the callback function MSIPConnectionObserver::ErrorOccured(), passing the error code KErrSIPForbidden.

                Note:

                • If an application uses the SIP Profile Agent for SIP registration, the SIP Profile Agent handles the HTTP Digest challenges related to the registration procedure according to the SIP profile information.

                • The SIP stack maintains a HTTP Digest cache which stores username and password pairs for realms. If the username and password have been configured for a proxy, or if the application has already provided them after being asked through a MSIPHttpDigestChallengeObserver::ChallengeReceived() call, then the SIP stack uses them to answer subsequent challenges for a matching realm automatically.

                  For example, if the application uses a SIP Profile whose proxy is configured with HTTP Digest passwords and then sends an INVITE, it does not need to provide the passwords for the proxy as the SIP stack gets it from the HTTP Digest cache.

                Notification of a failed refresh

                The following example shows how an application is notified when a refresh request within a dialog terminates after an error occurs. In this example the application sends a SUBSCRIBE request with refresh, and receives a 2xx class response. The SIP stack periodically sends a refreshed SUBSCRIBE message. After successfully refreshed SUBSCRIBE requests, the remote server responds with a '481 response', and the application receives the following callback:

                MSIPConnectionObserver::ErrorOccured(TInt aError, CSIPDialogAssocBase& aDialogAssoc)

                If the value of aError is KErrSIPTerminatedWithResponse, then the actual SIP response causing the refresh to end can be found as follows:

                • Check that aDialogAssoc.Type() returns "SUBSCRIBE".

                • Call the function with the following signature to get the refresh instance (CSIPRefresh object):

                  const CSIPRefresh* CSIPSubscribeDialogAssoc::SIPRefresh() const

                • Use the CSIPRefresh object to get the associated transaction by calling the following function:

                  const CSIPClientTransaction* CSIPRefresh::SIPTransaction() const

                  Note: The returned CSIPClientTransaction object is not similar to the one returned from the call to SendSubscribeL(), that the application originally used to send the SUBSCRIBE request.

                • Call the following function to get the SIP response:

                  const CSIPResponseElements* CSIPClientTransaction::ResponseElements() const
                Error handling

                Errors are passed to an application by calling the callback functions or by leaving. For more information, see Cleanup support overview. If an error occurs during the synchronous part of an operation is initiated by the application, functions leave with an error code. If an error occurs during the asynchronous processing stage, the error is passed to the application through one of the MSIPConnectionObserver::ErrorOccured() callback functions.

                There are several overloaded variants of ErrorOccured() functions. Each of them takes the error code and reference to the SIP Client API object that encountered the error:

                • A call to the variants of ErrorOccured() taking a CSIPTransactionBase or CSIPClientTransaction parameter means that transaction has entered the state CTransactionBase::ETerminated.

                • A call to the variant of ErrorOccured() taking a CSIPRegistrationBinding parameter means that the registration context is no longer active, that is CSIPRegistrationBinding::IsContextActive() == EFalse.

                  If the registration was being refreshed, then the refresh has also ended and its state is CSIPRefresh::ETerminated.

                If the callback function MSIPConnectionObserver::ConnectionStateChanged() is called and the aState parameter is either CSIPConnection::EInactive or CSIPConnection::EUnavailable, then all dialogs, registrations, and standalone transactions using the CSIPConnection are terminated.

                To avoid an overload of callback calls in this type of situation, calls to ErrorOccured() for the individual dialog, registration and transaction objects are not sent to the application.

                When the connection state changes, the MSIPConnectionObserver::ConnectionStateChanged() callback function does not provide a reason. Call CSIPConnection::GetConnectionError() to get details about the connection error that caused the change.

                Refreshing a Connection

                To refresh a connection, do the following steps:

                1. Start the connection on the desired IAP.

                2. Monitor the status of the connection using the MSIPConnectionObserver::ConnectionStateChanged(CSIPConnection::TState - aState) function.

                3. If the connection is inactive, notify the EInactive state to the application through MSIPConnectionObserver::ConnectionStateChanged() function that is, if (CSIPConnection::TState == EInactive), then send a RefreshConnection() function to make it active.

                  Note: This requires a bearer monitor on that IAP to which a refresh request is sent.

                4. Any changes to the state of the connection is notified through MSIPConnectionObserver::ConnectionStateChanged().

                The following sequence diagram shows how a client refreshes a connection.

                The following example code describes how to refresh a connection.

                // It is assumed that the connection is started and is in an Inactive state that is, -// (CSIPConnection::TState == EInactive) - -// Refresh the IAP ID of the connection by sending a Refresh Request to the Bearer monitor of the IAP -CSIPConnection:: RefreshConnection() - -// Note: The application is notified of the changes in the state of the connection through the + + + + + +How to use the SIP Client API
                Protocols

                The following sections describe how to do the following:

                • Starting the SIP Client

                • Closing SIP Client

                • Sending a SIP request

                • Receiving a SIP request

                • Receiving a SIP request and creating a session

                • Registration

                • Creating a dialog with INVITE

                • Generating a '100 SIP response'

                • Responding to a CANCEL request

                • Sending a SIP request and responding to a HTTP Digest challenge

                • Notification of a failed refresh

                • Error handling

                • Refreshing a Connection

                Starting the SIP Client

                To start the SIP Client:

                1. Create an instance of the CSIP class. The CSIP class creates a CSIP object and implements the callback functions defined by MSIPObserver. The CSIP object connects the client to a shared server.

                  Note: The server is started if it is not active. This may take a short time while the server side resources are created and initialised.

                2. Create an instance of the CSIPConnection class to use an IAP. The CSIPConnection class must implement the callback functions defined by MSIPConnectionObserver. The CSIPConnection class creates CSIPConnection object. The CSIPConnection object forms a sub-session between the client and the server.

                3. Call the CSIPConnection::NewL() function to create an active connection. The CSIPConnection::EActive state indicates that the object can be used to send SIP messages and create registrations and dialogs. The current state is asked by calling CSIPConnection::State(). The MSIPConnectionObserver::ConnectionStateChanged(CSIPConnection:: + EActive) callback function is called.

                The following illustration shows the sequence of events involved in starting the SIP Client API.

                Closing the SIP Client

                To close the SIP Client:

                • Delete the CSIP object to close the connection to the SIP server.

                • Delete the CSIPConnection object to close the sub-session between the client and the server.

                • When the connection has been closed, operations on objects that depend on the connection fail with the KErrSIPResourceNotAvailable error code.

                For example, if an application has CSIPConnection and CSIPRegistrationBinding objects, and it deletes the CSIPConnection object, then subsequent attempts to use the CSIPRegistrationBinding object fails. This is because CSIPRegistrationBinding cannot communicate with the server side of the SIP stack without the CSIPConnection object.

                The following illustration shows the order for deleting SIP Client API objects.

                Sending a SIP request

                To send a SIP request:

                • Create a CSIPRequestElements object and enter the required fields of the request.

                • Call the CSIPConnection::SendRequestL(CSIPRequestElements*) function to take control of the CSIPRequestElements objects and communicate the request to the server side of the SIP stack.

                  CSIPConnection creates a CSIPClientTransaction object and returns it to the application.

                Note: SendRequestL() starts the server side processing of sending the MESSAGE request. This task takes time as address resolving and socket operations are done only after the SendRequestL() call is returned. If an error occurs after SendRequestL() returns, then the error is communicated to the application through one of the MSIPConnectionObserver::ErrorOccured() callback functions. An example of such a failure is failure to resolve the address. When SendRequestL() returns, the MESSAGE request is not yet sent to the network, and is being processed on the server side of the SIP stack.

                After SendRequestL() returns and the sending of a MESSAGE request is in progress on the shared server, there is no way for the application to cancel that operation. This also applies to other operation types. However the CSIPClientTransaction::CancelL() function is used to send a CANCEL request after the application sends an INVITE request.

                When the SIP response is received from the server side, the CSIPConnection object:

                1. creates a CSIPResponseElements object to represent the SIP response

                2. attaches it to the CSIPClientTransaction object

                3. notifies the application through a call to one of the MSIPConnectionObserver:: IncomingResponse() callback functions.

                The application determines the kind of response received by accessing the CSIPResponseElements object through CSIPClientTransaction. As the response is provisional, the application does not delete the CSIPClientTransaction object. A '200 response' is received later, and the application then deletes the CSIPClientTransaction object.

                Then, create a CSIPResponseElements object to represent the SIP response, attach it to CSIPClientTransaction and notify the application with MSIPConnectionObserver:: + IncomingResponse.

                The following illustration shows the sequence of events involved in sending a MESSAGE request and receiving two responses to it.

                Receiving a SIP request

                A standalone SIP request is received through an existing CSIPConnection object. The CSIPConnection creates CSIPRequestElements and CSIPServerTransaction objects before notifying the application through the MSIPConnectionObserver::IncomingRequest() callback function. The CSIPRequestElements and CSIPServerTransaction represent the incoming SIP request

                The CSIPServerTransaction object is passed to the CSIPRequestElements object through the callback function. The application retrieves information about the request from the CSIPServerTransaction object.

                To send a response, the application creates a CSIPResponseElements object and passes it to CSIPServerTransaction::SendResponseL(). This passes the response to the server side for further processing. When SendResponseL() is returned, the application no longer needs the CSIPServerTransaction object and deletes it.

                The following illustration shows the sequence of events involved in receiving a MESSAGE request and sending a response to it.

                Receiving a SIP request and creating a session

                The SIP stack receives a SIP INVITE request from the network acting as a User Agent Server (UAS) and creates an invite server transaction for the received request. The SIP stack sends a '100 SIP response' to the remote UA. After comparing the received request with the stored application capabilities, the SIP stack routes the received INVITE request to the chosen application.

                The application creates a CSIPInviteDialogAssoc object and the SIP stack creates an instance of CSIPDialog. The application sends a '200 SIP response' to the remote UA. The remote UA acknowledges the '200 SIP' response with ACK and creates a SIP session is between the local and remote UA.

                The following illustration shows the sequence of events involved in receiving a SIP request and creating a SIP dialog.

                Registration

                An application creates a CSIPRefresh object to initiate a registration. It then creates a CSIPRegistrationBinding object, passing CSIPRefresh to it.

                Note: It is not mandatory to create a CSIPRefresh object. It is required if the registration is to be refreshed by the SIP stack.

                After the CSIPRegistrationBinding object exists, the application initiates the registration process by calling RegisterL() on the CSIPRegistrationBinding object. CSIPRegistrationBinding forms a REGISTER request and communicates it to the server side of the SIP stack, it instantiates the CSIPClientTransaction object and returns it to the application.

                When the '200 SIP response' is received from the server side, CSIPConnection creates the CSIPResponseElements object to contain the response, and then routes the response to CSIPRegistrationBinding. CSIPRegistrationBinding attaches the response to CSIPClientTransaction. The application is informed about the response through one of the MSIPConnectionObserver::IncomingResponse() callback functions.

                The application does not require the CSIPClientTransaction object and can delete it. The IsContextActive() finds out if the registration is successful.

                The following illustration shows the sequence of events involved in registering with a refresh and receiving a '200 OK response'.

                Configuring the registration

                When registering an SIP connection, applications have two options to configure the registration : outbound proxy caching and expiration value removal. To set each of these options, call CSIPRegistrationBinding::SetProperty() with the corresponding property constant, as explained below.

                The SIP stack resolves the IP address of the outbound proxy during registration. The default behavior is to resolve the address again for each SIP message sent using this registration context. However, you can also cache the address to optimise network traffic. If you set KSIPCacheOutboundProxyIP property to ETrue, the SIP stack reuses the proxy address that was resolved during registration. The proxy address is refreshed by successful REGISTER transactions, which always perform a DNS query.

                By default, the SIP stack sends the expiration value in the REGISTER request. In the '200 OK' answer to a REGISTER message, the registrar returns an expiration value that may be different from the value that was sent. The SIP stack validates the returned expiration value against the minimum and maximum expiration values: if the returned expiration value is out of range, the SIP stack uses the minimum value or the maximum value.

                • The minimum expiration value is 30 seconds, to reduce network activity and battery consumption.

                • The maximum expiration value is the expiration value that you specify for the REGISTER request. By default, the maximum expiration value is 3600 seconds, to protect the application from DOS attacks that provide '200 OK' responses with a very high expiration value.

                If you set KSIPSendWithExpires to EFalse, the SIP stack does not send the application's expiration value in the REGISTER message.

                Creating a dialog with INVITE

                To create a dialog with INVITE an application creates CSIPInviteDialogAssoc and CSIPMessageElements objects. The application must enter the relevant SIP headers in the CSIPMessageElements object before passing it to CSIPInviteDialogAssoc using the CSIPInviteDialogAssoc::SendInviteL() function.

                CSIPInviteDialogAssoc then forms an INVITE request and communicates it to the server side of the SIP stack. It then creates a CSIPClientTransaction object, and returns it to the application.

                When the server sends '180 response', the CSIPConnection creates a CSIPResponseElements object to contain the response, and then routes the response to CSIPDialog. CSIPDialog attaches the response to CSIPClientTransaction. The application is informed about the receipt of the '180 response' through a call to one of the MSIPConnectionObserver:: IncomingResponse() callback functions.

                When the '200 response' is received, processing similar to '180 response' occurs. Then the application responds by sending an ACK request. This is done by invoking the CSIPInviteDialogAssoc::SendAckL() function, which forms the ACK request and sends it to the server side of the SIP stack.

                The INVITE request might fork at a proxy, so the server side of the SIP stack waits for several possible responses. When the forking is does not happen, the server side of the SIP stack sends an InviteCompleted event. The SIP Client API forwards the InviteCompleted event to the application, indicating that the application can now delete the CSIPClientTransaction.

                The following figure shows the sequence of events involved in sending an INVITE, receiving a response and sending an ACK.

                Generating a '100 SIP response'

                The SIP stack generates a '100 response' automatically when it receives an INVITE request from the network. Applications are not allowed to send '100 responses'.

                Responding to a CANCEL request

                When the SIP stack receives a CANCEL request from the network, it automatically responds to it. CANCEL requests are never passed to an application.

                If the SIP stack:

                • does not find a matching transaction for a CANCEL request, it automatically generates a '481 response'.

                • finds a matching transaction for a CANCEL request, it automatically generates a '200 response'.

                • finds a matching INVITE server transaction that is in the Proceeding state (that is a final response is not yet sent), it also automatically generates a '487 response' to the INVITE transaction.

                After these actions are complete, the SIP stack informs the application by calling the MSIPConnectionObserver::InviteCanceled() callback function.

                Sending a SIP request and responding to a HTTP Digest challenge

                A SIP server in the signalling chain challenges any SIP request initiated by the application with an HTTP Digest challenge by responding with a '401 SIP response', '407 SIP response' or a '494 SIP response'. The responses contain details of the challenge. These responses are never passed directly to the application. Instead, they are passed to the application through a call to the callback function MSIPHttpDigestChallengeObserver::ChallengeReceived().

                To enable an application to respond to a challenge, it must:

                • create a CSIPHttpDigest object

                • provide an implementation of the callback function MSIPHttpDigestChallengeObserver::ChallengeReceived() .

                The application can either accept or reject the challenge:

                • If it accepts the challenge, the callback function must call CSIPHttpDigest::SetCredentialsL(), specifying the username, password, and the realm passed to the callback function.

                  Then, SIP stack re-sends the original SIP request with the HTTP Digest response.

                • If it rejects the challenge, the callback function must call CSIPHttpDigest::IgnoreChallenge(), specifying the realm passed to the callback function.

                  Then, SIP stack calls the callback function MSIPConnectionObserver::ErrorOccured(), by passing the error code KErrSIPForbidden.

                If an application does not want to receive the HTTP Digest challenge then it must not create a CSIPHttpDigest object. In this event, the SIP stack calls the callback function MSIPConnectionObserver::ErrorOccured(), passing the error code KErrSIPForbidden.

                Note:

                • If an application uses the SIP Profile Agent for SIP registration, the SIP Profile Agent handles the HTTP Digest challenges related to the registration procedure according to the SIP profile information.

                • The SIP stack maintains a HTTP Digest cache which stores username and password pairs for realms. If the username and password have been configured for a proxy, or if the application has already provided them after being asked through a MSIPHttpDigestChallengeObserver::ChallengeReceived() call, then the SIP stack uses them to answer subsequent challenges for a matching realm automatically.

                  For example, if the application uses a SIP Profile whose proxy is configured with HTTP Digest passwords and then sends an INVITE, it does not need to provide the passwords for the proxy as the SIP stack gets it from the HTTP Digest cache.

                Notification of a failed refresh

                The following example shows how an application is notified when a refresh request within a dialog terminates after an error occurs. In this example the application sends a SUBSCRIBE request with refresh, and receives a 2xx class response. The SIP stack periodically sends a refreshed SUBSCRIBE message. After successfully refreshed SUBSCRIBE requests, the remote server responds with a '481 response', and the application receives the following callback:

                MSIPConnectionObserver::ErrorOccured(TInt aError, CSIPDialogAssocBase& aDialogAssoc)

                If the value of aError is KErrSIPTerminatedWithResponse, then the actual SIP response causing the refresh to end can be found as follows:

                • Check that aDialogAssoc.Type() returns "SUBSCRIBE".

                • Call the function with the following signature to get the refresh instance (CSIPRefresh object):

                  const CSIPRefresh* CSIPSubscribeDialogAssoc::SIPRefresh() const

                • Use the CSIPRefresh object to get the associated transaction by calling the following function:

                  const CSIPClientTransaction* CSIPRefresh::SIPTransaction() const

                  Note: The returned CSIPClientTransaction object is not similar to the one returned from the call to SendSubscribeL(), that the application originally used to send the SUBSCRIBE request.

                • Call the following function to get the SIP response:

                  const CSIPResponseElements* CSIPClientTransaction::ResponseElements() const
                Error handling

                Errors are passed to an application by calling the callback functions or by leaving. For more information, see Cleanup support overview. If an error occurs during the synchronous part of an operation is initiated by the application, functions leave with an error code. If an error occurs during the asynchronous processing stage, the error is passed to the application through one of the MSIPConnectionObserver::ErrorOccured() callback functions.

                There are several overloaded variants of ErrorOccured() functions. Each of them takes the error code and reference to the SIP Client API object that encountered the error:

                • A call to the variants of ErrorOccured() taking a CSIPTransactionBase or CSIPClientTransaction parameter means that transaction has entered the state CTransactionBase::ETerminated.

                • A call to the variant of ErrorOccured() taking a CSIPRegistrationBinding parameter means that the registration context is no longer active, that is CSIPRegistrationBinding::IsContextActive() == EFalse.

                  If the registration was being refreshed, then the refresh has also ended and its state is CSIPRefresh::ETerminated.

                If the callback function MSIPConnectionObserver::ConnectionStateChanged() is called and the aState parameter is either CSIPConnection::EInactive or CSIPConnection::EUnavailable, then all dialogs, registrations, and standalone transactions using the CSIPConnection are terminated.

                To avoid an overload of callback calls in this type of situation, calls to ErrorOccured() for the individual dialog, registration and transaction objects are not sent to the application.

                When the connection state changes, the MSIPConnectionObserver::ConnectionStateChanged() callback function does not provide a reason. Call CSIPConnection::GetConnectionError() to get details about the connection error that caused the change.

                Refreshing a Connection

                To refresh a connection, do the following steps:

                1. Start the connection on the desired IAP.

                2. Monitor the status of the connection using the MSIPConnectionObserver::ConnectionStateChanged(CSIPConnection::TState + aState) function.

                3. If the connection is inactive, notify the EInactive state to the application through MSIPConnectionObserver::ConnectionStateChanged() function that is, if (CSIPConnection::TState == EInactive), then send a RefreshConnection() function to make it active.

                  Note: This requires a bearer monitor on that IAP to which a refresh request is sent.

                4. Any changes to the state of the connection is notified through MSIPConnectionObserver::ConnectionStateChanged().

                The following sequence diagram shows how a client refreshes a connection.

                The following example code describes how to refresh a connection.

                // It is assumed that the connection is started and is in an Inactive state that is, +// (CSIPConnection::TState == EInactive) + +// Refresh the IAP ID of the connection by sending a Refresh Request to the Bearer monitor of the IAP +CSIPConnection:: RefreshConnection() + +// Note: The application is notified of the changes in the state of the connection through the // ConnectionStateChanged() function of MSIPConnectionObserver Interface.
                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B10B048F-37FF-53E7-92B9-83F8C197566A.dita --- a/Symbian3/SDK/Source/GUID-B10B048F-37FF-53E7-92B9-83F8C197566A.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-B10B048F-37FF-53E7-92B9-83F8C197566A.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,22 +1,330 @@ - - - - - -Image Decoding

                This document gives you more information about the Image Decoding functionality.

                Purpose

                The image decoding class CImageDecoder provides functions to decode images held in descriptors or files from standard formats for use with devices such as screens, browsers and viewer applications.

                Required Background

                Image decoding features are provided through Imaging Frameworks and Imaging plugins. The standard formats supported by the decode plugins are shown in the table in Imaging Frameworks Overview.

                Introduction

                The decoding process comprises the following sections:

                • Creation - The creation of the CImageDecoder object and any requirements necessary.

                • Conversion - Covers the basic form of image decoding. More advanced features such as progressive and buffered decoding are described separately.

                • Enquiry features - Additional features that enable you to retrieve information stored in certain types of images, for example frame information and comments.

                • Streamed and progressive decoding - Reading partial image files and displaying image data before the entire image is read.

                • Buffered decoding - The decoding of an image using a buffered input rather than a file or descriptor.

                Setup and Configuration Requirements

                The CImageDecoder classes use synchronous methods to open an image and asynchronous methods to perform conversions or transformations. The asynchronous operations use the standard system of taking a pointer to a TRequestStatus object that is signalled on completion of the requested action. The assumption is that the client application or the calling DLL holds the TRequestStatus values within active objects. The structure of the active objects is dependent on the code that uses the Imaging Frameworks and its own requirements, particularly its internal architecture and how many images are opened simultaneously.

                In addition to the use of active objects in the interfacing, many of the Imaging Frameworks internal functions make extensive use of them to provide asynchronous behaviour. As with any use of an active object it is necessary to have an active scheduler in the same thread as the application making use of the object. The Decoders can also be created so the plugin and framework runs in a separate thread. This is achieved by setting the EOptionAlwaysThread option when constructing the decoder objects. By running the object in its own thread, the application is shielded from any latency that can occur during image conversion, or possibly due to a badly written plugin.

                Using Image Decoding

                The Following tasks are covered in this tutorial:

                • How to create the object during decoding

                • How to convert encoded data to decoded data

                • How to retrieve the information stored in certain types of images

                • How to perform the streaming and the progressive during decoding

                • How to perform the buffered decoding

                Basic Procedure For Creation

                The high level steps to create the object during decoding are as follows:

                1. CImageDecoder decodes images stored in files or in descriptors. The decoder object is owned by the client and must be deleted once decoding is finished. CImageDecoder objects cannot be reused to decode other images, each image requires its own instance of the decoder.

                2. CImageDecoder objects are created using the CImageDecoder::DataNewL() and CImageDecoder::FileNewL() factory functions for images held in descriptors or files respectively.

                3. When you create a CImageDecoder object, a suitable plugin must be associated with the image to be decoded. The Imaging plugin depends on the factory function you use to create the object and what parameters you specify. There are four alternatives:

                  • MIME type The plugin is determined by looking up a specified MIME type against a list of known MIME type/plugin implementations. Use the following "File" factory function (or its "Data" equivalent).

                    static CImageDecoder* FileNewL(RFs& aFs, const TDesC& aSourceFilename, const TDesC8& aMIMEType, const TOptions aOptions = EOptionNone); -

                  • Image type and sub-type The plugin is determined by looking up the specified image type and sub-types against a list of known type/sub-type plugin implementations. Use the following "File" factory function (or its "Data" equivalent).

                    static CImageDecoder* FileNewL(RFs& aFs, const TDesC& aSourceFilename, const TOptions aOptions = EOptionNone, const TUid aImageType = KNullUid, const TUid aImageSubType = KNullUid, const TUid aDecoderUid = KNullUid); -

                    Note: For images types that do not have sub-types use KNullUid.

                  • Implementation UID The plugin is determined by looking up its specific UID and the image type and sub-type. Use the same FileNewL() factory function shown in "Image type and sub-type", but in addition to the type and sub-type parameters, also specify the plugin UID using aDecoderUid.

                    Note: Implementation UID is supported because it is possible to have more than one plugin for a particular image type. This method is recommended if the application or calling DLL needs to exploit features of a particular plugin.

                  • Automatic detection - no MIME type, format type/sub-type or UIDs are specified. The plugin analyses the header information of the specified image. Use the same FileNewL() factory function shown in "Image type and sub-type", but do not specify any values for aImageType aImageSubType or aDecoderUid.

                    If a suitable plugin cannot be found, the factory function leaves with KErrNotFound. If a suitable plugin is found, but that plugin cannot interpret the image data the factory function leaves with KErrCorrupt.

                    Note: Some image formats cannot be automatically detected because they do not contain sufficient header information, for example, WBMP and OTA images. Under such circumstances, use one of the other three alternative for opening the image.

                It is possible for more than one valid plugin decoder to be available for a specific image format. If a plugin determined by MIME type or type/sub-type fails to open an image due to KErrCorrupt, it will continue to try with subsequent valid plugins if available. This mechanism is carried out in the system and is not visible to the application. If you require a specific function available within a specific plugin, specify that plugin using aDecoderUid.

                Basic Procedure For Conversion

                The high level steps to convert encoded data to decoded data are as follow:

                1. As part of the CImageDecoder creation basic information about the image is pre-read from the image headers. This information is used to support certain enquiry methods such as CImageDecoder::FrameCount() and CImageDecoder::FrameInfo() (For more information about the retrieve information stored in certain types of images is supplied in Retrieve Information features).

                2. You can decode any subset of individual frames, in any order, and to repeat the decoding if necessary. To decode an image frame use the asynchronous conversion method CImageDecoder::Convert(), as follows.

                -void Convert(TRequestStatus* aRequestStatus, CFbsBitmap& aDestination, TInt aFrameNumber = 0); - -void ContinueConvert(TRequestStatus* aRequestStatus);

                Note: The use of CImageDecoder::ContinueConvert() is described in Streamed and progressive decoding.

                There are different type of sub-procedures which have to be followed before decode conversion, they are:

                • Bitmap Masks conversion

                • Scaling and display modes

                • Animations

                • Background colours

                Basic Procedure For Bitmap Masks conversion

                The high level steps to Bitmap Masks conversion are as follows:

                1. There is a second variant of the Convert() function intended for use when decoding images with bitmap masks.

                  -void Convert(TRequestStatus* aRequestStatus, CFbsBitmap& aDestination, CFbsBitmap& aDestinationMask, TInt aFrameNumber = 0); -

                2. Within the Symbian platform it is normal to store the bitmap mask separately from the main image data. Calls such as BitBltMasked() expect this data to be provided separately. This separation is true for both CFbsBitmap objects and MBM files.

                3. To determine whether an image contains a bitmap mask use FrameInfo(), the presence or absence of a mask will be indicated the ETransparencyPossible flag.

                  The following two types of mask are available:

                  • 8-bit alpha blend - indicated by the EAlphaChannel flag of CImageDecoder::FrameInfo() iFlags. The destination mask bitmap must be of type EGray256.

                  • Simple on/off mask - if no EAlphaChannel flag is set. The destination bitmap mask can be either EGray2 or EGray256.

                Note: Images that contain bitmap masks do not have to have those masks decoded if they are not required.

                Basic Procedure For Scaling and display modes

                The high level steps to Scale and display are shown here:

                1. Before Convert() is used, the destination CFbsBitmap objects for image data and bitmap masks are created. The simplest way to do this is to use a 1 to 1 approach, that is, create the CFbsBitmap object with the same properties as the source image. This is achieved by using something similar to:

                  iFrameInfo = &imageDecoder->FrameInfo(FrameNum); - -iBitmap->Create(iFrameInfo->iOverallSizeInPixels, iFrameInfo->iFrameDisplayMode ); -

                2. If the ECanDither flag of CImageDecoder::FrameInfo() iFlags is set then the destination display mode can be adjusted. It is recommended that the window display mode is used as it is more efficient.

                  Note: The mask bitmap must have the same size in pixels as the main image, even though the display mode is generally different.

                3. The size of the image bitmap is available via FrameInfo() (iOverallSizeInPixels). However, in addition to a direct mapping of the size of an image, ReducedSize() function can be used to calculate the reduced size of the decoded bitmap based on the input parameters.

                4. If the EFullyScaleable flag of FrameInfo() iFlags is set, you can specify any size for the CFbsBitmap and the image will be resized accordingly.

                Basic Procedure For Animations

                The high level steps to decode a GIF multi-frame image are as follow:

                1. Included in the CImageDecoder::FrameInfo() result are flags that enable the support of GIF animation. These flags are iDelay, ELeaveInPlace, ERestoreToBackground and ERestoreToPrevious. ICL provides these flags to enable the application to implement the animation; ICL does not provide functions to display the animation directly.

                2. Processing the information from these flags will inevitably require a state machine, and additional timers, within the application. Requirements will vary depending on the architecture of the client application itself.

                Basic Procedure For Background colours

                1. Some image formats contain background colour information. This is information is presented through CImageDecoder::FrameInfo() iBackgroundColor.

                2. If a non-masked image with background colour is decoded, the colour is included in the image data. If the decoded image also contains a bitmap mask, then the background colour will be a component of the mask CFbsBitmap object. Depending on your application, you may want to choose your own background colour rather than use the one provided by the source image.

                Basic Procedure To Retrieve Information From An Image

                The high level steps to retrieve the information stored in certain types of images are shown here:

                1. CImageDecode::FrameData() Provides access to additional chunks of data within the images, for example, palette and similar lookup tables, copyright information and other strings. This information should be used with care, the returned data is merely a reference to the original data within the CImageDecoder object, and is only valid for the lifetime of the object.

                2. CImageDecode::NumberOfImageComments() and CImageDecode::ImageCommentL() Images can have comments embedded in them. These comments are usually either embedded as a single repository which can be retrieved on an image level, or multiple repositories attached to individual frames within the image. The two functions above return the number of comments attached to the entire image and provide a mechanism for retrieving any of those comments.

                3. CImageDecode::NumberOfFrameComments() and CImageDecode::FrameCommentL() Similar functionality to above, but these functions return the number of comments attached to individually specified frames and provide a mechanism for retrieving any of those comments.

                4. CImageDecode::FrameInfoStringsLC and CImageDecode::FrameInfoStringsL() Provide a list of data for a specified frame, including data items such as format, plugin description, size and so on, in a readable format. Although the property strings can be accessed by name, it is recommended that they be generally treated as a list of strings.

                Basic Procedure Streamed and Progressive Decoding

                CImageDecoder includes facilities to support the simultaneous decoding and display of images as they are being loaded. The decoder does not wait for the entire image to be loaded before processing it, rather it begins as soon as possible, stops when it runs out of data and then carries on when more data is available.

                The high level steps to perform the streaming and the progressive during decoding are shown here:

                1. If there is insufficient data to work out the image format (plugin decoder to use) CImageDecoder::FileNewL() (or its "Data" equivalent) leaves with KErrUnderflow. This is only applicable to instances where automatic detection of the plugin decoder is used. For more information see, "Automatic detection" in Creation.

                2. As soon as the correct plugin decoder has been determined it is opened and whatever addition image data available is scanned. The plugin decoder continues to decode image data as it arrives, updating FrameCount() whenever it becomes aware of a new frame within the data. The internal flag CImageDecoder::IsHeaderProcessingComplete() is maintained at EFalse until the entire image has been loaded.

                3. Frames can be decoded before the entire image is loaded, but the frame to be decoded must be at least partially loaded. If IsHeaderProcessingComplete() is set to EFalse and FrameCount() is equal to or less than the frame to decode, the application must wait for the relevant frame to load. In such circumstances a call to CImageDecoder::ContinueProcessingHeadersL() should be made that scans for any further headers. FrameCount() and IsHeaderProcessingComplete() should then be recalled to determine if the frame has arrived.

                4. Once FrameCount() is greater than the frame the application wants to decode, it is possible to start to decoding the frame using CImageDecoder::Convert(). Frame headers and their associated data do not always follow each other in some image formats. This has the implication that although FrameCount() has indicated that the frame is available, it may not yet be fully loaded. Under such circumstances as much decoding as possible is undertaken, and Convert() then completes with the error code KErrUnderflow. If the EPartialDecodeInvalid flag (from FrameInfo()) is not set, the partially decoded image can be displayed - for some image formats, a partially decoded image is not generally usable, but this facility is supported by most known formats. Obviously, if all of the image is present, Convert() completes with KErrNone as normal.

                5. Where only a partial conversion has been completed, CImageDecoder::ContinueConvert() should be used to continue converting when new data arrives. ContinueConvert() continues to convert the frame data where the previous call left off. This function should continue to be called until it returns the error code KErrNone rather than KErrUnderflow.

                  Note: The CFbsBitmap must never be resized during a conversion session using ContinueConvert(), if resizing does occur, a panic will be raised by the function. If resizing or any other parameter changes need to be made to the CFbsBitmap, frame decoding should be restarted by using Convert() rather than trying to continue an existing conversion session.

                There is no explicit decoder call to say "all of the data is now present". This could be done via inference, continuously checking IsHeaderProcessingComplete() until it returns ETrue. However, this is not advisable as it is possible that IsHeaderProcessingComplete() could continue to return EFalse even after the application has finished sending image data. Your state machine should be written so that it takes this possibility into account.

                Basic Procedure For Buffered Decoding

                CBufferedImageDecoder is a wrapper that encapsulates not only a CImageDecoder but also the descriptor used to store the image, and in some circumstances can replace the use of CImageDecoder itself. CBufferedImageDecoder can always be created, even if there is no data available at the time of creation. Another key feature of CBufferedImageDecoder is that it can be reused to decode multiple images.

                The high level steps to perform the buffered decoding are shown here:

                1. The decoder is created using the CBufferedImageDecoder::NewL() factory function, and the decoding process is started with one of the two CBufferedImageDecoder::OpenL() calls, specifying either MIME-type or image type/sub-type and UID, which are similar to CImageDecoder::DataNewL(). If not enough data is available to create an internal decoder a call to CBufferedImageDecoder::ValidDecoder() returns EFalse. The decoder keeps an internal copy of the data provided so the client can discard its own copy.

                  Warning: The decoding and enquiry functions must not be used until an internal decoder has been created, otherwise calls will panic with EDecoderNotCreated.

                2. Additional data can be supplied to the decoder, when it becomes available, by using CBufferedImageDecoder::AppendDataL() and CBufferedImageDecoder::ContinueOpenL(), which will copy the data and try to find an appropriate plugin. This step should be repeated until enough data is available to create the internal decoder, indicated by ValidDecoder() returning ETrue. OpenL() and ContinueOpenL() will leave with KErrCorrupt if a suitable decoder is found, but that decoder was unable to interpret the supplied image data.

                  Note: As with OpenL(), data provided by AppendDataL() is kept in an internal buffer by the decoder so the client can discard its own copy.

                3. The process for decoding the image header and frames are the same as for CImageDecoder with IsHeaderProcessingComplete(), FrameCount(), Convert() and ContinueConvert() calls except that the data is not appended to a descriptor, but supplied to the decoder with AppendDataL().

                4. The decoder can be reused by calling a CBufferedImageDecoder::Reset(), which destroys the internal data buffer and decoder. A new decoder plugin can then be started using OpenL().

                Imaging Frameworks overview Image Conversion Overview Image Encoding Tutorial Guide to Symbian supplied Codecs                 \ No newline at end of file + + + + + +Image +Decoding +

                This document gives you more information about the Image Decoding functionality.

                +
                Purpose

                The image decoding class CImageDecoder provides +functions to decode images held in descriptors or files from standard formats +for use with devices such as screens, browsers and viewer applications.

                Required Background

                Image decoding features are provided through +Imaging Frameworks and Imaging plugins. The standard formats supported by +the decode plugins are shown in the table in Imaging +Frameworks Overview.

                Introduction

                The decoding process comprises the following sections:

                  +

                • Creation - The +creation of the CImageDecoder object and any requirements +necessary.

                  • +

                • Conversion - +Covers the basic form of image decoding. More advanced features such as progressive +and buffered decoding are described separately.

                  • +

                • Enquiry features - +Additional features that enable you to retrieve information stored in certain +types of images, for example frame information and comments.

                  • +

                • Streamed and progressive +decoding - Reading partial image files and displaying image data before +the entire image is read.

                  • +

                • Buffered decoding - +The decoding of an image using a buffered input rather than a file or descriptor.

                  • +

                Setup +and Configuration Requirements

                The CImageDecoder classes +use synchronous methods to open an image and asynchronous methods to perform +conversions or transformations. The asynchronous operations use the standard +system of taking a pointer to a TRequestStatus object that +is signalled on completion of the requested action. The assumption is that +the client application or the calling DLL holds the TRequestStatus values +within active objects. The structure of the active objects is dependent on +the code that uses the Imaging Frameworks and its own requirements, particularly +its internal architecture and how many images are opened simultaneously.

                In +addition to the use of active objects in the interfacing, many of the Imaging +Frameworks internal functions make extensive use of them to provide asynchronous +behaviour. As with any use of an active object it is necessary to have an +active scheduler in the same thread as the application making use of the object. +The Decoders can also be created so the plugin and framework runs in a separate +thread. This is achieved by setting the EOptionAlwaysThread option +when constructing the decoder objects. By running the object in its own thread, +the application is shielded from any latency that can occur during image conversion, +or possibly due to a badly written plugin.

                +
                Using Image Decoding

                The Following tasks are covered +in this tutorial:

                  +

                • How to create the object during decoding

                  • +

                • How to convert encoded data to decoded data

                  • +

                • How to retrieve the information stored in certain types of images

                  • +

                • How to perform the streaming and the progressive during decoding

                  • +

                • How to perform the buffered decoding

                  • +

                Basic Procedure For Creation

                The +high level steps to create the object during decoding are as follows:

                  +

                1. CImageDecoder decodes +images stored in files or in descriptors. The decoder object is owned by the +client and must be deleted once decoding is finished. CImageDecoder objects +cannot be reused to decode other images, each image requires its own instance +of the decoder.

                  2. +

                2. CImageDecoder objects +are created using the CImageDecoder::DataNewL() and CImageDecoder::FileNewL() factory +functions for images held in descriptors or files respectively.

                  3. +

                3. When you create a CImageDecoder object, +a suitable plugin must be associated with the image to be decoded. The Imaging +plugin depends on the factory function you use to create the object and what +parameters you specify. There are four alternatives:

                    +

                  • MIME type The +plugin is determined by looking up a specified MIME type against a list of +known MIME type/plugin implementations. Use the following "File" factory function +(or its "Data" equivalent).

                    static CImageDecoder* FileNewL(RFs& aFs, const TDesC& aSourceFilename, const TDesC8& aMIMEType, const TOptions aOptions = EOptionNone); +
                    • +

                  • Image type and sub-type The +plugin is determined by looking up the specified image type and sub-types +against a list of known type/sub-type plugin implementations. Use the following +"File" factory function (or its "Data" equivalent).

                    static CImageDecoder* FileNewL(RFs& aFs, const TDesC& aSourceFilename, const TOptions aOptions = EOptionNone, const TUid aImageType = KNullUid, const TUid aImageSubType = KNullUid, const TUid aDecoderUid = KNullUid); +

                    Note: For images types that do not have sub-types +use KNullUid.

                    • +

                  • Implementation UID The +plugin is determined by looking up its specific UID and the image type and +sub-type. Use the same FileNewL() factory function shown +in "Image type and sub-type", but in addition to the type and sub-type parameters, +also specify the plugin UID using aDecoderUid.

                    Note: Implementation +UID is supported because it is possible to have more than one plugin for a +particular image type. This method is recommended if the application or calling +DLL needs to exploit features of a particular plugin.

                    • +

                  • Automatic detection - +no MIME type, format type/sub-type or UIDs are specified. The plugin analyses +the header information of the specified image. Use the same FileNewL() factory +function shown in "Image type and sub-type", but do not specify any values +for aImageType aImageSubType or aDecoderUid.

                    If +a suitable plugin cannot be found, the factory function leaves with KErrNotFound. +If a suitable plugin is found, but that plugin cannot interpret the image +data the factory function leaves with KErrCorrupt.

                    Note: +Some image formats cannot be automatically detected because they do not contain +sufficient header information, for example, WBMP and OTA images. Under such +circumstances, use one of the other three alternative for opening the image.

                    • +
                  4. +

                It is possible for more than one valid plugin decoder to be available +for a specific image format. If a plugin determined by MIME type or type/sub-type +fails to open an image due to KErrCorrupt, it will continue +to try with subsequent valid plugins if available. This mechanism is carried +out in the system and is not visible to the application. If you require a +specific function available within a specific plugin, specify that plugin +using aDecoderUid.

                Basic Procedure For Conversion

                The +high level steps to convert encoded data to decoded data are as follow:

                  +

                1. As part of the CImageDecoder creation +basic information about the image is pre-read from the image headers. This +information is used to support certain enquiry methods such as CImageDecoder::FrameCount() and CImageDecoder::FrameInfo() (For more information about the retrieve information stored in certain types +of images is supplied in Retrieve +Information features).

                  2. +

                2. You can decode any subset +of individual frames, in any order, and to repeat the decoding if necessary. +To decode an image frame use the asynchronous conversion method CImageDecoder::Convert(), +as follows.

                  3. +
                +void Convert(TRequestStatus* aRequestStatus, CFbsBitmap& aDestination, TInt aFrameNumber = 0); + +void ContinueConvert(TRequestStatus* aRequestStatus);

                Note: The +use of CImageDecoder::ContinueConvert() is described in Streamed +and progressive decoding.

                There are different type of sub-procedures +which have to be followed before decode conversion, they are:

                  +

                • Bitmap Masks conversion

                  • +

                • Scaling and display modes

                  • +

                • Animations

                  • +

                • Background colours

                  • +

                Basic Procedure For Bitmap +Masks conversion

                The high level steps to Bitmap Masks conversion +are as follows:

                  +

                1. There is a second variant +of the Convert() function intended for use when decoding +images with bitmap masks.

                  +void Convert(TRequestStatus* aRequestStatus, CFbsBitmap& aDestination, CFbsBitmap& aDestinationMask, TInt aFrameNumber = 0); +
                  2. +

                2. Within the Symbian platform +it is normal to store the bitmap mask separately from the main image data. +Calls such as BitBltMasked() expect this data to be provided +separately. This separation is true for both CFbsBitmap objects +and MBM files.

                  3. +

                3. To determine whether +an image contains a bitmap mask use FrameInfo(), the presence +or absence of a mask will be indicated the ETransparencyPossible flag.

                  The +following two types of mask are available:

                    +

                  • 8-bit alpha blend - +indicated by the EAlphaChannel flag of CImageDecoder::FrameInfo() iFlags. +The destination mask bitmap must be of type EGray256.

                    • +

                  • Simple on/off mask - +if no EAlphaChannel flag is set. The destination bitmap mask +can be either EGray2 or EGray256.

                    • +
                  4. +

                Note: Images that contain bitmap masks do not have to have +those masks decoded if they are not required.

                Basic Procedure For Scaling +and display modes

                The high level steps to Scale and display are +shown here:

                  +

                1. Before Convert() is +used, the destination CFbsBitmap objects for image data +and bitmap masks are created. The simplest way to do this is to use a 1 to +1 approach, that is, create the CFbsBitmap object with the +same properties as the source image. This is achieved by using something similar +to:

                  iFrameInfo = &imageDecoder->FrameInfo(FrameNum); + +iBitmap->Create(iFrameInfo->iOverallSizeInPixels, iFrameInfo->iFrameDisplayMode ); +
                  2. +

                2. If the ECanDither flag +of CImageDecoder::FrameInfo() iFlags is +set then the destination display mode can be adjusted. It is recommended that +the window display mode is used as it is more efficient.

                  Note: The +mask bitmap must have the same size in pixels as the main image, even though +the display mode is generally different.

                  3. +

                3. The size of the image +bitmap is available via FrameInfo() (iOverallSizeInPixels). +However, in addition to a direct mapping of the size of an image, ReducedSize() function +can be used to calculate the reduced size of the decoded bitmap based on the +input parameters.

                  4. +

                4. If the EFullyScaleable flag +of FrameInfo() iFlags is set, you can specify +any size for the CFbsBitmap and the image will be resized +accordingly.

                  5. +

                Basic Procedure For Animations

                The +high level steps to decode a GIF multi-frame image are as follow:

                  +

                1. Included in the CImageDecoder::FrameInfo() result +are flags that enable the support of GIF animation. These flags are iDelay, ELeaveInPlace, ERestoreToBackground and ERestoreToPrevious. ICL provides these flags to enable +the application to implement the animation; ICL does not provide functions +to display the animation directly.

                  2. +

                2. Processing the information +from these flags will inevitably require a state machine, and additional timers, +within the application. Requirements will vary depending on the architecture +of the client application itself.

                  3. +

                Basic Procedure For Background +colours

                  +

                1. Some image formats contain +background colour information. This is information is presented through CImageDecoder::FrameInfo() iBackgroundColor.

                  2. +

                2. If a non-masked image +with background colour is decoded, the colour is included in the image data. +If the decoded image also contains a bitmap mask, then the background colour +will be a component of the mask CFbsBitmap object. Depending +on your application, you may want to choose your own background colour rather +than use the one provided by the source image.

                  3. +

                Basic Procedure To Retrieve +Information From An Image

                The high level steps to retrieve the +information stored in certain types of images are shown here:

                  +

                1. CImageDecoder::FrameData() Provides +access to additional chunks of data within the images, for example, palette +and similar lookup tables, copyright information and other strings. This information +should be used with care, the returned data is merely a reference to the original +data within the CImageDecoder object, and is only valid +for the lifetime of the object.

                  2. +

                2. CImageDecoder::NumberOfImageComments() and CImageDecoder::ImageCommentL() Images can have comments embedded in them. These comments are usually either +embedded as a single repository which can be retrieved on an image level, +or multiple repositories attached to individual frames within the image. The +two functions above return the number of comments attached to the entire image +and provide a mechanism for retrieving any of those comments.

                  3. +

                3. CImageDecoder::NumberOfFrameComments() and CImageDecoder::FrameCommentL() Similar functionality to above, but these functions return the number of +comments attached to individually specified frames and provide a mechanism +for retrieving any of those comments.

                  4. +

                4. CImageDecoder::FrameInfoStringsLC and CImageDecoder::FrameInfoStringsL() Provide a list of data for a specified frame, including data items such +as format, plugin description, size and so on, in a readable format. Although +the property strings can be accessed by name, it is recommended that they +be generally treated as a list of strings.

                  5. +

                Basic Procedure Streamed +and Progressive Decoding

                CImageDecoder includes +facilities to support the simultaneous decoding and display of images as they +are being loaded. The decoder does not wait for the entire image to be loaded +before processing it, rather it begins as soon as possible, stops when it +runs out of data and then carries on when more data is available.

                The +high level steps to perform the streaming and the progressive during decoding +are shown here:

                  +

                1. If there is insufficient +data to work out the image format (plugin decoder to use) CImageDecoder::FileNewL() (or +its "Data" equivalent) leaves with KErrUnderflow. This is +only applicable to instances where automatic detection of the plugin decoder +is used. For more information see, "Automatic detection" in Creation.

                  2. +

                2. As soon as the correct +plugin decoder has been determined it is opened and whatever addition image +data available is scanned. The plugin decoder continues to decode image data +as it arrives, updating FrameCount() whenever it becomes +aware of a new frame within the data. The internal flag CImageDecoder::IsHeaderProcessingComplete() is +maintained at EFalse until the entire image has been loaded.

                  3. +

                3. Frames can be decoded +before the entire image is loaded, but the frame to be decoded must be at +least partially loaded. If IsHeaderProcessingComplete() is +set to EFalse and FrameCount() is equal +to or less than the frame to decode, the application must wait for the relevant +frame to load. In such circumstances a call to CImageDecoder::ContinueProcessingHeadersL() should +be made that scans for any further headers. FrameCount() and IsHeaderProcessingComplete() should +then be recalled to determine if the frame has arrived.

                  4. +

                4. Once FrameCount() is +greater than the frame the application wants to decode, it is possible to +start to decoding the frame using CImageDecoder::Convert(). +Frame headers and their associated data do not always follow each other in +some image formats. This has the implication that although FrameCount() has +indicated that the frame is available, it may not yet be fully loaded. Under +such circumstances as much decoding as possible is undertaken, and Convert() then +completes with the error code KErrUnderflow. If the EPartialDecodeInvalid flag +(from FrameInfo()) is not set, the partially decoded image +can be displayed - for some image formats, a partially decoded image is not +generally usable, but this facility is supported by most known formats. Obviously, +if all of the image is present, Convert() completes with KErrNone as +normal.

                  5. +

                5. Where only a partial +conversion has been completed, CImageDecoder::ContinueConvert() should +be used to continue converting when new data arrives. ContinueConvert() continues +to convert the frame data where the previous call left off. This function +should continue to be called until it returns the error code KErrNone rather +than KErrUnderflow.

                  Note: The CFbsBitmap must +never be resized during a conversion session using ContinueConvert(), +if resizing does occur, a panic will be raised by the function. If resizing +or any other parameter changes need to be made to the CFbsBitmap, +frame decoding should be restarted by using Convert() rather +than trying to continue an existing conversion session.

                  6. +

                There is no explicit decoder call to say "all of the data is now +present". This could be done via inference, continuously checking IsHeaderProcessingComplete() until +it returns ETrue. However, this is not advisable as it is +possible that IsHeaderProcessingComplete() could continue +to return EFalse even after the application has finished +sending image data. Your state machine should be written so that it takes +this possibility into account.

                Basic Procedure For Buffered +Decoding

                CBufferedImageDecoder is a wrapper +that encapsulates not only a CImageDecoder but also the +descriptor used to store the image, and in some circumstances can replace +the use of CImageDecoder itself. CBufferedImageDecoder can +always be created, even if there is no data available at the time of creation. +Another key feature of CBufferedImageDecoder is that it can +be reused to decode multiple images.

                The high level steps to perform +the buffered decoding are shown here:

                  +

                1. The decoder is created +using the CBufferedImageDecoder::NewL() factory function, +and the decoding process is started with one of the two CBufferedImageDecoder::OpenL() calls, +specifying either MIME-type or image type/sub-type and UID, which are similar +to CImageDecoder::DataNewL(). If not enough data is available +to create an internal decoder a call to CBufferedImageDecoder::ValidDecoder() returns EFalse. +The decoder keeps an internal copy of the data provided so the client can +discard its own copy.

                  Warning: The decoding and enquiry functions +must not be used until an internal decoder has been created, otherwise calls +will panic with EDecoderNotCreated.

                  2. +

                2. Additional data can +be supplied to the decoder, when it becomes available, by using CBufferedImageDecoder::AppendDataL() and CBufferedImageDecoder::ContinueOpenL(), which will copy the data and try to find an appropriate plugin. This step +should be repeated until enough data is available to create the internal decoder, +indicated by ValidDecoder() returning ETrue. OpenL() and ContinueOpenL() will +leave with KErrCorrupt if a suitable decoder is found, but +that decoder was unable to interpret the supplied image data.

                  Note: +As with OpenL(), data provided by AppendDataL() is +kept in an internal buffer by the decoder so the client can discard its own +copy.

                  3. +

                3. The process for decoding +the image header and frames are the same as for CImageDecoder with IsHeaderProcessingComplete(), FrameCount(), Convert() and ContinueConvert() calls +except that the data is not appended to a descriptor, but supplied to the +decoder with AppendDataL().

                  4. +

                4. The decoder can be reused +by calling a CBufferedImageDecoder::Reset(), which destroys +the internal data buffer and decoder. A new decoder plugin can then be started +using OpenL().

                  5. +
                +                 +Imaging Frameworks +overview +Image Conversion +Overview +Image Encoding +Tutorial +Guide to +Symbian supplied Codecs +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B1254526-3C72-59E7-88C0-667FC051379F.dita --- a/Symbian3/SDK/Source/GUID-B1254526-3C72-59E7-88C0-667FC051379F.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-B1254526-3C72-59E7-88C0-667FC051379F.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,12 +1,12 @@ - - - - - -Extended SMS Converter

                The Extended SMS Converter uses the lossy mechanism to extend the alphabet of the standard converter. It maps a wider set of input character codes, including commonly-used Eastern European Unicode characters, to the standard 7-bit alphabet. This section describes the Extended SMS Converter and the alphabet it supports.

                Introduction

                Languages supported by this converter include Croatian, Czech, Estonian, Hungarian, Icelandic, Latvian, Lithuanian, Polish, Romanian, Serbian, Slovak, Slovenian, Turkish, Portuguese and Spanish. This converter is identified by the KCharacterSetIdentifierExtendedSms7Bit UID, which is defined in the charconv.h file.

                Any undefined Unicode is converted to a question mark (?)–GSM code 0x37. Any code outside GSM 0x00 ~0x7F is converted to the Unicode replacement character 0xFFFD.

                Alphabet

                The highlighted boxes in Figure 1 illustrate the alphabet of the extended SMS converter:

                • GSM 7-bit default alphabet

                • GSM 7-bit default alphabet extension table

                • Extra lossy conversions–exclude 9 characters listed in Table 2

                • Extended lossy conversions–shown as Lossy Characters 2 in Figure 1.

                Figure 1

                Table 1 lists the extra lossy conversions supported by this converter in addition to those supported by the standard converter.

                Table 1

                Character

                Unicode

                GSM

                Converted Character

                Ώ GREEK CAPITAL LETTER OMEGA WITH TONOS

                U+038F

                0x15

                Ω GREEK CAPITAL LETTER OMEGA

                (NO-BREAK SPACE)

                U+00A0

                0x20

                (SPACE)

                « LEFT-POINTING DOUBLE ANGLE QUOTATION MARK *

                U+00AB

                0x22

                " QUOTATION MARK

                » RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK *

                U+00BB

                0x22

                " QUOTATION MARK

                ` GRAVE ACCENT

                U+0060

                0x27

                ' APOSTROPHE

                ´ ACUTE ACCENT

                U+00B4

                0x27

                ' APOSTROPHE

                ΄ GREEK TONOS

                U+0384

                0x27

                ' APOSTROPHE

                ΅ GREEK DIALYTIKA TONOS

                U+0385

                0x27

                ' APOSTROPHE

                × MULTIPLICATION SIGN

                U+00D7

                0x2A

                * ASTERISK

                ¸ CEDILLA

                U+00B8

                0x2C

                , COMMA

                SOFT HYPHEN

                U+00AD

                0x2D

                - HYPHEN-MINUS

                · MIDDLE DOT

                U+00B7

                0x2E

                . FULL STOP

                ÷ DIVISION SIGN

                U+00F7

                0x2F

                / SOLIDUS

                ¹ SUPERSCRIPT ONE

                U+00B9

                0x31

                1 DIGIT ONE

                ² SUPERSCRIPT TWO

                U+00B2

                0x32

                2 DIGIT TWO

                ³ SUPERSCRIPT THREE

                U+00B3

                0x33

                3 DIGIT THREE

                ; GREEK QUESTION MARK (Erotimatiko)

                U+037E

                0x3B

                ; SEMICOLON

                Ā LATIN CAPITAL LETTER A WITH MACRON

                U+0100

                0x41

                A LATIN CAPITAL LETTER A

                Ă LATIN CAPITAL LETTER A WITH BREVE

                U+0102

                0x41

                A LATIN CAPITAL LETTER A

                Ą LATIN CAPITAL LETTER A WITH OGONEK

                U+0104

                0x41

                A LATIN CAPITAL LETTER A

                Ć LATIN CAPITAL LETTER C WITH ACUTE

                U+0106

                0x43

                C LATIN CAPITAL LETTER C

                Ĉ LATIN CAPITAL LETTER C WITH CIRCUMFLEX

                U+0108

                0x43

                C LATIN CAPITAL LETTER C

                Ċ LATIN CAPITAL LETTER C WITH DOT ABOVE

                U+010A

                0x43

                C LATIN CAPITAL LETTER C

                Č LATIN CAPITAL LETTER C WITH CARON

                U+010C

                0x43

                C LATIN CAPITAL LETTER C

                Ð LATIN CAPITAL LETTER ETH (Icelandic)

                U+00D0

                0x44

                D LATIN CAPITAL LETTER D

                Ď LATIN CAPITAL LETTER D WITH CARON

                U+010E

                0x44

                D LATIN CAPITAL LETTER D

                Đ LATIN CAPITAL LETTER D WITH STROKE

                U+0110

                0x44

                D LATIN CAPITAL LETTER D

                Ē LATIN CAPITAL LETTER E WITH MACRON

                U+0112

                0x45

                E LATIN CAPITAL LETTER E

                Ĕ LATIN CAPITAL LETTER E WITH BREVE

                U+0114

                0x45

                E LATIN CAPITAL LETTER E

                Ė LATIN CAPITAL LETTER E WITH DOT ABOVE

                U+0116

                0x45

                E LATIN CAPITAL LETTER E

                Ę LATIN CAPITAL LETTER E WITH OGONEK

                U+0118

                0x45

                E LATIN CAPITAL LETTER E

                Ě LATIN CAPITAL LETTER E WITH CARON

                U+011A

                0x45

                E LATIN CAPITAL LETTER E

                Ĝ LATIN CAPITAL LETTER G WITH CIRCUMFLEX

                U+011C

                0x47

                G LATIN CAPITAL LETTER G

                Ğ LATIN CAPITAL LETTER G WITH BREVE

                U+011E

                0x47

                G LATIN CAPITAL LETTER G

                Ġ LATIN CAPITAL LETTER G WITH DOT ABOVE

                U+0120

                0x47

                G LATIN CAPITAL LETTER G

                Ģ LATIN CAPITAL LETTER G WITH CEDILLA

                U+0122

                0x47

                G LATIN CAPITAL LETTER G

                Ĥ LATIN CAPITAL LETTER H WITH CIRCUMFLEX

                U+0124

                0x48

                H LATIN CAPITAL LETTER H

                Ħ LATIN CAPITAL LETTER H WITH STROKE

                U+0126

                0x48

                H LATIN CAPITAL LETTER H

                Ĩ LATIN CAPITAL LETTER I WITH TILDE

                U+0128

                0x49

                I LATIN CAPITAL LETTER I

                Ī LATIN CAPITAL LETTER I WITH MACRON

                U+012A

                0x49

                I LATIN CAPITAL LETTER I

                Ĭ LATIN CAPITAL LETTER I WITH BREVE

                U+012C

                0x49

                I LATIN CAPITAL LETTER I

                Į LATIN CAPITAL LETTER I WITH OGONEK

                U+012E

                0x49

                I LATIN CAPITAL LETTER I

                İ LATIN CAPITAL LETTER I WITH DOT ABOVE

                U+0130

                0x49

                I LATIN CAPITAL LETTER I

                Ĵ LATIN CAPITAL LETTER J WITH CIRCUMFLEX

                U+0134

                0x4A

                J LATIN CAPITAL LETTER J

                Ķ LATIN CAPITAL LETTER K WITH CEDILLA

                U+0136

                0x4B

                K LATIN CAPITAL LETTER K

                Ĺ LATIN CAPITAL LETTER L WITH ACUTE

                U+0139

                0x4C

                L LATIN CAPITAL LETTER L

                Ļ LATIN CAPITAL LETTER L WITH CEDILLA

                U+013B

                0x4C

                L LATIN CAPITAL LETTER L

                Ľ LATIN CAPITAL LETTER L WITH CARON

                U+013D

                0x4C

                L LATIN CAPITAL LETTER L

                Ŀ LATIN CAPITAL LETTER L WITH MIDDLE DOT

                U+013F

                0x4C

                L LATIN CAPITAL LETTER L

                Ł LATIN CAPITAL LETTER L WITH STROKE

                U+0141

                0x4C

                L LATIN CAPITAL LETTER L

                Ń LATIN CAPITAL LETTER N WITH ACUTE

                U+0143

                0x4E

                N LATIN CAPITAL LETTER N

                Ņ LATIN CAPITAL LETTER N WITH CEDILLA

                U+0145

                0x4E

                N LATIN CAPITAL LETTER N

                Ň LATIN CAPITAL LETTER N WITH CARON

                U+0147

                0x4E

                N LATIN CAPITAL LETTER N

                Ŋ LATIN CAPITAL LETTER ENG (Sami)

                U+014A

                0x4E

                N LATIN CAPITAL LETTER N

                Ō LATIN CAPITAL LETTER O WITH MACRON

                U+014C

                0x4F

                O LATIN CAPITAL LETTER O

                Ŏ LATIN CAPITAL LETTER O WITH BREVE

                U+014E

                0x4F

                O LATIN CAPITAL LETTER O

                ΠLATIN CAPITAL LIGATURE OE

                U+0152

                0x4F

                O LATIN CAPITAL LETTER O

                Ŕ LATIN CAPITAL LETTER R WITH ACUTE

                U+0154

                0x52

                R LATIN CAPITAL LETTER R

                Ŗ LATIN CAPITAL LETTER R WITH CEDILLA

                U+0156

                0x52

                R LATIN CAPITAL LETTER R

                Ř LATIN CAPITAL LETTER R WITH CARON

                U+0158

                0x52

                R LATIN CAPITAL LETTER R

                Ś LATIN CAPITAL LETTER S WITH ACUTE

                U+015A

                0x53

                S LATIN CAPITAL LETTER S

                Ŝ LATIN CAPITAL LETTER S WITH CIRCUMFLEX

                U+015C

                0x53

                S LATIN CAPITAL LETTER S

                Ş LATIN CAPITAL LETTER S WITH CEDILLA *

                U+015E

                0x53

                S LATIN CAPITAL LETTER S

                Š LATIN CAPITAL LETTER S WITH CARON

                U+0160

                0x53

                S LATIN CAPITAL LETTER S

                Þ LATIN CAPITAL LETTER THORN (Icelandic)

                U+00DE

                0x54

                T LATIN CAPITAL LETTER T

                Ţ LATIN CAPITAL LETTER T WITH CEDILLA *

                U+0162

                0x54

                T LATIN CAPITAL LETTER T

                Ť LATIN CAPITAL LETTER T WITH CARON

                U+0164

                0x54

                T LATIN CAPITAL LETTER T

                Ŧ LATIN CAPITAL LETTER T WITH STROKE

                U+0166

                0x54

                T LATIN CAPITAL LETTER T

                Ũ LATIN CAPITAL LETTER U WITH TILDE

                U+0168

                0x55

                U LATIN CAPITAL LETTER U

                Ū LATIN CAPITAL LETTER U WITH MACRON

                U+016A

                0x55

                U LATIN CAPITAL LETTER U

                Ŭ LATIN CAPITAL LETTER U WITH BREVE

                U+016C

                0x55

                U LATIN CAPITAL LETTER U

                Ů LATIN CAPITAL LETTER U WITH RING ABOVE

                U+016E

                0x55

                U LATIN CAPITAL LETTER U

                Ų LATIN CAPITAL LETTER U WITH OGONEK

                U+0172

                0x55

                U LATIN CAPITAL LETTER U

                Ŵ LATIN CAPITAL LETTER W WITH CIRCUMFLEX

                U+0174

                0x57

                W LATIN CAPITAL LETTER W

                Ŷ LATIN CAPITAL LETTER Y WITH CIRCUMFLEX

                U+0176

                0x59

                Y LATIN CAPITAL LETTER Y

                Ÿ LATIN CAPITAL LETTER Y WITH DIAERESIS

                U+0178

                0x59

                Y LATIN CAPITAL LETTER Y

                Ź LATIN CAPITAL LETTER Z WITH ACUTE

                U+0179

                0x5A

                Z LATIN CAPITAL LETTER Z

                Ż LATIN CAPITAL LETTER Z WITH DOT ABOVE

                U+017B

                0x5A

                Z LATIN CAPITAL LETTER Z

                Ž LATIN CAPITAL LETTER Z WITH CARON

                U+017D

                0x5A

                Z LATIN CAPITAL LETTER Z

                Ö LATIN CAPITAL LETTER O WITH DIAERESIS

                U+00D6

                0x5C

                Ö LATIN CAPITAL LETTER O WITH DIAERESIS

                Ő LATIN CAPITAL LETTER O WITH DOUBLE ACUTE

                U+0150

                0x5C

                Ö LATIN CAPITAL LETTER O WITH DIAERESIS

                Ű LATIN CAPITAL LETTER U WITH DOUBLE ACUTE

                U+0170

                0x5E

                Ü LATIN CAPITAL LETTER U WITH DIAERESIS

                ā LATIN SMALL LETTER A WITH MACRON

                U+0101

                0x61

                a LATIN SMALL LETTER A

                ă LATIN SMALL LETTER A WITH BREVE

                U+0103

                0x61

                a LATIN SMALL LETTER A

                ą LATIN SMALL LETTER A WITH OGONEK

                U+0105

                0x61

                a LATIN SMALL LETTER A

                ª FEMININE ORDINAL INDICATOR

                U+00AA

                0x61

                a LATIN SMALL LETTER A

                ć LATIN SMALL LETTER C WITH ACUTE

                U+0107

                0x63

                c LATIN SMALL LETTER C

                ĉ LATIN SMALL LETTER C WITH CIRCUMFLEX

                U+0109

                0x63

                c LATIN SMALL LETTER C

                ċ LATIN SMALL LETTER C WITH DOT ABOVE

                U+010B

                0x63

                c LATIN SMALL LETTER C

                č LATIN SMALL LETTER C WITH CARON

                U+010D

                0x63

                c LATIN SMALL LETTER C

                ¢ CENT SIGN

                U+00A2

                0x63

                c LATIN SMALL LETTER C

                © COPYRIGHT SIGN

                U+00A9

                0x63

                c LATIN SMALL LETTER C

                ð LATIN SMALL LETTER ETH (Icelandic)

                U+00F0

                0x64

                d LATIN SMALL LETTER D

                ď LATIN SMALL LETTER D WITH CARON

                U+010F

                0x64

                d LATIN SMALL LETTER D

                đ LATIN SMALL LETTER D WITH STROKE

                U+0111

                0x64

                d LATIN SMALL LETTER D

                ē LATIN SMALL LETTER E WITH MACRON

                U+0113

                0x65

                e LATIN SMALL LETTER E

                ĕ LATIN SMALL LETTER E WITH BREVE

                U+0115

                0x65

                e LATIN SMALL LETTER E

                ė LATIN SMALL LETTER E WITH DOT ABOVE

                U+0117

                0x65

                e LATIN SMALL LETTER E

                ę LATIN SMALL LETTER E WITH OGONEK

                U+0119

                0x65

                e LATIN SMALL LETTER E

                ě LATIN SMALL LETTER E WITH CARON

                U+011B

                0x65

                e LATIN SMALL LETTER E

                ĝ LATIN SMALL LETTER G WITH CIRCUMFLEX

                U+011D

                0x67

                g LATIN SMALL LETTER G

                ğ LATIN SMALL LETTER G WITH BREVE

                U+011F

                0x67

                g LATIN SMALL LETTER G

                ġ LATIN SMALL LETTER G WITH DOT ABOVE

                U+0121

                0x67

                g LATIN SMALL LETTER G

                ģ LATIN SMALL LETTER G WITH CEDILLA

                U+0123

                0x67

                g LATIN SMALL LETTER G

                ĥ LATIN SMALL LETTER H WITH CIRCUMFLEX

                U+0125

                0x68

                h LATIN SMALL LETTER H

                ħ LATIN SMALL LETTER H WITH STROKE

                U+0127

                0x68

                h LATIN SMALL LETTER H

                ĩ LATIN SMALL LETTER I WITH TILDE

                U+0129

                0x69

                i LATIN SMALL LETTER I

                ī LATIN SMALL LETTER I WITH MACRON

                U+012B

                0x69

                i LATIN SMALL LETTER I

                ĭ LATIN SMALL LETTER I WITH BREVE

                U+012D

                0x69

                i LATIN SMALL LETTER I

                į LATIN SMALL LETTER I WITH OGONEK

                U+012F

                0x69

                i LATIN SMALL LETTER I

                ı LATIN SMALL LETTER DOTLESS I

                U+0131

                0x69

                i LATIN SMALL LETTER I

                ĵ LATIN SMALL LETTER J WITH CIRCUMFLEX

                U+0135

                0x6A

                j LATIN SMALL LETTER J

                ķ LATIN SMALL LETTER K WITH CEDILLA

                U+0137

                0x6B

                k LATIN SMALL LETTER K

                ĸ LATIN SMALL LETTER KRA (Greenlandic)

                U+0138

                0x6B

                k LATIN SMALL LETTER K

                ĺ LATIN SMALL LETTER L WITH ACUTE

                U+013A

                0x6C

                l LATIN SMALL LETTER L

                ļ LATIN SMALL LETTER L WITH CEDILLA

                U+013C

                0x6C

                l LATIN SMALL LETTER L

                ľ LATIN SMALL LETTER L WITH CARON

                U+013E

                0x6C

                l LATIN SMALL LETTER L

                ŀ LATIN SMALL LETTER L WITH MIDDLE DOT

                U+0140

                0x6C

                l LATIN SMALL LETTER L

                ł LATIN SMALL LETTER L WITH STROKE

                U+0142

                0x6C

                l LATIN SMALL LETTER L

                ń LATIN SMALL LETTER N WITH ACUTE

                U+0144

                0x6E

                n LATIN SMALL LETTER N

                ņ LATIN SMALL LETTER N WITH CEDILLA

                U+0146

                0x6E

                n LATIN SMALL LETTER N

                ň LATIN SMALL LETTER N WITH CARON

                U+0148

                0x6E

                n LATIN SMALL LETTER N

                ʼn LATIN SMALL LETTER N PRECEDED BY APOSTROPHE

                U+0149

                0x6E

                n LATIN SMALL LETTER N

                 ŋ LATIN SMALL LETTER ENG (Sami)

                U+014B

                0x6E

                n LATIN SMALL LETTER N

                ō LATIN SMALL LETTER O WITH MACRON

                U+014D

                0x6F

                o LATIN SMALL LETTER O

                ŏ LATIN SMALL LETTER O WITH BREVE

                U+014F

                0x6F

                o LATIN SMALL LETTER O

                ° DEGREE SIGN

                U+00B0

                0x6F

                o LATIN SMALL LETTER O

                º MASCULINE ORDINAL INDICATOR

                U+00BA

                0x6F

                o LATIN SMALL LETTER O

                œ LATIN SMALL LIGATURE OE

                U+0153

                0x6F

                o LATIN SMALL LETTER O

                ŕ LATIN SMALL LETTER R WITH ACUTE

                U+0155

                0x72

                r LATIN SMALL LETTER R

                ŗ LATIN SMALL LETTER R WITH CEDILLA

                U+0157

                0x72

                r LATIN SMALL LETTER R

                ř LATIN SMALL LETTER R WITH CARON

                U+0159

                0x72

                r LATIN SMALL LETTER R

                ® REGISTERED SIGN

                U+00AE

                0x72

                r LATIN SMALL LETTER R

                ś LATIN SMALL LETTER S WITH ACUTE

                U+015B

                0x73

                s LATIN SMALL LETTER S

                ŝ LATIN SMALL LETTER S WITH CIRCUMFLEX

                U+015D

                0x73

                s LATIN SMALL LETTER S

                ş LATIN SMALL LETTER S WITH CEDILLA *

                U+015F

                0x73

                s LATIN SMALL LETTER S

                š LATIN SMALL LETTER S WITH CARON

                U+0161

                0x73

                s LATIN SMALL LETTER S

                þ LATIN SMALL LETTER THORN (Icelandic)

                U+00FE

                0x74

                t LATIN SMALL LETTER T

                ţ LATIN SMALL LETTER T WITH CEDILLA *

                U+0163

                0x74

                t LATIN SMALL LETTER T

                ť LATIN SMALL LETTER T WITH CARON

                U+0165

                0x74

                t LATIN SMALL LETTER T

                ŧ LATIN SMALL LETTER T WITH STROKE

                U+0167

                0x74

                t LATIN SMALL LETTER T

                ũ LATIN SMALL LETTER U WITH TILDE

                U+0169

                0x75

                u LATIN SMALL LETTER U

                ū LATIN SMALL LETTER U WITH MACRON

                U+016B

                0x75

                u LATIN SMALL LETTER U

                ŭ LATIN SMALL LETTER U WITH BREVE

                U+016D

                0x75

                u LATIN SMALL LETTER U

                ů LATIN SMALL LETTER U WITH RING ABOVE

                U+016F

                0x75

                u LATIN SMALL LETTER U

                ų LATIN SMALL LETTER U WITH OGONEK

                U+0173

                0x75

                u LATIN SMALL LETTER U

                µ MICRO SIGN

                U+00B5

                0x75

                u LATIN SMALL LETTER U

                ŵ LATIN SMALL LETTER W WITH CIRCUMFLEX

                U+0175

                0x77

                w LATIN SMALL LETTER W

                ŷ LATIN SMALL LETTER Y WITH CIRCUMFLEX

                U+0177

                0x79

                y LATIN SMALL LETTER Y

                ź LATIN SMALL LETTER Z WITH ACUTE

                U+017A

                0x7A

                z LATIN SMALL LETTER Z

                 ż LATIN SMALL LETTER Z WITH DOT ABOVE

                U+017C

                0x7A

                z LATIN SMALL LETTER Z

                ž LATIN SMALL LETTER Z WITH CARON

                U+017E

                0x7A

                z LATIN SMALL LETTER Z

                ő LATIN SMALL LETTER O WITH DOUBLE ACUTE

                U+0151

                0x7C

                ö LATIN SMALL LETTER O WITH DIAERESIS

                ű LATIN SMALL LETTER U WITH DOUBLE ACUTE

                U+0171

                0x7E

                ü LATIN SMALL LETTER U WITH DIAERESIS

                Table 2 lists the 9 characters in Lossy Character 1 supported by Standard SMS Converter but not by Extended SMS Converter.

                Table 2

                Character

                Unicode

                GSM

                Converted Character

                ϕ GREEK PHI SYMBOL

                0x03D5

                0x12

                Φ GREEK CAPITAL LETTER PHI

                Ω OHM SIGN

                0x2126

                0x15

                Ω GREEK CAPITAL LETTER OMEGA

                ∏ N-ARY PRODUCT

                0x220F

                0x16

                Π GREEK CAPITAL LETTER PI

                ∑ N-ARY SUMMATION

                0x2211

                0x18

                Σ GREEK CAPITAL LETTER SIGMA

                ϑ GREEK THETA SYMBOL

                0x03D1

                0x19

                Θ GREEK CAPITAL LETTER THETA

                ϐ GREEK BETA SYMBOL

                0x03D0

                0x42

                B LATIN CAPITAL LETTER B

                ϒ GREEK UPSILON WITH HOOK SYMBOL

                0x03D2

                0x59

                Y LATIN CAPITAL LETTER Y

                ϓ GREEK UPSILON WITH ACUTE AND HOOK SYMBOL

                0x03D3

                0x59

                Y LATIN CAPITAL LETTER Y

                ϔ GREEK UPSILON WITH DIAERESIS AND HOOK SYMBOL

                0x03D4

                0x59

                Y LATIN CAPITAL LETTER Y

                See also

                SMS Encodings and Converters Overview

                \ No newline at end of file + + + + + +Extended SMS Converter

                The Extended SMS Converter uses the lossy mechanism to extend the alphabet of the standard converter. It maps a wider set of input character codes, including commonly-used Eastern European Unicode characters, to the standard 7-bit alphabet. This section describes the Extended SMS Converter and the alphabet it supports.

                Introduction

                Languages supported by this converter include Croatian, Czech, Estonian, Hungarian, Icelandic, Latvian, Lithuanian, Polish, Romanian, Serbian, Slovak, Slovenian, Turkish, Portuguese and Spanish. This converter is identified by the KCharacterSetIdentifierExtendedSms7Bit UID, which is defined in the charconv.h file.

                Any undefined Unicode is converted to a question mark (?)–GSM code 0x37. Any code outside GSM 0x00 ~0x7F is converted to the Unicode replacement character 0xFFFD.

                Alphabet

                The highlighted boxes in Figure 1 illustrate the alphabet of the extended SMS converter:

                • GSM 7-bit default alphabet

                • GSM 7-bit default alphabet extension table

                • Extra lossy conversions–exclude 9 characters listed in Table 2

                • Extended lossy conversions–shown as Lossy Characters 2 in Figure 1.

                Figure 1

                Table 1 lists the extra lossy conversions supported by this converter in addition to those supported by the standard converter.

                Table 1

                Character

                Unicode

                GSM

                Converted Character

                Ώ GREEK CAPITAL LETTER OMEGA WITH TONOS

                U+038F

                0x15

                Ω GREEK CAPITAL LETTER OMEGA

                (NO-BREAK SPACE)

                U+00A0

                0x20

                (SPACE)

                « LEFT-POINTING DOUBLE ANGLE QUOTATION MARK *

                U+00AB

                0x22

                " QUOTATION MARK

                » RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK *

                U+00BB

                0x22

                " QUOTATION MARK

                ` GRAVE ACCENT

                U+0060

                0x27

                ' APOSTROPHE

                ´ ACUTE ACCENT

                U+00B4

                0x27

                ' APOSTROPHE

                ΄ GREEK TONOS

                U+0384

                0x27

                ' APOSTROPHE

                ΅ GREEK DIALYTIKA TONOS

                U+0385

                0x27

                ' APOSTROPHE

                × MULTIPLICATION SIGN

                U+00D7

                0x2A

                * ASTERISK

                ¸ CEDILLA

                U+00B8

                0x2C

                , COMMA

                SOFT HYPHEN

                U+00AD

                0x2D

                - HYPHEN-MINUS

                · MIDDLE DOT

                U+00B7

                0x2E

                . FULL STOP

                ÷ DIVISION SIGN

                U+00F7

                0x2F

                / SOLIDUS

                ¹ SUPERSCRIPT ONE

                U+00B9

                0x31

                1 DIGIT ONE

                ² SUPERSCRIPT TWO

                U+00B2

                0x32

                2 DIGIT TWO

                ³ SUPERSCRIPT THREE

                U+00B3

                0x33

                3 DIGIT THREE

                ; GREEK QUESTION MARK (Erotimatiko)

                U+037E

                0x3B

                ; SEMICOLON

                Ā LATIN CAPITAL LETTER A WITH MACRON

                U+0100

                0x41

                A LATIN CAPITAL LETTER A

                Ă LATIN CAPITAL LETTER A WITH BREVE

                U+0102

                0x41

                A LATIN CAPITAL LETTER A

                Ą LATIN CAPITAL LETTER A WITH OGONEK

                U+0104

                0x41

                A LATIN CAPITAL LETTER A

                Ć LATIN CAPITAL LETTER C WITH ACUTE

                U+0106

                0x43

                C LATIN CAPITAL LETTER C

                Ĉ LATIN CAPITAL LETTER C WITH CIRCUMFLEX

                U+0108

                0x43

                C LATIN CAPITAL LETTER C

                Ċ LATIN CAPITAL LETTER C WITH DOT ABOVE

                U+010A

                0x43

                C LATIN CAPITAL LETTER C

                Č LATIN CAPITAL LETTER C WITH CARON

                U+010C

                0x43

                C LATIN CAPITAL LETTER C

                Ð LATIN CAPITAL LETTER ETH (Icelandic)

                U+00D0

                0x44

                D LATIN CAPITAL LETTER D

                Ď LATIN CAPITAL LETTER D WITH CARON

                U+010E

                0x44

                D LATIN CAPITAL LETTER D

                Đ LATIN CAPITAL LETTER D WITH STROKE

                U+0110

                0x44

                D LATIN CAPITAL LETTER D

                Ē LATIN CAPITAL LETTER E WITH MACRON

                U+0112

                0x45

                E LATIN CAPITAL LETTER E

                Ĕ LATIN CAPITAL LETTER E WITH BREVE

                U+0114

                0x45

                E LATIN CAPITAL LETTER E

                Ė LATIN CAPITAL LETTER E WITH DOT ABOVE

                U+0116

                0x45

                E LATIN CAPITAL LETTER E

                Ę LATIN CAPITAL LETTER E WITH OGONEK

                U+0118

                0x45

                E LATIN CAPITAL LETTER E

                Ě LATIN CAPITAL LETTER E WITH CARON

                U+011A

                0x45

                E LATIN CAPITAL LETTER E

                Ĝ LATIN CAPITAL LETTER G WITH CIRCUMFLEX

                U+011C

                0x47

                G LATIN CAPITAL LETTER G

                Ğ LATIN CAPITAL LETTER G WITH BREVE

                U+011E

                0x47

                G LATIN CAPITAL LETTER G

                Ġ LATIN CAPITAL LETTER G WITH DOT ABOVE

                U+0120

                0x47

                G LATIN CAPITAL LETTER G

                Ģ LATIN CAPITAL LETTER G WITH CEDILLA

                U+0122

                0x47

                G LATIN CAPITAL LETTER G

                Ĥ LATIN CAPITAL LETTER H WITH CIRCUMFLEX

                U+0124

                0x48

                H LATIN CAPITAL LETTER H

                Ħ LATIN CAPITAL LETTER H WITH STROKE

                U+0126

                0x48

                H LATIN CAPITAL LETTER H

                Ĩ LATIN CAPITAL LETTER I WITH TILDE

                U+0128

                0x49

                I LATIN CAPITAL LETTER I

                Ī LATIN CAPITAL LETTER I WITH MACRON

                U+012A

                0x49

                I LATIN CAPITAL LETTER I

                Ĭ LATIN CAPITAL LETTER I WITH BREVE

                U+012C

                0x49

                I LATIN CAPITAL LETTER I

                Į LATIN CAPITAL LETTER I WITH OGONEK

                U+012E

                0x49

                I LATIN CAPITAL LETTER I

                İ LATIN CAPITAL LETTER I WITH DOT ABOVE

                U+0130

                0x49

                I LATIN CAPITAL LETTER I

                Ĵ LATIN CAPITAL LETTER J WITH CIRCUMFLEX

                U+0134

                0x4A

                J LATIN CAPITAL LETTER J

                Ķ LATIN CAPITAL LETTER K WITH CEDILLA

                U+0136

                0x4B

                K LATIN CAPITAL LETTER K

                Ĺ LATIN CAPITAL LETTER L WITH ACUTE

                U+0139

                0x4C

                L LATIN CAPITAL LETTER L

                Ļ LATIN CAPITAL LETTER L WITH CEDILLA

                U+013B

                0x4C

                L LATIN CAPITAL LETTER L

                Ľ LATIN CAPITAL LETTER L WITH CARON

                U+013D

                0x4C

                L LATIN CAPITAL LETTER L

                Ŀ LATIN CAPITAL LETTER L WITH MIDDLE DOT

                U+013F

                0x4C

                L LATIN CAPITAL LETTER L

                Ł LATIN CAPITAL LETTER L WITH STROKE

                U+0141

                0x4C

                L LATIN CAPITAL LETTER L

                Ń LATIN CAPITAL LETTER N WITH ACUTE

                U+0143

                0x4E

                N LATIN CAPITAL LETTER N

                Ņ LATIN CAPITAL LETTER N WITH CEDILLA

                U+0145

                0x4E

                N LATIN CAPITAL LETTER N

                Ň LATIN CAPITAL LETTER N WITH CARON

                U+0147

                0x4E

                N LATIN CAPITAL LETTER N

                Ŋ LATIN CAPITAL LETTER ENG (Sami)

                U+014A

                0x4E

                N LATIN CAPITAL LETTER N

                Ō LATIN CAPITAL LETTER O WITH MACRON

                U+014C

                0x4F

                O LATIN CAPITAL LETTER O

                Ŏ LATIN CAPITAL LETTER O WITH BREVE

                U+014E

                0x4F

                O LATIN CAPITAL LETTER O

                ΠLATIN CAPITAL LIGATURE OE

                U+0152

                0x4F

                O LATIN CAPITAL LETTER O

                Ŕ LATIN CAPITAL LETTER R WITH ACUTE

                U+0154

                0x52

                R LATIN CAPITAL LETTER R

                Ŗ LATIN CAPITAL LETTER R WITH CEDILLA

                U+0156

                0x52

                R LATIN CAPITAL LETTER R

                Ř LATIN CAPITAL LETTER R WITH CARON

                U+0158

                0x52

                R LATIN CAPITAL LETTER R

                Ś LATIN CAPITAL LETTER S WITH ACUTE

                U+015A

                0x53

                S LATIN CAPITAL LETTER S

                Ŝ LATIN CAPITAL LETTER S WITH CIRCUMFLEX

                U+015C

                0x53

                S LATIN CAPITAL LETTER S

                Ş LATIN CAPITAL LETTER S WITH CEDILLA *

                U+015E

                0x53

                S LATIN CAPITAL LETTER S

                Š LATIN CAPITAL LETTER S WITH CARON

                U+0160

                0x53

                S LATIN CAPITAL LETTER S

                Þ LATIN CAPITAL LETTER THORN (Icelandic)

                U+00DE

                0x54

                T LATIN CAPITAL LETTER T

                Ţ LATIN CAPITAL LETTER T WITH CEDILLA *

                U+0162

                0x54

                T LATIN CAPITAL LETTER T

                Ť LATIN CAPITAL LETTER T WITH CARON

                U+0164

                0x54

                T LATIN CAPITAL LETTER T

                Ŧ LATIN CAPITAL LETTER T WITH STROKE

                U+0166

                0x54

                T LATIN CAPITAL LETTER T

                Ũ LATIN CAPITAL LETTER U WITH TILDE

                U+0168

                0x55

                U LATIN CAPITAL LETTER U

                Ū LATIN CAPITAL LETTER U WITH MACRON

                U+016A

                0x55

                U LATIN CAPITAL LETTER U

                Ŭ LATIN CAPITAL LETTER U WITH BREVE

                U+016C

                0x55

                U LATIN CAPITAL LETTER U

                Ů LATIN CAPITAL LETTER U WITH RING ABOVE

                U+016E

                0x55

                U LATIN CAPITAL LETTER U

                Ų LATIN CAPITAL LETTER U WITH OGONEK

                U+0172

                0x55

                U LATIN CAPITAL LETTER U

                Ŵ LATIN CAPITAL LETTER W WITH CIRCUMFLEX

                U+0174

                0x57

                W LATIN CAPITAL LETTER W

                Ŷ LATIN CAPITAL LETTER Y WITH CIRCUMFLEX

                U+0176

                0x59

                Y LATIN CAPITAL LETTER Y

                Ÿ LATIN CAPITAL LETTER Y WITH DIAERESIS

                U+0178

                0x59

                Y LATIN CAPITAL LETTER Y

                Ź LATIN CAPITAL LETTER Z WITH ACUTE

                U+0179

                0x5A

                Z LATIN CAPITAL LETTER Z

                Ż LATIN CAPITAL LETTER Z WITH DOT ABOVE

                U+017B

                0x5A

                Z LATIN CAPITAL LETTER Z

                Ž LATIN CAPITAL LETTER Z WITH CARON

                U+017D

                0x5A

                Z LATIN CAPITAL LETTER Z

                Ö LATIN CAPITAL LETTER O WITH DIAERESIS

                U+00D6

                0x5C

                Ö LATIN CAPITAL LETTER O WITH DIAERESIS

                Ő LATIN CAPITAL LETTER O WITH DOUBLE ACUTE

                U+0150

                0x5C

                Ö LATIN CAPITAL LETTER O WITH DIAERESIS

                Ű LATIN CAPITAL LETTER U WITH DOUBLE ACUTE

                U+0170

                0x5E

                Ü LATIN CAPITAL LETTER U WITH DIAERESIS

                ā LATIN SMALL LETTER A WITH MACRON

                U+0101

                0x61

                a LATIN SMALL LETTER A

                ă LATIN SMALL LETTER A WITH BREVE

                U+0103

                0x61

                a LATIN SMALL LETTER A

                ą LATIN SMALL LETTER A WITH OGONEK

                U+0105

                0x61

                a LATIN SMALL LETTER A

                ª FEMININE ORDINAL INDICATOR

                U+00AA

                0x61

                a LATIN SMALL LETTER A

                ć LATIN SMALL LETTER C WITH ACUTE

                U+0107

                0x63

                c LATIN SMALL LETTER C

                ĉ LATIN SMALL LETTER C WITH CIRCUMFLEX

                U+0109

                0x63

                c LATIN SMALL LETTER C

                ċ LATIN SMALL LETTER C WITH DOT ABOVE

                U+010B

                0x63

                c LATIN SMALL LETTER C

                č LATIN SMALL LETTER C WITH CARON

                U+010D

                0x63

                c LATIN SMALL LETTER C

                ¢ CENT SIGN

                U+00A2

                0x63

                c LATIN SMALL LETTER C

                © COPYRIGHT SIGN

                U+00A9

                0x63

                c LATIN SMALL LETTER C

                ð LATIN SMALL LETTER ETH (Icelandic)

                U+00F0

                0x64

                d LATIN SMALL LETTER D

                ď LATIN SMALL LETTER D WITH CARON

                U+010F

                0x64

                d LATIN SMALL LETTER D

                đ LATIN SMALL LETTER D WITH STROKE

                U+0111

                0x64

                d LATIN SMALL LETTER D

                ē LATIN SMALL LETTER E WITH MACRON

                U+0113

                0x65

                e LATIN SMALL LETTER E

                ĕ LATIN SMALL LETTER E WITH BREVE

                U+0115

                0x65

                e LATIN SMALL LETTER E

                ė LATIN SMALL LETTER E WITH DOT ABOVE

                U+0117

                0x65

                e LATIN SMALL LETTER E

                ę LATIN SMALL LETTER E WITH OGONEK

                U+0119

                0x65

                e LATIN SMALL LETTER E

                ě LATIN SMALL LETTER E WITH CARON

                U+011B

                0x65

                e LATIN SMALL LETTER E

                ĝ LATIN SMALL LETTER G WITH CIRCUMFLEX

                U+011D

                0x67

                g LATIN SMALL LETTER G

                ğ LATIN SMALL LETTER G WITH BREVE

                U+011F

                0x67

                g LATIN SMALL LETTER G

                ġ LATIN SMALL LETTER G WITH DOT ABOVE

                U+0121

                0x67

                g LATIN SMALL LETTER G

                ģ LATIN SMALL LETTER G WITH CEDILLA

                U+0123

                0x67

                g LATIN SMALL LETTER G

                ĥ LATIN SMALL LETTER H WITH CIRCUMFLEX

                U+0125

                0x68

                h LATIN SMALL LETTER H

                ħ LATIN SMALL LETTER H WITH STROKE

                U+0127

                0x68

                h LATIN SMALL LETTER H

                ĩ LATIN SMALL LETTER I WITH TILDE

                U+0129

                0x69

                i LATIN SMALL LETTER I

                ī LATIN SMALL LETTER I WITH MACRON

                U+012B

                0x69

                i LATIN SMALL LETTER I

                ĭ LATIN SMALL LETTER I WITH BREVE

                U+012D

                0x69

                i LATIN SMALL LETTER I

                į LATIN SMALL LETTER I WITH OGONEK

                U+012F

                0x69

                i LATIN SMALL LETTER I

                ı LATIN SMALL LETTER DOTLESS I

                U+0131

                0x69

                i LATIN SMALL LETTER I

                ĵ LATIN SMALL LETTER J WITH CIRCUMFLEX

                U+0135

                0x6A

                j LATIN SMALL LETTER J

                ķ LATIN SMALL LETTER K WITH CEDILLA

                U+0137

                0x6B

                k LATIN SMALL LETTER K

                ĸ LATIN SMALL LETTER KRA (Greenlandic)

                U+0138

                0x6B

                k LATIN SMALL LETTER K

                ĺ LATIN SMALL LETTER L WITH ACUTE

                U+013A

                0x6C

                l LATIN SMALL LETTER L

                ļ LATIN SMALL LETTER L WITH CEDILLA

                U+013C

                0x6C

                l LATIN SMALL LETTER L

                ľ LATIN SMALL LETTER L WITH CARON

                U+013E

                0x6C

                l LATIN SMALL LETTER L

                ŀ LATIN SMALL LETTER L WITH MIDDLE DOT

                U+0140

                0x6C

                l LATIN SMALL LETTER L

                ł LATIN SMALL LETTER L WITH STROKE

                U+0142

                0x6C

                l LATIN SMALL LETTER L

                ń LATIN SMALL LETTER N WITH ACUTE

                U+0144

                0x6E

                n LATIN SMALL LETTER N

                ņ LATIN SMALL LETTER N WITH CEDILLA

                U+0146

                0x6E

                n LATIN SMALL LETTER N

                ň LATIN SMALL LETTER N WITH CARON

                U+0148

                0x6E

                n LATIN SMALL LETTER N

                ʼn LATIN SMALL LETTER N PRECEDED BY APOSTROPHE

                U+0149

                0x6E

                n LATIN SMALL LETTER N

                 ŋ LATIN SMALL LETTER ENG (Sami)

                U+014B

                0x6E

                n LATIN SMALL LETTER N

                ō LATIN SMALL LETTER O WITH MACRON

                U+014D

                0x6F

                o LATIN SMALL LETTER O

                ŏ LATIN SMALL LETTER O WITH BREVE

                U+014F

                0x6F

                o LATIN SMALL LETTER O

                ° DEGREE SIGN

                U+00B0

                0x6F

                o LATIN SMALL LETTER O

                º MASCULINE ORDINAL INDICATOR

                U+00BA

                0x6F

                o LATIN SMALL LETTER O

                œ LATIN SMALL LIGATURE OE

                U+0153

                0x6F

                o LATIN SMALL LETTER O

                ŕ LATIN SMALL LETTER R WITH ACUTE

                U+0155

                0x72

                r LATIN SMALL LETTER R

                ŗ LATIN SMALL LETTER R WITH CEDILLA

                U+0157

                0x72

                r LATIN SMALL LETTER R

                ř LATIN SMALL LETTER R WITH CARON

                U+0159

                0x72

                r LATIN SMALL LETTER R

                ® REGISTERED SIGN

                U+00AE

                0x72

                r LATIN SMALL LETTER R

                ś LATIN SMALL LETTER S WITH ACUTE

                U+015B

                0x73

                s LATIN SMALL LETTER S

                ŝ LATIN SMALL LETTER S WITH CIRCUMFLEX

                U+015D

                0x73

                s LATIN SMALL LETTER S

                ş LATIN SMALL LETTER S WITH CEDILLA *

                U+015F

                0x73

                s LATIN SMALL LETTER S

                š LATIN SMALL LETTER S WITH CARON

                U+0161

                0x73

                s LATIN SMALL LETTER S

                þ LATIN SMALL LETTER THORN (Icelandic)

                U+00FE

                0x74

                t LATIN SMALL LETTER T

                ţ LATIN SMALL LETTER T WITH CEDILLA *

                U+0163

                0x74

                t LATIN SMALL LETTER T

                ť LATIN SMALL LETTER T WITH CARON

                U+0165

                0x74

                t LATIN SMALL LETTER T

                ŧ LATIN SMALL LETTER T WITH STROKE

                U+0167

                0x74

                t LATIN SMALL LETTER T

                ũ LATIN SMALL LETTER U WITH TILDE

                U+0169

                0x75

                u LATIN SMALL LETTER U

                ū LATIN SMALL LETTER U WITH MACRON

                U+016B

                0x75

                u LATIN SMALL LETTER U

                ŭ LATIN SMALL LETTER U WITH BREVE

                U+016D

                0x75

                u LATIN SMALL LETTER U

                ů LATIN SMALL LETTER U WITH RING ABOVE

                U+016F

                0x75

                u LATIN SMALL LETTER U

                ų LATIN SMALL LETTER U WITH OGONEK

                U+0173

                0x75

                u LATIN SMALL LETTER U

                µ MICRO SIGN

                U+00B5

                0x75

                u LATIN SMALL LETTER U

                ŵ LATIN SMALL LETTER W WITH CIRCUMFLEX

                U+0175

                0x77

                w LATIN SMALL LETTER W

                ŷ LATIN SMALL LETTER Y WITH CIRCUMFLEX

                U+0177

                0x79

                y LATIN SMALL LETTER Y

                ź LATIN SMALL LETTER Z WITH ACUTE

                U+017A

                0x7A

                z LATIN SMALL LETTER Z

                 ż LATIN SMALL LETTER Z WITH DOT ABOVE

                U+017C

                0x7A

                z LATIN SMALL LETTER Z

                ž LATIN SMALL LETTER Z WITH CARON

                U+017E

                0x7A

                z LATIN SMALL LETTER Z

                ő LATIN SMALL LETTER O WITH DOUBLE ACUTE

                U+0151

                0x7C

                ö LATIN SMALL LETTER O WITH DIAERESIS

                ű LATIN SMALL LETTER U WITH DOUBLE ACUTE

                U+0171

                0x7E

                ü LATIN SMALL LETTER U WITH DIAERESIS

                Table 2 lists the 9 characters in Lossy Character 1 supported by Standard SMS Converter but not by Extended SMS Converter.

                Table 2

                Character

                Unicode

                GSM

                Converted Character

                ϕ GREEK PHI SYMBOL

                0x03D5

                0x12

                Φ GREEK CAPITAL LETTER PHI

                Ω OHM SIGN

                0x2126

                0x15

                Ω GREEK CAPITAL LETTER OMEGA

                ∏ N-ARY PRODUCT

                0x220F

                0x16

                Π GREEK CAPITAL LETTER PI

                ∑ N-ARY SUMMATION

                0x2211

                0x18

                Σ GREEK CAPITAL LETTER SIGMA

                ϑ GREEK THETA SYMBOL

                0x03D1

                0x19

                Θ GREEK CAPITAL LETTER THETA

                ϐ GREEK BETA SYMBOL

                0x03D0

                0x42

                B LATIN CAPITAL LETTER B

                ϒ GREEK UPSILON WITH HOOK SYMBOL

                0x03D2

                0x59

                Y LATIN CAPITAL LETTER Y

                ϓ GREEK UPSILON WITH ACUTE AND HOOK SYMBOL

                0x03D3

                0x59

                Y LATIN CAPITAL LETTER Y

                ϔ GREEK UPSILON WITH DIAERESIS AND HOOK SYMBOL

                0x03D4

                0x59

                Y LATIN CAPITAL LETTER Y

                See also

                SMS Encodings and Converters Overview

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B12AAA82-0534-5FBB-B9BA-33056B988575_d0e357005_href.png Binary file Symbian3/SDK/Source/GUID-B12AAA82-0534-5FBB-B9BA-33056B988575_d0e357005_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B12AAA82-0534-5FBB-B9BA-33056B988575_d0e363085_href.png Binary file Symbian3/SDK/Source/GUID-B12AAA82-0534-5FBB-B9BA-33056B988575_d0e363085_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B12EEEF5-311B-49F8-A2DA-D6EF6A705071-master.png Binary file Symbian3/SDK/Source/GUID-B12EEEF5-311B-49F8-A2DA-D6EF6A705071-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B12EEEF5-311B-49F8-A2DA-D6EF6A705071_d0e53053_href.png Binary file Symbian3/SDK/Source/GUID-B12EEEF5-311B-49F8-A2DA-D6EF6A705071_d0e53053_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B12EEEF5-311B-49F8-A2DA-D6EF6A705071_d0e58775_href.png Binary file Symbian3/SDK/Source/GUID-B12EEEF5-311B-49F8-A2DA-D6EF6A705071_d0e58775_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B131AE10-B9B1-53D2-8CAA-A9045957D6F9_d0e213742_href.png Binary file Symbian3/SDK/Source/GUID-B131AE10-B9B1-53D2-8CAA-A9045957D6F9_d0e213742_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B131AE10-B9B1-53D2-8CAA-A9045957D6F9_d0e217479_href.png Binary file Symbian3/SDK/Source/GUID-B131AE10-B9B1-53D2-8CAA-A9045957D6F9_d0e217479_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B16A0370-F18F-4035-B3D6-ED550D8D68F9.dita --- a/Symbian3/SDK/Source/GUID-B16A0370-F18F-4035-B3D6-ED550D8D68F9.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-B16A0370-F18F-4035-B3D6-ED550D8D68F9.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,43 +1,43 @@ - - - - - -Presentation -of text -
                Alignment

                The -default text alignment in left-to-right languages is on the left. There are -only a few exceptions to this in specific cases, for example, soft indicators -in the Idle state, which are right-aligned.

                In right-to-left UI languages, -the default text alignment is on the right.

                -
                Truncation

                When -a text does not fit into the view where it is displayed, it should be truncated. -By default, texts are truncated from the end, and ellipsis (...) is displayed -at the end of the truncated text as an indication. There are two exceptions -to this main rule:

                  -

                • Phone numbers are truncated from the beginning, because the first digits -of a phone number are usually considered less important than the numbers at -the end.

                  • -

                • This general rule may be overridden in certain detailed components, -where the latter part of the text is more differentiating than the beginning. -Such might be, for example, queries to select an email address.

                  • -
                -
                Marquee scrolling

                When -a text does not fit to a list view, the list text can be horizontally scrolling. -Marquee scrolling should be used for texts that are not generated by the phone -and for which truncation is not desired for some reason. For example, a Web -address may not fit to one row of text in a list and it may be important to -see the whole address.

                Scrolling is done only when the item is highlighted. -The text is scrolled in only one direction, and it does not loop.

                -
                Content zooming

                Content -zooming is supported in the various lists, forms and settings in the Symbian -UI. In this way, users can either use smaller font sizes to fit more information -on the screen, or they can increase the text size if necessary. The user can -choose between three different zoom levels using General Settings.

                + + + + + +Presentation +of text +
                Alignment

                The +default text alignment in left-to-right languages is on the left. There are +only a few exceptions to this in specific cases, for example, soft indicators +in the home screen, which are right-aligned.

                In right-to-left UI languages, +the default text alignment is on the right.

                +
                Truncation

                When +a text does not fit into the view where it is displayed, it should be truncated. +By default, texts are truncated from the end, and ellipsis (...) is displayed +at the end of the truncated text as an indication. There are two exceptions +to this main rule:

                  +

                • Phone numbers are truncated from the beginning, because the first digits +of a phone number are usually considered less important than the numbers at +the end.

                  • +

                • This general rule may be overridden in certain detailed components, +where the latter part of the text is more differentiating than the beginning. +Such might be, for example, queries to select an email address.

                  • +
                +
                Marquee scrolling

                When +a text does not fit to a list view, the list text can be horizontally scrolling. +Marquee scrolling should be used for texts that are not generated by the phone +and for which truncation is not desired for some reason. For example, a Web +address may not fit to one row of text in a list and it may be important to +see the whole address.

                Scrolling is done only when the item is highlighted. +The text is scrolled in only one direction, and it does not loop.

                +
                Content zooming

                Content +zooming is supported in the various lists, forms and settings in the Symbian +UI. In this way, users can either use smaller font sizes to fit more information +on the screen, or they can increase the text size if necessary. The user can +choose between three different zoom levels using General Settings.

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B16E3A7D-FF14-559A-BF86-2A1A1A584CDC_d0e341463_href.png Binary file Symbian3/SDK/Source/GUID-B16E3A7D-FF14-559A-BF86-2A1A1A584CDC_d0e341463_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B16E3A7D-FF14-559A-BF86-2A1A1A584CDC_d0e347660_href.png Binary file Symbian3/SDK/Source/GUID-B16E3A7D-FF14-559A-BF86-2A1A1A584CDC_d0e347660_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B172B71E-10DE-5AC6-9F10-A7EC74CE0B7F-master.png Binary file Symbian3/SDK/Source/GUID-B172B71E-10DE-5AC6-9F10-A7EC74CE0B7F-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B172B71E-10DE-5AC6-9F10-A7EC74CE0B7F_d0e382778_href.png Binary file Symbian3/SDK/Source/GUID-B172B71E-10DE-5AC6-9F10-A7EC74CE0B7F_d0e382778_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B1CB6374-2C2B-5D6C-9A7C-6E49D8F235B8.dita --- a/Symbian3/SDK/Source/GUID-B1CB6374-2C2B-5D6C-9A7C-6E49D8F235B8.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-B1CB6374-2C2B-5D6C-9A7C-6E49D8F235B8.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,210 +1,210 @@ - - - - - -Display -Control and Mapping in the Window Server ClientScreenPlay provides support for externally connected displays, -such as TV-out. Previous versions of Symbian and the non-ScreenPlay variant -consider the size of each display to be fixed, assuming it to be built into -the phone. However, for High-Definition Multimedia Interface (HDMI) and composite -video connectors, there is a range of resolutions that can change dynamically. -ScreenPlay provides an optional feature that supports switching between resolutions -at runtime and notifies Window Server clients when there are changes to the -resolution and connectedness. -

                This topic builds on the introduction in Dynamic -Resolution Switching.

                -

                The CWsScreenDevice Window Server client-side API has -a GetInterface() function, which you can use to return pointers -to the MDisplayControl and MDisplayMapping interfaces -or null if the interface is not supported. For example:

                -// Establish connection and get display control interface. -class CWindowClient : public CBase - { - ... - RWsSession iSession; - CWsScreenDevice* iScreenDevice; - MDisplayControl* iDisplayControl; - MDisplayMapping* iDisplayMapping; - TWsDisplayChangedEvent iLastEvent; - } - -void CWindowClient::ConstructL(TInt aDisplayNumber) - { - User::LeaveIfError(iSession.Connect()); - iScreenDevice = new(ELeave) CWsScreenDevice(iSession); - User::LeaveIfError(iScreenDevice->Construct(aDisplayNumber)); - iDisplayControl = iScreenDevice->GetInterface(EDisplayControl); - User::LeaveIfNull(iDisplayControl); - iDisplayMapping = iScreenDevice->GetInterface(EDisplayMapping); - User::LeaveIfNull(iDisplayMapping); - } -

                In addition, CWsScreenDevice provides the IsCurrentModeDynamic() and IsModeDynamic() functions -for querying whether the current screen mode and a given screen mode are dynamic. -If a screen mode is dynamic, the application extent always fills the full -UI space and the area returned by CWsScreenDevice::SizeInPixels() always -matches the actual resolution that is in use. However, the MDisplayMapping interface -also provides features that enable you to draw outside the application UI -extent.

                -
                MDisplayControl

                The MDisplayControl interface -provides Window Server clients with functions for setting and getting the -current display configuration, getting a list of available resolutions and -enabling display change event notifications (EEventDisplayChanged). -The following diagram shows the class hierarchy.

                - Display control class diagram - -

                Once you have obtained -the MDisplayControl interface, you can call GetResolutions() on -it. For example:

                // Get available resolutions -RArray<MDisplayControl::TResolution> resolutions; -User::LeaveIfError(iDisplayControl->GetResolutions(resolutions)); - -// Use resolution list. - -

                You can use the EnableDisplayChangedEvents() function -to register for notifications of the EEventDisplayChanged event. -This is generated when the display device is attached or detached or there -is a change in the current resolution, the resolution list or the current -configuration. For example, this can be generated by a render stage or the -composition engine in response to a hardware event (such as an external display -being connected or disconnected). The event is sometimes, but not always, -triggered by a change in the screen mode.

                There are therefore two -aspects to the event in that it can be triggered by a display change or a -configuration change. Typically you check the event against the previous one -to see what has changed.

                The following table provides a summary of -how this event compares to EEventScreenDeviceChanged.

                - - - -Action -EEventScreenDeviceChanged -EEventDisplayChanged - - - - -

                Screen mode change

                -

                Always triggers this event

                -

                Triggers this event only if it causes a change in the configuration.

                -                 - -

                Display configuration change

                -

                Generally does not trigger this event

                -

                Generally triggers this event

                -                 - - -

                The following example first registers for notification of EEventDisplayChanged events -and then changes the screen mode. The second part illustrates a simplified -handler for the events. It demonstrates checking the event against the previous -one to see whether the resolution or configuration has changed.

                // Establish connection and get display control interface. - -iDisplayControl->EnableDisplayChangeEvents(ETrue); - -iScreenDevice->SetScreenMode(2); // Number depends on WSINI.INI config. -iScreenDevice->SetAppScreenMode(2); // Ensure application windows are - // shown in the new mode. -... - -// Simplified event handler. -TWsEvent event; -iSession.GetEvent(event); - -switch (event.Type()) - { - case EEventScreenDeviceChanged: - { - TSize screenSize = iScreenDevice->SizeInPixels(); - // Re-layout windows for new application screen dimensions - } - break; - case Redraw: - { - // Draw content of window - } - break; - case EEventDisplayChanged: - { - TWsDisplayChangedEvent* newEvent; - newEvent = event.DisplayChanged(); - - if (newEvent->iResolutionListChangeId != - iLastEvent.iResolutionListChangeId) - { - // ... - } - - if (newEvent->iConfigurationChangeId != - iLastEvent.iConfigurationChangeId) - { - TDisplayConfiguration config; - User::LeaveIfError( - iDisplayControl->GetConfiguration(config))); - // Handle updated configuration - // May be entirely handled by screen device changed event - } - iLastEvent = *newEvent; - } - break; - }

                Here is an example of setting a new display resolution:

                TDisplayConfiguration config; -config.SetResolution(TSize(1280, 720)); -config.SetRotation(MDisplayControl::ERotation180); - -User::LeaveIfError(iDisplayControl->SetConfiguration(config)); -
                -
                MDisplayMapping

                The MDisplayMapping interface -enables Window Server clients to map between coordinate spaces, allowing for -translation and scaling of coordinates. For example, suppose an application -is to draw a virtual keyboard outside of the application's extent. This requires -knowing the extent of both the application and the full UI area. The application -can use the MDisplayMapping interface to get this information, -so that the virtual keyboard can be drawn within the full UI area but outside -of the application's extent.

                - Display mapping class diagram - -

                The MDisplayMapping interface is very -flexible. UIDs are used to signify the application UI coordinate space, the -full UI space, the composition/display coordinate space (which may be a different -scale to the UI coordinate space) and the Direct Screen Access (DSA) space -(which may match the full UI space, or be offset relative to the application -UI space).

                The MapCoordinates() function -takes a rectangle, a source space and a target space and returns the correspondingly -mapped rectangle in the target space. To map a point, use a rectangle with -a width and height of one pixel, because the scaling between UI space and -composition/display space may enlarge (or sometimes reduce) the rectangle’s -size.

                For example, consider the following diagram, in which the outer -rectangle represents the display area and the inner one represents the application -space (screen mode).

                -Display area and application extent - -

                The display resolution is 1280 x 720, the application size is 176 -x 208 and a virtual resolution of 426 x 240 has been introduced, which gives -a scaling factor of three in each direction. All pixels are approximately -square, for simplicity. The application area has been centered in the display, -giving an X offset of (426-176)/2 and a Y offset of (240-208)/2, -or (125, 16).

                To put a window on screen to fill the display, create -a rectangle positioned at (0,0) with a size of the current resolution (426 -x 240). Then pass this in with a source space of the full UI and target space -of the application. This results in a rectangle of the same size but at offset -(125,16).

                In addition, to use an external surface at the real resolution, -pass this rectangle in with a source space of the application UI and a target -space of the composition/display. This results in a rectangle with size of -1280 x 720, which you can then use when creating the surface. Because the -UI surface and external surface are scaled independently, the UI memory requirements -can remain low, even with high resolution video, viewfinder and games. For -an example code snippet, see External -Surfaces Overview.

                -                 -Window Server -Client-Side Library Concepts -Dynamic Resolution - Switching -The wsini.ini -File Reference + + + + + +Display +Control and Mapping in the Window Server ClientScreenPlay provides support for externally connected displays, +such as TV-out. Previous versions of Symbian and the non-ScreenPlay variant +consider the size of each display to be fixed, assuming it to be built into +the phone. However, for High-Definition Multimedia Interface (HDMI) and composite +video connectors, there is a range of resolutions that can change dynamically. +ScreenPlay provides an optional feature that supports switching between resolutions +at runtime and notifies Window Server clients when there are changes to the +resolution and connectedness. +

                This topic builds on the introduction in Dynamic +Resolution Switching.

                +

                The CWsScreenDevice Window Server client-side API has +a GetInterface() function, which you can use to return pointers +to the MDisplayControl and MDisplayMapping interfaces +or null if the interface is not supported. For example:

                +// Establish connection and get display control interface. +class CWindowClient : public CBase + { + ... + RWsSession iSession; + CWsScreenDevice* iScreenDevice; + MDisplayControl* iDisplayControl; + MDisplayMapping* iDisplayMapping; + TWsDisplayChangedEvent iLastEvent; + } + +void CWindowClient::ConstructL(TInt aDisplayNumber) + { + User::LeaveIfError(iSession.Connect()); + iScreenDevice = new(ELeave) CWsScreenDevice(iSession); + User::LeaveIfError(iScreenDevice->Construct(aDisplayNumber)); + iDisplayControl = iScreenDevice->GetInterface(EDisplayControl); + User::LeaveIfNull(iDisplayControl); + iDisplayMapping = iScreenDevice->GetInterface(EDisplayMapping); + User::LeaveIfNull(iDisplayMapping); + } +

                In addition, CWsScreenDevice provides the IsCurrentModeDynamic() and IsModeDynamic() functions +for querying whether the current screen mode and a given screen mode are dynamic. +If a screen mode is dynamic, the application extent always fills the full +UI space and the area returned by CWsScreenDevice::SizeInPixels() always +matches the actual resolution that is in use. However, the MDisplayMapping interface +also provides features that enable you to draw outside the application UI +extent.

                +
                MDisplayControl

                The MDisplayControl interface +provides Window Server clients with functions for setting and getting the +current display configuration, getting a list of available resolutions and +enabling display change event notifications (EEventDisplayChanged). +The following diagram shows the class hierarchy.

                + Display control class diagram + +

                Once you have obtained +the MDisplayControl interface, you can call GetResolutions() on +it. For example:

                // Get available resolutions +RArray<MDisplayControl::TResolution> resolutions; +User::LeaveIfError(iDisplayControl->GetResolutions(resolutions)); + +// Use resolution list. + +

                You can use the EnableDisplayChangedEvents() function +to register for notifications of the EEventDisplayChanged event. +This is generated when the display device is attached or detached or there +is a change in the current resolution, the resolution list or the current +configuration. For example, this can be generated by a render stage or the +composition engine in response to a hardware event (such as an external display +being connected or disconnected). The event is sometimes, but not always, +triggered by a change in the screen mode.

                There are therefore two +aspects to the event in that it can be triggered by a display change or a +configuration change. Typically you check the event against the previous one +to see what has changed.

                The following table provides a summary of +how this event compares to EEventScreenDeviceChanged.

                + + + +Action +EEventScreenDeviceChanged +EEventDisplayChanged + + + + +

                Screen mode change

                +

                Always triggers this event

                +

                Triggers this event only if it causes a change in the configuration.

                +                 + +

                Display configuration change

                +

                Generally does not trigger this event

                +

                Generally triggers this event

                +                 + + +

                The following example first registers for notification of EEventDisplayChanged events +and then changes the screen mode. The second part illustrates a simplified +handler for the events. It demonstrates checking the event against the previous +one to see whether the resolution or configuration has changed.

                // Establish connection and get display control interface. + +iDisplayControl->EnableDisplayChangeEvents(ETrue); + +iScreenDevice->SetScreenMode(2); // Number depends on WSINI.INI config. +iScreenDevice->SetAppScreenMode(2); // Ensure application windows are + // shown in the new mode. +... + +// Simplified event handler. +TWsEvent event; +iSession.GetEvent(event); + +switch (event.Type()) + { + case EEventScreenDeviceChanged: + { + TSize screenSize = iScreenDevice->SizeInPixels(); + // Re-layout windows for new application screen dimensions + } + break; + case Redraw: + { + // Draw content of window + } + break; + case EEventDisplayChanged: + { + TWsDisplayChangedEvent* newEvent; + newEvent = event.DisplayChanged(); + + if (newEvent->iResolutionListChangeId != + iLastEvent.iResolutionListChangeId) + { + // ... + } + + if (newEvent->iConfigurationChangeId != + iLastEvent.iConfigurationChangeId) + { + TDisplayConfiguration config; + User::LeaveIfError( + iDisplayControl->GetConfiguration(config))); + // Handle updated configuration + // May be entirely handled by screen device changed event + } + iLastEvent = *newEvent; + } + break; + }

                Here is an example of setting a new display resolution:

                TDisplayConfiguration config; +config.SetResolution(TSize(1280, 720)); +config.SetRotation(MDisplayControl::ERotation180); + +User::LeaveIfError(iDisplayControl->SetConfiguration(config)); +
                +
                MDisplayMapping

                The MDisplayMapping interface +enables Window Server clients to map between coordinate spaces, allowing for +translation and scaling of coordinates. For example, suppose an application +is to draw a virtual keyboard outside of the application's extent. This requires +knowing the extent of both the application and the full UI area. The application +can use the MDisplayMapping interface to get this information, +so that the virtual keyboard can be drawn within the full UI area but outside +of the application's extent.

                + Display mapping class diagram + +

                The MDisplayMapping interface is very +flexible. UIDs are used to signify the application UI coordinate space, the +full UI space, the composition/display coordinate space (which may be a different +scale to the UI coordinate space) and the Direct Screen Access (DSA) space +(which may match the full UI space, or be offset relative to the application +UI space).

                The MapCoordinates() function +takes a rectangle, a source space and a target space and returns the correspondingly +mapped rectangle in the target space. To map a point, use a rectangle with +a width and height of one pixel, because the scaling between UI space and +composition/display space may enlarge (or sometimes reduce) the rectangle’s +size.

                For example, consider the following diagram, in which the outer +rectangle represents the display area and the inner one represents the application +space (screen mode).

                +Display area and application extent + +

                The display resolution is 1280 x 720, the application size is 176 +x 208 and a virtual resolution of 426 x 240 has been introduced, which gives +a scaling factor of three in each direction. All pixels are approximately +square, for simplicity. The application area has been centered in the display, +giving an X offset of (426-176)/2 and a Y offset of (240-208)/2, +or (125, 16).

                To put a window on screen to fill the display, create +a rectangle positioned at (0,0) with a size of the current resolution (426 +x 240). Then pass this in with a source space of the full UI and target space +of the application. This results in a rectangle of the same size but at offset +(125,16).

                In addition, to use an external surface at the real resolution, +pass this rectangle in with a source space of the application UI and a target +space of the composition/display. This results in a rectangle with size of +1280 x 720, which you can then use when creating the surface. Because the +UI surface and external surface are scaled independently, the UI memory requirements +can remain low, even with high resolution video, viewfinder and games. For +an example code snippet, see External +Surfaces Overview.

                +                 +Window Server +Client-Side Library Concepts +Dynamic Resolution + Switching +The wsini.ini +File Reference                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B1D63E7B-81EB-5F75-96C3-789E5C3E4C03.dita --- a/Symbian3/SDK/Source/GUID-B1D63E7B-81EB-5F75-96C3-789E5C3E4C03.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-B1D63E7B-81EB-5F75-96C3-789E5C3E4C03.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,238 +1,238 @@ - - - - - -How to -construct and manipulate a doubly linked listThis document describes how to construct and use a doubly linked -list. -

                The following code fragments show how a doubly linked list can be constructed -and manipulated. The list consists of CItem objects. In this -example, a CItem object can contain an item of text implemented -as an HBufC. The CItem objects can form -elements of a doubly linked list using the iDlink data member -as the link object.

                -

                The class is declared as:

                -class CItem : public CBase - { -public : - static CItem* NewL(const TDesC& aText); - static CItem* NewLC(const TDesC& aText); - virtual ~CItem(); -public : - static const TInt iOffset; -private : - void ConstructL(const TDesC& aText); -private : - TDblQueLink iDlink; - HBufC* iText; - friend class CXy; - }; -

                The CItem member functions are implemented as:

                -const TInt CItem::iOffset = _FOFF(CItem,iDlink); -CItem* CItem::NewLC(const TDesC& aText) - { - CItem* self = new (ELeave) CItem; - CleanupStack::PushL(self); - self->ConstructL(aText); - return self; - } -CItem* CItem::NewL(const TDesC& aText) - { - CItem* self = CItem::NewLC(aText); - CleanupStack::Pop(); - return self; - } -void CItem::ConstructL(const TDesC& aText) - { - iText = aText.AllocL(); - } -CItem::~CItem() - { - delete (iText); - } -

                As part of its construction process, a CItem constructs -an HBufC of the correct length and copies the content of -the descriptor parameter into it.

                -

                A CXy object maintains the list by:

                -
                  -

                • creating CItem objects -and adding them into the list

                  • -

                • removing CItem objects -from the list and then destroying them

                  • -
                -

                The class is declared as:

                -class CXy : public CBase - { -public : - CXy(); - virtual ~CXy(); - void DoItems(); - TBool AddItem(const TDesC& anItem,TItemPos aPos); -private : - TDblQue<CItem> iHdr; - TDblQueIter<CItem> iIter; - }; -

                Here, the list header, iHdr, and the iterator, iIter, -are declared as data members of the class and are constructed when the CXy object -is constructed. A C++ constructor must be supplied so that iIter can -be properly constructed. (TDblQueIter has no default constructor).

                -

                Specifically:

                -
                  -

                • AddItem() constructs -a new CItem and adds it to the list, either after the current -item or at the end of the list.

                  • -

                • DoItems() scans -through the list, removing and destroying each element from the list.

                  • -
                -

                The CXy member functions are implemented as:

                -CXy::CXy() - : iHdr(CItem::iOffset),iIter(iHdr) //construct header & iterator - {} -CXy::~CXy() - { - CItem* anyitem; - - iIter.SetToFirst(); - while ((anyitem = iIter++) != NULL) - { - anyitem->iDlink.Deque(); - delete anyitem; - }; - } -

                Before destroying a CXy object, the list is destroyed. -This is achieved using the iterator. The iterator pointer is set to point -to each element in turn, removing that element from the list before destroying -it.

                -

                Once the iterator has reached the end of the list, the operator++ returns NULL.

                -

                The destruction process is safe if the list is empty; the statement iter.SetToFirst() is -harmless, the operator++ returns NULL and -execution of the body of the while loop never happens.

                -TBool CXy::AddItem(const TDesC& aText,TItemPos aPos) - { - CItem* newitem; - - TRAPD(leavecode,newitem = CItem::NewL(aText)); - if (leavecode != KErrNone) - return EFalse; // Cannot create a CItem - switch (aPos) - { - case EAtEnd: - iHdr.AddLast(*newitem); // Add at back of list - return ETrue; - - case EAfterCurrent: - CItem* currentitem = iIter; - if (currentitem) - { - newitem->iDlink.Enque(&currentitem->iDlink); - iIter.Set(*newitem); - } - else - { - iHdr.AddFirst(*newitem); - iIter.SetToFirst(); - } - return ETrue; - } - - return EFalse; - } -

                This member function creates a new CItem and then, depending -on the value of aPos, either adds it at the back of the list -or after the current element. TItemPos is just an enumeration -taking the enumerators EAtEnd and EAfterCurrent.

                -

                The statement:

                -newitem->iDlink.Enque(&currentitem->iDlink); -

                inserts the newly created CItem with pointer newitem, after the -existing item with pointer currentitem.

                -

                Note also that the statement:

                -CItem* currentitem = iIter; - -

                implicitly uses the conversion operator T*() where, in -general, T is the class forming elements of the list. In -this specific example, the conversion operator returns a pointer to the current -element, of type CItem, in the list. Immediately after construction -of the iterator iIter, the value of currentitem is NULL.

                -void CXy::DoItems() - { - CItem* currentitem; - - iIter.SetToFirst(); - - while((currentitem = iIter++) != NULL) - { - // do something with the text; - currentitem->iDlink.Deque(); - delete currentitem; - }; - } -

                The DoItems() member function iterates through the whole -list, removing each CItem object in turn before destroying -it. This member function could be modified to include extra functionality -before the removal and destruction of the CItem element.

                -

                If the list is empty on entry to this function, the iter.SetToFirst() statement -is safe, currentitem is NULL on the first -execution of the while condition and the body of the while loop -is never executed.

                -

                Executing the code:

                - { - _LIT(KTxtOne,"one"); - _LIT(KTxtTwo,"two"); - _LIT(KTxtThree",three"); - _LIT(KTxtFour,"four"); - _LIT(KTxtFive,"five"); - _LIT(KTxtSix,"six"); - - CXy* items; - - items = new CXy; - - items->AddItem(KTxtone,EAfterCurrent); - items->AddItem(KTxttwo,EAtEnd); - items->AddItem(KTxtthree,EAfterCurrent); - items->AddItem(KTxtfour,EAtEnd); - items->AddItem(KTxtfive,EAfterCurrent); - items->AddItem(KTxtsix,EAtEnd); - ... - -

                results in the construction of a doubly linked list of CItem objects -each containing a pointer to an HBufC descriptor containing -the text as shown:

                - - -<image href="GUID-03AC137D-173A-558C-A2F3-9522870AC43C_d0e217986_href.png" placement="inline"/> -</fig> -<p>The following code destroys the list elements and the <codeph>CXy</codeph> object -containing the list header and iterator:</p> -<codeblock id="GUID-37EF4182-834F-51BF-9250-61B479BFD3D1" xml:space="preserve"> ... - items->DoItems(); - delete items; - }</codeblock> -<p>There are a number of other possible ways to proceed, depending on the -precise needs of an application. In the previous example, the list header -and the iterator are declared as members of the class.</p> -<p>Some situations may demand that a list be created, used and destroyed within -the scope of a member function. Because list headers and iterators are “<codeph>T</codeph> ” -types, they can be declared on the stack; for example:</p> -<codeblock id="GUID-E29EDC0D-C7DE-5E35-B39F-DA63110DF630" xml:space="preserve">void CXy::SomeFunction(); - { - TDblQue<CItem> iHdr(CItem::iOffset); - TDblQueIter<CItem> iIter(iHdr); - - // the body of the function - // - - } -</codeblock> -<p>The list header and the iterator go out of scope at the end of the function -and are destroyed. Unless the list elements themselves are “<codeph>T</codeph> ” -types and exist on the stack, make sure that they are explicitly destroyed -before the function terminates.</p> +<?xml version="1.0" encoding="utf-8"?> +<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> +<!-- This component and the accompanying materials are made available under the terms of the License +"Eclipse Public License v1.0" which accompanies this distribution, +and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> +<!-- Initial Contributors: + Nokia Corporation - initial contribution. +Contributors: +--> +<!DOCTYPE concept + PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> +<concept id="GUID-B1D63E7B-81EB-5F75-96C3-789E5C3E4C03" xml:lang="en"><title>How to +construct and manipulate a doubly linked listThis document describes how to construct and use a doubly linked +list. +

                The following code fragments show how a doubly linked list can be constructed +and manipulated. The list consists of CItem objects. In this +example, a CItem object can contain an item of text implemented +as an HBufC. The CItem objects can form +elements of a doubly linked list using the iDlink data member +as the link object.

                +

                The class is declared as:

                +class CItem : public CBase + { +public : + static CItem* NewL(const TDesC& aText); + static CItem* NewLC(const TDesC& aText); + virtual ~CItem(); +public : + static const TInt iOffset; +private : + void ConstructL(const TDesC& aText); +private : + TDblQueLink iDlink; + HBufC* iText; + friend class CXy; + }; +

                The CItem member functions are implemented as:

                +const TInt CItem::iOffset = _FOFF(CItem,iDlink); +CItem* CItem::NewLC(const TDesC& aText) + { + CItem* self = new (ELeave) CItem; + CleanupStack::PushL(self); + self->ConstructL(aText); + return self; + } +CItem* CItem::NewL(const TDesC& aText) + { + CItem* self = CItem::NewLC(aText); + CleanupStack::Pop(); + return self; + } +void CItem::ConstructL(const TDesC& aText) + { + iText = aText.AllocL(); + } +CItem::~CItem() + { + delete (iText); + } +

                As part of its construction process, a CItem constructs +an HBufC of the correct length and copies the content of +the descriptor parameter into it.

                +

                A CXy object maintains the list by:

                +
                  +

                • creating CItem objects +and adding them into the list

                  • +

                • removing CItem objects +from the list and then destroying them

                  • +
                +

                The class is declared as:

                +class CXy : public CBase + { +public : + CXy(); + virtual ~CXy(); + void DoItems(); + TBool AddItem(const TDesC& anItem,TItemPos aPos); +private : + TDblQue<CItem> iHdr; + TDblQueIter<CItem> iIter; + }; +

                Here, the list header, iHdr, and the iterator, iIter, +are declared as data members of the class and are constructed when the CXy object +is constructed. A C++ constructor must be supplied so that iIter can +be properly constructed. (TDblQueIter has no default constructor).

                +

                Specifically:

                +
                  +

                • AddItem() constructs +a new CItem and adds it to the list, either after the current +item or at the end of the list.

                  • +

                • DoItems() scans +through the list, removing and destroying each element from the list.

                  • +
                +

                The CXy member functions are implemented as:

                +CXy::CXy() + : iHdr(CItem::iOffset),iIter(iHdr) //construct header & iterator + {} +CXy::~CXy() + { + CItem* anyitem; + + iIter.SetToFirst(); + while ((anyitem = iIter++) != NULL) + { + anyitem->iDlink.Deque(); + delete anyitem; + }; + } +

                Before destroying a CXy object, the list is destroyed. +This is achieved using the iterator. The iterator pointer is set to point +to each element in turn, removing that element from the list before destroying +it.

                +

                Once the iterator has reached the end of the list, the operator++ returns NULL.

                +

                The destruction process is safe if the list is empty; the statement iter.SetToFirst() is +harmless, the operator++ returns NULL and +execution of the body of the while loop never happens.

                +TBool CXy::AddItem(const TDesC& aText,TItemPos aPos) + { + CItem* newitem; + + TRAPD(leavecode,newitem = CItem::NewL(aText)); + if (leavecode != KErrNone) + return EFalse; // Cannot create a CItem + switch (aPos) + { + case EAtEnd: + iHdr.AddLast(*newitem); // Add at back of list + return ETrue; + + case EAfterCurrent: + CItem* currentitem = iIter; + if (currentitem) + { + newitem->iDlink.Enque(&currentitem->iDlink); + iIter.Set(*newitem); + } + else + { + iHdr.AddFirst(*newitem); + iIter.SetToFirst(); + } + return ETrue; + } + + return EFalse; + } +

                This member function creates a new CItem and then, depending +on the value of aPos, either adds it at the back of the list +or after the current element. TItemPos is just an enumeration +taking the enumerators EAtEnd and EAfterCurrent.

                +

                The statement:

                +newitem->iDlink.Enque(&currentitem->iDlink); +

                inserts the newly created CItem with pointer newitem, after the +existing item with pointer currentitem.

                +

                Note also that the statement:

                +CItem* currentitem = iIter; + +

                implicitly uses the conversion operator T*() where, in +general, T is the class forming elements of the list. In +this specific example, the conversion operator returns a pointer to the current +element, of type CItem, in the list. Immediately after construction +of the iterator iIter, the value of currentitem is NULL.

                +void CXy::DoItems() + { + CItem* currentitem; + + iIter.SetToFirst(); + + while((currentitem = iIter++) != NULL) + { + // do something with the text; + currentitem->iDlink.Deque(); + delete currentitem; + }; + } +

                The DoItems() member function iterates through the whole +list, removing each CItem object in turn before destroying +it. This member function could be modified to include extra functionality +before the removal and destruction of the CItem element.

                +

                If the list is empty on entry to this function, the iter.SetToFirst() statement +is safe, currentitem is NULL on the first +execution of the while condition and the body of the while loop +is never executed.

                +

                Executing the code:

                + { + _LIT(KTxtOne,"one"); + _LIT(KTxtTwo,"two"); + _LIT(KTxtThree",three"); + _LIT(KTxtFour,"four"); + _LIT(KTxtFive,"five"); + _LIT(KTxtSix,"six"); + + CXy* items; + + items = new CXy; + + items->AddItem(KTxtone,EAfterCurrent); + items->AddItem(KTxttwo,EAtEnd); + items->AddItem(KTxtthree,EAfterCurrent); + items->AddItem(KTxtfour,EAtEnd); + items->AddItem(KTxtfive,EAfterCurrent); + items->AddItem(KTxtsix,EAtEnd); + ... + +

                results in the construction of a doubly linked list of CItem objects +each containing a pointer to an HBufC descriptor containing +the text as shown:

                + + +<image href="GUID-03AC137D-173A-558C-A2F3-9522870AC43C_d0e214249_href.png" placement="inline"/> +</fig> +<p>The following code destroys the list elements and the <codeph>CXy</codeph> object +containing the list header and iterator:</p> +<codeblock id="GUID-37EF4182-834F-51BF-9250-61B479BFD3D1" xml:space="preserve"> ... + items->DoItems(); + delete items; + }</codeblock> +<p>There are a number of other possible ways to proceed, depending on the +precise needs of an application. In the previous example, the list header +and the iterator are declared as members of the class.</p> +<p>Some situations may demand that a list be created, used and destroyed within +the scope of a member function. Because list headers and iterators are “<codeph>T</codeph> ” +types, they can be declared on the stack; for example:</p> +<codeblock id="GUID-E29EDC0D-C7DE-5E35-B39F-DA63110DF630" xml:space="preserve">void CXy::SomeFunction(); + { + TDblQue<CItem> iHdr(CItem::iOffset); + TDblQueIter<CItem> iIter(iHdr); + + // the body of the function + // + + } +</codeblock> +<p>The list header and the iterator go out of scope at the end of the function +and are destroyed. Unless the list elements themselves are “<codeph>T</codeph> ” +types and exist on the stack, make sure that they are explicitly destroyed +before the function terminates.</p> </conbody></concept> \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B21638E4-B3B5-4D4C-B3F5-1627E367F100.dita --- a/Symbian3/SDK/Source/GUID-B21638E4-B3B5-4D4C-B3F5-1627E367F100.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-B21638E4-B3B5-4D4C-B3F5-1627E367F100.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,18 +1,23 @@ -<?xml version="1.0" encoding="utf-8"?> -<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> -<!-- This component and the accompanying materials are made available under the terms of the License -"Eclipse Public License v1.0" which accompanies this distribution, -and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> -<!-- Initial Contributors: - Nokia Corporation - initial contribution. -Contributors: ---> -<!DOCTYPE concept - PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> -<concept id="GUID-B21638E4-B3B5-4D4C-B3F5-1627E367F100" xml:lang="en"><title>Cut, -copy, and paste -

                The Cut, Copy and Paste functions are available from the Options menu -in editors. In viewers, Copy command is in a stylus pop-up menu that is opened -via touch release after text selection.

                -

                Dragging function works both in editors and viewers.

                + + + + + +Cut, +copy, and paste +

                The Cut, Copy and Paste functions are available from the Options menu +in editors. In viewers, Copy command is in a stylus pop-up menu that is opened +via touch release after text selection.

                +

                Dragging function works both in editors and viewers.

                +
                See Also
                  +

                • Selecting text

                  • +

                • Text editing

                  • +

                • Editing Menu

                  • +
                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B21A4858-162A-50F1-8F88-4259B7F7238E_d0e113898_href.png Binary file Symbian3/SDK/Source/GUID-B21A4858-162A-50F1-8F88-4259B7F7238E_d0e113898_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B21A4858-162A-50F1-8F88-4259B7F7238E_d0e120436_href.png Binary file Symbian3/SDK/Source/GUID-B21A4858-162A-50F1-8F88-4259B7F7238E_d0e120436_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B2523978-4262-4E32-B50D-4818AC561B6D-master.png Binary file Symbian3/SDK/Source/GUID-B2523978-4262-4E32-B50D-4818AC561B6D-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B2523978-4262-4E32-B50D-4818AC561B6D_d0e63770_href.png Binary file Symbian3/SDK/Source/GUID-B2523978-4262-4E32-B50D-4818AC561B6D_d0e63770_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B2523978-4262-4E32-B50D-4818AC561B6D_d0e68992_href.png Binary file Symbian3/SDK/Source/GUID-B2523978-4262-4E32-B50D-4818AC561B6D_d0e68992_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B26A4743-F331-5AC3-A40A-28B14B785857.dita --- a/Symbian3/SDK/Source/GUID-B26A4743-F331-5AC3-A40A-28B14B785857.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-B26A4743-F331-5AC3-A40A-28B14B785857.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,127 +1,117 @@ - - - - - -SearchSortExample: -enhanced search and sort for Message StoreThis example demonstrates the enhanced search and sort API for -message stores. This API was implemented in Symbian^3. -
                Purpose

                Prior to Symbian^3, the Message Store API -had limited support for selecting and sorting message records and fields. -From Symbian^3, the API implements more extensive search and sort options.

                This -example demonstrates the new functionality by implementing the following use -cases:

                  -

                • Display the header information -for all message entries.

                  • -

                • Perform a simple (single -search criteria) non-iterative search-sort and display the matching entries. -This has the following options:

                    -

                  • case sensitivity on -/ off,

                    • -

                  • whole word search on -/ off.

                    • -
                  • -

                • Perform a combined (more -than one search criteria) non-iterative search-sort and display the number -of matching entries. This has the following options:

                    -

                  • case sensitivity on -/ off,

                    • -

                  • whole word search on -/ off.

                    • -
                  • -

                • Perform an iterative -search-sort (searches for entries one at a time) and display the number of -matching entries.

                  • -

                • Perform a search-sort -using a query ID. The query ID is generated by a previous search-sort operation.

                  • -

                Before implementing these use cases, the example creates a POP3/SMTP -message store with five message entries.

                -
                Class summary

                The example demonstrates the following -classes and enums:

                CMsvSearchSortOperation CMsvSearchSortQuery TMsvMessagePart TMsvSearchSortResultType

                -
                Download

                Click -on the following link to download the example: searchsortexample.zip

                Click: browse to view the example code.

                -
                Design -and implementation

                Project Implementation

                The project -implements the following classes:

                CKeyReader: Derived from CActive. -This reads keypresses and calls the appropriate example function.

                CMessAsyncWaiter: Derived -from CActive. This handles the CMsvSearchSortOperation::RequestL() asynchronous -request. This RequestL() function takes CMessAsyncWaiter::iStatus as -one of its parameters and then waits on the status. When the search is complete -the client is notified of the event's completion by CMessAsyncWaiter::RunL() being -called, after which the example prepares the buffer and displays the results.

                CSearchsortExample: Derived -from CBase and MMsvSessionObserver. MMsvSessionObserver is -an interface for notification of events from a Message Server session.

                CSearchsortExample implements HandleSessionEventL() to handle the two event types EMsvEntriesCreated and EMsvServerReady. -It also creates the SMTP message entries and carries out searching and sorting.

                Simple -non-iterative search-sort

                The example starts by creating a message -server session using CMsvSession, which represents a channel -of communication between a client thread (client-side MTM, user interface -MTM, or message client application) and the Message Server thread. Then it -creates an instance of CMsvSearchSortOperation to perform -the search-sort operation, and passes the session object into it.

                A -search-sort query is created using CMsvSearchSortQuery::NewL() and -is configured using various member functions of class CMsvSearchSortQuery for -instance whether to search for whole or partial words and the case sensitivity.

                The -search and sort options are added to the query using CMsvSearchSortQuery::AddSearchOptionL() and CMsvSearchSortQuery::AddSortOptionL().

                The search-sort operation is started by calling CMsvSearchSortOperation::RequestL(), -passing the query as a parameter. If no iterator parameter is specified, the -search defaults to non-iterative.

                An instance of the CMessAsyncWaiter class -is created for handling the asynchronous search request. This object is waited -on until the Message Server completes the request. The results of the search -are stored in an array using CMsvSearchSortOperation::GetResultsL().

                The -result count is displayed by calling CMsvSearchSortOperation::GetResultCountL().

                The -query ID of the search is retrieved from the Message server, for later use, -using the CMsvSearchSortOperation::GetQueryId() function.

                Simple -iterative search-sort

                Iterative search-sort follows the same steps -as described above, except that an iterator parameter is passed to the RequestL() function. -To retrieve the results, CMsvSearchSortOperation::GetNextResultL() is -called in a while loop to retrieve one entry at a time. Iterative -searching is useful when the client may not have enough memory to store an -array of results.

                Combined search-sort

                A combined search-sort -is done by adding additional search options using CMsvSearchSortQuery::AddSearchOptionL().

                Search-sort -using a query ID

                A query ID identifies a search-sort query. It -is obtained by calling CMsvSearchSortOperation::GetQueryIdL() following -the completion of CMsvSearchSortOperation::RequestL(). -In this example, the query ID generated by the simple non-iterative search-sort -is used to repeat the same search-sort. The overloaded CMsvSearchSortOperation::RequestL() function -is used to initiate a search-sort operation with a query ID.

                After -the request completes, a list of index entry ID objects (TMsvId or TMsvEntry depending -on how the query was configured, using CMsvSearchSortQuery::SetResultType()) -is retrieved using CMsvSearchSortOperation::GetResultsL(). -Finally the matching results are displayed in the console.

                -
                Building and -configuring

                To build the example:

                  -

                • You can build the example -from your IDE or the command line.

                  If you use an IDE, import the bld.inf file -of the example into your IDE, and use the build command of the IDE.

                  If -you use the command line, open a command prompt, and set the current directory -to the source code directory of the example. You can then build the example -with the SBSv1 build tools with the following commands:

                  bldmake -bldfiles

                  abld build

                  How to use bldmake and How to use abld describe -how to use the SBSv1 build tools.

                  • -

                • For the emulator, the -example builds an executable called searchsortexample.exe in -the epoc32\release\winscw\<udeb or urel>\ folder.

                  • -
                -
                Running the -example

                searchsortexample.exe takes user -input from the console. The menu for the current example is as shown below:

                - -

                The user input is handled by CKeyReader::RunL().

                For -simple and combined non-iterative search-sort, the user provides the following -inputs: 1) the text in the "To" field to search for, 2) whether case sensitivity -is on of off, 3) whether whole word searching is on or off.

                The input -values are saved in variables which are passed to the function CSearchsortExample::SearchSortRequestWithoutIteratorL(), -and the settings are made accordingly.

                For the combined search-sort -the 2nd and 3rd search options (size and subject) are hard coded. The iterative -search-sort searches by size, which is also hard coded.

                To execute -a search-sort using a query ID, CMsvSearchSortOperation::RequestL() must -first have been called because it generates the query ID. So, either option -2 or 3 must have been called before option 5.

                -
                See also

                Search-Sort -Overview

                + + + + + +SearchSortExample: enhanced search and sort for Message StoreThis example demonstrates the enhanced search and sort +API for message stores. This API was implemented in Symbian^3. +
                Purpose

                Prior to Symbian^3, the Message Store API had limited support +for selecting and sorting message records and fields. From Symbian^3, +the API implements more extensive search and sort options.

                This example demonstrates the new functionality by implementing the +following use cases:

                  +

                • Display the +header information for all message entries.

                  • +

                • Perform a simple +(single search criteria) non-iterative search-sort and display the +matching entries. This has the following options:

                    +

                  • case sensitivity +on / off,

                    • +

                  • whole word search +on / off.

                    • +
                  • +

                • Perform a combined +(more than one search criteria) non-iterative search-sort and display +the number of matching entries. This has the following options:

                    +

                  • case sensitivity +on / off,

                    • +

                  • whole word search +on / off.

                    • +
                  • +

                • Perform an iterative +search-sort (searches for entries one at a time) and display the number +of matching entries.

                  • +

                • Perform a search-sort +using a query ID. The query ID is generated by a previous search-sort +operation.

                  • +

                Before implementing these use cases, the example creates +a POP3/SMTP message store with five message entries.

                +
                Class +summary

                The example demonstrates the following classes and +enums:

                  +

                • CMsvSearchSortOperation

                  • +

                • CMsvSearchSortQuery

                  • +

                • TMsvMessagePart

                  • +

                • TMsvSearchSortResultType

                  • +
                +
                Download

                Click on the following link to download the example: searchsortexample.zip

                Click: browse to view the example code.

                +
                Design and implementation

                Project Implementation

                The project implements the following classes:

                CKeyReader: Derived from CActive. This reads +keypresses and calls the appropriate example function.

                CMessAsyncWaiter: Derived from CActive. This +handles the CMsvSearchSortOperation::RequestL() asynchronous +request. This RequestL() function takes CMessAsyncWaiter::iStatus as one of its parameters and then waits on the status. When the +search is complete the client is notified of the event's completion +by CMessAsyncWaiter::RunL() being called, after which +the example prepares the buffer and displays the results.

                CSearchsortExample: Derived from CBase and MMsvSessionObserver. MMsvSessionObserver is an interface for notification of events from a Message Server +session.

                CSearchsortExample implements HandleSessionEventL() to handle the two event types EMsvEntriesCreated and EMsvServerReady. +It also creates the SMTP message entries and carries out searching +and sorting.

                Simple non-iterative search-sort

                The example starts by creating a message server session using CMsvSession, which represents a channel of communication +between a client thread (client-side MTM, user interface MTM, or message +client application) and the Message Server thread. Then it creates +an instance of CMsvSearchSortOperation to perform +the search-sort operation, and passes the session object into it.

                A search-sort query is created using CMsvSearchSortQuery::NewL() and is configured using various member functions of class CMsvSearchSortQuery for instance whether to search for +whole or partial words and the case sensitivity.

                The search +and sort options are added to the query using CMsvSearchSortQuery::AddSearchOptionL() and CMsvSearchSortQuery::AddSortOptionL().

                The search-sort operation is started by calling CMsvSearchSortOperation::RequestL(), passing the query as a parameter. If no iterator parameter is specified, +the search defaults to non-iterative.

                An instance of the CMessAsyncWaiter class is created for handling the asynchronous +search request. This object is waited on until the Message Server +completes the request. The results of the search are stored in an +array using CMsvSearchSortOperation::GetResultsL().

                The result count is displayed by calling CMsvSearchSortOperation::GetResultCountL().

                The query ID of the search is retrieved from the Message +server, for later use, using the CMsvSearchSortOperation::GetQueryId() function.

                Simple iterative search-sort

                Iterative +search-sort follows the same steps as described above, except that +an iterator parameter is passed to the RequestL() function. To retrieve the results, CMsvSearchSortOperation::GetNextResultL() is called in a while loop to retrieve one entry +at a time. Iterative searching is useful when the client may not have +enough memory to store an array of results.

                Combined search-sort

                A combined search-sort is done by adding additional search +options using CMsvSearchSortQuery::AddSearchOptionL().

                Search-sort using a query ID

                A query ID +identifies a search-sort query. It is obtained by calling CMsvSearchSortOperation::GetQueryIdL() following the completion +of CMsvSearchSortOperation::RequestL(). In this +example, the query ID generated by the simple non-iterative search-sort +is used to repeat the same search-sort. The overloaded CMsvSearchSortOperation::RequestL() function is used to initiate a search-sort operation with a query +ID.

                After the request completes, a list of index entry ID +objects (TMsvId or TMsvEntry depending on how the query was configured, using CMsvSearchSortQuery::SetResultType()) is retrieved using CMsvSearchSortOperation::GetResultsL(). Finally the matching results are displayed in the console.

                +
                Building +and configuring

                To build the example:

                  +

                • You can build +the example from your IDE or the command line.

                  If you use +an IDE, import the bld.inf file of the example +into your IDE, and use the build command of the IDE.

                  If you +use the command line, open a command prompt, and set the current directory +to the source code directory of the example. You can then build the +example with the SBSv1 build tools with the following commands:

                  bldmake bldfiles

                  abld +build

                  How to use bldmake and How to +use abld describe how to use the SBSv1 build tools.

                  • +

                • For the emulator, +the example builds an executable called searchsortexample.exe in the epoc32\release\winscw\<udeb +or urel>\ folder.

                  • +
                +
                Running +the example

                searchsortexample.exe takes user input from the console. The menu for the current example +is as shown below:

                + +

                The user input is handled by CKeyReader::RunL().

                For simple and combined non-iterative search-sort, the +user provides the following inputs: 1) the text in the "To" field +to search for, 2) whether case sensitivity is on of off, 3) whether +whole word searching is on or off.

                The input values are saved +in variables which are passed to the function CSearchsortExample::SearchSortRequestWithoutIteratorL(), and the settings are made accordingly.

                For the combined +search-sort the 2nd and 3rd search options (size and subject) are +hard coded. The iterative search-sort searches by size, which is also +hard coded.

                To execute a search-sort using a query ID, CMsvSearchSortOperation::RequestL(CMsvSearchSortQuery *,TBool,TRequestStatus +&,TInt) must first have been called because it generates +the query ID. So, either option 2 or 3 must have been called before +option 5.

                +
                See +also

                Search-Sort Overview

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B2B34DFF-6EBE-424A-9480-C9F1CB6E2D56_d0e3348_href.png Binary file Symbian3/SDK/Source/GUID-B2B34DFF-6EBE-424A-9480-C9F1CB6E2D56_d0e3348_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B2B34DFF-6EBE-424A-9480-C9F1CB6E2D56_d0e4623_href.png Binary file Symbian3/SDK/Source/GUID-B2B34DFF-6EBE-424A-9480-C9F1CB6E2D56_d0e4623_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B2E63B13-7B72-5CBF-ACD0-1F2D2E1EEF19_d0e185390_href.png Binary file Symbian3/SDK/Source/GUID-B2E63B13-7B72-5CBF-ACD0-1F2D2E1EEF19_d0e185390_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B2E63B13-7B72-5CBF-ACD0-1F2D2E1EEF19_d0e191986_href.png Binary file Symbian3/SDK/Source/GUID-B2E63B13-7B72-5CBF-ACD0-1F2D2E1EEF19_d0e191986_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B3166752-9B99-5669-8AB4-078164144AA1_d0e176531_href.png Binary file Symbian3/SDK/Source/GUID-B3166752-9B99-5669-8AB4-078164144AA1_d0e176531_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B3166752-9B99-5669-8AB4-078164144AA1_d0e183125_href.png Binary file Symbian3/SDK/Source/GUID-B3166752-9B99-5669-8AB4-078164144AA1_d0e183125_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B32ED85A-913E-5C06-AEEB-1E2D6EF4CECF.dita --- a/Symbian3/SDK/Source/GUID-B32ED85A-913E-5C06-AEEB-1E2D6EF4CECF.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-B32ED85A-913E-5C06-AEEB-1E2D6EF4CECF.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,30 +1,30 @@ - - - - - -Drawing a Rounded Rectangle

                This topic provides an example that demonstrates how to draw a rounded rectangle using DrawRoundRect(). The dimensions of each corner (corner size and corner height) are given by a TSize argument.

                - Rounded rectangle construction - ... -// draw a rectangle with rounded corners, centered in the rectangle -TSize cornerSize(20,20); // set up the size of a rounded cornerSize -gc.DrawRoundRect(box,cornerSize); -...

                In the following example code, one of the ellipses specified by the corner argument is shown, to illustrate how the rounded rectangle is constructed:

                ... -// draw a rectangle with rounded corners, -//centered in the rectangle, showing a corner ellipse -TSize cornerSize(20,20); // size of a rounded corner - -// rect for corner ellipse is twice the corner size -TSize cornerEllipseSize(cornerSize.iHeight*2,cornerSize.iWidth*2); -TRect cornerRectTl(box.iTl,cornerEllipseSize); -gc.DrawRoundRect(box,cornerSize); -gc.SetPenStyle(CGraphicsContext::EDottedPen); -gc.DrawEllipse(cornerRectTl); // corner construction ellipse -...                 Drawing + + + + + +Drawing a Rounded Rectangle

                This topic provides an example that demonstrates how to draw a rounded rectangle using DrawRoundRect(). The dimensions of each corner (corner size and corner height) are given by a TSize argument.

                + Rounded rectangle construction + ... +// draw a rectangle with rounded corners, centered in the rectangle +TSize cornerSize(20,20); // set up the size of a rounded cornerSize +gc.DrawRoundRect(box,cornerSize); +...

                In the following example code, one of the ellipses specified by the corner argument is shown, to illustrate how the rounded rectangle is constructed:

                ... +// draw a rectangle with rounded corners, +//centered in the rectangle, showing a corner ellipse +TSize cornerSize(20,20); // size of a rounded corner + +// rect for corner ellipse is twice the corner size +TSize cornerEllipseSize(cornerSize.iHeight*2,cornerSize.iWidth*2); +TRect cornerRectTl(box.iTl,cornerEllipseSize); +gc.DrawRoundRect(box,cornerSize); +gc.SetPenStyle(CGraphicsContext::EDottedPen); +gc.DrawEllipse(cornerRectTl); // corner construction ellipse +...                 Drawing to a Graphics Context Tutorials Drawing and Graphics Contexts                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B340078C-9EFC-4017-8F43-B0BBCE4935DC.dita --- a/Symbian3/SDK/Source/GUID-B340078C-9EFC-4017-8F43-B0BBCE4935DC.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,89 +0,0 @@ - - - - - -Playing -a video clip -

                To open, play and retrieve information about video data stored in a -file, descriptor, or URL, use the video player utility of the Multimedia Framework -to develop your application. To play a video clip, the application needs to -repeat the steps described in the illustration below.

                -The steps required to play a video clip -

                To play a video clip, use the methods of the CVideoPlayerUtility class -to construct your application.

                -
                To play a video -
                  -

                1. Create a video -player object, open a video clip and prepare it to be played.

                  -
                    -

                  • Create a player object using the CVideoPlayerUtility::NewL() method.

                    -
                    • -

                  • Open a video clip from a file, descriptor using the respective CVideoPlayerUtility::OpenFileL() or CVideoPlayerUtility::OpenDesL(). Streamed -content can be opened with CVideoPlayerUtility::OpenUrlL(). MVideoPlayerUtilityObserver::MvpuoOpenComplete() is -called upon completion.

                    • -

                  • Prepare the video clip to be read using CVideoPlayerUtility::Prepare(). MVideoPlayerUtilityObserver::MvpuoPrepareComplete() is -called upon completion.

                    • -
                  -
                  2. -

                2. Configure -the player settings.

                  You can check and set, for example, the playback -priority, display window, audio track, video frame size and frame rate, audio -and video codecs and bitrates, and the MIME type of the video clip. For more -information on the options, see the CVideoPlayerUtility class.

                  -
                  3. -

                3. Play the video -clip.

                  -
                    -

                  • Start the playback of a video clip using the CVideoPlayerUtility::Play() method.

                    -
                    • -

                  • Pause playback using the CVideoPlayerUtility::PauseL() method. Resume playback -by calling CVideoPlayerUtility::Play() again.

                    • -

                  • Stop playback using the CVideoPlayerUtility::Stop() method. If the playback -is not explicitly stopped, MVideoPlayerUtilityObserver::MvpuoPlayComplete() is called upon completion.

                    • -
                  -
                  4. -

                4. To exit the -application or to switch it to the background, close the video clip and unload -all controllers using the CVideoPlayerUtility::Close() method.

                  5. -

                5. Include the VideoPlayer.h header -file in the appropriate class file(s).

                  6. -

                6. Make sure -you have correct capabilities information -set for your application. You need at least the UserEnvironment capability. -If you want to set the recording priority for the video/audio device, you -need the MultimediaDD capability.

                  7. -

                7. Make sure mediaclientvideo.lib is -accessible to your linker when compiling your application by including it -in your mmp file or by editing the project properties in -your IDE, depending on your build environment.

                  8. -
                -
                -
                Additional information -on playing a video clip -

                For code examples, see How -to play a video using CVideoPlayerUtility on Forum Nokia Developer -Community Wiki.

                -

                For more information on CVideoPlayerUtility, see Multimedia -recipes at the Symbian Foundation.

                -

                For information on the codecs needed to play a video clip, see Supported codecs.

                -

                For more information about CVideoPlayerUtility in the -Video Client library see following documents:

                -
                  -

                • Creating -and Preparing a Video Player

                  • -

                • Configuring -the Video Player

                  • -

                • Controlling -Video Playback

                  • -

                • Controlling -the Video Controller Plugin

                  • -
                -
                -                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B35E6CAD-C9C8-467E-85CF-9781DEC8BF7C.dita --- a/Symbian3/SDK/Source/GUID-B35E6CAD-C9C8-467E-85CF-9781DEC8BF7C.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-B35E6CAD-C9C8-467E-85CF-9781DEC8BF7C.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,89 +1,89 @@ - - - - - -Text -editingThis section describes the common principles of text editing, focusing -on Latin based scripts. Requirements of other writing systems and input methods, -such as those used for Chinese or Arabic, are not covered in detail. -

                Character input is accomplished using the keyboard. S60 supports both a -full QWERTY keyboard and the ITU-T standard for numeric keypads. It specifies -the mapping of Latin (English) characters to the keys, assigning three or -four letters to each Numeric key from 2 to 9. The input of a specific character -can happen either by repeated key presses within a time-out, or using some -language-specific algorithm that tries to find the correct characters according -to the produced key sequence.

                -

                For more information on text input on touch devices, see Text -input.

                -

                Some keys, such as the star (*), hash (#) key, clear key, and edit key, -have specific functions assigned to them during text editing. The functions -depend on the keyboard type (ITU-T or QWERTY) and whether text prediction -or multitapping mode is active. The four available modes are:

                -
                  -

                • ITU-T inmultitapping mode

                  • -

                • ITU-T with text prediction on

                  • -

                • QWERTY keyboard with text prediction on

                  • -

                • QWERTY keyboard with text prediction off

                  • -
                -Specific key -functions on ITU-T keypad - - - -

                Key

                 -

                Function on ITU-T keypad

                 -                 - - - -

                Numeric key 1

                 -

                Punctuation. The most used punctuation characters are available -using repeated key presses within a time-out.

                 -                 - -

                Star (*) key

                 -

                In the alpha mode, offers the next match in Predictive Text input. -In the alpha mode, a long press opens the special characters table, where -the complete set of punctuation and other characters are displayed. One character -can be picked at a time with Selection key. It is also possible to feed in -more than one character without having to re-open the list by pressing 5 on -the desired characters one after another and completing the selection by pressing -Selection key on the last item. In a typical number mode, produces a * character, -repeated presses produce other characters allowed within phone numbers: +, -p, w.

                In devices with no Edit key, a short press of the Star (*) key -opens the editing menu and a long press opens the special characters table.

                 -                 - -

                Hash (#) key

                 -

                In the alpha mode, changes the character case (upper case, lower -case, text case). In a typical number mode, produces a # character.In devices -with no Edit key, a short press changes the current case and the text prediction -mode (on/off), and a long key press (together with the Arrow keys) selects -text.

                 -                 - -

                Clear key

                 -

                Clears the previous character from the cursor. In case more characters -are selected, clears all the selected characters.

                 -                 - -

                Edit key

                -

                Press and release: opens the editing menu (see Editing -menu). Selects characters when pressed simultaneously with the Arrow -keys (see Selecting -text).

                 -                 - - -
                -
                Using -text editing in C++ applications

                The API to use for providing text -editing functionality is the Editors API. For implementation information, see Using the Editors API.

                + + + + + +Text +editingThis section describes the common principles of text editing, focusing +on Latin based scripts. Requirements of other writing systems and input methods, +such as those used for Chinese or Arabic, are not covered in detail. +

                Character input is accomplished using the keyboard. S60 supports both a +full QWERTY keyboard and the ITU-T standard for numeric keypads. It specifies +the mapping of Latin (English) characters to the keys, assigning three or +four letters to each Numeric key from 2 to 9. The input of a specific character +can happen either by repeated key presses within a time-out, or using some +language-specific algorithm that tries to find the correct characters according +to the produced key sequence.

                +

                For more information on text input on touch devices, see Text +input.

                +

                Some keys, such as the star (*), hash (#) key, clear key, and edit key, +have specific functions assigned to them during text editing. The functions +depend on the keyboard type (ITU-T or QWERTY) and whether text prediction +or multi-tapping mode is active. The four available modes are:

                +
                  +

                • ITU-T in multi-tapping mode.

                  • +

                • ITU-T with text prediction ON.

                  • +

                • QWERTY keyboard with text prediction ON.

                  • +

                • QWERTY keyboard with text prediction OFF.

                  • +
                +Specific key +functions on ITU-T keypad + + + +

                Key

                 +

                Function on ITU-T keypad

                 +                 + + + +

                Numeric key 1

                 +

                Punctuation. The most used punctuation characters are available +using repeated key presses within a time-out.

                 +                 + +

                Star (*) key

                 +

                In the alpha mode, offers the next match in Predictive Text input. +In the alpha mode, a long press opens the special characters table, where +the complete set of punctuation and other characters are displayed. One character +can be picked at a time with Selection key. It is also possible to feed in +more than one character without having to re-open the list by pressing 5 on +the desired characters one after another and completing the selection by pressing +Selection key on the last item. In a typical number mode, produces a * character, +repeated presses produce other characters allowed within phone numbers: +, +p, w.

                In devices with no Edit key, a short press of the Star (*) key +opens the editing menu and a long press opens the special characters table.

                 +                 + +

                Hash (#) key

                 +

                In the alpha mode, changes the character case (upper case, lower +case, text case). In a typical number mode, produces a # character.In devices +with no Edit key, a short press changes the current case and the text prediction +mode (ON/OFF), and a long key press (together with the Arrow keys) selects +text.

                 +                 + +

                Clear key

                 +

                Clears the previous character from the cursor. In case more characters +are selected, clears all the selected characters.

                 +                 + +

                Edit key

                +

                Press and release: opens the editing menu (see Editing +menu). Selects characters when pressed simultaneously with the Arrow +keys (see Selecting +text).

                 +                 + + +
                +
                Using +text editing in applications

                The API to use for providing text editing +functionality is the Editors API. For implementation information, see Using the Editors API.

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B3760707-2810-4CD9-82C7-6A40DE638D36.dita --- a/Symbian3/SDK/Source/GUID-B3760707-2810-4CD9-82C7-6A40DE638D36.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-B3760707-2810-4CD9-82C7-6A40DE638D36.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,23 +1,23 @@ - - - - - -Submenu -indicators -

                A submenu is at times used for changing the mode or temporary settings -in applications. Radio buttons are used when only one item may be selected -and tick marks are used where the user can choose more than one item. The -indicators show the currently active mode or settings when the submenu is -opened.

                - -Submenu indicators: radio buttons - - + + + + + +Submenu +indicators +

                A submenu is at times used for changing the mode or temporary settings +in applications. Radio buttons are used when only one item may be selected +and tick marks are used where the user can choose more than one item. The +indicators show the currently active mode or settings when the submenu is +opened.

                + +Submenu indicators: radio buttons + +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B386CA7A-F527-5584-9455-371E623DCF76.dita --- a/Symbian3/SDK/Source/GUID-B386CA7A-F527-5584-9455-371E623DCF76.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-B386CA7A-F527-5584-9455-371E623DCF76.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,172 +1,163 @@ - - - - - - System -Start Example -
                Download

                Click on the following link to download -the example: SysStart.zip

                Click: browse to view the example code.

                -
                Description

                This -example demonstrates the use of resource files at the time of System Start-up. -System starter is an architecture designed to provide a consistent, transparent, -easily customisable method of starting components (i.e. servers and applications) -at device boot. It allows an ordering of components according to criticality -and dependency by means of a Static Start-up Configuration (SSC).

                -
                Related APIs

                egSysStart::E32Main ()

                egSysStart::Simple -()

                -
                Resource files

                In -this example a resource file SSCForStartupMode0.rss is used -at Start-up.

                On a target device booting normally, the SSC SSCForStartupMode0.rss is -always used for start-up. This SSC is associated with startup mode zero, which -is defined as EStartupModeUndefined in e32modes.h. The -System Starter architecture provides an ability to select between a number -of static Start-up configurations (rss files) depending on the desired Start-up -Mode, for example: Full, Emergency, Charging, or Test. Each of these modes -may require different sets of components and order of execution.

                The -start-up process in the resource file is staged via an ordering of Start-up -States or phases. These states cannot be removed or their values altered. -They appear in the following order:

                EStartupStateUndefined – -Value before the system enters its first state/ undefined state.

                EStartupStateCriticalStatic – -Within this Start-up State all ROM based (static) components or resources -that are critical to the operation of the phone function are started.

                EStartupStateCriticalDynamic – -Within this Start-up State all non-ROM based (dynamic) components or resources -that are critical to the operation of the phone function are started.

                EStartupStateNonCritical – -Within this Start-up State all ROM based (static) or non-ROM based (dynamic) -components or resources that are non-critical to the operation of the phone -function are started. All components that have not already been started and -are required at device boot are started in this Start-up State.

                This -allows start-up to be split into separate, distinct states with a defined -order. Within each state, a STATE_INFO structure containing -information regarding that state is located. This contains the following information:

                - - - -

                Id

                -

                The id of the state as defined in the custom header file

                -                 - -

                Name

                -

                A text string describing the state

                -                 - -

                Command_list

                -

                The name of the Command array in the SSC which contains the list -of Commands to invoke in that state

                -                 - -

                Next

                -

                The name of the Command array corresponding to the next state

                -                 - - -

                Following the STATE_INFO structure in the SSC -is a COMMAND_ARRAY structure. This contains details of all -commands to be executed within that list. Its name matches the command_list -identifier in the STATE_INFO struct and contains one array -entry: Commands. The Command entry contains a list of all commands to be executed. -Each instance in the rss file is headed with the START_PROCESS_INFO identifier -and contains any value needed to override the defaults specified in startup.rh.

                - - - -Type -

                Set by default. Should not be specified in the SSC.

                -                 - -Path -

                The location of the binary e.g. path = "Z:\sys\bin\fbserv.exe"

                -                 - -Args -

                Arguments passed to the process.

                -                 - -start_method -

                The enum TStartupCommandType is defined in startup.hrh. -Currently it takes one of three values:

                  -

                • EFireAndForget (the -default)

                  • -

                • EWaitForStart

                  • -

                • EDeferredWaitForStart

                  • -

                Use EFireAndForget if there is no need for the -process to be started serially in other words as soon as the process has been -invoked, the System Starter can continue with starting the next process without -waiting for the process to rendezvous.

                Use EWaitForStart if -the process needs to get to a certain stage before starting the next process. -The starter cannot continue with the next Command until a rendezvous has been -made with the first process.

                Note that the apparc component must be -started with mode EWaitForStart to allow connection with -the server to take place.

                Use EDeferredWaitForStart if -there is no need to start the process serially, but at a later stage there -is a command which cannot be invoked until this process has initialized. Using -this value allows a number of commands to be started and the System Starter -to wait for them all at a later point in the SSC. This ensures later on that -the initializations of all EDeferredWaitForStart commands -have completed.

                EWaitForStart and EDeferredWaitForStart depend -upon receiving a rendezvous from the started process. By default this is performed -automatically by EikonEnv. If however, you wish your component to perform -its own rendezvous, then the following function should be overridden in your -AppUi class and return EFalse.

                TBool CCoeAppUi::FrameworkCallsRendezvous();

                -                 - -timeout -

                This field is for use with start_method EWaitForStart only.

                Indicate -if a timer should be started when attempting to start the process by filling -in this timeout value in milliseconds. The value is 0 by default indicating -that no timer will be started.

                Note that if the timer expires before -a rendezvous with the component is made, the component will be killed. If -the component is a critical process this will result in a Kern:4 Panic (which -on licensee phones usually initiates in a system restart).

                -                 - -retry_failure_recovery_method -

                This specifies the action to take if an error is returned from an -attempt to start the process.

                It is set to ERestartOS by -default. This means if the process fails to start the system will restart -in the default start-up mode.

                If it is set to EIgnoreOnFailure then -the starter will continue with the next Command. This option is intended for -non-critical components on which nothing critical is dependent.

                If -it is set to ERestartOSWithMode the system will be restarted -in a specific start-up mode.

                Note: this field has a slightly different -use depending on the start mode: in modes EFireAndForget and EDeferredWaitForStart a -failure will be indicated only if there is an immediate error for example -the initial process creation/invocation fails. In EWaitForStart a -failure will also be indicated if there is no successful rendezvous.

                -                 - -no_of_retries_on_failure -

                For use with start_method EWaitForStart only. -Set to 0 by default.

                This specifies the maximum number of times the -starter should try to start a failed process. After the process has been retried -the specified number of times, the starter will act according to the value -in the retry_failure_recovery_method field. This is used -in conjunction with the timeout value.

                -                 - -monitor -

                Indicates whether the started process should be monitored for failure -by the System Monitor component. The value is 0 by default indicating that -no monitoring will be done.

                A value of 1 indicates monitoring should -be performed. The recovery policy set by retry_failure_recovery_method (and -if applicable retry_failure_recovery_startup_mode) will be used by the System -Monitor if a failure occurs to this process during the lifetime of the system.

                Note: -if the component being started is a System Critical process, monitoring must -not be enabled.

                -                 - -retry_failure_recovery_startup_mode -

                For use with retry_failure_recovery_method ERestartOSWithMode only.

                Used -to specify the start-up mode the system should restart with. This is set to EStartupModeUndefined by -default.

                -                 - - -
                + + + + + + System Start Example +
                Download

                Click on the following link to +download the example: SysStart.zip

                Click: browse to view the example code.

                +
                Description

                This example demonstrates the use of resource files at the time +of System Start-up. System starter is an architecture designed to +provide a consistent, transparent, easily customisable method of starting +components (i.e. servers and applications) at device boot. It allows +an ordering of components according to criticality and dependency +by means of a Static Start-up Configuration (SSC).

                +
                Related APIs
                  +

                • egSysStart::E32Main ()

                  • +

                • egSysStart::Simple ()

                  • +
                +
                Resource +files

                In this example a resource file SSCForStartupMode0.rss is used at Start-up.

                On a target device booting normally, +the SSC SSCForStartupMode0.rss is always used for +start-up. This SSC is associated with startup mode zero, which is +defined as EStartupModeUndefined in e32modes.h. +The System Starter architecture provides an ability to select between +a number of static Start-up configurations (rss files) depending on +the desired Start-up Mode, for example: Full, Emergency, Charging, +or Test. Each of these modes may require different sets of components +and order of execution.

                The start-up process in the resource +file is staged via an ordering of Start-up States or phases. These +states cannot be removed or their values altered. They appear in the +following order:

                TStartupCommandType::EStartupStateUndefined – Value before the system enters its first state/ undefined state.

                TStartupCommandType::EStartupStateCriticalStatic – Within this Start-up State all ROM based (static) components or +resources that are critical to the operation of the phone function +are started.

                TStartupCommandType::EStartupStateCriticalDynamic – Within this Start-up State all non-ROM based (dynamic) components +or resources that are critical to the operation of the phone function +are started.

                TStartupCommandType::EStartupStateNonCritical – Within this Start-up State all ROM based (static) or non-ROM based +(dynamic) components or resources that are non-critical to the operation +of the phone function are started. All components that have not already +been started and are required at device boot are started in this Start-up +State.

                This allows start-up to be split into separate, distinct +states with a defined order. Within each state, a STATE_INFO structure containing information regarding that state is located. +This contains the following information:

                + + + +

                Id

                +

                The id of the state as defined in the custom header file

                +                 + +

                Name

                +

                A text string describing the state

                +                 + +

                Command_list

                +

                The name of the Command array in the SSC which contains +the list of Commands to invoke in that state

                +                 + +

                Next

                +

                The name of the Command array corresponding to the next +state

                +                 + + +

                Following the STATE_INFO structure in +the SSC is a COMMAND_ARRAY structure. This contains +details of all commands to be executed within that list. Its name +matches the command_list identifier in the STATE_INFO struct and contains one array entry: Commands. The Command entry +contains a list of all commands to be executed. Each instance in the +rss file is headed with the START_PROCESS_INFO identifier +and contains any value needed to override the defaults specified in startup.rh.

                + + + +Type +

                Set by default. Should not be specified in the SSC.

                +                 + +Path +

                The location of the binary e.g. path = "Z:\sys\bin\fbserv.exe"

                +                 + +Args +

                Arguments passed to the process.

                +                 + +start_method +

                The enum TStartupCommandType is defined +in startup.hrh. Currently it takes one of three values:

                  +

                • EFireAndForget (the default)

                  • +

                • EWaitForStart

                  • +

                • EDeferredWaitForStart

                  • +

                Use EFireAndForget if there is no need +for the process to be started serially in other words as soon as the +process has been invoked, the System Starter can continue with starting +the next process without waiting for the process to rendezvous.

                Use EWaitForStart if the process needs to +get to a certain stage before starting the next process. The starter +cannot continue with the next Command until a rendezvous has been +made with the first process.

                Note that the apparc component +must be started with mode EWaitForStart to allow +connection with the server to take place.

                Use EDeferredWaitForStart if there is no need to start the process serially, but at a later +stage there is a command which cannot be invoked until this process +has initialized. Using this value allows a number of commands to be +started and the System Starter to wait for them all at a later point +in the SSC. This ensures later on that the initializations of all EDeferredWaitForStart commands have completed.

                EWaitForStart and EDeferredWaitForStart depend upon receiving a rendezvous from the started process. By +default this is performed automatically by EikonEnv. If however, you +wish your component to perform its own rendezvous, then the following +function should be overridden in your AppUi class and return EFalse.

                TBool CCoeAppUi::FrameworkCallsRendezvous();

                +                 + +timeout +

                This field is for use with start_method EWaitForStart only.

                Indicate if a timer should be started when attempting +to start the process by filling in this timeout value in milliseconds. +The value is 0 by default indicating that no timer will be started.

                Note that if the timer expires before a rendezvous with the component +is made, the component will be killed. If the component is a critical +process this will result in a Kern:4 Panic (which on licensee phones +usually initiates in a system restart).

                +                 + +retry_failure_recovery_method +

                This specifies the action to take if an error is returned +from an attempt to start the process.

                It is set to ERestartOS by default. This means if the process fails +to start the system will restart in the default start-up mode.

                If it is set to EIgnoreOnFailure then the +starter will continue with the next Command. This option is intended +for non-critical components on which nothing critical is dependent.

                If it is set to ERestartOSWithMode the system +will be restarted in a specific start-up mode.

                Note: this +field has a slightly different use depending on the start mode: in +modes EFireAndForget and EDeferredWaitForStart a failure will be indicated only if there is an immediate error +for example the initial process creation/invocation fails. In EWaitForStart a failure will also be indicated if there +is no successful rendezvous.

                +                 + +no_of_retries_on_failure +

                For use with start_method EWaitForStart only. Set to 0 by default.

                This specifies the maximum number +of times the starter should try to start a failed process. After the +process has been retried the specified number of times, the starter +will act according to the value in the retry_failure_recovery_method field. This is used in conjunction with the timeout value.

                +                 + +monitor +

                Indicates whether the started process should be monitored +for failure by the System Monitor component. The value is 0 by default +indicating that no monitoring will be done.

                A value of 1 indicates +monitoring should be performed. The recovery policy set by retry_failure_recovery_method (and if applicable retry_failure_recovery_startup_mode) +will be used by the System Monitor if a failure occurs to this process +during the lifetime of the system.

                Note: if the component +being started is a System Critical process, monitoring must not be +enabled.

                +                 + +retry_failure_recovery_startup_mode +

                For use with retry_failure_recovery_method ERestartOSWithMode only.

                Used to specify the start-up mode the system should +restart with. This is set to EStartupModeUndefined by default.

                +                 + + +
                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B3BE018B-0EC5-5866-9BD7-50CBF5670324.dita --- a/Symbian3/SDK/Source/GUID-B3BE018B-0EC5-5866-9BD7-50CBF5670324.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-B3BE018B-0EC5-5866-9BD7-50CBF5670324.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,242 +1,244 @@ - - - - - -Language-Neutral -Files

                Language-Neutral files are files that are required to be installed -irrespective of the languages supported on the Symbian device.

                This -Language-Neutral files section specifies the location and name of each file -on the PC and its target location on the Symbian device. Files are installed -in the order in which they are specified in the PKG file.

                -Syntax "source-filename" - "destination-filename"[, install-options]

                where

                - - - -

                Argument

                -

                Description

                -                 - -

                source-filename

                -

                Specifies the name and location of the file on computer that must -be included in the SIS file.

                -                 - -

                destination-filename

                -

                Specifies the location on the Symbian device, to which the file -must be installed. See, destination-filename for more information.

                -                 - -

                install-options

                -

                Specifies the type of file and how it affects the installation or -removal. It is an optional comma-separated list. See, install-options, for more information.

                -                 - - -

                destination-filename

                The destination-filename must -specify the full path. A ! character can be used instead -of a drive letter to enable the Symbian device user to install the file to -any required location. As an alternative to !, the $ character -can be used to denote the system drive.

                The destination-filename must -not be specified if the file is not required to be installed. For example, -a text file containing a licence agreement to be displayed during the installation -must not include destination-filename and can be specified with empty quotes.

                If -a file can be installed by other packages, for example, a shared DLL, it is -recommended to install it using an embedded SIS file.

                The destination-filename can -be specified in one of the following formats:

                "drive:path" "!:path" ""

                install-options

                The -following table provides a list of the install-options.

                - - - -Name -Abbreviation -Description - - - - -

                FILE

                -

                FF

                -

                Specifies a standard installable file. For example:

                "text\file1.txt"-"!:\private\E800005A\file1.txt", FF                 -                 - -

                FILETEXT

                [,text-options]

                -

                FT

                [,text-options]

                -

                A text file that is displayed in a dialog box during installation. -The dialog type is determined by the text-options specified. -See, text-options for -more information.

                Text files are not installed on the target device, -so the target location is empty. An example FILETEXT line -is:

                "text\textfilec.txt"-"", FT, TC

                Any FILETEXT statements -present in a PKG file for a preinstalled application are ignored by the software -installer.

                -                 - -

                FILERUN

                [,run-options][,RUNWAITEND]

                -

                FR

                [,run-options][,RW]

                -

                Specifies a file that is installed on the Symbian device and run -during installation or uninstallation of packages based on the RI, RR and RB arguments. -For details, see run-options.

                For -example:

                "\epoc32\release\armv5\urel\zoom.exe"-"!:\sys\bin\zoom.exe", FILERUN, RUNINSTALL

                Notes:

                  -

                • The file can be an executable -or a document containing text.

                  • -

                • The untrusted applications -are run through the FILERUN (FR) -or FILEMIME (FM) statements based on configuration -of the installation policy.

                  • -
                 -                 - -

                FILEMIME,

                mime-type

                ,run-options

                [,RUNWAITEND]

                -

                FM,

                mime-type

                ,run-options -[,RW]

                -

                Instructs the installer to associate the file with the default application -associated with the given MIME type, for example, text or - x-vCard is required to be open for contact details.

                The -MIME type in quotes must be specified after the FM argument. FILEMIME is -intended for use with files that are launched during the installation or uninstallation -and not for standard installation files. For example:

                "my_picture.gif"-"", FM, "image/gif", RI

                The Software Installer ignores any FILEMIME statements -present in a PKG file for a preinstalled application.

                -                 - - -

                text-options

                text-options can -be used after FT is specified. It is used by the UI to determine -the type of dialog that is used to display the text. It can have one of the -following values.

                - - - -Name -Abbreviation -Description - - - - -

                TEXTCONTINUE

                -

                TC

                -

                It is recommended that the UI displays a dialog containing a Continue button.

                The -installation continues regardless of the return value of the dialog.

                -                 - -

                TEXTABORT

                -

                TA

                -

                It is recommended that the UI displays a dialog containing Yes /No buttons.

                The -software installer continues with the installation if the dialog returns true -(if the Symbian device user selects Yes). It aborts the installation -if the dialog returns false (if the Symbian device user selects No).

                -                 - -

                TEXTEXIT

                -

                TE

                -

                Same as TEXTABORT.

                -                 - -

                FORCEABORT

                -

                FA

                -

                It is recommended that the UI displays a dialog containing a ForceAbort button.

                On -selecting this dialog, it aborts the installation.

                -                 - -

                TEXTSKIP

                 -

                TS

                 -

                It is recommended that the UI displays a dialog containing Yes /No buttons.

                The -software installer continues the installation without skipping -the file mentioned in the next statement if the dialog returns true (if the -Symbian device user selects Yes). It skips the installation -of the file mentioned in the next statement if the dialog returns false (if -the Symbian device user selects No).

                 -                 - - -

                Note: UIs can implement installation dialogs differently, -so you must refer to the UI SDK for details about the actual behaviour.

                run-options

                run-options can -be used after FR or FM has been specified. -It can be any of the following:

                - - - -Name -Abbreviation -Description - - - - -

                RUNINSTALL

                -

                RI

                -

                Run on install

                -                 - -

                RUNREMOVE

                -

                RR

                -

                Run on uninstall and upgrade

                -                 - -

                RUNBOTH

                -

                RB

                -

                Run on install, uninstall and upgrade

                -                 - -

                RUNBEFORESHUTDOWN

                -

                RBS

                -

                Run on uninstall before the applications in the package are shut -down

                -                 - - -

                Optionally, RW (or RUNWAITEND) -can be specified in addition to the run-options. If this -option is specified, the installation server waits for the program to terminate -before continuing with the install. If this option is not specified, the installation -server runs the program and continues with the installation. The program is -shut down after the installation is complete.

                When uninstalling a package -with a RUNREMOVE or RUNBOTH executable specified, -the installation server always waits for the executable to terminate or timeout -before continuing with the uninstall.

                Verification options

                The -following option is available for checking the integrity of a file at restore -time:

                - - - -Name -Abbreviation -Description - - - - -

                VERIFY

                -

                VR

                -

                This flag is necessary if the integrity of a file installed in a -directory outside \sys or \restore needs -to be verified at restore time. For example, an application can check this -flag to verify that a security policy file restored to its private directory -is identical to the file delivered by the SIS file.

                The following -example illustrates the usage of this option:

                "data\ups_01041000_01041001.rsc"- -"$:\private\10283558\policies\ups_01041000_01041001.rsc", VERIFY                 -                 - - -

                Import and Private -Directories

                The software installer ensures that files are placed -in appropriate areas of the file system. The following rules are applied:

                  -

                • A package can only deliver -a data file into the private directory belonging to any executable in the -package. If a package delivers three executables: SID1, SID2, SID3 (where -SID stands for Secure ID), then data files can be delivered to /private/SID1/, /private/SID2/, -or /private/SID3/. In an upgrade, this is possible by -associating the upgrade package with the SIDs present in the original package -unless one of the original executables is to be removed during the upgrade.

                  • -

                • Any package can deliver -a file into the //private/SID/import of an entirely unrelated -package. However, replacement and eclipsing rules apply.

                  • -
                 + + + + + +Language-Neutral +Files

                Language-Neutral files are files that are required to be installed +irrespective of the languages supported on the Symbian device.

                This +Language-Neutral files section specifies the location and name of each file +on the PC and its target location on the Symbian device. Files are installed +in the order in which they are specified in the PKG file.

                +Syntax "source-filename" - "destination-filename"[, install-options]

                where

                + + + +

                Argument

                +

                Description

                +                 + +

                source-filename

                +

                Specifies the name and location of the file on computer that must +be included in the SIS file.

                +                 + +

                destination-filename

                +

                Specifies the location on the Symbian device, to which the file +must be installed. See, destination-filename for more information.

                +                 + +

                install-options

                +

                Specifies the type of file and how it affects the installation or +removal. It is an optional comma-separated list. See, install-options, for more information.

                +                 + + +

                destination-filename

                The destination-filename must +specify the full path. A ! character can be used instead +of a drive letter to enable the Symbian device user to install the file to +any required location. As an alternative to !, the $ character +can be used to denote the system drive.

                The destination-filename must +not be specified if the file is not required to be installed. For example, +a text file containing a licence agreement to be displayed during the installation +must not include destination-filename and can be specified with empty quotes.

                If +a file can be installed by other packages, for example, a shared DLL, it is +recommended to install it using an embedded SIS file.

                The destination-filename can +be specified in one of the following formats:

                "drive:path" "!:path" ""

                install-options

                The +following table provides a list of the install-options.

                + + + +Name +Abbreviation +Description + + + + +

                FILE

                +

                FF

                +

                Specifies a standard installable file. For example:

                "text\file1.txt"-"!:\private\E800005A\file1.txt", FF                 +                 + +

                FILETEXT

                [,text-options]

                +

                FT

                [,text-options]

                +

                A text file that is displayed in a dialog box during installation. +The dialog type is determined by the text-options specified. +See, text-options for +more information.

                Text files are not installed on the target device, +so the target location is empty. An example FILETEXT line +is:

                "text\textfilec.txt"-"", FT, TC

                Any FILETEXT statements +present in a PKG file for a preinstalled application are ignored by the software +installer.

                For Unicode text files to be displayed correctly, it is +recommended that the Byte Order Mark (BOM) be specified at the +beginning of the text files.

                 +                 + +

                FILERUN

                [,run-options][,RUNWAITEND]

                +

                FR

                [,run-options][,RW]

                +

                Specifies a file that is installed on the Symbian device and run +during installation or uninstallation of packages based on the RI, RR and RB arguments. +For details, see run-options.

                For +example:

                "\epoc32\release\armv5\urel\zoom.exe"-"!:\sys\bin\zoom.exe", FILERUN, RUNINSTALL

                Notes:

                  +

                • The file can be an executable +or a document containing text.

                  • +

                • The untrusted applications +are run through the FILERUN (FR) +or FILEMIME (FM) statements based on configuration +of the installation policy.

                  • +
                 +                 + +

                FILEMIME,

                mime-type

                ,run-options

                [,RUNWAITEND]

                +

                FM,

                mime-type

                ,run-options +[,RW]

                +

                Instructs the installer to associate the file with the default application +associated with the given MIME type, for example, text or + x-vCard is required to be open for contact details.

                The +MIME type in quotes must be specified after the FM argument. FILEMIME is +intended for use with files that are launched during the installation or uninstallation +and not for standard installation files. For example:

                "my_picture.gif"-"", FM, "image/gif", RI

                The Software Installer ignores any FILEMIME statements +present in a PKG file for a preinstalled application.

                +                 + + +

                text-options

                text-options can +be used after FT is specified. It is used by the UI to determine +the type of dialog that is used to display the text. It can have one of the +following values.

                + + + +Name +Abbreviation +Description + + + + +

                TEXTCONTINUE

                +

                TC

                +

                It is recommended that the UI displays a dialog containing a Continue button.

                The +installation continues regardless of the return value of the dialog.

                +                 + +

                TEXTABORT

                +

                TA

                +

                It is recommended that the UI displays a dialog containing Yes /No buttons.

                The +software installer continues with the installation if the dialog returns true +(if the Symbian device user selects Yes). It aborts the installation +if the dialog returns false (if the Symbian device user selects No).

                +                 + +

                TEXTEXIT

                +

                TE

                +

                Same as TEXTABORT.

                +                 + +

                FORCEABORT

                +

                FA

                +

                It is recommended that the UI displays a dialog containing a ForceAbort button.

                On +selecting this dialog, it aborts the installation.

                +                 + +

                TEXTSKIP

                 +

                TS

                 +

                It is recommended that the UI displays a dialog containing Yes /No buttons.

                The +software installer continues the installation without skipping the file mentioned +in the next statement if the dialog returns true (if the Symbian device user +selects Yes). It skips the installation of the file mentioned +in the next statement if the dialog returns false (if the Symbian device user +selects No).

                 +                 + + +

                Note: UIs can implement installation dialogs differently, +so you must refer to the UI SDK for details about the actual behaviour.

                run-options

                run-options can +be used after FR or FM has been specified. +It can be any of the following:

                + + + +Name +Abbreviation +Description + + + + +

                RUNINSTALL

                +

                RI

                +

                Run on install

                +                 + +

                RUNREMOVE

                +

                RR

                +

                Run on uninstall and upgrade

                +                 + +

                RUNBOTH

                +

                RB

                +

                Run on install, uninstall and upgrade

                +                 + +

                RUNBEFORESHUTDOWN

                +

                RBS

                +

                Run on uninstall before the applications in the package are shut +down

                +                 + + +

                Optionally, RW (or RUNWAITEND) +can be specified in addition to the run-options. If this +option is specified, the installation server waits for the program to terminate +before continuing with the install. If this option is not specified, the installation +server runs the program and continues with the installation. The program is +shut down after the installation is complete.

                When uninstalling a package +with a RUNREMOVE or RUNBOTH executable specified, +the installation server always waits for the executable to terminate or timeout +before continuing with the uninstall.

                Verification options

                The +following option is available for checking the integrity of a file at restore +time:

                + + + +Name +Abbreviation +Description + + + + +

                VERIFY

                +

                VR

                +

                This flag is necessary if the integrity of a file installed in a +directory outside \sys or \restore needs +to be verified at restore time. For example, an application can check this +flag to verify that a security policy file restored to its private directory +is identical to the file delivered by the SIS file.

                The following +example illustrates the usage of this option:

                "data\ups_01041000_01041001.rsc"- +"$:\private\10283558\policies\ups_01041000_01041001.rsc", VERIFY                 +                 + + +

                Import and Private +Directories

                The software installer ensures that files are placed +in appropriate areas of the file system. The following rules are applied:

                  +

                • A package can only deliver +a data file into the private directory belonging to any executable in the +package. If a package delivers three executables: SID1, SID2, SID3 (where +SID stands for Secure ID), then data files can be delivered to /private/SID1/, /private/SID2/, +or /private/SID3/. In an upgrade, this is possible by +associating the upgrade package with the SIDs present in the original package +unless one of the original executables is to be removed during the upgrade.

                  • +

                • Any package can deliver +a file into the //private/SID/import of an entirely unrelated +package. However, replacement and eclipsing rules apply.

                  • +
                                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B409C23A-F89E-5D30-B172-1F39C3F6A57F_d0e18988_href.png Binary file Symbian3/SDK/Source/GUID-B409C23A-F89E-5D30-B172-1F39C3F6A57F_d0e18988_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B409C23A-F89E-5D30-B172-1F39C3F6A57F_d0e49332_href.png Binary file Symbian3/SDK/Source/GUID-B409C23A-F89E-5D30-B172-1F39C3F6A57F_d0e49332_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B409C23A-F89E-5D30-B172-1F39C3F6A57F_d0e54890_href.png Binary file Symbian3/SDK/Source/GUID-B409C23A-F89E-5D30-B172-1F39C3F6A57F_d0e54890_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B452DBD8-F9EB-4DAB-9D0C-3B11D7C360F4.dita --- a/Symbian3/SDK/Source/GUID-B452DBD8-F9EB-4DAB-9D0C-3B11D7C360F4.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-B452DBD8-F9EB-4DAB-9D0C-3B11D7C360F4.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,49 +1,49 @@ - - - - - -Text -setting -

                When editing text in a text setting component, a touch down and release -anywhere in the editor field launches the Touch Input window. The editing -indicator is placed above the text setting field top right corner.

                - -Text setting pop-up - - -Default -touch events when editing text in a text setting pop-up - - - - - - -

                User action

                 -

                State change

                 -

                Feedback

                 -                 - - - -

                Touch down

                 -

                No change

                 -

                Tactile: Sensitive edit effect and audio feedback are provided with -touch down event.

                 -                 - -

                Touch release

                 -

                Touch Input window in number mode is launched.

                 -

                Tactile: Sensitive edit effect is provided with touch release event. -No audio feedback.

                 -                 - - + + + + + +Text +setting +

                When editing text in a text setting component, a touch down and release +anywhere in the editor field launches the Touch Input window. The editing +indicator is placed above the text setting field top right corner.

                + +Text setting pop-up + + +
                Default +touch events when editing text in a text setting pop-up + + + + + + +

                User action

                 +

                State change

                 +

                Feedback

                 +                 + + + +

                Touch down

                 +

                No change

                 +

                Tactile: Sensitive edit effect and audio feedback are provided with +touch down event.

                 +                 + +

                Touch release

                 +

                Touch Input window in number mode is launched.

                 +

                Tactile: Sensitive edit effect is provided with touch release event. +No audio feedback.

                 +                 + +
                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B459E37A-BECE-5087-9827-C93310890674_d0e281229_href.png Binary file Symbian3/SDK/Source/GUID-B459E37A-BECE-5087-9827-C93310890674_d0e281229_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B459E37A-BECE-5087-9827-C93310890674_d0e284915_href.png Binary file Symbian3/SDK/Source/GUID-B459E37A-BECE-5087-9827-C93310890674_d0e284915_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B46C54AD-268C-58A0-B244-134C4D8BDFE1_d0e19466_href.png Binary file Symbian3/SDK/Source/GUID-B46C54AD-268C-58A0-B244-134C4D8BDFE1_d0e19466_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B46C54AD-268C-58A0-B244-134C4D8BDFE1_d0e25044_href.png Binary file Symbian3/SDK/Source/GUID-B46C54AD-268C-58A0-B244-134C4D8BDFE1_d0e25044_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B4834A49-587E-41AD-B0D3-0622B173B2AD_d0e75413_href.png Binary file Symbian3/SDK/Source/GUID-B4834A49-587E-41AD-B0D3-0622B173B2AD_d0e75413_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B4834A49-587E-41AD-B0D3-0622B173B2AD_d0e80545_href.png Binary file Symbian3/SDK/Source/GUID-B4834A49-587E-41AD-B0D3-0622B173B2AD_d0e80545_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B48F7684-76E6-51C1-B85A-08A1F1EBD807_d0e80517_href.png Binary file Symbian3/SDK/Source/GUID-B48F7684-76E6-51C1-B85A-08A1F1EBD807_d0e80517_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B48F7684-76E6-51C1-B85A-08A1F1EBD807_d0e87229_href.png Binary file Symbian3/SDK/Source/GUID-B48F7684-76E6-51C1-B85A-08A1F1EBD807_d0e87229_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B4F15CA3-CAD4-5A87-9610-A656CA337B72.dita --- a/Symbian3/SDK/Source/GUID-B4F15CA3-CAD4-5A87-9610-A656CA337B72.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-B4F15CA3-CAD4-5A87-9610-A656CA337B72.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,19 +1,19 @@ - - - - - -Comms Buffers (MBuf) ans Comms ChainsThis topic describes Comms buffers (MBuf) and Comms chains.
                APIs

                The following diagram is a partial representation of the class hierarchy for RMBuf.

                - Comms buffer -

                For more information about these classes, see the following table and the reference documentation:

                Class Description

                RMBuf

                Representation of a shared buffer designed to carry packets within the Comms Data Plane.

                It includes Comms metadata (such as the offset, the size and the type of the data within the buffer) and links to the next buffer in the buffer chain.

                Part of the API is located in the parent class : RCommsBuf.

                RMBufChain

                Chain of RMBuf objects.

                Part of the API is located in the parent class : RCommsBufChain.

                Buffer layout

                The following diagram shows the contents of a Comms buffer and the location of the metadata. The metadata is at the end so that the device drivers can ignore the metadata and write their payload at the beginning of the buffer.

                - Comms buffer contents -

                The metadata contains information about the payload: its length and offset, the type of data it contains, and references to the pond and the pool where the buffer's memory is located. Whenever you perform an operation on an MBuf, the chain or the pond update the metadata.

                The offset at the beginning of the buffer is an important optimisation when sending data downwards through the Comms Data Plane. Leaving enough space for the protocol headers enables Comms Framework components to prepend their data to the payload without requesting a new MBuf and its addition to the front of the buffer chain. Therefore, you should always define a pool according to the biggest packet that the bottom of the stack may receive : for example, 1518 bytes for Ethernet packets.

                The following diagram is an example illustrating how the Comms Data Plane removes the headers from the payload (on the way up the stack) or prepend header to the payload (on the way down):

                - Header manipulation example -

                For simplified code corresponding to this diagram, see Data Access Example.

                Overview Shared Buffers Advanced Pond + + + + + +Comms Buffers (MBuf) ans Comms ChainsThis topic describes Comms buffers (MBuf) and Comms chains.
                APIs

                The following diagram is a partial representation of the class hierarchy for RMBuf.

                + Comms buffer +

                For more information about these classes, see the following table and the reference documentation:

                Class Description

                RMBuf

                Representation of a shared buffer designed to carry packets within the Comms Data Plane.

                It includes Comms metadata (such as the offset, the size and the type of the data within the buffer) and links to the next buffer in the buffer chain.

                Part of the API is located in the parent class : RCommsBuf.

                RMBufChain

                Chain of RMBuf objects.

                Part of the API is located in the parent class : RCommsBufChain.

                Buffer layout

                The following diagram shows the contents of a Comms buffer and the location of the metadata. The metadata is at the end so that the device drivers can ignore the metadata and write their payload at the beginning of the buffer.

                + Comms buffer contents +

                The metadata contains information about the payload: its length and offset, the type of data it contains, and references to the pond and the pool where the buffer's memory is located. Whenever you perform an operation on an MBuf, the chain or the pond update the metadata.

                The offset at the beginning of the buffer is an important optimisation when sending data downwards through the Comms Data Plane. Leaving enough space for the protocol headers enables Comms Framework components to prepend their data to the payload without requesting a new MBuf and its addition to the front of the buffer chain. Therefore, you should always define a pool according to the biggest packet that the bottom of the stack may receive : for example, 1518 bytes for Ethernet packets.

                The following diagram is an example illustrating how the Comms Data Plane removes the headers from the payload (on the way up the stack) or prepend header to the payload (on the way down):

                + Header manipulation example +

                For simplified code corresponding to this diagram, see Data Access Example.

                Overview Shared Buffers Advanced Pond Guide                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B51A9A1F-8E80-4DF6-904A-7BD1A8976BBB.dita --- a/Symbian3/SDK/Source/GUID-B51A9A1F-8E80-4DF6-904A-7BD1A8976BBB.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-B51A9A1F-8E80-4DF6-904A-7BD1A8976BBB.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,88 +1,78 @@ - - - - - -<ph>Symbian -Developer Library for Application Developers</ph>Welcome to the Developer Library for Symbian^3. This library is -intended for C++ developers creating applications for Symbian^3. - - - - - -Begin here -Application and Middleware Layers - - - - -

                These sections provide some starting points for using the library -and the platform.

                About -this Library

                About -Symbian^3

                Essential -idioms

                Example -programs

                Symbian C++ Quick Start

                Going -Beyond Hello: A Tutorial for Symbian C++ Applications

                 -

                The Application Layer provides application user interfaces and application -engines.

                Messaging -Applications

                PIM

                The -Middleware Layer provides application services, including UI frameworks and -high level communications.

                Application -Installation

                Browsing and downloading

                Classic -UI

                Generic -Application Support

                Messaging -Middleware

                Multimedia -Protocols

                 -                 - - - - - -Key APIs -OS Layer - - - - -

                These are quick links to some APIs that most Symbian C++ programs -use.

                Arrays and -lists

                Basic -types

                Cleanup -support

                Client/server

                Descriptors

                 -

                The OS Layer provides the Symbian Kernel, and frameworks to support -fundamental services.

                Cellular -Baseband Services

                Communications -Framework

                Device -Services

                Generic -OS Services

                Graphics

                Kernel and Hardware Services

                Locating Services

                Multimedia

                OS Security

                Networking Services

                Persistent Data Services

                Shortlink -Services

                Text -and Localization

                - -

                 - - - - -Expert Programming -All Documents - - - - -

                These documents help you write better and safer programs.

                Security

                 -

                These links take you to full lists of packages and tools described -in the library.

                Symbian -Guide

                Tools -and Utilities

                 -                 - - + + + + + +<ph>Symbian Developer Library for +Application Developers</ph>Welcome to the Developer Library +for Symbian^3.This library +is intended for C++ developers creating applications for Symbian^3. +

                +

                + + + +Begin here +Application and Middleware Layers + + + + +

                These sections provide some starting points for using the +library and the platform.

                About this Library

                About +Symbian^3

                Essential idioms

                Example +programs

                Symbian C++ Quick Start

                Going Beyond Hello: A Tutorial for +Symbian C++ Applications

                 +

                The Application Layer provides application user interfaces +and application engines.

                Messaging Applications

                PIM

                The Middleware Layer provides application services, +including UI frameworks and high level communications.

                Application Installation

                Browsing and downloading

                Classic UI

                Generic Application +Support

                Messaging Middleware

                Multimedia +Protocols

                 +                 + + + + + +Key APIs +OS Layer + + + + +

                These are quick links to some APIs that most Symbian C++ +programs use.

                Arrays and lists

                Basic +types

                Cleanup support

                Client/server

                Descriptors

                 +

                The OS Layer provides the Symbian Kernel, and frameworks +to support fundamental services.

                Cellular Baseband Services

                Communications Framework

                Device +Services

                Generic OS Services

                Graphics

                Kernel and Hardware Services

                Locating Services

                Multimedia

                OS +Security

                Networking Services

                Persistent +Data Services

                Shortlink +Services

                Text and Localization

                + +

                 + + + + +Expert Programming +All Documents + + + + +

                These documents help you write better and safer programs.

                Security

                 +

                These links take you to full lists of packages and tools +described in the library.

                Symbian Guide

                API +Specifications

                Reference

                Tools and +Utilities

                 +                 + +
                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B541BD01-29BE-4CB7-9420-ABEE0BDC9BA4.dita --- a/Symbian3/SDK/Source/GUID-B541BD01-29BE-4CB7-9420-ABEE0BDC9BA4.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-B541BD01-29BE-4CB7-9420-ABEE0BDC9BA4.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,96 +1,96 @@ - - - - - -Writing -a Standard Registration Resource FileFor Symbian OS V9.1 and onwards, the name of the standard registration -resource file must be the same as that of the executable with .rss extension. -All the registration resource structure types are defined in RegistryInfo.rh. -This file has to be included in the registration resource file. - -Define a single REGISTRY_INFO resource. - - -Set the dll_uid -to the DLL's UID. - -Set interfaces member -to be an array of INTERFACE_INFO resources. -

                Each INTERFACE_INFO resource defines registration -information for implementations of the interface identified by interface_uid -member. The information takes the form of an array of IMPLEMENTATION_INFO resources. -

                -                 -Each IMPLEMENTATION_INFO resource -declares the properties of a single implementation. It has five members: - -implementation_uid: -An unique identifier for the implementation. -

                For this value, use a new UID allocated by Symbian Signed. The allocated -value can be from the protected or non-protected range of UIDs.

                -                 -version_no: -The version of the interface implementation. - -display_name: -The external name of the implementation. - -default_data: -The data identifier field used by the resolver to determine if the implementation -matches a client request. - -opaque_data: -A binary data field that can contain additional data. This additional data -can be used by the custom resolvers. - -                 -                 -                 -

                The following example depicts a resource registration file for -an implementation collection with two implementations.

                // 10009DB1.RSS -// -#include "RegistryInfo.rh" - -RESOURCE REGISTRY_INFO theInfo -{ -dll_uid = 0x10009DB1; -interfaces = - { - INTERFACE_INFO - { - interface_uid = 0x10009DC0; - implementations = - { - IMPLEMENTATION_INFO - { - implementation_uid = 0x10009DC3; - version_no = 1; - display_name = "Implementation name 1"; - default_data = "text/wml"; - opaque_data = "some extra data"; - }, - IMPLEMENTATION_INFO - { - implementation_uid = 0x10009DC4; - version_no = 1; - display_name = "Implementation name 1"; - default_data = "text/xml||Type of data handled"; - opaque_data = ""; - } - }; - } - }; -}                 -                 -Writing -the Version 2 Registration Resource File -Writing the -Version 3 Registration Resource File + + + + + +Writing +a Standard Registration Resource FileFor Symbian OS V9.1 and onwards, the name of the standard registration +resource file must be the same as that of the executable with .rss extension. +All the registration resource structure types are defined in RegistryInfo.rh. +This file has to be included in the registration resource file. + +Define a single REGISTRY_INFO resource. + + +Set the dll_uid +to the DLL's UID. + +Set interfaces member +to be an array of INTERFACE_INFO resources. +

                Each INTERFACE_INFO resource defines registration +information for implementations of the interface identified by interface_uid +member. The information takes the form of an array of IMPLEMENTATION_INFO resources. +

                +                 +Each IMPLEMENTATION_INFO resource +declares the properties of a single implementation. It has five members: + +implementation_uid: +An unique identifier for the implementation. +

                For this value, use a new UID allocated by Symbian Signed. The allocated +value can be from the protected or non-protected range of UIDs.

                +                 +version_no: +The version of the interface implementation. + +display_name: +The external name of the implementation. + +default_data: +The data identifier field used by the resolver to determine if the implementation +matches a client request. + +opaque_data: +A binary data field that can contain additional data. This additional data +can be used by the custom resolvers. + +                 +                 +                 +

                The following example depicts a resource registration file for +an implementation collection with two implementations.

                // 10009DB1.RSS +// +#include "RegistryInfo.rh" + +RESOURCE REGISTRY_INFO theInfo +{ +dll_uid = 0x10009DB1; +interfaces = + { + INTERFACE_INFO + { + interface_uid = 0x10009DC0; + implementations = + { + IMPLEMENTATION_INFO + { + implementation_uid = 0x10009DC3; + version_no = 1; + display_name = "Implementation name 1"; + default_data = "text/wml"; + opaque_data = "some extra data"; + }, + IMPLEMENTATION_INFO + { + implementation_uid = 0x10009DC4; + version_no = 1; + display_name = "Implementation name 1"; + default_data = "text/xml||Type of data handled"; + opaque_data = ""; + } + }; + } + }; +}                 +                 +Writing +the Version 2 Registration Resource File +Writing the +Version 3 Registration Resource File                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B563AC07-A54B-50E2-A3B2-821E8BC2C863.dita --- a/Symbian3/SDK/Source/GUID-B563AC07-A54B-50E2-A3B2-821E8BC2C863.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-B563AC07-A54B-50E2-A3B2-821E8BC2C863.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,33 +1,33 @@ - - - - - -Using -CDirScanThis topic describes about setting up the scan and -parsing path. -
                Setting up the scan using SetScanDataL() - -

                Taking the above directory structure, if SetScanData() is -called as follows:

                _LIT(KDirText,"C:\\TopDir\\"); -... -SetScanDataL(KDirText,KEntryAttDir,ESortByName|EAscending,CDirScan::EScanDownTree); -...

                then the directories are scanned, by repeatedly calling CDirScan::NextL() in -the following order: TopDir, Dir1, Dir2, Dir3, Dir4, Dir5, Dir6, Dir7. -The sort key of EAscending means that multiple directories -within the same parent directory are scanned in ascending alphabetic or numeric -order.

                If the scan direction is upwards, i.e.CDirScan::EScanUpTree, -the directories are scanned in the order: Dir2, Dir4, Dir3, Dir1, Dir6, Dir7, Dir5, TopDir.

                -
                Parsing paths using FullPath()

                If the full path -of the entry currently being scanned is:

                C:\Topdir\Middledir\Bottomdir\

                and -the top level directory in the scan as passed to SetScanDataL() is:

                C:\Topdir\

                then:

                  -

                • AbbreviatedPath() returns \Middledir\

                  • -

                • FullPath() returns C:\Topdir\Middledir\.

                  • -
                + + + + + +Using +CDirScanThis topic describes about setting up the scan and +parsing path. +
                Setting up the scan using SetScanDataL() + +

                Taking the above directory structure, if SetScanData() is +called as follows:

                _LIT(KDirText,"C:\\TopDir\\"); +... +SetScanDataL(KDirText,KEntryAttDir,ESortByName|EAscending,CDirScan::EScanDownTree); +...

                then the directories are scanned, by repeatedly calling CDirScan::NextL() in +the following order: TopDir, Dir1, Dir2, Dir3, Dir4, Dir5, Dir6, Dir7. +The sort key of EAscending means that multiple directories +within the same parent directory are scanned in ascending alphabetic or numeric +order.

                If the scan direction is upwards, i.e.CDirScan::EScanUpTree, +the directories are scanned in the order: Dir2, Dir4, Dir3, Dir1, Dir6, Dir7, Dir5, TopDir.

                +
                Parsing paths using FullPath()

                If the full path +of the entry currently being scanned is:

                C:\Topdir\Middledir\Bottomdir\

                and +the top level directory in the scan as passed to SetScanDataL() is:

                C:\Topdir\

                then:

                  +

                • AbbreviatedPath() returns \Middledir\

                  • +

                • FullPath() returns C:\Topdir\Middledir\.

                  • +
                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B574CC84-342C-4613-A628-B32B7876D595_d0e3445_href.png Binary file Symbian3/SDK/Source/GUID-B574CC84-342C-4613-A628-B32B7876D595_d0e3445_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B574CC84-342C-4613-A628-B32B7876D595_d0e4720_href.png Binary file Symbian3/SDK/Source/GUID-B574CC84-342C-4613-A628-B32B7876D595_d0e4720_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B57D7C53-DFDB-4590-8227-EA251D1ABBC7.dita --- a/Symbian3/SDK/Source/GUID-B57D7C53-DFDB-4590-8227-EA251D1ABBC7.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,44 +0,0 @@ - - - - - -Using -autofocus -

                Autofocus support for camera applications is controlled through the CCameraAdvancedSettings class. For more information on -using autofocus, see:

                -
                  -

                • Advanced Settings -for Focus, Drive Modes, and Bracket Modes

                  • -

                • Using the camera autofocus feature in S60 devices on -Forum Nokia.

                  • -
                - -Implementation of autofocus - - -

                Pressing the camera shutter key on the device halfway down generates additional -key events. The key events can be used to activate autofocus if the camera -hardware supports the functionality. Shutter release (image capture) can be -triggered by pressing the key all the way down. The key presses generate separate -key events. To capture other than autofocus key events from the shutter key, -you need the SwEvent capability.

                -

                The settings you can use in your application depend on the camera hardware -on the device. The Camera API allows you to query almost all features of the -device camera. For example, to get a list of supported advanced settings, -use the CCameraAdvancedSettings::GetSupportedSettingsL() method.

                -

                For more information on how to easily use the device camera with zoom and -autofocus by using a CameraWrapper made by Forum Nokia, see Camera Example on Forum Nokia. The Camera Wrapper -provides a unified interface for various Symbian camera APIs. The example -application supports the use of both the keypad and touch UI. The application -can be self-signed, but it also provides an option to use the dedicated camera -key (Symbian signing required).

                -
                See also

                Advanced Camera Settings -Tutorial

                -                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B58D3727-6E05-51C8-8EC2-52768A136BD5.dita --- a/Symbian3/SDK/Source/GUID-B58D3727-6E05-51C8-8EC2-52768A136BD5.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-B58D3727-6E05-51C8-8EC2-52768A136BD5.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,92 +1,92 @@ - - - - - -Window -Server Client-Side Events OverviewA client application connects to the Window Server by creating -a Window Server session and calling RWsSession::Connect(). -Events generated by the Window Server are then delivered to the client via -the session, and the client must handle these events appropriately. -

                Variant: ScreenPlay and non-ScreenPlay. Target -audience: Application developers.

                -
                Window server event types

                The Window Server generates -events of three different classes, as shown in the following diagram.

                - Window server event types - - - - - -Class -Description - - - - -

                TWsEvent

                -

                General events, -which represent user input events, such as pointer and key events. You handle -these by using an active object of standard priority.

                -                 - -

                TWsRedrawEvent

                -

                Redraw events. -You handle these by using an active object of lower priority.

                -                 - -

                TWsPriorityKeyEvent

                -

                Priority -key events. You handle these by using an active object of higher priority.

                -                 - - -

                All Window Server applications handle standard events, and nearly -all handle redraw events. Only a few, however, handle priority key events. -It is only in very rare cases that an application does not handle redraw events, -because this requires that all its windows are backed-up windows.

                Events -are always associated with a window. For some event types, such as key events, -this is a window group. For other event types, such as pointer events, it -is a drawable window. The event delivered to the client contains a handle -that can be used to identify the window: this is the handle that was passed -as a parameter when the window was created. For window groups, however, this -is usually unnecessary, because most applications have only one window group.

                Symbian -recommends that you handle each event class with a separate active object, -in order that the classes can be handled at different priorities.

                -
                Handling events

                The Window Server maintains a server-side -buffer of all events queued to an application—each application has its own -queue within the buffer (this is only for general events—redraw and priority -key events are handled by a different mechanism). Each application must handle -events appropriately. The RWsSession::GetEvent() function -(or RWsSession::GetRedraw() or RWsSession::GetPriorityKey()) must be called -as the first stage of handling a completed request, and the event must then -be analyzed and handled.

                Each event must be handled relatively quickly -(at most a couple of seconds) so that the application remains responsive to -user input. If an event requires more extended processing (such as a key which -causes a large spreadsheet recalculation), then this processing should be -split into smaller chunks and handled by a client-side active object running -at lower priority than the GetEvent() handler.

                An -application which does not observe these protocols will stop running—although -it will not stop the whole device. The Window Server supports hotkeys which -it handles directly, so that a badly behaved application may be killed by -the server.

                -                 -Pointer Handling - -Declaring -a Window Server Event-Handling Class -Processing -Window-Group Events -Processing -Window Events -Processing -System Events -Window Server -Client-Side Events + + + + + +Window +Server Client-Side Events OverviewA client application connects to the Window Server by creating +a Window Server session and calling RWsSession::Connect(). +Events generated by the Window Server are then delivered to the client via +the session, and the client must handle these events appropriately. +

                Variant: ScreenPlay and non-ScreenPlay. Target +audience: Application developers.

                +
                Window server event types

                The Window Server generates +events of three different classes, as shown in the following diagram.

                + Window server event types + + + + + +Class +Description + + + + +

                TWsEvent

                +

                General events, +which represent user input events, such as pointer and key events. You handle +these by using an active object of standard priority.

                +                 + +

                TWsRedrawEvent

                +

                Redraw events. +You handle these by using an active object of lower priority.

                +                 + +

                TWsPriorityKeyEvent

                +

                Priority +key events. You handle these by using an active object of higher priority.

                +                 + + +

                All Window Server applications handle standard events, and nearly +all handle redraw events. Only a few, however, handle priority key events. +It is only in very rare cases that an application does not handle redraw events, +because this requires that all its windows are backed-up windows.

                Events +are always associated with a window. For some event types, such as key events, +this is a window group. For other event types, such as pointer events, it +is a drawable window. The event delivered to the client contains a handle +that can be used to identify the window: this is the handle that was passed +as a parameter when the window was created. For window groups, however, this +is usually unnecessary, because most applications have only one window group.

                Symbian +recommends that you handle each event class with a separate active object, +in order that the classes can be handled at different priorities.

                +
                Handling events

                The Window Server maintains a server-side +buffer of all events queued to an application—each application has its own +queue within the buffer (this is only for general events—redraw and priority +key events are handled by a different mechanism). Each application must handle +events appropriately. The RWsSession::GetEvent() function +(or RWsSession::GetRedraw() or RWsSession::GetPriorityKey()) must be called +as the first stage of handling a completed request, and the event must then +be analyzed and handled.

                Each event must be handled relatively quickly +(at most a couple of seconds) so that the application remains responsive to +user input. If an event requires more extended processing (such as a key which +causes a large spreadsheet recalculation), then this processing should be +split into smaller chunks and handled by a client-side active object running +at lower priority than the GetEvent() handler.

                An +application which does not observe these protocols will stop running—although +it will not stop the whole device. The Window Server supports hotkeys which +it handles directly, so that a badly behaved application may be killed by +the server.

                +                 +Pointer Handling + +Declaring +a Window Server Event-Handling Class +Processing +Window-Group Events +Processing +Window Events +Processing +System Events +Window Server +Client-Side Events                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B5DE1C86-2B16-4B22-887F-7079E54A8ED6.dita --- a/Symbian3/SDK/Source/GUID-B5DE1C86-2B16-4B22-887F-7079E54A8ED6.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-B5DE1C86-2B16-4B22-887F-7079E54A8ED6.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,65 +1,65 @@ - - - - - -Traditional -Symbian UI application architecture -

                The following image illustrates the components of the traditional architecture -approach.

                -Traditional Symbian UI application architecture classes -

                Symbian platform applications that follow the traditional Symbian UI -application architecture require:

                -
                  -

                • a UI -controller derived from CAknAppUi.

                  • -

                • a view or -views derived from CCoeControl.

                  • -
                -

                The traditional Symbian UI application architecture provides the most -flexible approach to application UI construction. Traditional architecture -is easier to port across different platforms than view -architecture. Traditional architecture is also the best choice for -single-view applications, if launching the view from external applications -is not required.

                -

                Typical responsibilities in this architecture are:

                -
                  -

                • CAknAppUi-derived class acts as a UI controller:

                  -
                    -

                  • It creates one -or more CCoeControl-derived views.

                    • -

                  • It handles events, -including enabling views to handle key -events.

                    • -

                  • To switch -between views, it creates and destroys or shows and hides views.

                    -
                    • -

                  • It handles menu commands.

                    -
                    • -

                  • It receives events such as layout and foreground notifications -from the run-time environment.

                    • -
                  -
                  • -
                -
                  -

                • CCoeControl-derived view:

                  -
                    -

                  • Shows application data and state on the screen.

                    • -

                  • Receives user input.

                    • -

                  • Notifies the CAknAppUi-derived class of -relevant events.

                    • -

                  • Often observes model changes (directly or via the UI controller) -and updates the screen accordingly.

                    • -
                  -
                  • -
                -

                For more information on the CAknApplication and CAknDocument-derived -classes, see Framework -requirements for GUI applications.

                + + + + + +Traditional +Symbian UI application architecture +

                The following image illustrates the components of the traditional architecture +approach.

                +Traditional Symbian UI application architecture classes +

                Symbian platform applications that follow the traditional Symbian UI +application architecture require:

                +
                  +

                • a UI +controller derived from CAknAppUi.

                  • +

                • a view or +views derived from CCoeControl.

                  • +
                +

                The traditional Symbian UI application architecture provides the most +flexible approach to application UI construction. Traditional architecture +is easier to port across different platforms than view +architecture. Traditional architecture is also the best choice for +single-view applications, if launching the view from external applications +is not required.

                +

                Typical responsibilities in this architecture are:

                +
                  +

                • CAknAppUi-derived class acts as a UI controller:

                  +
                    +

                  • It creates one +or more CCoeControl-derived views.

                    • +

                  • It handles events, +including enabling views to handle key +events.

                    • +

                  • To switch +between views, it creates and destroys or shows and hides views.

                    +
                    • +

                  • It handles menu commands.

                    +
                    • +

                  • It receives events such as layout and foreground notifications +from the run-time environment.

                    • +
                  +
                  • +
                +
                  +

                • CCoeControl-derived view:

                  +
                    +

                  • Shows application data and state on the screen.

                    • +

                  • Receives user input.

                    • +

                  • Notifies the CAknAppUi-derived class of +relevant events.

                    • +

                  • Often observes model changes (directly or via the UI controller) +and updates the screen accordingly.

                    • +
                  +
                  • +
                +

                For more information on the CAknApplication and CAknDocument-derived +classes, see Framework +requirements for GUI applications.

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B683496C-652E-5F48-924E-52D2FF3A78A7.dita --- a/Symbian3/SDK/Source/GUID-B683496C-652E-5F48-924E-52D2FF3A78A7.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-B683496C-652E-5F48-924E-52D2FF3A78A7.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,64 +1,64 @@ - - - - - -Direct -File StoreThe main characteristic of a direct file store is that streams -can be created and objects externalized to them but, once the streams have -been committed and closed, they cannot subsequently be changed. -

                Once the streams have been committed and closed, they cannot be replaced, -deleted, extended or changed in any way. A direct file store is useful for -the type of application which treats the in-memory copy of its data as its -prime copy, such as a word processor which implements the classic load/save -paradigm. In this paradigm:

                -
                  -

                • application data is -first created, in an internal, non-persistent, form — i.e., in RAM

                  • -

                • when the file is first -saved, the data is externalised to the file store. When saving its data, an -application writes the whole object network forming the data to a new direct -file store, replacing any existing file of the same name. The last stream -written is always the root stream.

                  • -

                • the application can -exit

                  • -

                • when the application -is started again, it can open the file store and read in the persistent data. -It need not load the whole object network into memory; the loading of objects -can be deferred by using Swizzles.

                  • -

                • the data is edited in -its internal, non-persistent form

                  • -

                • when data is saved again, -the old file is erased (or renamed for safety!) and completely rewritten

                  • -
                -

                With a direct file store, a stream may not be appended once it has been -written and closed. Writing to different streams may not be interleaved. The -root stream must be the last stream to be written. The direct file store is -very efficient as the allocation of new streams, and finding existing streams, -are trivially mapped onto the most efficient operations of the underlying -file system.

                -

                For this type of application, the most efficient file format is obtained -when all the data is written in sequence to the file. Any references within -the file are to data which was written earlier. When reading the file back, -it is read in several sections starting with a section that is at the end of -the file.

                -

                A typical relationship between a direct file store and its contained streams -is shown below. In this stream network streams I and J must -be written before stream A; stream K must be written before -stream C; streams A,B and C must be written before -the root stream.

                - -Streams linked in a store - - -

                Direct file stores are encapsulated by the CDirectFileStore class.

                -                 -Store Streams - + + + + + +Direct +File StoreThe main characteristic of a direct file store is that streams +can be created and objects externalized to them but, once the streams have +been committed and closed, they cannot subsequently be changed. +

                Once the streams have been committed and closed, they cannot be replaced, +deleted, extended or changed in any way. A direct file store is useful for +the type of application which treats the in-memory copy of its data as its +prime copy, such as a word processor which implements the classic load/save +paradigm. In this paradigm:

                +
                  +

                • application data is +first created, in an internal, non-persistent, form — i.e., in RAM

                  • +

                • when the file is first +saved, the data is externalised to the file store. When saving its data, an +application writes the whole object network forming the data to a new direct +file store, replacing any existing file of the same name. The last stream +written is always the root stream.

                  • +

                • the application can +exit

                  • +

                • when the application +is started again, it can open the file store and read in the persistent data. +It need not load the whole object network into memory; the loading of objects +can be deferred by using Swizzles.

                  • +

                • the data is edited in +its internal, non-persistent form

                  • +

                • when data is saved again, +the old file is erased (or renamed for safety!) and completely rewritten

                  • +
                +

                With a direct file store, a stream may not be appended once it has been +written and closed. Writing to different streams may not be interleaved. The +root stream must be the last stream to be written. The direct file store is +very efficient as the allocation of new streams, and finding existing streams, +are trivially mapped onto the most efficient operations of the underlying +file system.

                +

                For this type of application, the most efficient file format is obtained +when all the data is written in sequence to the file. Any references within +the file are to data which was written earlier. When reading the file back, +it is read in several sections starting with a section that is at the end of +the file.

                +

                A typical relationship between a direct file store and its contained streams +is shown below. In this stream network streams I and J must +be written before stream A; stream K must be written before +stream C; streams A,B and C must be written before +the root stream.

                + +Streams linked in a store + + +

                Direct file stores are encapsulated by the CDirectFileStore class.

                +                 +Store Streams +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B71AC5E3-8AA8-55AD-916F-9E873926011B.dita --- a/Symbian3/SDK/Source/GUID-B71AC5E3-8AA8-55AD-916F-9E873926011B.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-B71AC5E3-8AA8-55AD-916F-9E873926011B.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,89 +1,89 @@ - - - - - -Feature -Manager Collection Overview -

                The Feature Manager collection is a set of classes used to manipulate feature -flags.

                -
                Purpose

                A -feature is any piece of functionality which can be included in a phone at -ROM build time or excluded from it. An excluded feature is often written to -ROM at build time but excluded from the build by disabling it.

                -
                Architecture

                The -feature management system uses the standard client server architecture. The -relationship between the components is :

                - Architecture of the feature management system - - -

                Feature Manager Client is not supplied with all versions of Symbian -Platform. Feature Discovery, which is always supplied, provides a subset of -the functionality of Feature Manager Client and offers superior performance -under certain circumstances.

                The data which the Feature Manager manages -is stored as a collection of XML files in the feature database. These files -define a set of feature flags which can be accessed using the Feature Manager -API. The file featureuid.xml is the master record of -all features in the database. You do not manipulate the feature database directly. -

                The feature manager database is also accessed by the tool feat2hdr.pl which -is used at ROM build time to convert the data relating to each feature into -.iby and .h files used by the source code of the components which the features -refer to.

                -
                Description

                The -Feature Manager provides the functionality to

                  -

                • query features and report -on them,

                  • -

                • modify the status of -features, and

                  • -

                • set up notification -of changes to features.

                  • -
                -
                Components
                  -

                • Feature Manager Client -provides the complete functionality required for feature management.

                  • -

                • Feature Manager Server -maintains the table containing the list of features available on the device.

                  • -

                • Feature Discovery provides -the functionality to discover if a feature or feature set is available but -not to enable, disable or modify features.

                  • -

                Feature flags were formerly managed using the Feature Registry component, -which has now been deprecated. The old Feature Registry API calls continue -to be supported, but the old implementation has been scrapped in favour of -wrapper functions which call Feature Manager.

                -
                Using Feature Manager

                Feature flags, which are -held in the feature database, track changes to the status of features. It -is important to know that modifications through Feature Manager do not modify -the features themselves, though feature flags may be used by other components -which actually modify features.

                The Feature Manager provides the functionality -to:

                  -

                • report the availability -of feature flags,

                  • -

                • enable and disable feature -flags,

                  • -

                • modify the status of -feature flags and the data associated with them, and

                  • -

                • set up notification -of changes to the status of feature flags.

                  • -

                The Feature -Manager Tutorial provides detailed instructions on how to perform these -tasks.

                -                 -Feature Manager -Guide -Feature Manager -Installation Tutorial -Feature Manager -Modification Tutorials -Feature Manager -Querying Tutorials -Feature Manager -Notification Tutorials -Feature Manager -Reporting Tutorials + + + + + +Feature +Manager Collection Overview +

                The Feature Manager collection is a set of classes used to manipulate feature +flags.

                +
                Purpose

                A +feature is any piece of functionality which can be included in a phone at +ROM build time or excluded from it. An excluded feature is often written to +ROM at build time but excluded from the build by disabling it.

                +
                Architecture

                The +feature management system uses the standard client server architecture. The +relationship between the components is :

                + Architecture of the feature management system + + +

                Feature Manager Client is not supplied with all versions of Symbian +Platform. Feature Discovery, which is always supplied, provides a subset of +the functionality of Feature Manager Client and offers superior performance +under certain circumstances.

                The data which the Feature Manager manages +is stored as a collection of XML files in the feature database. These files +define a set of feature flags which can be accessed using the Feature Manager +API. The file featureuid.xml is the master record of +all features in the database. You do not manipulate the feature database directly. +

                The feature manager database is also accessed by the tool feat2hdr.pl which +is used at ROM build time to convert the data relating to each feature into +.iby and .h files used by the source code of the components which the features +refer to.

                +
                Description

                The +Feature Manager provides the functionality to

                  +

                • query features and report +on them,

                  • +

                • modify the status of +features, and

                  • +

                • set up notification +of changes to features.

                  • +
                +
                Components
                  +

                • Feature Manager Client +provides the complete functionality required for feature management.

                  • +

                • Feature Manager Server +maintains the table containing the list of features available on the device.

                  • +

                • Feature Discovery provides +the functionality to discover if a feature or feature set is available but +not to enable, disable or modify features.

                  • +

                Feature flags were formerly managed using the Feature Registry component, +which has now been deprecated. The old Feature Registry API calls continue +to be supported, but the old implementation has been scrapped in favour of +wrapper functions which call Feature Manager.

                +
                Using Feature Manager

                Feature flags, which are +held in the feature database, track changes to the status of features. It +is important to know that modifications through Feature Manager do not modify +the features themselves, though feature flags may be used by other components +which actually modify features.

                The Feature Manager provides the functionality +to:

                  +

                • report the availability +of feature flags,

                  • +

                • enable and disable feature +flags,

                  • +

                • modify the status of +feature flags and the data associated with them, and

                  • +

                • set up notification +of changes to the status of feature flags.

                  • +

                The Feature +Manager Tutorial provides detailed instructions on how to perform these +tasks.

                +                 +Feature Manager +Guide +Feature Manager +Installation Tutorial +Feature Manager +Modification Tutorials +Feature Manager +Querying Tutorials +Feature Manager +Notification Tutorials +Feature Manager +Reporting Tutorials                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B7542EA6-6188-5A3D-A287-0766F7B42DC0_d0e376536_href.png Binary file Symbian3/SDK/Source/GUID-B7542EA6-6188-5A3D-A287-0766F7B42DC0_d0e376536_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B7542EA6-6188-5A3D-A287-0766F7B42DC0_d0e382603_href.png Binary file Symbian3/SDK/Source/GUID-B7542EA6-6188-5A3D-A287-0766F7B42DC0_d0e382603_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B756AB28-A0EA-5AA3-86E3-CCFFCD642F08.dita --- a/Symbian3/SDK/Source/GUID-B756AB28-A0EA-5AA3-86E3-CCFFCD642F08.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-B756AB28-A0EA-5AA3-86E3-CCFFCD642F08.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,69 +1,69 @@ - - - - - -What -are linksThis topic describes the structure of links. A link is a container -and an element. A link is an item that can be stored in the Comms Database. -

                A link is a container. A link refers to another record. A link can be included -in a record.

                -

                A link is represented by the templated class CMDBRecordLink<T>. -The template parameter defines the type of record to which the link refers.

                - - - -

                A link is a public data member of a class. The class defines the structure -of record. This record is the 'parent' record of the linked record. For example, -Symbian platform defines the class CCDIAPRecord that -represents an Internet Access Point (IAP) record. A set of IAP records form -an IAP table. The public data members of this class are the fields and links -that make the record. The following code shows part of the class definition. -Some parts are omitted - this is not the complete class definition.

                -class CCDIAPRecord : public CCDRecordBase - { - public: - CMDBField<TDesC> iServiceType; - CMDBRecordLink<CCDServiceRecordBase> iService; - CMDBField<TDesC> iBearerType; - CMDBRecordLink<CCDBearerRecordBase> iBearer; - CMDBRecordLink<CCDNetworkRecord> iNetwork; - CMDBField<TUint32> iNetworkWeighting; - CMDBRecordLink<CCDLocationRecord> iLocation; - ... - } - -

                A CMDBRecordLink<T> object contains -an integer. The integer is the element -Id of the linked record in the database.

                -

                If you have a parent record in memory, you call the LoadL() function -on the link object CMDBRecordLink<T> to -get the linked record into memory. You can access the linked record through -the iLinkedRecord pointer. This pointer is a member of the CMDBRecordLinkBase class, -but you can access this data member through the CMDBRecordLink<T> object.

                -

                There are two cases:

                -
                  -

                • If you know what type -of record the link refers to you cast the pointer to the correct type. For -example:

                  CCDDialOutISPRecord* ptrIspRecord = static_cast<CCDDialOutISPRecord*>(ptrSingleIAPRecord->iService.iLinkedRecord);

                  where ptrSingleIAPRecord is of type CCDIAPRecord.

                  • -

                • If you do not know what -type of record the link refers to you cast the pointer to the base class for -records. You use GetFieldByNameL() or GetFieldByIdLaccess() to -access the data in the linked record. For example:

                  CCDServiceRecordBase* ptrServiceRecord = static_cast<CCDServiceRecordBase*>(ptrSingleIAPRecord->iService.iLinkedRecord); -CMDBField<TUint32>* field; - -// Find a field by its Id. In this code fragment, the field we are looking for -// is the bearer speed field. -field = (CMDBField<TUint32>*)ptrServiceRecord->GetFieldByIdL(KCDTIdBearerSpeed);
                  • -
                -                 -Following - a link to another table and finding a field by Id and by name: -Tutorial + + + + + +What +are linksThis topic describes the structure of links. A link is a container +and an element. A link is an item that can be stored in the Comms Database. +

                A link is a container. A link refers to another record. A link can be included +in a record.

                +

                A link is represented by the templated class CMDBRecordLink<T>. +The template parameter defines the type of record to which the link refers.

                + + + +

                A link is a public data member of a class. The class defines the structure +of record. This record is the 'parent' record of the linked record. For example, +Symbian platform defines the class CCDIAPRecord that +represents an Internet Access Point (IAP) record. A set of IAP records form +an IAP table. The public data members of this class are the fields and links +that make the record. The following code shows part of the class definition. +Some parts are omitted - this is not the complete class definition.

                +class CCDIAPRecord : public CCDRecordBase + { + public: + CMDBField<TDesC> iServiceType; + CMDBRecordLink<CCDServiceRecordBase> iService; + CMDBField<TDesC> iBearerType; + CMDBRecordLink<CCDBearerRecordBase> iBearer; + CMDBRecordLink<CCDNetworkRecord> iNetwork; + CMDBField<TUint32> iNetworkWeighting; + CMDBRecordLink<CCDLocationRecord> iLocation; + ... + } + +

                A CMDBRecordLink<T> object contains +an integer. The integer is the element +Id of the linked record in the database.

                +

                If you have a parent record in memory, you call the LoadL() function +on the link object CMDBRecordLink<T> to +get the linked record into memory. You can access the linked record through +the iLinkedRecord pointer. This pointer is a member of the CMDBRecordLinkBase class, +but you can access this data member through the CMDBRecordLink<T> object.

                +

                There are two cases:

                +
                  +

                • If you know what type +of record the link refers to you cast the pointer to the correct type. For +example:

                  CCDDialOutISPRecord* ptrIspRecord = static_cast<CCDDialOutISPRecord*>(ptrSingleIAPRecord->iService.iLinkedRecord);

                  where ptrSingleIAPRecord is of type CCDIAPRecord.

                  • +

                • If you do not know what +type of record the link refers to you cast the pointer to the base class for +records. You use GetFieldByNameL() or GetFieldByIdLaccess() to +access the data in the linked record. For example:

                  CCDServiceRecordBase* ptrServiceRecord = static_cast<CCDServiceRecordBase*>(ptrSingleIAPRecord->iService.iLinkedRecord); +CMDBField<TUint32>* field; + +// Find a field by its Id. In this code fragment, the field we are looking for +// is the bearer speed field. +field = (CMDBField<TUint32>*)ptrServiceRecord->GetFieldByIdL(KCDTIdBearerSpeed);
                  • +
                +                 +Following + a link to another table and finding a field by Id and by name: +Tutorial                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B783AF18-FF14-5864-A92C-8BE62E07C68D_d0e204842_href.png Binary file Symbian3/SDK/Source/GUID-B783AF18-FF14-5864-A92C-8BE62E07C68D_d0e204842_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B783AF18-FF14-5864-A92C-8BE62E07C68D_d0e209850_href.png Binary file Symbian3/SDK/Source/GUID-B783AF18-FF14-5864-A92C-8BE62E07C68D_d0e209850_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B7A40638-BA80-5175-B23D-2F3964C274A0.dita --- a/Symbian3/SDK/Source/GUID-B7A40638-BA80-5175-B23D-2F3964C274A0.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-B7A40638-BA80-5175-B23D-2F3964C274A0.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,126 +1,126 @@ - - - - - -Goals -of the Comms ArchitectureThis topic describes the goals of the Symbian platform Comms Architecture -and summarises how the architecture addresses these goals. -

                The Symbian platform Comms Architecture is also known by other terms such -as the Three-Plane Comms Architecture and Freeway. The Comms -Architecture provides several framework components for generic functionality -and a number of plug-in modules which plug into this framework to implement -the comms protocols.

                -

                The small number of components that make up the framework itself are referred -to as "Comms Framework" components while the plug-in modules themselves are -known as "Nodes" which are arranged in "Layers" within the framework. Many -of the Nodes are supplied as part of Symbian platform but their plug-in nature -allows some of these to be replaced with tailored modules by a device-manufacturer.

                -

                The Comms Architecture has several goals:

                -
                  -

                • Separation of Data and Control functions

                  • -

                • Flexibility

                    -

                  • no limitations in the -creation of individual stacks from the available protocols

                    • -

                  • streamline the addition -of new protocols

                    • -

                  • support for switching -between protocols depending on the current network availability

                    • -
                  • -

                • Improving performance so that high-priority data transfers are not interrupted -by lower-priority tasks.

                  • -
                -

                Other requirements on the Architecture include the need to remain efficient -in the use of ROM, RAM and processor resources, and to provide a high level -of reliability.

                -
                Separation -of Data and Control functions

                By separating the code for the data -flow and the control functions, it is possible to have each in a separate -thread or even each in a separate process. This allows appropriate resources -to be allocated and priority to be assigned to support Quality of Service, -prioritisation of time-critical data flows and optimised plug-ins for specific -protocols.

                Communication between the data and control threads, and -between the layers is performed by an asynchronous messaging system known -as the Transport.

                - Separation of Data Flows and Control in the Comms Architecture - - -

                In fact the Comms Architecture actually divides the area marked -Control above into two areas, Control and Management. This is -the reason that this Comms Architecture is also known as the Three-Plane -Architecture. In future diagrams there will be three Planes: Data -Flow, Control, and Management. The Control Plane is often shown divided in -half to indicate that the Control Plane handles both Connections and data -channels within a Connection. This is described in more detail in Planes.

                -
                Flexibility

                The -Comms Architecture uses the concept of multiple stacks of technologies, from -high level technologies such as FTP down to lower level technologies (link -layer technologies) running on GPRS or Wi-Fi. An individual Stack is -a set of technologies which make up a communication path. A Stack in this -context is a single list of technologies from the application to the physical -hardware. An example of such a Stack is: HTTP over TCP over IP over GPRS, -which might be used in web browsing via a subscriber's mobile network. The -layered architecture allows both flexibility in the configuration of these -Stacks, as well as dynamic reconfiguration of the Stacks in response to changes -in the environment of the device (for example moving from a Wi-Fi to a 3G -environment). The link-layer technologies are known as Bearers and -the ability to switch a Data Flow from one bearer to another is called Bearer -Mobility. But it is possible to have the ability to switch from one technology -to another at any level in the stack providing full mobility.

                - Example of several potential stacks of protocols reusing -the same protocols. -

                In this example IP and TCP are used in three different stacks. A -combination of these Stacks could be running concurrently.

                - -

                Each stack requires a configuration that details how these protocols -find and work with each other; the protocols themselves need to know how to -talk with the other protocols. To allow flexibility, each protocol must avoid -making assumptions about the protocols below or above it, and instead rely -on the framework and device configuration. The framework ensures that each -protocol is created and appropriately configured when required, and is attached -to the protocols above and below it.

                The advent of multiple wireless -technologies has allowed a device to switch between protocols depending on -what is available. This is known as Freeway, and an example would be for a -browser to switch from Wi-Fi to GPRS when a mobile device goes out of range -of a Wi-Fi hotspot but is in range of a GPRS signal. The Comms Architecture -provides for this by allowing such transitions to be defined on the device -as part of the definition of the possible combinations of protocols that could -make up the various Stacks.

                The figure below illustrates the scope -of the Comms Architecture in Symbian platform from the point of view of an -end-to-end connection.

                - The Comms Architecture shown in the scope of a complete -protocol stack and the end-to-end path between the applications -on each device. - -
                -
                Performance

                A -key requirement of the Comms Architecture is the performance of data transfer. -The data transfer performance can be measured in three different ways:

                  -

                • Throughput - -the amount of data transferred measured against time

                  • -

                • Latency - the -amount of time it takes a single element of data to move from one end of the -communication route to the other

                  • -

                • Jitter - the -unwanted variance in the potential delay for each item of data sent, which -in turn causes data to arrive in the wrong order or for unacceptably-long -pauses in the data stream .

                  • -

                The Comms Architecture addresses these needs by separating all control -and data tasks. The control tasks are those that are involved with the creation -and management of the data connections, but which are not directly involved -with the transfer of data itself. The data tasks are those involved directly -with the transfer of data. The control tasks are deemed as lower priority -than the data tasks, and thus the data tasks are always run in preference -to the control tasks. For example, if an application requests a new connection, -the creation of this connection will not interrupt any existing data transfer -operations.

                The Comms Architecture also improves the handling of Quality -of Service resource reservation by structuring the framework around the concept -of channels, with the framework then able to specify the Quality of Service -parameters per channel.

                + + + + + +Goals +of the Comms ArchitectureThis topic describes the goals of the Symbian platform Comms Architecture +and summarises how the architecture addresses these goals. +

                The Symbian platform Comms Architecture is also known by other terms such +as the Three-Plane Comms Architecture and Freeway. The Comms +Architecture provides several framework components for generic functionality +and a number of plug-in modules which plug into this framework to implement +the comms protocols.

                +

                The small number of components that make up the framework itself are referred +to as "Comms Framework" components while the plug-in modules themselves are +known as "Nodes" which are arranged in "Layers" within the framework. Many +of the Nodes are supplied as part of Symbian platform but their plug-in nature +allows some of these to be replaced with tailored modules by a device-manufacturer.

                +

                The Comms Architecture has several goals:

                +
                  +

                • Separation of Data and Control functions

                  • +

                • Flexibility

                    +

                  • no limitations in the +creation of individual stacks from the available protocols

                    • +

                  • streamline the addition +of new protocols

                    • +

                  • support for switching +between protocols depending on the current network availability

                    • +
                  • +

                • Improving performance so that high-priority data transfers are not interrupted +by lower-priority tasks.

                  • +
                +

                Other requirements on the Architecture include the need to remain efficient +in the use of ROM, RAM and processor resources, and to provide a high level +of reliability.

                +
                Separation +of Data and Control functions

                By separating the code for the data +flow and the control functions, it is possible to have each in a separate +thread or even each in a separate process. This allows appropriate resources +to be allocated and priority to be assigned to support Quality of Service, +prioritisation of time-critical data flows and optimised plug-ins for specific +protocols.

                Communication between the data and control threads, and +between the layers is performed by an asynchronous messaging system known +as the Transport.

                + Separation of Data Flows and Control in the Comms Architecture + + +

                In fact the Comms Architecture actually divides the area marked +Control above into two areas, Control and Management. This is +the reason that this Comms Architecture is also known as the Three-Plane +Architecture. In future diagrams there will be three Planes: Data +Flow, Control, and Management. The Control Plane is often shown divided in +half to indicate that the Control Plane handles both Connections and data +channels within a Connection. This is described in more detail in Planes.

                +
                Flexibility

                The +Comms Architecture uses the concept of multiple stacks of technologies, from +high level technologies such as FTP down to lower level technologies (link +layer technologies) running on GPRS or Wi-Fi. An individual Stack is +a set of technologies which make up a communication path. A Stack in this +context is a single list of technologies from the application to the physical +hardware. An example of such a Stack is: HTTP over TCP over IP over GPRS, +which might be used in web browsing via a subscriber's mobile network. The +layered architecture allows both flexibility in the configuration of these +Stacks, as well as dynamic reconfiguration of the Stacks in response to changes +in the environment of the device (for example moving from a Wi-Fi to a 3G +environment). The link-layer technologies are known as Bearers and +the ability to switch a Data Flow from one bearer to another is called Bearer +Mobility. But it is possible to have the ability to switch from one technology +to another at any level in the stack providing full mobility.

                + Example of several potential stacks of protocols reusing +the same protocols. +

                In this example IP and TCP are used in three different stacks. A +combination of these Stacks could be running concurrently.

                + +

                Each stack requires a configuration that details how these protocols +find and work with each other; the protocols themselves need to know how to +talk with the other protocols. To allow flexibility, each protocol must avoid +making assumptions about the protocols below or above it, and instead rely +on the framework and device configuration. The framework ensures that each +protocol is created and appropriately configured when required, and is attached +to the protocols above and below it.

                The advent of multiple wireless +technologies has allowed a device to switch between protocols depending on +what is available. This is known as Freeway, and an example would be for a +browser to switch from Wi-Fi to GPRS when a mobile device goes out of range +of a Wi-Fi hotspot but is in range of a GPRS signal. The Comms Architecture +provides for this by allowing such transitions to be defined on the device +as part of the definition of the possible combinations of protocols that could +make up the various Stacks.

                The figure below illustrates the scope +of the Comms Architecture in Symbian platform from the point of view of an +end-to-end connection.

                + The Comms Architecture shown in the scope of a complete +protocol stack and the end-to-end path between the applications +on each device. + +
                +
                Performance

                A +key requirement of the Comms Architecture is the performance of data transfer. +The data transfer performance can be measured in three different ways:

                  +

                • Throughput - +the amount of data transferred measured against time

                  • +

                • Latency - the +amount of time it takes a single element of data to move from one end of the +communication route to the other

                  • +

                • Jitter - the +unwanted variance in the potential delay for each item of data sent, which +in turn causes data to arrive in the wrong order or for unacceptably-long +pauses in the data stream .

                  • +

                The Comms Architecture addresses these needs by separating all control +and data tasks. The control tasks are those that are involved with the creation +and management of the data connections, but which are not directly involved +with the transfer of data itself. The data tasks are those involved directly +with the transfer of data. The control tasks are deemed as lower priority +than the data tasks, and thus the data tasks are always run in preference +to the control tasks. For example, if an application requests a new connection, +the creation of this connection will not interrupt any existing data transfer +operations.

                The Comms Architecture also improves the handling of Quality +of Service resource reservation by structuring the framework around the concept +of channels, with the framework then able to specify the Quality of Service +parameters per channel.

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B7D1D1ED-932C-4A17-AE80-EDF163FC789A_d0e53483_href.png Binary file Symbian3/SDK/Source/GUID-B7D1D1ED-932C-4A17-AE80-EDF163FC789A_d0e53483_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B7D1D1ED-932C-4A17-AE80-EDF163FC789A_d0e61166_href.png Binary file Symbian3/SDK/Source/GUID-B7D1D1ED-932C-4A17-AE80-EDF163FC789A_d0e61166_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B7E55764-C137-4877-9083-63ACEAF30BE5_d0e58076_href.png Binary file Symbian3/SDK/Source/GUID-B7E55764-C137-4877-9083-63ACEAF30BE5_d0e58076_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B7E55764-C137-4877-9083-63ACEAF30BE5_d0e61475_href.png Binary file Symbian3/SDK/Source/GUID-B7E55764-C137-4877-9083-63ACEAF30BE5_d0e61475_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B7E5C7C1-E02F-575C-981B-E14DA10C63D2.dita --- a/Symbian3/SDK/Source/GUID-B7E5C7C1-E02F-575C-981B-E14DA10C63D2.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-B7E5C7C1-E02F-575C-981B-E14DA10C63D2.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,14 +1,14 @@ - - - - - -ArchitectureThis topic describes the architecture of the Root Server and the C32exe process. Figure 1 - The architecture of Root Server and - the C32exe process

                Figure 1 shows that the Root Server is a thread in the C32 process. The Root Server provider a Client library which other applications can use to request services of the Root Server. This client library is the only interaction the Root Server has outside the C32 process.

                The Root Server contains the functionality to manage the MBufs and Bindings of the C32 process. The Root Server creates Comms Provider Modules within the C32 process only. These Comms Provider Modules may have client libraries outside the C32 process. For example, the Socket Server Comms Provider Module loads esocksvr.dll. The esocksvr DLL has a client library esock.lib which applications use to request services from the Socket Server.

                Figure 2 shows the C32 process and Root Server with some example Comms Provider Modules and the Comms Configurator using the Root Server client API.

                Figure 2 - Comms Process with example CPMs - loaded                 \ No newline at end of file + + + + + +ArchitectureThis topic describes the architecture of the Root Server and the C32exe process. Figure 1 - The architecture of Root Server and + the C32exe process

                Figure 1 shows that the Root Server is a thread in the C32 process. The Root Server provider a Client library which other applications can use to request services of the Root Server. This client library is the only interaction the Root Server has outside the C32 process.

                The Root Server contains the functionality to manage the MBufs and Bindings of the C32 process. The Root Server creates Comms Provider Modules within the C32 process only. These Comms Provider Modules may have client libraries outside the C32 process. For example, the Socket Server Comms Provider Module loads esocksvr.dll. The esocksvr DLL has a client library esock.lib which applications use to request services from the Socket Server.

                Figure 2 shows the C32 process and Root Server with some example Comms Provider Modules and the Comms Configurator using the Root Server client API.

                Figure 2 - Comms Process with example CPMs + loaded                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B7F3F71A-2E05-58A5-98B2-0C62C65286D1_d0e108735_href.png Binary file Symbian3/SDK/Source/GUID-B7F3F71A-2E05-58A5-98B2-0C62C65286D1_d0e108735_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B7F3F71A-2E05-58A5-98B2-0C62C65286D1_d0e115273_href.png Binary file Symbian3/SDK/Source/GUID-B7F3F71A-2E05-58A5-98B2-0C62C65286D1_d0e115273_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B80E3FB0-C26F-52A8-B4DE-0A219B974ABC_d0e201451_href.png Binary file Symbian3/SDK/Source/GUID-B80E3FB0-C26F-52A8-B4DE-0A219B974ABC_d0e201451_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B80E3FB0-C26F-52A8-B4DE-0A219B974ABC_d0e206459_href.png Binary file Symbian3/SDK/Source/GUID-B80E3FB0-C26F-52A8-B4DE-0A219B974ABC_d0e206459_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B84FA223-3DFD-58C5-8CEF-C5AA73AA6290-GENID-1-8-1-3-1-1-7-1-9-1.dita --- a/Symbian3/SDK/Source/GUID-B84FA223-3DFD-58C5-8CEF-C5AA73AA6290-GENID-1-8-1-3-1-1-7-1-9-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,552 +0,0 @@ - - - - - -How -to write controls -

                Cone itself does not provide any concrete controls. Uikon and the UI variant -libraries provide a large number of 'stock' controls for application writers. -Application writers often need to supplement the standard set of controls -with application specific controls of their own. These may be completely new -controls or, more often, compound controls which contain a number of standard -controls.

                -

                This section describes how to create controls and how to integrate them -in to the control framework. It is divided into the following sections:

                -

                Creating -a control

                -

                Window -owning or not?

                -

                Creating -a compound control

                -

                Size, -position and layout

                -

                Drawing -and refreshing

                -

                Drawing -backgrounds

                -

                Drawing -text

                -

                Drawing -graphics

                -

                Handling -events

                -

                Implementing -the Object Provider (MOP) interface

                -
                Creating a -control

                A control is a class which derives from CCoeControl. -It should have a public constructor and, if any leaving function calls or -memory allocations are required during construction, a ConstructL() function. -The majority of re-useable and configurable controls have a ConstructFromResourceL() function -which allows a specific instance of a control to be configured using an application's -resource file. Obviously any memory allocated must be freed in the destructor. -Before a control is drawn to the screen it must be activated. The ActivateL() -function may be overriden to perform last-minute configuration (but -must call the function in the base class).

                -Class CMyControl : public CCoeControl - { - public: - CMyControl() ; - void ConstructL(...) ; - // from CCoeControl - void ConsructFromResourceL( TResourceReader& aReader ) ; - private: - ~CMyControl() ; - - // additional functions to handle events - // additional functions to draw the control - // additional functions to determine the size, layout and position the control - }
                -
                Window owning -or not?

                The decision over whether to make a control window owning -or not is usually straightforward. Each view requires a window, so the top-level -control must be window-owning and a child of the AppUi. Below this a window -owning control is normally only necessary where a sense of layering is required: -for instance a pop-up window or a scrolling window. Dialogs and menus are -window owning controls but these are normally implemented in the Uikon and -UI variant libraries and do not require custom derivation from CCoeControl. -Unnecessary window-owning controls should be avoided as they require more -infrastructure, place greater demand on the Window Server and reduce performance.

                If -a control must be window owning its window must either be created in the ConstructL() function -or by the caller. The former is preferred. There are several overloads of -the CreateWindowL() and CreateBackedUpWindowL() functions. -Those which do not take a parent parameter create a top-level window which -is a child of the root window.

                If a control is not window owning its SetContainerWindowL() function -must be called when it is instantiated.

                If it can, the Framework will -automatically set up the parent pointer when the window, or associated window -relationship is established. If it cannot do this, because CreateWindowL() or SetContainerWindowL() did -not provide a CCoeControl, the parent pointer (and MopParent) -may be set expicitly using SetParent() and SetMopParent().

                -
                Creating a -compound control

                Most applications UIs are built from compound -controls. Many custom controls are built up from stock controls and are therefore -also compound controls. When a compound control is constructed it constructs -its components in its ConstructL() function. When it receives -commands itself, such as ActivateL() and DrawNow() it -passes them on to each of its components. In most cases the Framework does -much of the donkey work as long as the compound control has been constructed -correctly.

                There are now two methods of creating and managing lodger -controls. The first method described is the one that should be used.

                -void MyControl::ConstructL( ... ) - { - // initialise the component array. This must be called once (subsequent calls have no effect) - InitComponentArrayL() ; - - // construct each component control and add it to the component array. - CComponent* myComponent = new (ELeave) CComponent ; - Components().AppendLC( myComponent ) ; // or InsertLC or InsertAfterLC(). Places item on cleanup stack. - myComponent->ConstructL() ; - myComponent->SetThisAndThatL() ; - CleanupStack::Pop( myComponent ) ; - }

                The return value of the insert and append methods is -a CCoeControlArray::TCursor object which works as an iterator. -It will remain valid when other items are inserted or deleted, or even if -the whole array is re-ordered.

                The insert and append methods leave -the component on the Cleanup Stack using a dedicated Cleanup Item that protects -the parent's array as well as the component itself.

                The insert and -append methods allow each component to be given an ID. The ID must be unique -only within the parent so typically a compound control will have an enum listing -each of its children's IDs. CCoeControlArray , accessed -using CCoeControl::Components(), has a ControlById() method -to retrieve components using their IDs.

                Components in the array are, -by default, owned by the parent and will be deleted automatically when the -parent is deleted. The default may be overridden using CCoeControlArray::SetControlsOwnedExternally(). -The setting applies to all of the components.

                Controls may be removed -from the array using one of the Remove() methods. These do -not delete.

                -class CCoeControlArray - ... - public: - IMPORT_C TInt Remove(const CCoeControl* aControl); - IMPORT_C CCoeControl* Remove(TCursor aRemoveAt); - IMPORT_C CCoeControl* RemoveById(TInt aControlId); - ... -

                Using the component array as described is now the approved -method of constructing and managing compound controls. In older versions of -Symbian OS a specific method of handling components was not provided and developers -were obliged to design their own. Bypassing the component array is still possible. -It is necessary to allocate and store the components (typically as member -data) and to implement the CountComponentControls() and ComponentControl() functions -to return the number of components and a specified component to the framework. -The new method offers significant advantages when controls are added and removed -dynamically or are dependant on run-time data. The new method is also integrated -with new layout managers.

                -
                Size, position -and layout

                There are several factors which contribute to a control's -size and position. The control itself will require a certain size in order -to display itself (and its data) correctly. The control's container will be -responsible for positioning the control but is also likely to be responsible -for positioning other controls - each of which will have its own requirements. -Additionally there are the requirements of the UI's look and feel that must -be complied with.

                Each control is responsible for implementing its -own Size() function.

                Until Symbian OS version 9.1 -it was normal to write layout code for simple and compound controls in the SizeChanged() function. -This is called by the framework, as one might expect, when a control's size -(its 'extent') is changed. From 9.1, however, Symbian OS supports the use -of the layout manager interface (MCoeLayoutManager) and -the SizeChanged() function is now implemented in the base -class. (Note that if a control's position is changed, with no size change, -using CCoeControl::SetPosition() its PositionChanged() function -is called and that default implementation of PositionChanged() is -empty).

                -class MCoeLayoutManager - ... - protected: - IMPORT_C MCoeLayoutManager(); - - public: - virtual TBool CanAttach() const = 0; - virtual void AttachL(CCoeControl& aCompoundControl) = 0; - virtual void Detach(CCoeControl& aCompoundControl) = 0; - virtual TSize CalcMinimumSize(const CCoeControl& aCompoundControl) const = 0; - virtual void PerformLayout() = 0; - virtual TInt CalcTextBaselineOffset(const CCoeControl& aCompoundControl, const TSize& aSize) const = 0; - virtual void SetTextBaselineSpacing(TInt aBaselineSpacing) = 0; - virtual TInt TextBaselineSpacing() const = 0; - virtual void HandleAddedControlL(const CCoeControl& aCompoundControl, const CCoeControl& aAddedControl) = 0; - virtual void HandleRemovedControl(const CCoeControl& aCompoundControl, const CCoeControl& aRemovedControl) = 0; - virtual TInt HandleControlReplaced(const CCoeControl& aOldControl, const CCoeControl& aNewControl) = 0; - ... -

                A layout manager may be attached to a compound control.

                -class CCoeControl - ... - protected: - IMPORT_C MCoeLayoutManager* LayoutManager() const; - IMPORT_C virtual void SetLayoutManagerL(MCoeLayoutManager* aLayoutManager); - - public: - IMPORT_C virtual TBool RequestRelayout(const CCoeControl* aChildCtrl); - ...

                The default implementations of MinimumSize() and SizeChanged() now -use the layout manager.

                -EXPORT_C TSize CCoeControl::MinimumSize() - { - const MCoeLayoutManager* layoutManager = LayoutManager(); - if (layoutManager) - return layoutManager->CalcMinimumSize(*this); - else - return iSize; - } - -EXPORT_C void CCoeControl::SizeChanged() - { - MCoeLayoutManager* layout = LayoutManager(); - if (layout) - layout->PerformLayout(); -

                The layout manager is responsible for the size and position -of the component controls. In practice it's likely that the UI variant libraries -will provide concrete layout managers. Application developers should use these -as the basis for control-specific layout managers.

                -
                Drawing and -refreshing

                A fundamental requirement of most controls is that they -are able to render themselves onto the screen. For most controls the drawing -process involves outputting text, painting backgrounds (either plain or from -a bitmap), drawing shapes (graphics objects) and drawing component controls.

                Screen -drawing may be initiated by the application itself, following something within -the application changing, or by the Window Server, due to something else in -the system updating the screen while the application is visible. In both cases -the control's Draw() function will be called automatically -by the framework. For compound controls all of the components' Draw() functions -will also be called - unless the component lies completely outside the area -that requires redrawing.

                As a control writer you will probably have -to implement a Draw() function.

                Here is the signature -for Draw():

                private: - void Draw( const TRect& aRect ) const ;

                Note that it -is private, takes a const TRect& as a parameter, must -not leave and is const.

                It should only be called -by the framework. Application initiated redraws should be through calls to DrawNow(), DrawDeferred() or -custom functions for drawing smaller elements.

                The aRect parameter -is the part of the control that requires drawing (refreshing).

                The -function is const and non-leaving because it is intended -to support the decoupling of drawing actions from application state.

                -
                Drawing backgrounds

                A -control's background is typically determined by the current colour scheme -or skin. It may be a plain colour or a bitmap. It's also possible that a control -is to appear non-rectangular or transparent in which case some of the background -will be the control underneath. Prior to Symbian OS 9.1 controls were required -to clear and update their whole area and creating these effects was rather -complex. From 9.1 controls are drawn 'backmost first'.

                Background -drawing should be done by a dedicated background drawer - i.e. an object which -implements the MCoeControlBackground interface. A background -can be attached to a CCoeControl using SetBackground() and -is used for that control and all of its children. When a control is drawn -the framework looks for the nearest background up the run-time hierarchy and -calls MCoeControlBackground::Draw().

                UI variant libraries -typically provide backgrounds. They are not owned by the controls to which -they are attached.

                -
                Drawing text

                Text -must be drawn with the correct color, font, size and direction. As with backgrounds, -these are determined at runtime according to UI customizations. This is achieved -by means of a Text Drawer. Note the use of the XCoeTextDrawer class. -This is a smart pointer (note the use of the -> operator -to access CCoeTextDrawerBase functions) which ensures that -only one text drawer is allocated on the heap at a time.

                -XCoeTextDrawer textDrawer( TextDrawer() ); -textDrawer->SetAlignment(iAlignment); -textDrawer->SetMargins(iMargin); -textDrawer->SetLineGapInPixels(iGapBetweenLines); -textDrawer.SetClipRect(aRect); // have to use . [dot] operator for SetClipRect() as not CCoeTextDrawerBase function. - -textDrawer.DrawText(gc, *iTextToDraw, Rect(), *Font()); -

                Text drawers are typically provided by the UI variant library -or skin manager. Controls within the run-time hierarchy can set the text drawer -for their children by overriding GetTextDrawer().

                Note -that the text drawer expects text to be passed as a TBidiText rather -than a descriptor. Controls should store all display text in TBidiText objects. -Application writers should consider the implications of right-to-left layouts -for languages such as Hebrew and Arabic.

                A control's GetTextDrawer() function -might look something like this. It checks on the current state of the control -(IsDimmed()) and passes the call on to a skin manager.

                -EXPORT_C void CMyButtonControl::GetTextDrawer(CCoeTextDrawerBase*& aTextDrawer, const CCoeControl* aDrawingControl, TInt /*aKey*/) const - { - const TInt textDrawerIndex = (IsDimmed() ? EButtonTextDimmed : EButtonText); - - SkinManager::GetTextDrawer(aTextDrawer, KSkinUidButton, textDrawerIndex, aDrawingControl); - } -

                If the control is drawing text on its own graphics (and does -not care about the text drawer of its parents) it can just create an XCoeTextDrawer object -on the stack in its Draw() method and initiate it from the -skin that it is currently using to draw its graphics, using the CSkinPatch::TextDrawer() method, -like this:

                -const CSkinPatch& skin = SkinManager::SkinPatch(KSomeSkinUid, KSomeSkinIndex, this); - -skin.DrawBitmap(gc, Rect(), aRect); -XCoeTextDrawer textDrawer( skin.TextDrawer(KSomeSkinUid, ESomeSkinTextDimmed, this) ); - -const CFont& font = ScreenFont(TCoeFont::NormalFont); -textDrawer.DrawText(gc, iText, rect, font); -

                The example above also illustrates how to retrieve the correct -font. CFont objects must not be stored in control member -data as they must change when the control's zoom state changes. Instead, a TCoeFont that -represents a font's size (logical or absolute in pixels) and style (plain, -bold, italic, subscript, or superscript) should be used.

                -class TCoeFont - ... - public: - IMPORT_C TCoeFont(TLogicalSize aSize, TInt aStyle, TInt aFlags = ENoFlags); - IMPORT_C TCoeFont(TInt aHeightInPixels, TInt aStyle, TInt aFlags = ENoFlags); - IMPORT_C TCoeFont(const TCoeFont& aFont); - IMPORT_C TCoeFont(); - ...

                By creating a TCoeFont object -describing the properties of the desired font, a CFont object -reference (needed to actually draw the text) can be fetched from the CCoeFontProvider. -A font provider can be attached to any CCoeControl and -will keep information about the typeface used by that control and all controls -below. A default font provider is attached to the CCoeEnv.

                -class CCoeControl - ... - public: - IMPORT_C const CCoeFontProvider& FindFontProvider() const; - IMPORT_C void SetFontProviderL(const CCoeFontProvider& aFontProvider); - ... -

                To get hold of the CFont object -a Draw() method can be implemented like this:

                -void CMyControl::Draw(const TRect& aRect) - { - const CCoeFontProvider& fontProvider = FindFontProvider(); - const CFont& font = fontProvider.Font(TCoeFont::LegendFont(), AccumulatedZoom()); - - XCoeTextDrawer textDrawer( TextDrawer() ); - textDrawer->SetAlignment(EHCenterVCenter); - textDrawer.DrawText(gc, iText, rect, font); - } -

                For convenience there’s a CCoeControl::ScreenFont() method -that locates the font provider and calls it with the control’s accumulated -zoom:

                -class CCoeControl - ... - protected: - IMPORT_C const CFont& ScreenFont(const TCoeFont& aFont) const; - ... -
                -
                Drawing graphics

                Controls -draw graphics objects - lines, rectangles, shapes and bitmaps to a graphics -context. The graphics context is provided by the Window Server and -represents a group of settings appropriate for the physical device that is -ultimately being drawn to. In most cases the device is a screen and a graphics -context should be obtained using CCoeControl::SystemGc(). CCoeControl::SystemGc() gets -the current graphics context from the run-time hierarchy. Controls in the -hierarchy may override graphics context settings which will then be passed -on to their children. Controls should not get their graphics context directly -from CCoeEnv as to do so would bypass the hierarchy.

                -void CMyControl::Draw( const TRect& aRect ) - { - CWindowGc& gc = SystemGc() ; // get gc from run time hierarchy - TRect rect = TRect( Size() ) ; - if ( IsBlanked() ) - { - // blank out the entire control - gc.SetPenStyle( CGraphicsContext::ENullPen ) ; - gc.SetBrushStyle( CGraphicsContext::ESolidBrush ) ; - TRgb blankColor = BlankingColor() ; - gc.SetBrushColor( blankColor ) ; - gc.DrawRect( rect ) ; - } - else - { - // draw masked bitmap in the centre of the control - // The parent will draw the background - TInt id = BitMapId() ; - - TInt x = Size().iWidth - iBitmap[id]->SizeInPixels().iWidth ; - TInt y = Size().iHeight - iBitmap[id]->SizeInPixels().iHeight ; - - TPoint pos = Rect().iTl ; - pos.iX = pos.iX + ( x / 2 ) ; - pos.iY = pos.iY + ( y / 2 ) ; - - gc.BitBltMasked( pos, iBitmap[id], rect, iMaskBitmap, ETrue ) ; - } - }

                Before a graphics context can be used it must be activated. -After use it must be deactivated. Activation and deactivation are done automatically -by the framework in DrawNow(), DrawDeferred() and HandleRedrawEvent() but -must be done explicitly for any other application initiated drawing by calling ActivateGc() and DeactivateGc().

                Controls may implement partial drawing to speed up performance. The Draw() function -may be split into sub functions: DrawThis(), DrawThat(), DrawTheOther(). -Each of these requires a corresponding DrawThisNow() and/or DrawThisDeferred() function.

                -CMyControl::Draw() - { - DrawThis() ; - DrawThat() ; - DrawTheOther() ; - } -CMyControl::DrawThisNow() - { - ActivateGc() ; - DrawThis() ; - DeactivateGc() ; - }
                -
                Handling events

                The -Control Framework supports user interaction in two ways: key-press events -and pointer events. Both types of event arrive through the Window Server though -they each arrive in a slightly different way. Both are closely related to -the concept of 'focus' and the location of the cursor.

                Handling -key events

                Key events are delivered to the AppUi. The Window -Server channels them through the root window of its current window group which -maps to the AppUi foreground application. The AppUi offers each key event -to each of the controls on its control stack in priority order until one of -the controls 'consumes' it.

                To receive key events a control must implement CCoeControl::OfferKeyEventL(). -If it handles the event it must return EKeyWasConsumed: If -it doesn't it must return EKeyWasNotConsumed so that the -next control on the stack receives it.

                -TKeyResponse CMyControl::OfferKeyEventL( const TKeyEvent& aKeyEvent, TEventCode aType) - { - TKeyResponse returnValue = EKeyWasConsumed ; - switch( aKeyEvent.iCode ) - { - case EKeyEnter : - // do stuff - break ; - case EKeyEscape : - // do stuff : - break ; - - ... - - default : - // did not recognise key event - returnValue = EKeyWasNotConsumed ; - break ; - } - return returnValue ; - }

                The handling of key events will depend on the design -and purpose of the control itself. Compound controls might need to keep track -of an input focus, or cursor, and to pass key events amongst -its lodgers. Input into one lodger might have an effect on another - pressing -a navigation key might cause one control to lose the highlight and another -to gain it, pressing a number key might cause a text editor to grow which -might, in turn, require all of the components below it to shuffle downwards -and a scroll bar to become visible (which might also require some controls -to be laid out differently).

                Handling pointer events

                Pointer -events are slightly different as the position of the pointer, rather than -of the focus, is significant. The Window Server passes a pointer event to -the top-most visible window at the point of contact. The Framework uses the -functions ProcessPointerEventL() and HandlePointerEventL() to -work down the hierarchy. The Framework also uses the MCoeControlObserver and -focussing mechanisms to inform the observer of the controls that will be losing -and gaining the focus.

                Using the Control Observer Interface

                The -Control Framework facilitates this type of relationship between a container -and its lodgers with the MCoeControlObserver interface. Typically -the container implements the interface and becomes the observer for each lodger -that can receive user input (focus). There is only one function in MCoeControlObserver:

                virtual void HandleControlEventL( CCoeControl *aControl, TCoeEvent aEventType ) = 0 ;

                and it is called when an observed control calls

                void CCoeControl::ReportEvent( MCoeControlObserver::TCoeEvent aEvent ) ;

                A control can have only one observer (or none) so ReportEvent() does -not need to specify an observer. An observer may observe any number of controls -so HandleControlEventL() takes the observed control as a -parameter. The other piece of information passed to the observer is a TCoeEvent.

                enum TCoeEvent - { - EEventRequestExit, - EEventRequestCancel, - EEventRequestFocus, - EEventPrepareFocusTransition, - EEventStateChanged, - EEventInteractionRefused - };

                CCoeControl also provides IsFocused(), SetFocused() and IsNonFocussing(). Note that Framework does not attempt to ensure exclusivity of focus, nor -does it give any visible indication of focus. It is up to the application -developer to ensure that only one control has the focus at a time, that the -focus is correctly transferred between controls, that only appropriate controls -receive the focus and that the focus is visible at all times.

                void CContainer::HandleControlEventL(CCoeControl* aControl, TCoeEvent aEventType) - { - switch (aEventType) - { - case EEventRequestFocus: - { - if( !(aControl->IsFocussed()) ) - { - aControl->SetFocus( ETrue ) ; - // remove focus from other controls - for ( Tint ii = 0 ; ii < CountComponentControls() ; ii++ ) - { - CCoeControl* ctl = ComponentControl( ii ) ; - if( ( ctl != aControl ) && !( ctl->IsNonFocussing() ) ) - { - aControl->SetFocus( EFalse ) ; - } - } - } - } - break; - ... - } - }

                Control developers may implement HandlePointerEventL(), -which is a virtual function, to perform pointer event functionality. The implementation -must, however, call the base class function.

                Controls may modify their -pointer area, possibly if they appear non-rectangular or overlap. To do so -requires the addition of a hit test which describes a hit-test region. A hit-test -region may cover all or part of one or more controls. A hit for a control -is registered in the area covered by both the control and its associated hit -test.

                The diagram below represents three controls, each of which is -rectangular but which appears on the screen as a non-rectangular bitmap. Only -a hit on a bitmap area should register. This could be achieved by defining -a single hit-test region in the shape (and position) of the three blue areas -and associating it with each of the controls. The class that implements the -hit-test region must implement the MCoeControlHitTest interface.

                - Hit-test region example - - -class MCoeControlHitTest - ... - public: - virtual TBool HitRegionContains( const TPoint& aPoint, const CCoeControl& aControl ) const = 0; -

                A hit test is associated with a control using CCoeControl::SetHitText(). -The base class implementation of HandlePointerEventL() performs -the following test:

                - ... - const MCoeControlHitTest* hitTest = ctrl->HitTest() ; - if( hitTest ) - { - if( hitTest->HitRegionContains( aPointerEvent.iPosition, *ctrl ) && - ctrl->Rect().Contains( aPointerEvent.iPosition ) )

                Note -that this is performed by a container when deciding which lodger to pass the -event onto. This snippet also illustrates how a control can find where (iPosition) -the pointer event actually occurred.

                Pointer support includes dragging -& grabbing. See TPointerEvent.

                -
                Implementing -the Object Provider (MOP) interface

                The Object -Provider mechanism exists to allow a control to call a function on -another control in the hierarchy for which it does not have a reference. It -simply calls MopGetObject() specifying the interface containing -the function. It may also call MopGetObjectNoChaining() to -inquire of a specific object whether it supports the requested interface.

                Only -controls which wish to supply an interface require customisation. In order -to be identifiable an interface must have an associated UID. The following -code samples show how CEikAlignedControl implements and -supplies MEikAlignedControl:

                -class MEikAlignedControl - ... - public: - DECLARE_TYPE_ID( 0x10A3D51B ) // Symbian allocated UID identifies this interface - ... - -class CEikAlignedControl : public CCoeControl, public MEikAlignedControl - { - ... - private: //from CCoeControl - IMPORT_C TTypeUid::Ptr MopSupplyObject( TTypeUid aId ) ; - ... - -EXPORT_C TTypeUid::Ptr CEikAlignedControl::MopSupplyObject( TTypeUid aId ) - { - if( aId.iUid == MEikAlignedControl::ETypeId ) - return aId.MakePtr( static_cast<MEikAlignedControl*>( this ) ) ; - - return CCoeControl::MopSupplyObject( aId ) ; // must call base class! - } -

                To get an interface from the object provider framework the -caller must use a pointer to the interface.

                - ... - MEikAlignedControl* alignedControl = NULL ; - MyControl->MopGetObject( alignedControl ) ; - if ( alignedControl ) - { - ... // etc.

                To get an interface from a specific object -the caller may use the no-chaining function call.

                - ... - MEikAlignedControl* alignedControl = NULL ; - aControl->MopGetObjectNoChaining( alignedControl ) ; - if ( alignedControl ) - { - ... // etc.
                -                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B84FA223-3DFD-58C5-8CEF-C5AA73AA6290-GENID-1-8-1-6-1-1-4-1-6-1-9-1.dita --- a/Symbian3/SDK/Source/GUID-B84FA223-3DFD-58C5-8CEF-C5AA73AA6290-GENID-1-8-1-6-1-1-4-1-6-1-9-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,552 +0,0 @@ - - - - - -How -to write controls -

                Cone itself does not provide any concrete controls. Uikon and the UI variant -libraries provide a large number of 'stock' controls for application writers. -Application writers often need to supplement the standard set of controls -with application specific controls of their own. These may be completely new -controls or, more often, compound controls which contain a number of standard -controls.

                -

                This section describes how to create controls and how to integrate them -in to the control framework. It is divided into the following sections:

                -

                Creating -a control

                -

                Window -owning or not?

                -

                Creating -a compound control

                -

                Size, -position and layout

                -

                Drawing -and refreshing

                -

                Drawing -backgrounds

                -

                Drawing -text

                -

                Drawing -graphics

                -

                Handling -events

                -

                Implementing -the Object Provider (MOP) interface

                -
                Creating a -control

                A control is a class which derives from CCoeControl. -It should have a public constructor and, if any leaving function calls or -memory allocations are required during construction, a ConstructL() function. -The majority of re-useable and configurable controls have a ConstructFromResourceL() function -which allows a specific instance of a control to be configured using an application's -resource file. Obviously any memory allocated must be freed in the destructor. -Before a control is drawn to the screen it must be activated. The ActivateL() -function may be overriden to perform last-minute configuration (but -must call the function in the base class).

                -Class CMyControl : public CCoeControl - { - public: - CMyControl() ; - void ConstructL(...) ; - // from CCoeControl - void ConsructFromResourceL( TResourceReader& aReader ) ; - private: - ~CMyControl() ; - - // additional functions to handle events - // additional functions to draw the control - // additional functions to determine the size, layout and position the control - }
                -
                Window owning -or not?

                The decision over whether to make a control window owning -or not is usually straightforward. Each view requires a window, so the top-level -control must be window-owning and a child of the AppUi. Below this a window -owning control is normally only necessary where a sense of layering is required: -for instance a pop-up window or a scrolling window. Dialogs and menus are -window owning controls but these are normally implemented in the Uikon and -UI variant libraries and do not require custom derivation from CCoeControl. -Unnecessary window-owning controls should be avoided as they require more -infrastructure, place greater demand on the Window Server and reduce performance.

                If -a control must be window owning its window must either be created in the ConstructL() function -or by the caller. The former is preferred. There are several overloads of -the CreateWindowL() and CreateBackedUpWindowL() functions. -Those which do not take a parent parameter create a top-level window which -is a child of the root window.

                If a control is not window owning its SetContainerWindowL() function -must be called when it is instantiated.

                If it can, the Framework will -automatically set up the parent pointer when the window, or associated window -relationship is established. If it cannot do this, because CreateWindowL() or SetContainerWindowL() did -not provide a CCoeControl, the parent pointer (and MopParent) -may be set expicitly using SetParent() and SetMopParent().

                -
                Creating a -compound control

                Most applications UIs are built from compound -controls. Many custom controls are built up from stock controls and are therefore -also compound controls. When a compound control is constructed it constructs -its components in its ConstructL() function. When it receives -commands itself, such as ActivateL() and DrawNow() it -passes them on to each of its components. In most cases the Framework does -much of the donkey work as long as the compound control has been constructed -correctly.

                There are now two methods of creating and managing lodger -controls. The first method described is the one that should be used.

                -void MyControl::ConstructL( ... ) - { - // initialise the component array. This must be called once (subsequent calls have no effect) - InitComponentArrayL() ; - - // construct each component control and add it to the component array. - CComponent* myComponent = new (ELeave) CComponent ; - Components().AppendLC( myComponent ) ; // or InsertLC or InsertAfterLC(). Places item on cleanup stack. - myComponent->ConstructL() ; - myComponent->SetThisAndThatL() ; - CleanupStack::Pop( myComponent ) ; - }

                The return value of the insert and append methods is -a CCoeControlArray::TCursor object which works as an iterator. -It will remain valid when other items are inserted or deleted, or even if -the whole array is re-ordered.

                The insert and append methods leave -the component on the Cleanup Stack using a dedicated Cleanup Item that protects -the parent's array as well as the component itself.

                The insert and -append methods allow each component to be given an ID. The ID must be unique -only within the parent so typically a compound control will have an enum listing -each of its children's IDs. CCoeControlArray , accessed -using CCoeControl::Components(), has a ControlById() method -to retrieve components using their IDs.

                Components in the array are, -by default, owned by the parent and will be deleted automatically when the -parent is deleted. The default may be overridden using CCoeControlArray::SetControlsOwnedExternally(). -The setting applies to all of the components.

                Controls may be removed -from the array using one of the Remove() methods. These do -not delete.

                -class CCoeControlArray - ... - public: - IMPORT_C TInt Remove(const CCoeControl* aControl); - IMPORT_C CCoeControl* Remove(TCursor aRemoveAt); - IMPORT_C CCoeControl* RemoveById(TInt aControlId); - ... -

                Using the component array as described is now the approved -method of constructing and managing compound controls. In older versions of -Symbian OS a specific method of handling components was not provided and developers -were obliged to design their own. Bypassing the component array is still possible. -It is necessary to allocate and store the components (typically as member -data) and to implement the CountComponentControls() and ComponentControl() functions -to return the number of components and a specified component to the framework. -The new method offers significant advantages when controls are added and removed -dynamically or are dependant on run-time data. The new method is also integrated -with new layout managers.

                -
                Size, position -and layout

                There are several factors which contribute to a control's -size and position. The control itself will require a certain size in order -to display itself (and its data) correctly. The control's container will be -responsible for positioning the control but is also likely to be responsible -for positioning other controls - each of which will have its own requirements. -Additionally there are the requirements of the UI's look and feel that must -be complied with.

                Each control is responsible for implementing its -own Size() function.

                Until Symbian OS version 9.1 -it was normal to write layout code for simple and compound controls in the SizeChanged() function. -This is called by the framework, as one might expect, when a control's size -(its 'extent') is changed. From 9.1, however, Symbian OS supports the use -of the layout manager interface (MCoeLayoutManager) and -the SizeChanged() function is now implemented in the base -class. (Note that if a control's position is changed, with no size change, -using CCoeControl::SetPosition() its PositionChanged() function -is called and that default implementation of PositionChanged() is -empty).

                -class MCoeLayoutManager - ... - protected: - IMPORT_C MCoeLayoutManager(); - - public: - virtual TBool CanAttach() const = 0; - virtual void AttachL(CCoeControl& aCompoundControl) = 0; - virtual void Detach(CCoeControl& aCompoundControl) = 0; - virtual TSize CalcMinimumSize(const CCoeControl& aCompoundControl) const = 0; - virtual void PerformLayout() = 0; - virtual TInt CalcTextBaselineOffset(const CCoeControl& aCompoundControl, const TSize& aSize) const = 0; - virtual void SetTextBaselineSpacing(TInt aBaselineSpacing) = 0; - virtual TInt TextBaselineSpacing() const = 0; - virtual void HandleAddedControlL(const CCoeControl& aCompoundControl, const CCoeControl& aAddedControl) = 0; - virtual void HandleRemovedControl(const CCoeControl& aCompoundControl, const CCoeControl& aRemovedControl) = 0; - virtual TInt HandleControlReplaced(const CCoeControl& aOldControl, const CCoeControl& aNewControl) = 0; - ... -

                A layout manager may be attached to a compound control.

                -class CCoeControl - ... - protected: - IMPORT_C MCoeLayoutManager* LayoutManager() const; - IMPORT_C virtual void SetLayoutManagerL(MCoeLayoutManager* aLayoutManager); - - public: - IMPORT_C virtual TBool RequestRelayout(const CCoeControl* aChildCtrl); - ...

                The default implementations of MinimumSize() and SizeChanged() now -use the layout manager.

                -EXPORT_C TSize CCoeControl::MinimumSize() - { - const MCoeLayoutManager* layoutManager = LayoutManager(); - if (layoutManager) - return layoutManager->CalcMinimumSize(*this); - else - return iSize; - } - -EXPORT_C void CCoeControl::SizeChanged() - { - MCoeLayoutManager* layout = LayoutManager(); - if (layout) - layout->PerformLayout(); -

                The layout manager is responsible for the size and position -of the component controls. In practice it's likely that the UI variant libraries -will provide concrete layout managers. Application developers should use these -as the basis for control-specific layout managers.

                -
                Drawing and -refreshing

                A fundamental requirement of most controls is that they -are able to render themselves onto the screen. For most controls the drawing -process involves outputting text, painting backgrounds (either plain or from -a bitmap), drawing shapes (graphics objects) and drawing component controls.

                Screen -drawing may be initiated by the application itself, following something within -the application changing, or by the Window Server, due to something else in -the system updating the screen while the application is visible. In both cases -the control's Draw() function will be called automatically -by the framework. For compound controls all of the components' Draw() functions -will also be called - unless the component lies completely outside the area -that requires redrawing.

                As a control writer you will probably have -to implement a Draw() function.

                Here is the signature -for Draw():

                private: - void Draw( const TRect& aRect ) const ;

                Note that it -is private, takes a const TRect& as a parameter, must -not leave and is const.

                It should only be called -by the framework. Application initiated redraws should be through calls to DrawNow(), DrawDeferred() or -custom functions for drawing smaller elements.

                The aRect parameter -is the part of the control that requires drawing (refreshing).

                The -function is const and non-leaving because it is intended -to support the decoupling of drawing actions from application state.

                -
                Drawing backgrounds

                A -control's background is typically determined by the current colour scheme -or skin. It may be a plain colour or a bitmap. It's also possible that a control -is to appear non-rectangular or transparent in which case some of the background -will be the control underneath. Prior to Symbian OS 9.1 controls were required -to clear and update their whole area and creating these effects was rather -complex. From 9.1 controls are drawn 'backmost first'.

                Background -drawing should be done by a dedicated background drawer - i.e. an object which -implements the MCoeControlBackground interface. A background -can be attached to a CCoeControl using SetBackground() and -is used for that control and all of its children. When a control is drawn -the framework looks for the nearest background up the run-time hierarchy and -calls MCoeControlBackground::Draw().

                UI variant libraries -typically provide backgrounds. They are not owned by the controls to which -they are attached.

                -
                Drawing text

                Text -must be drawn with the correct color, font, size and direction. As with backgrounds, -these are determined at runtime according to UI customizations. This is achieved -by means of a Text Drawer. Note the use of the XCoeTextDrawer class. -This is a smart pointer (note the use of the -> operator -to access CCoeTextDrawerBase functions) which ensures that -only one text drawer is allocated on the heap at a time.

                -XCoeTextDrawer textDrawer( TextDrawer() ); -textDrawer->SetAlignment(iAlignment); -textDrawer->SetMargins(iMargin); -textDrawer->SetLineGapInPixels(iGapBetweenLines); -textDrawer.SetClipRect(aRect); // have to use . [dot] operator for SetClipRect() as not CCoeTextDrawerBase function. - -textDrawer.DrawText(gc, *iTextToDraw, Rect(), *Font()); -

                Text drawers are typically provided by the UI variant library -or skin manager. Controls within the run-time hierarchy can set the text drawer -for their children by overriding GetTextDrawer().

                Note -that the text drawer expects text to be passed as a TBidiText rather -than a descriptor. Controls should store all display text in TBidiText objects. -Application writers should consider the implications of right-to-left layouts -for languages such as Hebrew and Arabic.

                A control's GetTextDrawer() function -might look something like this. It checks on the current state of the control -(IsDimmed()) and passes the call on to a skin manager.

                -EXPORT_C void CMyButtonControl::GetTextDrawer(CCoeTextDrawerBase*& aTextDrawer, const CCoeControl* aDrawingControl, TInt /*aKey*/) const - { - const TInt textDrawerIndex = (IsDimmed() ? EButtonTextDimmed : EButtonText); - - SkinManager::GetTextDrawer(aTextDrawer, KSkinUidButton, textDrawerIndex, aDrawingControl); - } -

                If the control is drawing text on its own graphics (and does -not care about the text drawer of its parents) it can just create an XCoeTextDrawer object -on the stack in its Draw() method and initiate it from the -skin that it is currently using to draw its graphics, using the CSkinPatch::TextDrawer() method, -like this:

                -const CSkinPatch& skin = SkinManager::SkinPatch(KSomeSkinUid, KSomeSkinIndex, this); - -skin.DrawBitmap(gc, Rect(), aRect); -XCoeTextDrawer textDrawer( skin.TextDrawer(KSomeSkinUid, ESomeSkinTextDimmed, this) ); - -const CFont& font = ScreenFont(TCoeFont::NormalFont); -textDrawer.DrawText(gc, iText, rect, font); -

                The example above also illustrates how to retrieve the correct -font. CFont objects must not be stored in control member -data as they must change when the control's zoom state changes. Instead, a TCoeFont that -represents a font's size (logical or absolute in pixels) and style (plain, -bold, italic, subscript, or superscript) should be used.

                -class TCoeFont - ... - public: - IMPORT_C TCoeFont(TLogicalSize aSize, TInt aStyle, TInt aFlags = ENoFlags); - IMPORT_C TCoeFont(TInt aHeightInPixels, TInt aStyle, TInt aFlags = ENoFlags); - IMPORT_C TCoeFont(const TCoeFont& aFont); - IMPORT_C TCoeFont(); - ...

                By creating a TCoeFont object -describing the properties of the desired font, a CFont object -reference (needed to actually draw the text) can be fetched from the CCoeFontProvider. -A font provider can be attached to any CCoeControl and -will keep information about the typeface used by that control and all controls -below. A default font provider is attached to the CCoeEnv.

                -class CCoeControl - ... - public: - IMPORT_C const CCoeFontProvider& FindFontProvider() const; - IMPORT_C void SetFontProviderL(const CCoeFontProvider& aFontProvider); - ... -

                To get hold of the CFont object -a Draw() method can be implemented like this:

                -void CMyControl::Draw(const TRect& aRect) - { - const CCoeFontProvider& fontProvider = FindFontProvider(); - const CFont& font = fontProvider.Font(TCoeFont::LegendFont(), AccumulatedZoom()); - - XCoeTextDrawer textDrawer( TextDrawer() ); - textDrawer->SetAlignment(EHCenterVCenter); - textDrawer.DrawText(gc, iText, rect, font); - } -

                For convenience there’s a CCoeControl::ScreenFont() method -that locates the font provider and calls it with the control’s accumulated -zoom:

                -class CCoeControl - ... - protected: - IMPORT_C const CFont& ScreenFont(const TCoeFont& aFont) const; - ... -
                -
                Drawing graphics

                Controls -draw graphics objects - lines, rectangles, shapes and bitmaps to a graphics -context. The graphics context is provided by the Window Server and -represents a group of settings appropriate for the physical device that is -ultimately being drawn to. In most cases the device is a screen and a graphics -context should be obtained using CCoeControl::SystemGc(). CCoeControl::SystemGc() gets -the current graphics context from the run-time hierarchy. Controls in the -hierarchy may override graphics context settings which will then be passed -on to their children. Controls should not get their graphics context directly -from CCoeEnv as to do so would bypass the hierarchy.

                -void CMyControl::Draw( const TRect& aRect ) - { - CWindowGc& gc = SystemGc() ; // get gc from run time hierarchy - TRect rect = TRect( Size() ) ; - if ( IsBlanked() ) - { - // blank out the entire control - gc.SetPenStyle( CGraphicsContext::ENullPen ) ; - gc.SetBrushStyle( CGraphicsContext::ESolidBrush ) ; - TRgb blankColor = BlankingColor() ; - gc.SetBrushColor( blankColor ) ; - gc.DrawRect( rect ) ; - } - else - { - // draw masked bitmap in the centre of the control - // The parent will draw the background - TInt id = BitMapId() ; - - TInt x = Size().iWidth - iBitmap[id]->SizeInPixels().iWidth ; - TInt y = Size().iHeight - iBitmap[id]->SizeInPixels().iHeight ; - - TPoint pos = Rect().iTl ; - pos.iX = pos.iX + ( x / 2 ) ; - pos.iY = pos.iY + ( y / 2 ) ; - - gc.BitBltMasked( pos, iBitmap[id], rect, iMaskBitmap, ETrue ) ; - } - }

                Before a graphics context can be used it must be activated. -After use it must be deactivated. Activation and deactivation are done automatically -by the framework in DrawNow(), DrawDeferred() and HandleRedrawEvent() but -must be done explicitly for any other application initiated drawing by calling ActivateGc() and DeactivateGc().

                Controls may implement partial drawing to speed up performance. The Draw() function -may be split into sub functions: DrawThis(), DrawThat(), DrawTheOther(). -Each of these requires a corresponding DrawThisNow() and/or DrawThisDeferred() function.

                -CMyControl::Draw() - { - DrawThis() ; - DrawThat() ; - DrawTheOther() ; - } -CMyControl::DrawThisNow() - { - ActivateGc() ; - DrawThis() ; - DeactivateGc() ; - }
                -
                Handling events

                The -Control Framework supports user interaction in two ways: key-press events -and pointer events. Both types of event arrive through the Window Server though -they each arrive in a slightly different way. Both are closely related to -the concept of 'focus' and the location of the cursor.

                Handling -key events

                Key events are delivered to the AppUi. The Window -Server channels them through the root window of its current window group which -maps to the AppUi foreground application. The AppUi offers each key event -to each of the controls on its control stack in priority order until one of -the controls 'consumes' it.

                To receive key events a control must implement CCoeControl::OfferKeyEventL(). -If it handles the event it must return EKeyWasConsumed: If -it doesn't it must return EKeyWasNotConsumed so that the -next control on the stack receives it.

                -TKeyResponse CMyControl::OfferKeyEventL( const TKeyEvent& aKeyEvent, TEventCode aType) - { - TKeyResponse returnValue = EKeyWasConsumed ; - switch( aKeyEvent.iCode ) - { - case EKeyEnter : - // do stuff - break ; - case EKeyEscape : - // do stuff : - break ; - - ... - - default : - // did not recognise key event - returnValue = EKeyWasNotConsumed ; - break ; - } - return returnValue ; - }

                The handling of key events will depend on the design -and purpose of the control itself. Compound controls might need to keep track -of an input focus, or cursor, and to pass key events amongst -its lodgers. Input into one lodger might have an effect on another - pressing -a navigation key might cause one control to lose the highlight and another -to gain it, pressing a number key might cause a text editor to grow which -might, in turn, require all of the components below it to shuffle downwards -and a scroll bar to become visible (which might also require some controls -to be laid out differently).

                Handling pointer events

                Pointer -events are slightly different as the position of the pointer, rather than -of the focus, is significant. The Window Server passes a pointer event to -the top-most visible window at the point of contact. The Framework uses the -functions ProcessPointerEventL() and HandlePointerEventL() to -work down the hierarchy. The Framework also uses the MCoeControlObserver and -focussing mechanisms to inform the observer of the controls that will be losing -and gaining the focus.

                Using the Control Observer Interface

                The -Control Framework facilitates this type of relationship between a container -and its lodgers with the MCoeControlObserver interface. Typically -the container implements the interface and becomes the observer for each lodger -that can receive user input (focus). There is only one function in MCoeControlObserver:

                virtual void HandleControlEventL( CCoeControl *aControl, TCoeEvent aEventType ) = 0 ;

                and it is called when an observed control calls

                void CCoeControl::ReportEvent( MCoeControlObserver::TCoeEvent aEvent ) ;

                A control can have only one observer (or none) so ReportEvent() does -not need to specify an observer. An observer may observe any number of controls -so HandleControlEventL() takes the observed control as a -parameter. The other piece of information passed to the observer is a TCoeEvent.

                enum TCoeEvent - { - EEventRequestExit, - EEventRequestCancel, - EEventRequestFocus, - EEventPrepareFocusTransition, - EEventStateChanged, - EEventInteractionRefused - };

                CCoeControl also provides IsFocused(), SetFocused() and IsNonFocussing(). Note that Framework does not attempt to ensure exclusivity of focus, nor -does it give any visible indication of focus. It is up to the application -developer to ensure that only one control has the focus at a time, that the -focus is correctly transferred between controls, that only appropriate controls -receive the focus and that the focus is visible at all times.

                void CContainer::HandleControlEventL(CCoeControl* aControl, TCoeEvent aEventType) - { - switch (aEventType) - { - case EEventRequestFocus: - { - if( !(aControl->IsFocussed()) ) - { - aControl->SetFocus( ETrue ) ; - // remove focus from other controls - for ( Tint ii = 0 ; ii < CountComponentControls() ; ii++ ) - { - CCoeControl* ctl = ComponentControl( ii ) ; - if( ( ctl != aControl ) && !( ctl->IsNonFocussing() ) ) - { - aControl->SetFocus( EFalse ) ; - } - } - } - } - break; - ... - } - }

                Control developers may implement HandlePointerEventL(), -which is a virtual function, to perform pointer event functionality. The implementation -must, however, call the base class function.

                Controls may modify their -pointer area, possibly if they appear non-rectangular or overlap. To do so -requires the addition of a hit test which describes a hit-test region. A hit-test -region may cover all or part of one or more controls. A hit for a control -is registered in the area covered by both the control and its associated hit -test.

                The diagram below represents three controls, each of which is -rectangular but which appears on the screen as a non-rectangular bitmap. Only -a hit on a bitmap area should register. This could be achieved by defining -a single hit-test region in the shape (and position) of the three blue areas -and associating it with each of the controls. The class that implements the -hit-test region must implement the MCoeControlHitTest interface.

                - Hit-test region example - - -class MCoeControlHitTest - ... - public: - virtual TBool HitRegionContains( const TPoint& aPoint, const CCoeControl& aControl ) const = 0; -

                A hit test is associated with a control using CCoeControl::SetHitText(). -The base class implementation of HandlePointerEventL() performs -the following test:

                - ... - const MCoeControlHitTest* hitTest = ctrl->HitTest() ; - if( hitTest ) - { - if( hitTest->HitRegionContains( aPointerEvent.iPosition, *ctrl ) && - ctrl->Rect().Contains( aPointerEvent.iPosition ) )

                Note -that this is performed by a container when deciding which lodger to pass the -event onto. This snippet also illustrates how a control can find where (iPosition) -the pointer event actually occurred.

                Pointer support includes dragging -& grabbing. See TPointerEvent.

                -
                Implementing -the Object Provider (MOP) interface

                The Object -Provider mechanism exists to allow a control to call a function on -another control in the hierarchy for which it does not have a reference. It -simply calls MopGetObject() specifying the interface containing -the function. It may also call MopGetObjectNoChaining() to -inquire of a specific object whether it supports the requested interface.

                Only -controls which wish to supply an interface require customisation. In order -to be identifiable an interface must have an associated UID. The following -code samples show how CEikAlignedControl implements and -supplies MEikAlignedControl:

                -class MEikAlignedControl - ... - public: - DECLARE_TYPE_ID( 0x10A3D51B ) // Symbian allocated UID identifies this interface - ... - -class CEikAlignedControl : public CCoeControl, public MEikAlignedControl - { - ... - private: //from CCoeControl - IMPORT_C TTypeUid::Ptr MopSupplyObject( TTypeUid aId ) ; - ... - -EXPORT_C TTypeUid::Ptr CEikAlignedControl::MopSupplyObject( TTypeUid aId ) - { - if( aId.iUid == MEikAlignedControl::ETypeId ) - return aId.MakePtr( static_cast<MEikAlignedControl*>( this ) ) ; - - return CCoeControl::MopSupplyObject( aId ) ; // must call base class! - } -

                To get an interface from the object provider framework the -caller must use a pointer to the interface.

                - ... - MEikAlignedControl* alignedControl = NULL ; - MyControl->MopGetObject( alignedControl ) ; - if ( alignedControl ) - { - ... // etc.

                To get an interface from a specific object -the caller may use the no-chaining function call.

                - ... - MEikAlignedControl* alignedControl = NULL ; - aControl->MopGetObjectNoChaining( alignedControl ) ; - if ( alignedControl ) - { - ... // etc.
                -                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B84FA223-3DFD-58C5-8CEF-C5AA73AA6290.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-B84FA223-3DFD-58C5-8CEF-C5AA73AA6290.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,552 @@ + + + + + +How to +write controls +

                Cone itself does not provide any concrete controls. Uikon and the UI variant +libraries provide a large number of 'stock' controls for application writers. +Application writers often need to supplement the standard set of controls +with application specific controls of their own. These may be completely new +controls or, more often, compound controls which contain a number of standard +controls.

                +

                This section describes how to create controls and how to integrate them +in to the control framework. It is divided into the following sections:

                +

                Creating +a control

                +

                Window +owning or not?

                +

                Creating +a compound control

                +

                Size, +position and layout

                +

                Drawing +and refreshing

                +

                Drawing +backgrounds

                +

                Drawing +text

                +

                Drawing +graphics

                +

                Handling +events

                +

                Implementing +the Object Provider (MOP) interface

                +
                Creating a +control

                A control is a class which derives from CCoeControl. +It should have a public constructor and, if any leaving function calls or +memory allocations are required during construction, a ConstructL() function. +The majority of re-useable and configurable controls have a ConstructFromResourceL() function +which allows a specific instance of a control to be configured using an application's +resource file. Obviously any memory allocated must be freed in the destructor. +Before a control is drawn to the screen it must be activated. The ActivateL() +function may be overriden to perform last-minute configuration (but +must call the function in the base class).

                +Class CMyControl : public CCoeControl + { + public: + CMyControl() ; + void ConstructL(...) ; + // from CCoeControl + void ConsructFromResourceL( TResourceReader& aReader ) ; + private: + ~CMyControl() ; + + // additional functions to handle events + // additional functions to draw the control + // additional functions to determine the size, layout and position the control + }
                +
                Window owning +or not?

                The decision over whether to make a control window owning +or not is usually straightforward. Each view requires a window, so the top-level +control must be window-owning and a child of the AppUi. Below this a window +owning control is normally only necessary where a sense of layering is required: +for instance a pop-up window or a scrolling window. Dialogs and menus are +window owning controls but these are normally implemented in the Uikon and +UI variant libraries and do not require custom derivation from CCoeControl. +Unnecessary window-owning controls should be avoided as they require more +infrastructure, place greater demand on the Window Server and reduce performance.

                If +a control must be window owning its window must either be created in the ConstructL() function +or by the caller. The former is preferred. There are several overloads of +the CreateWindowL() and CreateBackedUpWindowL() functions. +Those which do not take a parent parameter create a top-level window which +is a child of the root window.

                If a control is not window owning its SetContainerWindowL() function +must be called when it is instantiated.

                If it can, the Framework will +automatically set up the parent pointer when the window, or associated window +relationship is established. If it cannot do this, because CreateWindowL() or SetContainerWindowL() did +not provide a CCoeControl, the parent pointer (and MopParent) +may be set expicitly using SetParent() and SetMopParent().

                +
                Creating a +compound control

                Most applications UIs are built from compound +controls. Many custom controls are built up from stock controls and are therefore +also compound controls. When a compound control is constructed it constructs +its components in its ConstructL() function. When it receives +commands itself, such as ActivateL() and DrawNow() it +passes them on to each of its components. In most cases the Framework does +much of the donkey work as long as the compound control has been constructed +correctly.

                There are now two methods of creating and managing lodger +controls. The first method described is the one that should be used.

                +void MyControl::ConstructL( ... ) + { + // initialise the component array. This must be called once (subsequent calls have no effect) + InitComponentArrayL() ; + + // construct each component control and add it to the component array. + CComponent* myComponent = new (ELeave) CComponent ; + Components().AppendLC( myComponent ) ; // or InsertLC or InsertAfterLC(). Places item on cleanup stack. + myComponent->ConstructL() ; + myComponent->SetThisAndThatL() ; + CleanupStack::Pop( myComponent ) ; + }

                The return value of the insert and append methods is +a CCoeControlArray::TCursor object which works as an iterator. +It will remain valid when other items are inserted or deleted, or even if +the whole array is re-ordered.

                The insert and append methods leave +the component on the Cleanup Stack using a dedicated Cleanup Item that protects +the parent's array as well as the component itself.

                The insert and +append methods allow each component to be given an ID. The ID must be unique +only within the parent so typically a compound control will have an enum listing +each of its children's IDs. CCoeControlArray , accessed +using CCoeControl::Components(), has a ControlById() method +to retrieve components using their IDs.

                Components in the array are, +by default, owned by the parent and will be deleted automatically when the +parent is deleted. The default may be overridden using CCoeControlArray::SetControlsOwnedExternally(). +The setting applies to all of the components.

                Controls may be removed +from the array using one of the Remove() methods. These do +not delete.

                +class CCoeControlArray + ... + public: + IMPORT_C TInt Remove(const CCoeControl* aControl); + IMPORT_C CCoeControl* Remove(TCursor aRemoveAt); + IMPORT_C CCoeControl* RemoveById(TInt aControlId); + ... +

                Using the component array as described is now the approved +method of constructing and managing compound controls. In older versions of +Symbian OS a specific method of handling components was not provided and developers +were obliged to design their own. Bypassing the component array is still possible. +It is necessary to allocate and store the components (typically as member +data) and to implement the CountComponentControls() and ComponentControl() functions +to return the number of components and a specified component to the framework. +The new method offers significant advantages when controls are added and removed +dynamically or are dependant on run-time data. The new method is also integrated +with new layout managers.

                +
                Size, position +and layout

                There are several factors which contribute to a control's +size and position. The control itself will require a certain size in order +to display itself (and its data) correctly. The control's container will be +responsible for positioning the control but is also likely to be responsible +for positioning other controls - each of which will have its own requirements. +Additionally there are the requirements of the UI's look and feel that must +be complied with.

                Each control is responsible for implementing its +own Size() function.

                Until Symbian OS version 9.1 +it was normal to write layout code for simple and compound controls in the SizeChanged() function. +This is called by the framework, as one might expect, when a control's size +(its 'extent') is changed. From 9.1, however, Symbian OS supports the use +of the layout manager interface (MCoeLayoutManager) and +the SizeChanged() function is now implemented in the base +class. (Note that if a control's position is changed, with no size change, +using CCoeControl::SetPosition() its PositionChanged() function +is called and that default implementation of PositionChanged() is +empty).

                +class MCoeLayoutManager + ... + protected: + IMPORT_C MCoeLayoutManager(); + + public: + virtual TBool CanAttach() const = 0; + virtual void AttachL(CCoeControl& aCompoundControl) = 0; + virtual void Detach(CCoeControl& aCompoundControl) = 0; + virtual TSize CalcMinimumSize(const CCoeControl& aCompoundControl) const = 0; + virtual void PerformLayout() = 0; + virtual TInt CalcTextBaselineOffset(const CCoeControl& aCompoundControl, const TSize& aSize) const = 0; + virtual void SetTextBaselineSpacing(TInt aBaselineSpacing) = 0; + virtual TInt TextBaselineSpacing() const = 0; + virtual void HandleAddedControlL(const CCoeControl& aCompoundControl, const CCoeControl& aAddedControl) = 0; + virtual void HandleRemovedControl(const CCoeControl& aCompoundControl, const CCoeControl& aRemovedControl) = 0; + virtual TInt HandleControlReplaced(const CCoeControl& aOldControl, const CCoeControl& aNewControl) = 0; + ... +

                A layout manager may be attached to a compound control.

                +class CCoeControl + ... + protected: + IMPORT_C MCoeLayoutManager* LayoutManager() const; + IMPORT_C virtual void SetLayoutManagerL(MCoeLayoutManager* aLayoutManager); + + public: + IMPORT_C virtual TBool RequestRelayout(const CCoeControl* aChildCtrl); + ...

                The default implementations of MinimumSize() and SizeChanged() now +use the layout manager.

                +EXPORT_C TSize CCoeControl::MinimumSize() + { + const MCoeLayoutManager* layoutManager = LayoutManager(); + if (layoutManager) + return layoutManager->CalcMinimumSize(*this); + else + return iSize; + } + +EXPORT_C void CCoeControl::SizeChanged() + { + MCoeLayoutManager* layout = LayoutManager(); + if (layout) + layout->PerformLayout(); +

                The layout manager is responsible for the size and position +of the component controls. In practice it's likely that the UI variant libraries +will provide concrete layout managers. Application developers should use these +as the basis for control-specific layout managers.

                +
                Drawing and +refreshing

                A fundamental requirement of most controls is that they +are able to render themselves onto the screen. For most controls the drawing +process involves outputting text, painting backgrounds (either plain or from +a bitmap), drawing shapes (graphics objects) and drawing component controls.

                Screen +drawing may be initiated by the application itself, following something within +the application changing, or by the Window Server, due to something else in +the system updating the screen while the application is visible. In both cases +the control's Draw() function will be called automatically +by the framework. For compound controls all of the components' Draw() functions +will also be called - unless the component lies completely outside the area +that requires redrawing.

                As a control writer you will probably have +to implement a Draw() function.

                Here is the signature +for Draw():

                private: + void Draw( const TRect& aRect ) const ;

                Note that it +is private, takes a const TRect& as a parameter, must +not leave and is const.

                It should only be called +by the framework. Application initiated redraws should be through calls to DrawNow(), DrawDeferred() or +custom functions for drawing smaller elements.

                The aRect parameter +is the part of the control that requires drawing (refreshing).

                The +function is const and non-leaving because it is intended +to support the decoupling of drawing actions from application state.

                +
                Drawing backgrounds

                A +control's background is typically determined by the current colour scheme +or skin. It may be a plain colour or a bitmap. It's also possible that a control +is to appear non-rectangular or transparent in which case some of the background +will be the control underneath. Prior to Symbian OS 9.1 controls were required +to clear and update their whole area and creating these effects was rather +complex. From 9.1 controls are drawn 'backmost first'.

                Background +drawing should be done by a dedicated background drawer - i.e. an object which +implements the MCoeControlBackground interface. A background +can be attached to a CCoeControl using SetBackground() and +is used for that control and all of its children. When a control is drawn +the framework looks for the nearest background up the run-time hierarchy and +calls MCoeControlBackground::Draw().

                UI variant libraries +typically provide backgrounds. They are not owned by the controls to which +they are attached.

                +
                Drawing text

                Text +must be drawn with the correct color, font, size and direction. As with backgrounds, +these are determined at runtime according to UI customizations. This is achieved +by means of a Text Drawer. Note the use of the XCoeTextDrawer class. +This is a smart pointer (note the use of the -> operator +to access CCoeTextDrawerBase functions) which ensures that +only one text drawer is allocated on the heap at a time.

                +XCoeTextDrawer textDrawer( TextDrawer() ); +textDrawer->SetAlignment(iAlignment); +textDrawer->SetMargins(iMargin); +textDrawer->SetLineGapInPixels(iGapBetweenLines); +textDrawer.SetClipRect(aRect); // have to use . [dot] operator for SetClipRect() as not CCoeTextDrawerBase function. + +textDrawer.DrawText(gc, *iTextToDraw, Rect(), *Font()); +

                Text drawers are typically provided by the UI variant library +or skin manager. Controls within the run-time hierarchy can set the text drawer +for their children by overriding GetTextDrawer().

                Note +that the text drawer expects text to be passed as a TBidiText rather +than a descriptor. Controls should store all display text in TBidiText objects. +Application writers should consider the implications of right-to-left layouts +for languages such as Hebrew and Arabic.

                A control's GetTextDrawer() function +might look something like this. It checks on the current state of the control +(IsDimmed()) and passes the call on to a skin manager.

                +EXPORT_C void CMyButtonControl::GetTextDrawer(CCoeTextDrawerBase*& aTextDrawer, const CCoeControl* aDrawingControl, TInt /*aKey*/) const + { + const TInt textDrawerIndex = (IsDimmed() ? EButtonTextDimmed : EButtonText); + + SkinManager::GetTextDrawer(aTextDrawer, KSkinUidButton, textDrawerIndex, aDrawingControl); + } +

                If the control is drawing text on its own graphics (and does +not care about the text drawer of its parents) it can just create an XCoeTextDrawer object +on the stack in its Draw() method and initiate it from the +skin that it is currently using to draw its graphics, using the CSkinPatch::TextDrawer() method, +like this:

                +const CSkinPatch& skin = SkinManager::SkinPatch(KSomeSkinUid, KSomeSkinIndex, this); + +skin.DrawBitmap(gc, Rect(), aRect); +XCoeTextDrawer textDrawer( skin.TextDrawer(KSomeSkinUid, ESomeSkinTextDimmed, this) ); + +const CFont& font = ScreenFont(TCoeFont::NormalFont); +textDrawer.DrawText(gc, iText, rect, font); +

                The example above also illustrates how to retrieve the correct +font. CFont objects must not be stored in control member +data as they must change when the control's zoom state changes. Instead, a TCoeFont that +represents a font's size (logical or absolute in pixels) and style (plain, +bold, italic, subscript, or superscript) should be used.

                +class TCoeFont + ... + public: + IMPORT_C TCoeFont(TLogicalSize aSize, TInt aStyle, TInt aFlags = ENoFlags); + IMPORT_C TCoeFont(TInt aHeightInPixels, TInt aStyle, TInt aFlags = ENoFlags); + IMPORT_C TCoeFont(const TCoeFont& aFont); + IMPORT_C TCoeFont(); + ...

                By creating a TCoeFont object +describing the properties of the desired font, a CFont object +reference (needed to actually draw the text) can be fetched from the CCoeFontProvider. +A font provider can be attached to any CCoeControl and +will keep information about the typeface used by that control and all controls +below. A default font provider is attached to the CCoeEnv.

                +class CCoeControl + ... + public: + IMPORT_C const CCoeFontProvider& FindFontProvider() const; + IMPORT_C void SetFontProviderL(const CCoeFontProvider& aFontProvider); + ... +

                To get hold of the CFont object +a Draw() method can be implemented like this:

                +void CMyControl::Draw(const TRect& aRect) + { + const CCoeFontProvider& fontProvider = FindFontProvider(); + const CFont& font = fontProvider.Font(TCoeFont::LegendFont(), AccumulatedZoom()); + + XCoeTextDrawer textDrawer( TextDrawer() ); + textDrawer->SetAlignment(EHCenterVCenter); + textDrawer.DrawText(gc, iText, rect, font); + } +

                For convenience there’s a CCoeControl::ScreenFont() method +that locates the font provider and calls it with the control’s accumulated +zoom:

                +class CCoeControl + ... + protected: + IMPORT_C const CFont& ScreenFont(const TCoeFont& aFont) const; + ... +
                +
                Drawing graphics

                Controls +draw graphics objects - lines, rectangles, shapes and bitmaps to a graphics +context. The graphics context is provided by the Window Server and +represents a group of settings appropriate for the physical device that is +ultimately being drawn to. In most cases the device is a screen and a graphics +context should be obtained using CCoeControl::SystemGc(). CCoeControl::SystemGc() gets +the current graphics context from the run-time hierarchy. Controls in the +hierarchy may override graphics context settings which will then be passed +on to their children. Controls should not get their graphics context directly +from CCoeEnv as to do so would bypass the hierarchy.

                +void CMyControl::Draw( const TRect& aRect ) + { + CWindowGc& gc = SystemGc() ; // get gc from run time hierarchy + TRect rect = TRect( Size() ) ; + if ( IsBlanked() ) + { + // blank out the entire control + gc.SetPenStyle( CGraphicsContext::ENullPen ) ; + gc.SetBrushStyle( CGraphicsContext::ESolidBrush ) ; + TRgb blankColor = BlankingColor() ; + gc.SetBrushColor( blankColor ) ; + gc.DrawRect( rect ) ; + } + else + { + // draw masked bitmap in the centre of the control + // The parent will draw the background + TInt id = BitMapId() ; + + TInt x = Size().iWidth - iBitmap[id]->SizeInPixels().iWidth ; + TInt y = Size().iHeight - iBitmap[id]->SizeInPixels().iHeight ; + + TPoint pos = Rect().iTl ; + pos.iX = pos.iX + ( x / 2 ) ; + pos.iY = pos.iY + ( y / 2 ) ; + + gc.BitBltMasked( pos, iBitmap[id], rect, iMaskBitmap, ETrue ) ; + } + }

                Before a graphics context can be used it must be activated. +After use it must be deactivated. Activation and deactivation are done automatically +by the framework in DrawNow(), DrawDeferred() and HandleRedrawEvent() but +must be done explicitly for any other application initiated drawing by calling ActivateGc() and DeactivateGc().

                Controls may implement partial drawing to speed up performance. The Draw() function +may be split into sub functions: DrawThis(), DrawThat(), DrawTheOther(). +Each of these requires a corresponding DrawThisNow() and/or DrawThisDeferred() function.

                +CMyControl::Draw() + { + DrawThis() ; + DrawThat() ; + DrawTheOther() ; + } +CMyControl::DrawThisNow() + { + ActivateGc() ; + DrawThis() ; + DeactivateGc() ; + }
                +
                Handling events

                The +Control Framework supports user interaction in two ways: key-press events +and pointer events. Both types of event arrive through the Window Server though +they each arrive in a slightly different way. Both are closely related to +the concept of 'focus' and the location of the cursor.

                Handling +key events

                Key events are delivered to the AppUi. The Window +Server channels them through the root window of its current window group which +maps to the AppUi foreground application. The AppUi offers each key event +to each of the controls on its control stack in priority order until one of +the controls 'consumes' it.

                To receive key events a control must implement CCoeControl::OfferKeyEventL(). +If it handles the event it must return EKeyWasConsumed: If +it doesn't it must return EKeyWasNotConsumed so that the +next control on the stack receives it.

                +TKeyResponse CMyControl::OfferKeyEventL( const TKeyEvent& aKeyEvent, TEventCode aType) + { + TKeyResponse returnValue = EKeyWasConsumed ; + switch( aKeyEvent.iCode ) + { + case EKeyEnter : + // do stuff + break ; + case EKeyEscape : + // do stuff : + break ; + + ... + + default : + // did not recognise key event + returnValue = EKeyWasNotConsumed ; + break ; + } + return returnValue ; + }

                The handling of key events will depend on the design +and purpose of the control itself. Compound controls might need to keep track +of an input focus, or cursor, and to pass key events amongst +its lodgers. Input into one lodger might have an effect on another - pressing +a navigation key might cause one control to lose the highlight and another +to gain it, pressing a number key might cause a text editor to grow which +might, in turn, require all of the components below it to shuffle downwards +and a scroll bar to become visible (which might also require some controls +to be laid out differently).

                Handling pointer events

                Pointer +events are slightly different as the position of the pointer, rather than +of the focus, is significant. The Window Server passes a pointer event to +the top-most visible window at the point of contact. The Framework uses the +functions ProcessPointerEventL() and HandlePointerEventL() to +work down the hierarchy. The Framework also uses the MCoeControlObserver and +focussing mechanisms to inform the observer of the controls that will be losing +and gaining the focus.

                Using the Control Observer Interface

                The +Control Framework facilitates this type of relationship between a container +and its lodgers with the MCoeControlObserver interface. Typically +the container implements the interface and becomes the observer for each lodger +that can receive user input (focus). There is only one function in MCoeControlObserver:

                virtual void HandleControlEventL( CCoeControl *aControl, TCoeEvent aEventType ) = 0 ;

                and it is called when an observed control calls

                void CCoeControl::ReportEvent( MCoeControlObserver::TCoeEvent aEvent ) ;

                A control can have only one observer (or none) so ReportEvent() does +not need to specify an observer. An observer may observe any number of controls +so HandleControlEventL() takes the observed control as a +parameter. The other piece of information passed to the observer is a TCoeEvent.

                enum TCoeEvent + { + EEventRequestExit, + EEventRequestCancel, + EEventRequestFocus, + EEventPrepareFocusTransition, + EEventStateChanged, + EEventInteractionRefused + };

                CCoeControl also provides IsFocused(), SetFocused() and IsNonFocussing(). Note that Framework does not attempt to ensure exclusivity of focus, nor +does it give any visible indication of focus. It is up to the application +developer to ensure that only one control has the focus at a time, that the +focus is correctly transferred between controls, that only appropriate controls +receive the focus and that the focus is visible at all times.

                void CContainer::HandleControlEventL(CCoeControl* aControl, TCoeEvent aEventType) + { + switch (aEventType) + { + case EEventRequestFocus: + { + if( !(aControl->IsFocussed()) ) + { + aControl->SetFocus( ETrue ) ; + // remove focus from other controls + for ( Tint ii = 0 ; ii < CountComponentControls() ; ii++ ) + { + CCoeControl* ctl = ComponentControl( ii ) ; + if( ( ctl != aControl ) && !( ctl->IsNonFocussing() ) ) + { + aControl->SetFocus( EFalse ) ; + } + } + } + } + break; + ... + } + }

                Control developers may implement HandlePointerEventL(), +which is a virtual function, to perform pointer event functionality. The implementation +must, however, call the base class function.

                Controls may modify their +pointer area, possibly if they appear non-rectangular or overlap. To do so +requires the addition of a hit test which describes a hit-test region. A hit-test +region may cover all or part of one or more controls. A hit for a control +is registered in the area covered by both the control and its associated hit +test.

                The diagram below represents three controls, each of which is +rectangular but which appears on the screen as a non-rectangular bitmap. Only +a hit on a bitmap area should register. This could be achieved by defining +a single hit-test region in the shape (and position) of the three blue areas +and associating it with each of the controls. The class that implements the +hit-test region must implement the MCoeControlHitTest interface.

                + Hit-test region example + + +class MCoeControlHitTest + ... + public: + virtual TBool HitRegionContains( const TPoint& aPoint, const CCoeControl& aControl ) const = 0; +

                A hit test is associated with a control using CCoeControl::SetHitText(). +The base class implementation of HandlePointerEventL() performs +the following test:

                + ... + const MCoeControlHitTest* hitTest = ctrl->HitTest() ; + if( hitTest ) + { + if( hitTest->HitRegionContains( aPointerEvent.iPosition, *ctrl ) && + ctrl->Rect().Contains( aPointerEvent.iPosition ) )

                Note +that this is performed by a container when deciding which lodger to pass the +event onto. This snippet also illustrates how a control can find where (iPosition) +the pointer event actually occurred.

                Pointer support includes dragging +& grabbing. See TPointerEvent.

                +
                Implementing +the Object Provider (MOP) interface

                The Object +Provider mechanism exists to allow a control to call a function on +another control in the hierarchy for which it does not have a reference. It +simply calls MopGetObject() specifying the interface containing +the function. It may also call MopGetObjectNoChaining() to +inquire of a specific object whether it supports the requested interface.

                Only +controls which wish to supply an interface require customisation. In order +to be identifiable an interface must have an associated UID. The following +code samples show how CEikAlignedControl implements and +supplies MEikAlignedControl:

                +class MEikAlignedControl + ... + public: + DECLARE_TYPE_ID( 0x10A3D51B ) // Symbian allocated UID identifies this interface + ... + +class CEikAlignedControl : public CCoeControl, public MEikAlignedControl + { + ... + private: //from CCoeControl + IMPORT_C TTypeUid::Ptr MopSupplyObject( TTypeUid aId ) ; + ... + +EXPORT_C TTypeUid::Ptr CEikAlignedControl::MopSupplyObject( TTypeUid aId ) + { + if( aId.iUid == MEikAlignedControl::ETypeId ) + return aId.MakePtr( static_cast<MEikAlignedControl*>( this ) ) ; + + return CCoeControl::MopSupplyObject( aId ) ; // must call base class! + } +

                To get an interface from the object provider framework the +caller must use a pointer to the interface.

                + ... + MEikAlignedControl* alignedControl = NULL ; + MyControl->MopGetObject( alignedControl ) ; + if ( alignedControl ) + { + ... // etc.

                To get an interface from a specific object +the caller may use the no-chaining function call.

                + ... + MEikAlignedControl* alignedControl = NULL ; + aControl->MopGetObjectNoChaining( alignedControl ) ; + if ( alignedControl ) + { + ... // etc.
                +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B861091F-DFD7-5BDD-B73C-52833F972CBD.dita --- a/Symbian3/SDK/Source/GUID-B861091F-DFD7-5BDD-B73C-52833F972CBD.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-B861091F-DFD7-5BDD-B73C-52833F972CBD.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,85 +1,85 @@ - - - - - -Porting Notifiers to Secure PlatformThis page describes how to migrate notifiers to Symbian OS v9.1.
                Introduction

                Notifier plug-in DLLs ("notifiers") allow components with no direct UI linkage to interact with the user through a UI element; for example, a dialog box.

                You can migrate notifiers to Symbian OS v9.1 without major changes. Any notifier classes derived from MEikSrvNotifierBase must now derive from MEikSrvNotifierBase2. An enumeration is used to define an ECom-based notifier plug-in interface. This acts as a primary key to separate ECom-based notifier plug-ins from other types.

                Note: The Symbian platform architecture still supports old-style (non-ECom-based) plug-ins.

                Notifiers have the following features:

                • They can be installed in ROM (Z:), RAM (C:), or on a memory card (for example, E:).

                • They can be installed and un-installed using SIS files.

                • A single plug-in DLL can provide multiple notifiers. The plug-in DLL returns an array of MEikSrvNotifierBase2 class pointers through ECom.

                • Each notifier can have multiple implementations.

                Notifier source code example

                ECom defines standard framework functions that plug-ins implement. Here is an example of the required notifier source code:

                EXPORT_C CArrayPtr<MEikSrvNotifierBase2>* NotifierArray1() -// Lib main entry point - {...} - -EXPORT_C CArrayPtr<MEikSrvNotifierBase2>* NotifierArray2() -// Lib main entry point - {...} - -// Adding ECom support -#include <ImplementationProxy.h> -const TImplementationProxy ImplementationTable[] = - { - IMPLEMENTATION_PROXY_ENTRY(0x10022238,NotifierArray1), - IMPLEMENTATION_PROXY_ENTRY(0x10022237,NotifierArray2) - }; -EXPORT_C const TImplementationProxy* ImplementationGroupProxy(TInt& aTableCount) - { - aTableCount = sizeof(ImplementationTable)/sizeof(TImplementationProxy); - return ImplementationTable; - }
                Resource file example

                ECom uses resource files to define the main elements of application GUIs. Resource file names must have the format: <dll_uid>.rss.

                The following UIDs may appear in the resource file.

                UID Name

                Description

                dll_uid

                The UID of the notifier plug-in DLL.

                interface_uid

                The interface UID for all notifiers, which is defined in uikon.hrh as:

                #define KUikonUidpluginInterfaceNotifiers 0x101fdfae.

                implementation_uid

                This is implementation-specific.

                plug-in_UID

                The notifier’s UID.

                channel_UID

                The channel for a notifier (for example, a screen or LED).

                Together, the plug-in_UID and channel_UID uniquely identify the notifier plug-in.

                The following resource file corresponds to the C++ Source code, above. It defines two implementations of the notifier interface.

                // 10021239.rss -// - -#include "RegistryInfo.rh" -#include "Uikon.hrh" - -RESOURCE REGISTRY_INFO theInfo - { - dll_uid = 0x10021239; - interfaces = - { - INTERFACE_INFO - { - interface_uid = KUikonUidPluginInterfaceNotifiers; - implementations = - { - IMPLEMENTATION_INFO - { - implementation_uid = 0x10022237; - version_no = 1; - display_name = "TTNOTIFY2V2 Plugin 1"; - default_data = "TTNOTIFY2V2"; - opaque_data = "0"; - }, - IMPLEMENTATION_INFO - { - implementation_uid = 0x10022238; - version_no = 1; - display_name = "TTNOTIFY2V2 Plugin 2"; - default_data = "TTNOTIFY2V2"; - opaque_data = "0"; - } - }; - } - }; -}
                MMP file example

                This is an example project specification (.mmp) file for the notifier:

                -target TESTNOTIFIER.DLL -targettype PLUGIN -capability TrustedUI ProtServ -UID 0x10009D8D 0x10021239 -sourcepath ... -userinclude ... -systeminclude \epoc32\include \epoc32\include\techview -lang SC - -start resource 10021239.rss -target TESTNOTIFIER.rsc - -start resource TNOTDIAL.RSS -targetpath \private\10003a4a -header -end -source filename.cpp -library ECOM.LIB
                Using the extended notifier + + + + + +Porting Notifiers to Secure PlatformThis page describes how to migrate notifiers to Symbian OS v9.1.
                Introduction

                Notifier plug-in DLLs ("notifiers") allow components with no direct UI linkage to interact with the user through a UI element; for example, a dialog box.

                You can migrate notifiers to Symbian OS v9.1 without major changes. Any notifier classes derived from MEikSrvNotifierBase must now derive from MEikSrvNotifierBase2. An enumeration is used to define an ECom-based notifier plug-in interface. This acts as a primary key to separate ECom-based notifier plug-ins from other types.

                Note: The Symbian platform architecture still supports old-style (non-ECom-based) plug-ins.

                Notifiers have the following features:

                • They can be installed in ROM (Z:), RAM (C:), or on a memory card (for example, E:).

                • They can be installed and un-installed using SIS files.

                • A single plug-in DLL can provide multiple notifiers. The plug-in DLL returns an array of MEikSrvNotifierBase2 class pointers through ECom.

                • Each notifier can have multiple implementations.

                Notifier source code example

                ECom defines standard framework functions that plug-ins implement. Here is an example of the required notifier source code:

                EXPORT_C CArrayPtr<MEikSrvNotifierBase2>* NotifierArray1() +// Lib main entry point + {...} + +EXPORT_C CArrayPtr<MEikSrvNotifierBase2>* NotifierArray2() +// Lib main entry point + {...} + +// Adding ECom support +#include <ImplementationProxy.h> +const TImplementationProxy ImplementationTable[] = + { + IMPLEMENTATION_PROXY_ENTRY(0x10022238,NotifierArray1), + IMPLEMENTATION_PROXY_ENTRY(0x10022237,NotifierArray2) + }; +EXPORT_C const TImplementationProxy* ImplementationGroupProxy(TInt& aTableCount) + { + aTableCount = sizeof(ImplementationTable)/sizeof(TImplementationProxy); + return ImplementationTable; + }
                Resource file example

                ECom uses resource files to define the main elements of application GUIs. Resource file names must have the format: <dll_uid>.rss.

                The following UIDs may appear in the resource file.

                UID Name

                Description

                dll_uid

                The UID of the notifier plug-in DLL.

                interface_uid

                The interface UID for all notifiers, which is defined in uikon.hrh as:

                #define KUikonUidpluginInterfaceNotifiers 0x101fdfae.

                implementation_uid

                This is implementation-specific.

                plug-in_UID

                The notifier’s UID.

                channel_UID

                The channel for a notifier (for example, a screen or LED).

                Together, the plug-in_UID and channel_UID uniquely identify the notifier plug-in.

                The following resource file corresponds to the C++ Source code, above. It defines two implementations of the notifier interface.

                // 10021239.rss +// + +#include "RegistryInfo.rh" +#include "Uikon.hrh" + +RESOURCE REGISTRY_INFO theInfo + { + dll_uid = 0x10021239; + interfaces = + { + INTERFACE_INFO + { + interface_uid = KUikonUidPluginInterfaceNotifiers; + implementations = + { + IMPLEMENTATION_INFO + { + implementation_uid = 0x10022237; + version_no = 1; + display_name = "TTNOTIFY2V2 Plugin 1"; + default_data = "TTNOTIFY2V2"; + opaque_data = "0"; + }, + IMPLEMENTATION_INFO + { + implementation_uid = 0x10022238; + version_no = 1; + display_name = "TTNOTIFY2V2 Plugin 2"; + default_data = "TTNOTIFY2V2"; + opaque_data = "0"; + } + }; + } + }; +}
                MMP file example

                This is an example project specification (.mmp) file for the notifier:

                +target TESTNOTIFIER.DLL +targettype PLUGIN +capability TrustedUI ProtServ +UID 0x10009D8D 0x10021239 +sourcepath ... +userinclude ... +systeminclude \epoc32\include \epoc32\include\techview +lang SC + +start resource 10021239.rss +target TESTNOTIFIER.rsc + +start resource TNOTDIAL.RSS +targetpath \private\10003a4a +header +end +source filename.cpp +library ECOM.LIB
                Using the extended notifier framework                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B876D548-FD40-4369-B328-7427002B4851.dita --- a/Symbian3/SDK/Source/GUID-B876D548-FD40-4369-B328-7427002B4851.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-B876D548-FD40-4369-B328-7427002B4851.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,27 +1,29 @@ - - - - - -Title -pane touch observer APIThe Title pane touch observer API is used for observing when the -title pane has been tapped. -

                For user experience guidelines on the title pane, see the title -pane UI component description.

                -

                For implementation information, see Setting -the title pane touch pane observer.

                -

                For Title pane touch observer API classes and header files, see Classes -and Definitions.

                -
                API class structure

                MAknTitlePaneObserver is -part of CAknTitlePane.

                -
                Constraints -

                This API is valid for touch-enabled Symbian platforms.

                -
                Emulator support

                This -API is fully supported in the WINS/WINSCW emulator environment.

                + + + + + +Title +pane touch observer APIThe Title pane touch observer API is used for observing when the +title pane has been tapped. +

                For user experience guidelines on the title pane, see the title +pane UI component description.

                +

                For implementation information, see Setting +the title pane touch pane observer.

                +

                For Title pane touch observer API classes and header files, see Classes +and Definitions.

                +
                API class structure

                MAknTitlePaneObserver is +part of CAknTitlePane.

                +
                Changes and release information

                The Title pane touch +observer API is an SDK API and first released in S60 5th Edition.

                +
                Constraints +

                This API is valid for touch-enabled Symbian platforms.

                +
                Emulator support

                This +API is fully supported in the WINS/WINSCW emulator environment.

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B8BCC4F0-7F55-4728-B7EA-3280CA822C91.dita --- a/Symbian3/SDK/Source/GUID-B8BCC4F0-7F55-4728-B7EA-3280CA822C91.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-B8BCC4F0-7F55-4728-B7EA-3280CA822C91.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,43 +1,46 @@ - - - - - -Stylus -pop-up menu APIThe Stylus pop-up menu API is used for displaying commands in a -context menu the user can access by tapping an item on the device screen. - -Stylus pop-up menu displayed in a preview pop-up - - -

                A stylus pop up menu (CAknStylusPopUpMenu, defined in AknStylusPopUpMenu.h) -is a floating menu component that contains stylus-specific menu content. As -the name implies, the stylus pop up menu is meant to be used only with the -stylus by tapping a stylus interactive area. The pop-up menu is displayed -near the tapping position.

                -

                It is the application’s responsibility to create the stylus pop up menu -and handle the actions its menu items trigger.

                -

                For look and feel guidelines on the stylus pop-up menu, see the stylus -pop-up menu UI component description.

                -

                For implementation information, see Displaying -commands in a context menu.

                -

                For the Stylus pop-up menu API classes and header files, see Classes and -Definitions.

                -
                Constraints

                This -API is valid for touch-enabled Symbian platforms.

                -
                Emulator support

                This -API is fully supported in the WINS/WINSCW emulator environment.

                -                 -Related APIs -Information preview popup API - for creating a preview pop-up from which the stylus pop-up menu can -be launched - - + + + + + +Stylus +pop-up menu APIThe Stylus pop-up menu API is used for displaying commands in a +pop-up menu. + +Stylus pop-up menu displayed + + +

                A stylus pop up menu (CAknStylusPopUpMenu, defined in AknStylusPopUpMenu.h) +is a floating menu component that contains stylus-specific menu content. As +the name implies, the stylus pop up menu is meant to be used only with the +stylus by tapping a stylus interactive area. The pop-up menu is displayed +near the tapping position.

                +

                It is the application’s responsibility to create the stylus pop up menu +and handle the actions its menu items trigger. Note that this does not apply +to item-specific options menu.

                +

                For look and feel guidelines on the stylus pop-up menu, see the stylus +pop-up menu UI component description.

                +

                For implementation information, see Displaying +commands in a context menu.

                +

                For the Stylus pop-up menu API classes and header files, see Classes and +Definitions.

                +
                Changes and release information

                The Stylus pop-up +menu API is an SDK API and first released in S60 5th Edition.

                +
                Constraints

                This +API is valid for touch-enabled Symbian platforms.

                +
                Emulator support

                This +API is fully supported in the WINS/WINSCW emulator environment.

                +                 +Related APIs +Information preview popup API + for creating a preview pop-up from which the stylus pop-up menu can +be launched + +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B8D630CA-7CED-408E-B570-00FF95BE14ED-master.png Binary file Symbian3/SDK/Source/GUID-B8D630CA-7CED-408E-B570-00FF95BE14ED-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B8D630CA-7CED-408E-B570-00FF95BE14ED_d0e82130_href.png Binary file Symbian3/SDK/Source/GUID-B8D630CA-7CED-408E-B570-00FF95BE14ED_d0e82130_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B913762A-2C87-4218-8D20-EBF88F9756DC_d0e11326_href.png Binary file Symbian3/SDK/Source/GUID-B913762A-2C87-4218-8D20-EBF88F9756DC_d0e11326_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B913762A-2C87-4218-8D20-EBF88F9756DC_d0e12601_href.png Binary file Symbian3/SDK/Source/GUID-B913762A-2C87-4218-8D20-EBF88F9756DC_d0e12601_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B92B7DF8-0086-431F-91CE-6F193C045FB5_d0e2770_href.png Binary file Symbian3/SDK/Source/GUID-B92B7DF8-0086-431F-91CE-6F193C045FB5_d0e2770_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B92B7DF8-0086-431F-91CE-6F193C045FB5_d0e2872_href.png Binary file Symbian3/SDK/Source/GUID-B92B7DF8-0086-431F-91CE-6F193C045FB5_d0e2872_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B9306D01-1DE5-511A-AC1A-6E3E9749BA89_d0e246991_href.png Binary file Symbian3/SDK/Source/GUID-B9306D01-1DE5-511A-AC1A-6E3E9749BA89_d0e246991_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B9306D01-1DE5-511A-AC1A-6E3E9749BA89_d0e250728_href.png Binary file Symbian3/SDK/Source/GUID-B9306D01-1DE5-511A-AC1A-6E3E9749BA89_d0e250728_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B9414AE8-820E-4CA5-A9C4-29560CD6F2EF.dita --- a/Symbian3/SDK/Source/GUID-B9414AE8-820E-4CA5-A9C4-29560CD6F2EF.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-B9414AE8-820E-4CA5-A9C4-29560CD6F2EF.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,50 +1,53 @@ - - - - - -Application -signing -

                All Symbian applications must be signed before they can be installed. -All applications which use capability-protected -APIs, where the capability cannot be granted by the end user, have to be certified. -Such certification can be obtained through Symbian -Signed.

                -

                Signing is a means of encoding a digital certificate into the application -installation file. The certificate identifies the application’s vendor, and -grants access to capabilities defined during the build process.

                -

                The signing process is described in detail on the Symbian -Signed website.

                -
                Signing options -

                If your application only needs user capabilities (LocalServices, NetworkServices, ReadUserData, WriteUserData, UserEnvironment, andLocation), -you can self-sign the application.

                - -

                When the end users are installing a self-signed application, they are -informed that the application is untrusted and may decide to abort the installation. -In Nokia E-series devices the user must change a setting to allow self-signed -applications to install.

                -                 -

                Sign the sis installation -file with any private key. You can use the MakeKeys application -to create the needed private key and, for example, SignSIS to -sign the application. Both applications are delivered with the SDK. For more -information, see How -to sign a .Sis file with Self-Sign Certificate in the Forum Nokia -Developer Community Wiki.

                -

                The other signing options (Open Signed, Express Signed and Certified -Signed) are described in detail in The -Complete Guide to Symbian Signed.

                -
                -
                Additional information -on signing -

                The UID value you need to use for your application depends on whether -your application is signed or self-signed. For more information, see UID and How -to use UIDs.

                -
                + + + + + +Application +signing +

                All Symbian applications must be signed before they can be installed. +All applications which use capability-protected +APIs, where the capability cannot be granted by the end user, have to be certified. +Such certification can be obtained through Symbian +Signed.

                +

                Signing is a means of encoding a digital certificate into the application +installation file. The certificate identifies the application’s vendor, and +grants access to capabilities defined during the build process.

                +

                The signing process is described in detail on the Symbian +Signed website.

                +
                Signing options +

                If your application only needs user capabilities (LocalServices, NetworkServices, ReadUserData, WriteUserData, UserEnvironment, andLocation), +you can self-sign the application.

                + +

                When the end users are installing a self-signed application, they are +informed that the application is untrusted and may decide to abort the installation. +In Nokia E-series devices the user must change a setting to allow self-signed +applications to install.

                +                 + +

                Sign the sis installation +file with any private key. You can use the MakeKeys application +to create the needed private key and, for example, SignSIS to +sign the application. Both applications are delivered with the SDK. For more +information, see How +to sign a .Sis file with Self-Sign Certificate in the Forum Nokia +Developer Community Wiki.

                +

                The other signing options (Open Signed, Express Signed and Certified +Signed) are described in detail in The +Complete Guide to Symbian Signed.

                +
                +
                Additional information +on signing + +

                The UID value you need to use for +your application depends on whether your application is signed or self-signed. +For more information, see How +to use UIDs.

                +
                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B94B394F-E243-5AB0-BAF7-AF68982A3EA8_d0e330077_href.png Binary file Symbian3/SDK/Source/GUID-B94B394F-E243-5AB0-BAF7-AF68982A3EA8_d0e330077_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B94B394F-E243-5AB0-BAF7-AF68982A3EA8_d0e336234_href.png Binary file Symbian3/SDK/Source/GUID-B94B394F-E243-5AB0-BAF7-AF68982A3EA8_d0e336234_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B96A7D1B-957C-5050-9D1D-5439A13A5CED_d0e323931_href.png Binary file Symbian3/SDK/Source/GUID-B96A7D1B-957C-5050-9D1D-5439A13A5CED_d0e323931_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B96A7D1B-957C-5050-9D1D-5439A13A5CED_d0e330088_href.png Binary file Symbian3/SDK/Source/GUID-B96A7D1B-957C-5050-9D1D-5439A13A5CED_d0e330088_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B985B750-9B42-55ED-B7E4-41B06B44C365_d0e304465_href.jpg Binary file Symbian3/SDK/Source/GUID-B985B750-9B42-55ED-B7E4-41B06B44C365_d0e304465_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-B985B750-9B42-55ED-B7E4-41B06B44C365_d0e310480_href.jpg Binary file Symbian3/SDK/Source/GUID-B985B750-9B42-55ED-B7E4-41B06B44C365_d0e310480_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BA0D9DA9-3B54-4964-A4D6-9ADA4DEB7231.dita --- a/Symbian3/SDK/Source/GUID-BA0D9DA9-3B54-4964-A4D6-9ADA4DEB7231.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-BA0D9DA9-3B54-4964-A4D6-9ADA4DEB7231.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,90 +1,90 @@ - - - - - -Receiving -Data from SensorsYou can implement a data listener to receive data from the sensors. -Based on the data received, you can perform specific actions on the Symbian -device. For example, if you receive information from the sensor about the -distance between the device and the user then based on this information, you -can disable or enable the loudspeaker mode on the Symbian device. -

                Before listening -for sensor channel data, you must open -the sensor channel.

                 - -Implement the data -listener. -

                Inherit from the MSensrvDataListener interface -and implement the following pure virtual functions: MSensrvDataListener::DataReceived, MSensrvDataListener::DataError and MSensrvDataListener::GetDataListenerInterfaceL

                class DataListener:public MSensrvDataListener - { - public: - void DataReceived(CSensrvChannel& aChannel, TInt aCount, TInt aDataLost ) - { - ... - //Implementation - } - void DataError( CSensrvChannel&, TSensrvErrorSeverity) - { - ... - //Implementation - } - void GetDataListenerInterfaceL( TUid, TAny*&) - { - ... - //Implementation - } - };                 -                 -Start data listening. -

                Pass an instance of data listener implementation using the CSensrvChannel::StartDataListeningL() function.

                //Instance of the data listener implementation -DataListener dataListener; -... -CSensrvChannel* channel; -... -channel->StartDataListeningL(&dataListener, 1, 1, 0); -...

                When new data is available to be read in the sensor channel, -the client is notified by the MSensrvDataListener::DataReceived(CSensrvChannel -&,TInt,TInt) callback function. The channel data is received -into the receiving buffer. The receiving buffer is allocated from the heap -in the client's thread and its size is the channel data item size multiplied -by the maximum number of data items.

                -                 -Read the channel -data from the receiving buffer using the CSensrvChannel::GetData() function. -For more information about handling data notifications, see the following Example. - -After you get the -required sensor data feeds from the sensor channel, you can stop data listening -using the CSensrvChannel::StopDataListening() function. -channel->StopDataListening(); - -                 -

                The following example -shows how to handle the double tapping data notification that is received.

                Check -the channel type of the received data and then receive the data object using -the CSensrvChannel::GetData() function. The aCount parameter -provides the details about the number of data objects in the channels receiving -buffer. This number can be zero if the buffering period is used when data -listening is started. The aDataLost parameter provides -the details about the number of the lost data objects. For example, in heavy -load situations.

                void CTestClass::DataReceived( CSensrvChannel& aChannel, - TInt aCount, - TInt aDataLost ) - { - if ( aChannel.GetChannelInfo().iChannelType == KSensrvChannelTypeIdAccelerometerDoubleTappingData ) - { - TSensrvTappingData tappingData; - TPckg <TSensrvTappingData> tappingPackage( tappingData ); - aChannel.GetData( tappingPackage ); - } - }                 -

                End the session -with the sensor channel using the CSensrvChannel::CloseChannel() function.

                 + + + + + +Receiving +Data from SensorsYou can implement a data listener to receive data from the sensors. +Based on the data received, you can perform specific actions on the Symbian +device. For example, if you receive information from the sensor about the +distance between the device and the user then based on this information, you +can disable or enable the loudspeaker mode on the Symbian device. +

                Before listening +for sensor channel data, you must open +the sensor channel.

                 + +Implement the data +listener. +

                Inherit from the MSensrvDataListener interface +and implement the following pure virtual functions: MSensrvDataListener::DataReceived, MSensrvDataListener::DataError and MSensrvDataListener::GetDataListenerInterfaceL

                class DataListener:public MSensrvDataListener + { + public: + void DataReceived(CSensrvChannel& aChannel, TInt aCount, TInt aDataLost ) + { + ... + //Implementation + } + void DataError( CSensrvChannel&, TSensrvErrorSeverity) + { + ... + //Implementation + } + void GetDataListenerInterfaceL( TUid, TAny*&) + { + ... + //Implementation + } + };                 +                 +Start data listening. +

                Pass an instance of data listener implementation using the CSensrvChannel::StartDataListeningL() function.

                //Instance of the data listener implementation +DataListener dataListener; +... +CSensrvChannel* channel; +... +channel->StartDataListeningL(&dataListener, 1, 1, 0); +...

                When new data is available to be read in the sensor channel, +the client is notified by the MSensrvDataListener::DataReceived(CSensrvChannel +&,TInt,TInt) callback function. The channel data is received +into the receiving buffer. The receiving buffer is allocated from the heap +in the client's thread and its size is the channel data item size multiplied +by the maximum number of data items.

                +                 +Read the channel +data from the receiving buffer using the CSensrvChannel::GetData() function. +For more information about handling data notifications, see the following Example. + +After you get the +required sensor data feeds from the sensor channel, you can stop data listening +using the CSensrvChannel::StopDataListening() function. +channel->StopDataListening(); + +                 +

                The following example +shows how to handle the double tapping data notification that is received.

                Check +the channel type of the received data and then receive the data object using +the CSensrvChannel::GetData() function. The aCount parameter +provides the details about the number of data objects in the channels receiving +buffer. This number can be zero if the buffering period is used when data +listening is started. The aDataLost parameter provides +the details about the number of the lost data objects. For example, in heavy +load situations.

                void CTestClass::DataReceived( CSensrvChannel& aChannel, + TInt aCount, + TInt aDataLost ) + { + if ( aChannel.GetChannelInfo().iChannelType == KSensrvChannelTypeIdAccelerometerDoubleTappingData ) + { + TSensrvTappingData tappingData; + TPckg <TSensrvTappingData> tappingPackage( tappingData ); + aChannel.GetData( tappingPackage ); + } + }                 +

                End the session +with the sensor channel using the CSensrvChannel::CloseChannel() function.

                                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BA1071D5-E358-5B33-9204-CDCD0CECEF0A_d0e299317_href.png Binary file Symbian3/SDK/Source/GUID-BA1071D5-E358-5B33-9204-CDCD0CECEF0A_d0e299317_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BA1071D5-E358-5B33-9204-CDCD0CECEF0A_d0e305344_href.png Binary file Symbian3/SDK/Source/GUID-BA1071D5-E358-5B33-9204-CDCD0CECEF0A_d0e305344_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BA49FDC0-808B-5E05-81AC-98637214F304.dita --- a/Symbian3/SDK/Source/GUID-BA49FDC0-808B-5E05-81AC-98637214F304.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-BA49FDC0-808B-5E05-81AC-98637214F304.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,72 +1,72 @@ - - - - - -LBS -Quick StartLocation Based Services (LBS) provides location information for -installed applications and for remote services via a network. Location information -can be used for location stamping artefacts such as photographs and memos, -finding nearby services and facilities, navigation, and the ability for remote -parties to discover the user's whereabouts. -

                Location-based services (LBS) use coordinates from the World Geodetic System -(WGS 84), which is also used as a reference system by the Global Positioning -System (GPS).

                -

                The coordinates are based on values for latitude, longitude, and altitude -(elevation above sea level).

                -

                The North Pole is 90 degrees North (+90 degrees) and the South Pole is -90 degrees South (-90 degrees). The Equator is defined as 0 degrees; locations -above it have positive latitudes (0 to +90 degrees); those below (0 to -90 -degrees) negative ones.

                -

                There are two definitions of North Pole; Magnetic North Pole and True (Geographical) -North Pole. Any application with a compass must check how the API defines -North Pole.

                -

                The Magnetic North Pole is the point to which compasses point. The True -North Pole defines latitude as +90 degrees.

                -

                Meridians are constant longitudinal (north-south) values. The Prime (Greenwich) -Meridian’s value is 0 degrees. WGS84, which LBS use, defines its zero meridian -some 100 meters east of the Prime one. Locations east of the Prime Meridian -have positive longitudinal values (0 to +180 degrees), those west (0 to -180 -degrees) have negative ones.

                -

                As seen in the figure below, latitude lines are smaller near the poles. -At the equator, one degree of longitude is roughly 111.3 km, whereas at 60 -degrees of latitude one degree of longitude is only 55.8 km, which is more -difficult to see.

                - - - -
                Getting started -with LBS

                This section provides links to the most important documentation.

                For -application developers

                The Location -Acquisition API is the interface that programmers use to create location-aware -applications. The API gives developers the ability to get location fixes and -to obtain information about the positioning technologies available to the -mobile device.

                - -
                Technologies

                The -main technologies enabled on the Symbian platform by the LBS subsystem are -as follows:

                  -

                • Global Positioning System -(GPS)

                  The GPS system provides accurate, worldwide positioning. The -main disadvantage of GPS is the long time required to obtain a position fix -when the GPS hardware is first powered. LBS supports Assisted GPS (A-GPS) -to reduce the time required to get a position fix.

                  • -

                • Network based positioning

                  Network -based positioning is typically less accurate than GPS, but often provides -a faster fix of adequate accuracy for some applications.

                  • -

                • Secure User Plane Location -(SUPL) v1.0

                  SUPL defines an architecture for supporting Location Based -Services using IP bearers to connect handsets and network hosts. The Symbian -LBS subsystem contains a SUPL Protocol Module to support SUPL.

                  • -
                - -

                The above figure illustrates how the location information can be -provided to the device. Access to these location methods is provided through -the positioning modules.

                + + + + + +LBS +Quick StartLocation Based Services (LBS) provides location information for +installed applications and for remote services via a network. Location information +can be used for location stamping artefacts such as photographs and memos, +finding nearby services and facilities, navigation, and the ability for remote +parties to discover the user's whereabouts. +

                Location-based services (LBS) use coordinates from the World Geodetic System +(WGS 84), which is also used as a reference system by the Global Positioning +System (GPS).

                +

                The coordinates are based on values for latitude, longitude, and altitude +(elevation above sea level).

                +

                The North Pole is 90 degrees North (+90 degrees) and the South Pole is +90 degrees South (-90 degrees). The Equator is defined as 0 degrees; locations +above it have positive latitudes (0 to +90 degrees); those below (0 to -90 +degrees) negative ones.

                +

                There are two definitions of North Pole; Magnetic North Pole and True (Geographical) +North Pole. Any application with a compass must check how the API defines +North Pole.

                +

                The Magnetic North Pole is the point to which compasses point. The True +North Pole defines latitude as +90 degrees.

                +

                Meridians are constant longitudinal (north-south) values. The Prime (Greenwich) +Meridian’s value is 0 degrees. WGS84, which LBS use, defines its zero meridian +some 100 meters east of the Prime one. Locations east of the Prime Meridian +have positive longitudinal values (0 to +180 degrees), those west (0 to -180 +degrees) have negative ones.

                +

                As seen in the figure below, latitude lines are smaller near the poles. +At the equator, one degree of longitude is roughly 111.3 km, whereas at 60 +degrees of latitude one degree of longitude is only 55.8 km, which is more +difficult to see.

                + + + +
                Getting started +with LBS

                This section provides links to the most important documentation.

                For +application developers

                The Location +Acquisition API is the interface that programmers use to create location-aware +applications. The API gives developers the ability to get location fixes and +to obtain information about the positioning technologies available to the +mobile device.

                + +
                Technologies

                The +main technologies enabled on the Symbian platform by the LBS subsystem are +as follows:

                  +

                • Global Positioning System +(GPS)

                  The GPS system provides accurate, worldwide positioning. The +main disadvantage of GPS is the long time required to obtain a position fix +when the GPS hardware is first powered. LBS supports Assisted GPS (A-GPS) +to reduce the time required to get a position fix.

                  • +

                • Network based positioning

                  Network +based positioning is typically less accurate than GPS, but often provides +a faster fix of adequate accuracy for some applications.

                  • +

                • Secure User Plane Location +(SUPL) v1.0

                  SUPL defines an architecture for supporting Location Based +Services using IP bearers to connect handsets and network hosts. The Symbian +LBS subsystem contains a SUPL Protocol Module to support SUPL.

                  • +
                + +

                The above figure illustrates how the location information can be +provided to the device. Access to these location methods is provided through +the positioning modules.

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BA7B9BA6-B840-5182-90B0-A4914592A40D.dita --- a/Symbian3/SDK/Source/GUID-BA7B9BA6-B840-5182-90B0-A4914592A40D.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-BA7B9BA6-B840-5182-90B0-A4914592A40D.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,95 +1,95 @@ - - - - - -SendAs -ServerThis section provides detailed description of the SendAs Server -functions and how the SendAs Server processes the client request. -
                SendAs Server process and data flow

                The following -figure details the processes and data flow with SendAs Server.

                - SendAs Server process and data flow - -
                -
                SendAs Server functionality

                The following sections -give detailed information about the SendAs sever functionality:

                Creating -a SendAs message

                Client applications can create a message of a -given type that supports SendAs only in the Drafts folder of the message store. -It uses RSendAsMessage::Create() to create the message. -An MTM can specify its support of SendAs for a message type in the following -two ways:

                  -

                • The message type can -set the MTM_CAPABILITIES::send_capability resource in its -resource file. This allows the Message Server to know whether the message -type supports SendAs without loading its MTMs.

                  • -

                • If the MTM does not -declare whether it supports SendAs in its resource file, the Message Server -loads the MTM and queries if it supports the KUidMtmQueryCanSendMsg capability.

                  • -

                Modifying a SendAs message

                Client applications can -modify a message created by the RSendAsMessage::Create() method. -After sending the request, client applications can no longer modify the message. -They can add the following message parts, if supported by the message type.

                  -

                • Body text

                  • -

                • Attachment

                  • -

                • BIO type

                  • -

                • Recipients—address, -alias and type. For example, To, Cc or Bcc.

                  • -

                • Subject

                  • -

                Sending a SendAs Message

                When a client application -requests to send a message, it must specify whether SendAs must get confirmation -from the user to send the message or not.

                If a client application -that requests a unconfirmed send is not trusted with the capabilities specified -by the Server MTM of the given message type, the SendAs Server automatically -performs a confirmed send.

                For a confirmed send, the SendAs Server -uses the UI MTM for the message type to confirm the send request by querying -the phone user. If the send is confirmed by the phone user, the SendAs Server -moves the message to Outbox and sends the message. If the send is refused, -then the message remains in the Drafts folder and the Send-As Server fails -the send request.

                After the message send is initiated, the Server -MTM for the message type takes responsibility of the message. For successful -and unsuccessful sends, the Server MTM decides to which folder the message -must be moved to. It also governs the rescheduling policy for a failed send -request.

                A client application can obtain progress for both types of -send requests. Any failures associated with the send are reported back to -the client application through this progress information. The progress information -also provides a send state. For example, message waiting to be sent, sending, -message sent, or message send failed.

                Launching an editor for a -message type

                The SendAs Server allows client applications to launch -an editor for a specified message type that supports SendAs. After creating -a message, a client application can request to launch the appropriate editor. -It can launch the editor in two ways: a fire-and-forget launch or a launch -and wait. With the fire-and-forget launch, the client application is not notified -when an editor is closed. The launch and wait notifies the client application -when an editor closes.

                After the editor is launched, the SendAs Server -is no longer responsible for that message, the editor takes the responsibility. -The message editors are applications that are trusted with the required capabilities -to modify and send messages of that type. They communicate directly with the -Message Server using the Message Server APIs.

                Querying the message -type registry

                The SendAs Server provides several APIs to allow -client applications to query the message type registry. The following are -the available queries:

                  -

                • List the registered -message types that support a specified set of message capabilities. For example, -amount of body text allowed, attachments supported and so on.

                  • -

                • Obtain the available -account names for a specified message type

                  • -

                • Get the localised human -readable name for a specified message type that supports SendAs.

                  • -
                Message types that have no accounts or invalid accounts are not -listed. Validation is done by SendAs querying whether the UI MTM supports -validation of the accounts. If the UI MTM does not support validation, all -accounts are assumed to be valid. If the UI MTM supports the verification, -then the list of service IDs is passed to InvokeSyncFunctionL using -the KMtmUiFunctionValidateService command.

                The -SendAs Server allows client applications only to query the message type registry -about message types that support SendAs. Other message types are ignored.

                -                 -SendAs Overview - + + + + + +SendAs +ServerThis section provides detailed description of the SendAs Server +functions and how the SendAs Server processes the client request. +
                SendAs Server process and data flow

                The following +figure details the processes and data flow with SendAs Server.

                + SendAs Server process and data flow + +
                +
                SendAs Server functionality

                The following sections +give detailed information about the SendAs sever functionality:

                Creating +a SendAs message

                Client applications can create a message of a +given type that supports SendAs only in the Drafts folder of the message store. +It uses RSendAsMessage::Create() to create the message. +An MTM can specify its support of SendAs for a message type in the following +two ways:

                  +

                • The message type can +set the MTM_CAPABILITIES::send_capability resource in its +resource file. This allows the Message Server to know whether the message +type supports SendAs without loading its MTMs.

                  • +

                • If the MTM does not +declare whether it supports SendAs in its resource file, the Message Server +loads the MTM and queries if it supports the KUidMtmQueryCanSendMsg capability.

                  • +

                Modifying a SendAs message

                Client applications can +modify a message created by the RSendAsMessage::Create() method. +After sending the request, client applications can no longer modify the message. +They can add the following message parts, if supported by the message type.

                  +

                • Body text

                  • +

                • Attachment

                  • +

                • BIO type

                  • +

                • Recipients—address, +alias and type. For example, To, Cc or Bcc.

                  • +

                • Subject

                  • +

                Sending a SendAs Message

                When a client application +requests to send a message, it must specify whether SendAs must get confirmation +from the user to send the message or not.

                If a client application +that requests a unconfirmed send is not trusted with the capabilities specified +by the Server MTM of the given message type, the SendAs Server automatically +performs a confirmed send.

                For a confirmed send, the SendAs Server +uses the UI MTM for the message type to confirm the send request by querying +the phone user. If the send is confirmed by the phone user, the SendAs Server +moves the message to Outbox and sends the message. If the send is refused, +then the message remains in the Drafts folder and the Send-As Server fails +the send request.

                After the message send is initiated, the Server +MTM for the message type takes responsibility of the message. For successful +and unsuccessful sends, the Server MTM decides to which folder the message +must be moved to. It also governs the rescheduling policy for a failed send +request.

                A client application can obtain progress for both types of +send requests. Any failures associated with the send are reported back to +the client application through this progress information. The progress information +also provides a send state. For example, message waiting to be sent, sending, +message sent, or message send failed.

                Launching an editor for a +message type

                The SendAs Server allows client applications to launch +an editor for a specified message type that supports SendAs. After creating +a message, a client application can request to launch the appropriate editor. +It can launch the editor in two ways: a fire-and-forget launch or a launch +and wait. With the fire-and-forget launch, the client application is not notified +when an editor is closed. The launch and wait notifies the client application +when an editor closes.

                After the editor is launched, the SendAs Server +is no longer responsible for that message, the editor takes the responsibility. +The message editors are applications that are trusted with the required capabilities +to modify and send messages of that type. They communicate directly with the +Message Server using the Message Server APIs.

                Querying the message +type registry

                The SendAs Server provides several APIs to allow +client applications to query the message type registry. The following are +the available queries:

                  +

                • List the registered +message types that support a specified set of message capabilities. For example, +amount of body text allowed, attachments supported and so on.

                  • +

                • Obtain the available +account names for a specified message type

                  • +

                • Get the localised human +readable name for a specified message type that supports SendAs.

                  • +
                Message types that have no accounts or invalid accounts are not +listed. Validation is done by SendAs querying whether the UI MTM supports +validation of the accounts. If the UI MTM does not support validation, all +accounts are assumed to be valid. If the UI MTM supports the verification, +then the list of service IDs is passed to InvokeSyncFunctionL using +the KMtmUiFunctionValidateService command.

                The +SendAs Server allows client applications only to query the message type registry +about message types that support SendAs. Other message types are ignored.

                +                 +SendAs Overview +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BA8806CC-BE7C-4927-ACF6-DA0CB6E96AAA.dita --- a/Symbian3/SDK/Source/GUID-BA8806CC-BE7C-4927-ACF6-DA0CB6E96AAA.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-BA8806CC-BE7C-4927-ACF6-DA0CB6E96AAA.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,21 +1,21 @@ - - - - - -Indicators -

                Indicators are graphical or textual objects on the screen that provide -information about the status of the system. They cannot be used for input, -and there is no focus on an indicator: in non-touch UI the user cannot point -at an indicator to perform actions.

                -

                The various indicator types in use are described in the following sub-sections.

                -
                Using -indicators in C++ applications

                The API to use for indicators is -the Indicators API.

                + + + + + +Indicators +

                Indicators are graphical or textual objects on the screen that provide +information about the status of the system. They cannot be used for input, +and there is no focus on an indicator: in non-touch UI the user cannot point +at an indicator to perform actions.

                +
                Using +indicators in applications

                The API to use for indicators is the +Indicators API.

                The various indicator types in use are described in +the following sub-sections:

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BA96913A-38D2-4E57-BA95-52F1642A6D06.dita --- a/Symbian3/SDK/Source/GUID-BA96913A-38D2-4E57-BA95-52F1642A6D06.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-BA96913A-38D2-4E57-BA95-52F1642A6D06.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,19 +1,19 @@ - - - - - -Operator -indicator -

                In the Idle state, the title pane contains the operator indicator. It is -either a text or a graphical image.

                -
                Using operator -indicator in C++ applications

                The operator indicator is not accessible -to applications.

                + + + + + +Operator +indicator +

                In the home screen, the title pane contains the operator indicator. It +is either a text or a graphical image.

                +
                Using +operator indicator in applications

                The operator indicator is not +accessible to applications.

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BAABB057-5C48-4991-A283-DAC5D54562C1_d0e40442_href.png Binary file Symbian3/SDK/Source/GUID-BAABB057-5C48-4991-A283-DAC5D54562C1_d0e40442_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BAABB057-5C48-4991-A283-DAC5D54562C1_d0e46002_href.png Binary file Symbian3/SDK/Source/GUID-BAABB057-5C48-4991-A283-DAC5D54562C1_d0e46002_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BADAAC2D-8614-5036-95BC-3889457F7ED0.dita --- a/Symbian3/SDK/Source/GUID-BADAAC2D-8614-5036-95BC-3889457F7ED0.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-BADAAC2D-8614-5036-95BC-3889457F7ED0.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,14 +1,14 @@ - - - - - -Positioning ModulesThis document describes the classes that give information about Positioning Modules.
                Purpose

                This document is an overview of the Positioning Module information that is available to client applications using the Location Acquisition API. A Positioning Module is a software component that allows the Location Server to communicate with the mobile device hardware that obtains position data.

                See How to Use Positioning Module Information for an example of how to get Positioning Module information using the Location Acquisition API.

                Types of Positioning Modules

                In mobile devices there may be several Positioning Modules:

                • A Positioning Module that use GPS and/or A-GPS.

                • A Positioning Module that uses the network to obtain cell-based positions.

                • Positioning Modules that use other technologies, such as WLAN positioning.

                Positioning Module information classes

                The classes TPositionModuleInfo and TPositionQuality hold information about the capabilities of Positioning Modules and the quality of position information that they can provide. Figure 1 illustrates these classes.

                - Figure 1. TPositionModuleInfo and TPositionQuality classes -
                TPositionModuleInfo

                TPositionModuleInfo describes a Positioning Module. This description includes:

                • The technology type used by the Positioning Module.

                  A Positioning Module can use positioning technology which is terminal-based (such as GPS), network based, or a combination of the two (such as A-GPS). The method TPositionModuleInfo::TechnologyType() returns this information.

                • The capabilities of the Positioning Module.

                  Different Positioning Modules have different capabilities which depend on the Positioning Module technology type. Most Positioning Modules have the capability to provide latitude and longitude information. Some Positioning Modules can also supply altitude information, course information and satellite data. This information is returned by the method TPositionModuleInfo::Capabilities() as a bit mask of type TPositionModuleInfo::TCapabilities.

                • A unique identifier returned by TPositionModule::ModuleId().

                  This identifier is used to select a specific Positioning Module when a client application wishes to use a specific positioning technology to obtain a location fix.

                A TPositionModuleInfo object obtains a reference to its TPositionQuality object by calling TPositionModuleInfo::GetPositionQuality().

                TPositionQuality

                TPositionQuality describes the quality of information that a Positioning Module can provide. The quality describes the accuracy of information, the time to obtain a location fix, the cost of obtaining the fix and power consumption:

                • TPositionQuality::HorizontalAccuracy() and TPositionQuality::VerticalAccuracy() return location accuracy information.

                • TPositionQuality::TimeToFirstFix() and TPositionQuality::TimeToNextFix() return a typical time to get a location fix as a TTimeIntervalMicroSeconds value.

                • TPositionQuality::CostIndicator() returns a cost for using the Positioning Module to get location information. The value returned is an estimate, not a precise cost value and is of type TPositionQuality::TCostIndicator. The cost estimate helps the location server to make a choice of the Positioning Module to use to get a location fix when a specific Positioning Module is not chosen by a client application.

                • TPositionQuality::PowerConsumption() returns an estimate of power consumption for using a Positioning Module. This estimate is of type TPositionQuality::TPowerConsumption and as with cost, it helps the Location Server make a choice of Positioning Module to use to get a location fix.

                See also

                How to Use Positioning Module Information

                \ No newline at end of file + + + + + +Positioning ModulesThis document describes the classes that give information about Positioning Modules.
                Purpose

                This document is an overview of the Positioning Module information that is available to client applications using the Location Acquisition API. A Positioning Module is a software component that allows the Location Server to communicate with the mobile device hardware that obtains position data.

                See How to Use Positioning Module Information for an example of how to get Positioning Module information using the Location Acquisition API.

                Types of Positioning Modules

                In mobile devices there may be several Positioning Modules:

                • A Positioning Module that use GPS and/or A-GPS.

                • A Positioning Module that uses the network to obtain cell-based positions.

                • Positioning Modules that use other technologies, such as WLAN positioning.

                Positioning Module information classes

                The classes TPositionModuleInfo and TPositionQuality hold information about the capabilities of Positioning Modules and the quality of position information that they can provide. Figure 1 illustrates these classes.

                + Figure 1. TPositionModuleInfo and TPositionQuality classes +
                TPositionModuleInfo

                TPositionModuleInfo describes a Positioning Module. This description includes:

                • The technology type used by the Positioning Module.

                  A Positioning Module can use positioning technology which is terminal-based (such as GPS), network based, or a combination of the two (such as A-GPS). The method TPositionModuleInfo::TechnologyType() returns this information.

                • The capabilities of the Positioning Module.

                  Different Positioning Modules have different capabilities which depend on the Positioning Module technology type. Most Positioning Modules have the capability to provide latitude and longitude information. Some Positioning Modules can also supply altitude information, course information and satellite data. This information is returned by the method TPositionModuleInfo::Capabilities() as a bit mask of type TPositionModuleInfo::TCapabilities.

                • A unique identifier returned by TPositionModule::ModuleId().

                  This identifier is used to select a specific Positioning Module when a client application wishes to use a specific positioning technology to obtain a location fix.

                A TPositionModuleInfo object obtains a reference to its TPositionQuality object by calling TPositionModuleInfo::GetPositionQuality().

                TPositionQuality

                TPositionQuality describes the quality of information that a Positioning Module can provide. The quality describes the accuracy of information, the time to obtain a location fix, the cost of obtaining the fix and power consumption:

                • TPositionQuality::HorizontalAccuracy() and TPositionQuality::VerticalAccuracy() return location accuracy information.

                • TPositionQuality::TimeToFirstFix() and TPositionQuality::TimeToNextFix() return a typical time to get a location fix as a TTimeIntervalMicroSeconds value.

                • TPositionQuality::CostIndicator() returns a cost for using the Positioning Module to get location information. The value returned is an estimate, not a precise cost value and is of type TPositionQuality::TCostIndicator. The cost estimate helps the location server to make a choice of the Positioning Module to use to get a location fix when a specific Positioning Module is not chosen by a client application.

                • TPositionQuality::PowerConsumption() returns an estimate of power consumption for using a Positioning Module. This estimate is of type TPositionQuality::TPowerConsumption and as with cost, it helps the Location Server make a choice of Positioning Module to use to get a location fix.

                See also

                How to Use Positioning Module Information

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BB35DBCC-FE56-547F-BADA-9EF854691ADC.dita --- a/Symbian3/SDK/Source/GUID-BB35DBCC-FE56-547F-BADA-9EF854691ADC.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-BB35DBCC-FE56-547F-BADA-9EF854691ADC.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,31 +1,27 @@ - - - - - -S60 -Platform: POP/IMAP Example -
                Description This -C++ application shows how to retrieve e-mail from a remote mailbox to an S60 -device using IMAP and POP protocols. The usual e-mail features such as sending, -editing, and deleting e-mail messages are demonstrated. The updated example -has been modified to support S60 5th Edition and touch UI. Important classes: -CMsvSession, CClientMtmRegistry, CMtmUiRegistry, CMsvOperation, CMsvEntrySelection, -CMsvEntry, CBaseMtm. For more details, click on this link : POP/IMAP Example
                -
                Download

                Click -on the following link to download the example: InternetEmai.zip

                Click: browse to view the example code.

                -
                Build

                The Symbian build process describes -how to build an application.

                The InternetEmail example -builds an executable called InternetEmail.exe in the -standard location (\epoc32\release\winscw\ <build_variant> for -CodeWarrior). After launching the executable, depending on the emulator you -are using, you may need to task away from the app launcher/shell screen to -view the console.

                -
                See also

                POP3 MTM Overview

                SMTP MTM Overview

                + + + + + +POP/IMAP +Example +
                Description This +C++ application shows how to retrieve e-mail from a remote mailbox to a device +using IMAP and POP protocols. The usual e-mail features such as sending, editing, +and deleting e-mail messages are demonstrated.
                +
                Download

                Click +on the following link to download the example: InternetEmai.zip

                Click: browse to view the example code.

                +
                Build

                The Symbian build process describes +how to build an application.

                The InternetEmail example builds an executable +called InternetEmail.exe in the standard location (\epoc32\release\winscw\ <build_variant> for +CodeWarrior). After launching the executable, depending on the emulator you +are using, you may need to task away from the app launcher/shell screen to +view the console.

                +
                See also

                POP3 MTM Overview

                SMTP MTM Overview

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BB38AFE5-56FE-552D-8715-438936865B69_d0e322770_href.jpg Binary file Symbian3/SDK/Source/GUID-BB38AFE5-56FE-552D-8715-438936865B69_d0e322770_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BB38AFE5-56FE-552D-8715-438936865B69_d0e328927_href.jpg Binary file Symbian3/SDK/Source/GUID-BB38AFE5-56FE-552D-8715-438936865B69_d0e328927_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BB8B3A11-0BBC-4759-A7F4-A28C9E70573F.dita --- a/Symbian3/SDK/Source/GUID-BB8B3A11-0BBC-4759-A7F4-A28C9E70573F.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-BB8B3A11-0BBC-4759-A7F4-A28C9E70573F.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,233 +1,235 @@ - - - - - -Touch -support for UI components -

                This table is filtered for SDK, -PDK and internal publications. To view the conditions, see document map on -the left hand pane. They have attribute marks

                - - - - -

                Component

                 -

                Example image

                 -

                Touch support

                 -                 - - - - -

                Stylus pop-up -menu

                 - - - -

                Touch down and hold activates the item.

                 -                 - -

                Toolbar

                 - - - -

                A short tap activates the item (emulates a selection key press).

                 -                 - -

                Choice list

                 - - - -

                A short tap activates the item.

                 -                 - -

                Forms

                 - - - -

                In the view state (a normal two-row list item), a short tap activates -it (emulates a selection key press).

                In the edit state, a short tap -launches a touch input window. Within a item, the functionality is as for -a text field.

                 -                 - -

                Form items

                  -

                • Text field

                  • -

                • Pop-up field

                  • -

                • Slider

                  • -
                 - - - -

                Same as for equivalent setting items

                 -                 - -

                Grouped soft -notification, List -query, Grid -query

                 - - - -

                A short tap activates the item (emulates a selection key press).

                 -                 - -

                Left/Right arrows in the Navi -pane

                 - - - -

                A short tap activates the item.

                 -                 - -

                Markable -list

                Selection -list

                 - - - -

                A short tap activates the item (emulates a selection key press).

                -                 - -

                Menu list (for example,Options -menu and submenus)

                 - - - -

                A short tap activates the item (emulates a selection key press).

                 -                 - -

                Multi-selection -list

                 - - - -

                A short tap marks/unmarks the item.

                -                 - -

                Preview pop-up

                 - - - - -                 - -

                Scroll pane

                For more -information, see Scroll -pane.

                 - - - - -                 - -

                Setting items

                 - - -                 - -

                Pop-up setting

                 - - - -

                A short tap activates the item (emulates a selection key press).

                 -                 - -

                Multi-selection list setting

                 - - - -

                A short tap activates the item.

                 -                 - -

                Text setting

                 - - - -

                The cursor can be moved with the text field. Dragging selects a -block of text.

                 -                 - -

                Slider setting

                 - - - -

                The slider thumb is draggable.

                 -                 - -

                Setting list

                 - - - -

                A short tap activates the item(emulates a selection key press).

                 -                 - -

                Softkeys (left and right) in the Control -pane

                There is no middle softkey label in Touch UI                 - - - - -                 - -

                Tabs in the Navi -pane

                 - - - -

                A short tap activates the item

                 -                 - -

                Status pane

                -
                  -

                • Title -pane

                  • -

                • Navi -pane

                  • -

                • Battery -pane

                  • -

                • Universal -indicator pane

                  • -

                • Signal -pane

                  • -
                 - - - -

                A short tap activates the functionality if the sub-pane has one -(the signal and battery panes are inactive).

                 -                 - -

                Slider -pop-up

                  -

                • Volume Controller

                  • -
                 - - - -

                Draggable slider thumb. Icons can be set as tappable.

                Volume -slider thumb is draggable, and muting can be done directly by tapping the -speaker icon.

                 -                 - -

                Universal -indicator pop-up

                 - - - -

                Tapping the link performs the application-specific functionality. -Most commonly, opens the application. Tapping the description text without -the link functionality is inactive.

                 -                 - - -
                -

                + + + + + +Touch support for UI components +

                This table is filtered for +SDK, PDK and internal publications. To view the conditions, see document +map on the left hand pane. They have attribute marks

                + + + + +

                Component

                 +

                Example image

                 +

                Touch support

                 +                 + + + + + + + +

                Stylus +pop-up menu

                 + + + +

                Long tap activates the item.

                 +                 + +

                Toolbar

                 + + + +

                A short tap activates the item (emulates a selection key +press).

                 +                 + +

                Choice +list

                 + + + +

                A short tap activates the item.

                 +                 + +

                Forms

                 + + + +

                In the view state (a normal two-row list item), a short +tap activates it (emulates a selection key press).

                In the edit +state, a short tap launches a touch input window. Within a item, the +functionality is as for a text field.

                 +                 + +

                Form +items

                  +

                • Text field

                  • +

                • Pop-up field

                  • +

                • Slider

                  • +
                 + + + + +

                Same as for equivalent setting items

                 +                 + +

                Grouped +soft notification, List query, Grid query

                 + + + +

                A short tap activates the item (emulates a selection key +press).

                 +                 + +

                Left/Right arrows in the Navi pane

                 + + + + +

                A short tap activates the item and navigates between the +views.

                 +                 + +

                Markable +list

                Selection list

                 + + + +

                A short tap activates the item (emulates a selection key +press).

                +                 + +

                Menu list (for example,Options menu and submenus)

                 + + + +

                A short tap activates the item (emulates a selection key +press).

                 +                 + +

                Multi-selection +list

                 + + + +

                A short tap marks/unmarks the item.

                +                 + +

                Preview +pop-up

                 + + + + +                 + +

                Scrollbar.

                 + + + + +                 + +

                Setting items

                 + + +                 + +

                Pop-up setting

                 + + + +

                A short tap activates the item (emulates a selection key +press).

                 +                 + +

                Multi-selection list setting

                 + + + +

                A short tap activates the item.

                 +                 + +

                Text +setting

                 + + + +

                The cursor can be moved with the text field. Dragging selects +a block of text.

                 +                 + +

                Slider +setting

                 + + + +

                The slider thumb is draggable.

                 +                 + +

                Setting +list

                 + + + +

                A short tap activates the item(emulates a selection key +press).

                 +                 + +

                Softkeys (left and right) in the Control pane

                There is no middle softkey label in Touch UI                 + + + + +                 + +

                Status +pane

                  +

                • Title +pane

                  • +

                • Navi +pane

                  • +

                • Battery +pane

                  • +

                • Universal +indicator pane

                  • +

                • Signal +pane

                  • +

                • Clock +Pane

                  • +
                 + + + +

                A short tap activates the functionality if the sub-pane +has one (the signal and battery panes are inactive).

                 +                 + +

                Slider pop-up

                  +

                • Volume +Controller

                  • +
                 + + + +

                Draggable slider thumb. Icons can be set as tappable.

                Volume slider thumb is draggable, and muting can be done directly +by tapping the speaker icon.

                 +                 + +

                Universal +indicator pop-up

                 + + + +

                Tapping the link performs the application-specific functionality. +Most commonly, opens the application. Tapping the description text +without the link functionality is inactive.

                 +                 + + +
                +

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BBBA5C6C-4E8B-513A-8FA1-C7A04C54C140.dita --- a/Symbian3/SDK/Source/GUID-BBBA5C6C-4E8B-513A-8FA1-C7A04C54C140.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-BBBA5C6C-4E8B-513A-8FA1-C7A04C54C140.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,47 +1,47 @@ - - - - - -Clipboard -

                The Symbian platform supports the concept of cut, copy and -paste by providing a clipboard. An application can copy data to the clipboard -and the same data can then be pasted in by the same application or by any -other application.

                -

                The clipboard is a resource which is shared by all applications. An application -must, therefore, hold the clipboard for the minimum time possible.

                -
                Cut, copy and paste

                The clipboard is encapsulated -by the CClipboard class. Applications use this class when -they place data on, or retrieve data from the clipboard.

                It is implemented -as a direct file store. When the data is placed on the clipboard, it is stored -in the clipboard's store as a stream or a network of streams. Every data type -placed on the clipboard is identified by a UID. This allows a pasting application -to identify the required data.

                It uses a stream dictionary to maintain -UID and stream ID pairs, and always makes the stream dictionary the root stream -of the store.

                The essential features of the CClipboard class -are shown in the following diagram:

                - Clipboard class structure - -

                Any type of data can be placed on the clipboard. When retrieving -data, applications check the UID in the stream dictionary to determine whether -there is any data relevant to them. The following diagram illustrates a typical -situation:

                - Clipboard store - -
                -                 -Using Clipboard - -Direct file -stores -Dictionary -stores -UID manipulation - + + + + + +Clipboard +

                The Symbian platform supports the concept of cut, copy and +paste by providing a clipboard. An application can copy data to the clipboard +and the same data can then be pasted in by the same application or by any +other application.

                +

                The clipboard is a resource which is shared by all applications. An application +must, therefore, hold the clipboard for the minimum time possible.

                +
                Cut, copy and paste

                The clipboard is encapsulated +by the CClipboard class. Applications use this class when +they place data on, or retrieve data from the clipboard.

                It is implemented +as a direct file store. When the data is placed on the clipboard, it is stored +in the clipboard's store as a stream or a network of streams. Every data type +placed on the clipboard is identified by a UID. This allows a pasting application +to identify the required data.

                It uses a stream dictionary to maintain +UID and stream ID pairs, and always makes the stream dictionary the root stream +of the store.

                The essential features of the CClipboard class +are shown in the following diagram:

                + Clipboard class structure + +

                Any type of data can be placed on the clipboard. When retrieving +data, applications check the UID in the stream dictionary to determine whether +there is any data relevant to them. The following diagram illustrates a typical +situation:

                + Clipboard store + +
                +                 +Using Clipboard + +Direct file +stores +Dictionary +stores +UID manipulation +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BBC374AD-88E6-5C58-88BB-B939C2948DDA-GENID-1-8-1-3-1-1-7-1-8-1.dita --- a/Symbian3/SDK/Source/GUID-BBC374AD-88E6-5C58-88BB-B939C2948DDA-GENID-1-8-1-3-1-1-7-1-8-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,50 +0,0 @@ - - - - - -Application -user interface (AppUi) -

                Cone provides the CCoeAppUi class as a generic base -for application user interface development. Uikon provides a specialization, CEikAppUi, -from which concrete application UIs can be derived. UI variant libraries typically -derive their own AppUi base class from CEikAppUi to standardize -common UI paradigms. CCoeAppUi is, therefore, normally -a 'long way' from the surface of the finished application and knows little -of the concrete controls or functionality that it contains.

                -

                CCoeAppUi provides the following key functionality:

                -
                  -

                • An event-handling framework

                  CCoeAppUi is -the at the top of the run-time control hierarchy. It is the point at which -key-press events are received from the Window Server. Many of the event-handling -functions are virtual and implemented in the derived AppUi classes.

                  • -
                - - - -
                  -

                • View Management

                  The -View Manager (CCoeViewManager) is encapsulated by CCoeAppUi which -provides a view management API.

                  Views are concrete classes that implement -the MCoeView interface. Typically they are top-level window-owning -controls.

                  The significance of views is that they are known of outside -the application to which they belong. This allows one application to switch, -or link, directly to a view in another. If the target application is running -it will be brought to the foreground with the linked view activated. If it -isn't running it will be started up first.

                  All of the API required -for implementing, registering, activating, deactivating, linking and observing -is provided by MCoeView and CCoeAppUi.

                  To -participate fully in the view architecture an application must register at -least one view. An application with no views may still be linked to using -the view architecture. It registers itself with a TVwsViewId containing -its application UID. Obviously it will not receive activation and deactivation -events but will trigger view switch events in other applications' views.

                  An -application may opt out of the view architecture (see TApaCommand::EApaCommandRunWithoutViews and TApaCommand::EApaCommandBackgroundAndWithoutViews)

                  • -
                -                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BBC374AD-88E6-5C58-88BB-B939C2948DDA-GENID-1-8-1-6-1-1-4-1-6-1-8-1.dita --- a/Symbian3/SDK/Source/GUID-BBC374AD-88E6-5C58-88BB-B939C2948DDA-GENID-1-8-1-6-1-1-4-1-6-1-8-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,50 +0,0 @@ - - - - - -Application -user interface (AppUi) -

                Cone provides the CCoeAppUi class as a generic base -for application user interface development. Uikon provides a specialization, CEikAppUi, -from which concrete application UIs can be derived. UI variant libraries typically -derive their own AppUi base class from CEikAppUi to standardize -common UI paradigms. CCoeAppUi is, therefore, normally -a 'long way' from the surface of the finished application and knows little -of the concrete controls or functionality that it contains.

                -

                CCoeAppUi provides the following key functionality:

                -
                  -

                • An event-handling framework

                  CCoeAppUi is -the at the top of the run-time control hierarchy. It is the point at which -key-press events are received from the Window Server. Many of the event-handling -functions are virtual and implemented in the derived AppUi classes.

                  • -
                - - - -
                  -

                • View Management

                  The -View Manager (CCoeViewManager) is encapsulated by CCoeAppUi which -provides a view management API.

                  Views are concrete classes that implement -the MCoeView interface. Typically they are top-level window-owning -controls.

                  The significance of views is that they are known of outside -the application to which they belong. This allows one application to switch, -or link, directly to a view in another. If the target application is running -it will be brought to the foreground with the linked view activated. If it -isn't running it will be started up first.

                  All of the API required -for implementing, registering, activating, deactivating, linking and observing -is provided by MCoeView and CCoeAppUi.

                  To -participate fully in the view architecture an application must register at -least one view. An application with no views may still be linked to using -the view architecture. It registers itself with a TVwsViewId containing -its application UID. Obviously it will not receive activation and deactivation -events but will trigger view switch events in other applications' views.

                  An -application may opt out of the view architecture (see TApaCommand::EApaCommandRunWithoutViews and TApaCommand::EApaCommandBackgroundAndWithoutViews)

                  • -
                -                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BBC374AD-88E6-5C58-88BB-B939C2948DDA.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-BBC374AD-88E6-5C58-88BB-B939C2948DDA.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,50 @@ + + + + + +Application +user interface (AppUi) +

                Cone provides the CCoeAppUi class as a generic base +for application user interface development. Uikon provides a specialization, CEikAppUi, +from which concrete application UIs can be derived. UI variant libraries typically +derive their own AppUi base class from CEikAppUi to standardize +common UI paradigms. CCoeAppUi is, therefore, normally +a 'long way' from the surface of the finished application and knows little +of the concrete controls or functionality that it contains.

                +

                CCoeAppUi provides the following key functionality:

                +
                  +

                • An event-handling framework

                  CCoeAppUi is +the at the top of the run-time control hierarchy. It is the point at which +key-press events are received from the Window Server. Many of the event-handling +functions are virtual and implemented in the derived AppUi classes.

                  • +
                + + + +
                  +

                • View Management

                  The +View Manager (CCoeViewManager) is encapsulated by CCoeAppUi which +provides a view management API.

                  Views are concrete classes that implement +the MCoeView interface. Typically they are top-level window-owning +controls.

                  The significance of views is that they are known of outside +the application to which they belong. This allows one application to switch, +or link, directly to a view in another. If the target application is running +it will be brought to the foreground with the linked view activated. If it +isn't running it will be started up first.

                  All of the API required +for implementing, registering, activating, deactivating, linking and observing +is provided by MCoeView and CCoeAppUi.

                  To +participate fully in the view architecture an application must register at +least one view. An application with no views may still be linked to using +the view architecture. It registers itself with a TVwsViewId containing +its application UID. Obviously it will not receive activation and deactivation +events but will trigger view switch events in other applications' views.

                  An +application may opt out of the view architecture (see TApaCommand::EApaCommandRunWithoutViews and TApaCommand::EApaCommandBackgroundAndWithoutViews)

                  • +
                +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BBDC3880-DFC3-42C0-913D-E90AB318E015_d0e38273_href.png Binary file Symbian3/SDK/Source/GUID-BBDC3880-DFC3-42C0-913D-E90AB318E015_d0e38273_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BBDC3880-DFC3-42C0-913D-E90AB318E015_d0e43840_href.png Binary file Symbian3/SDK/Source/GUID-BBDC3880-DFC3-42C0-913D-E90AB318E015_d0e43840_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BC498630-E802-5A36-8DB1-D67F739CAD64_d0e317327_href.png Binary file Symbian3/SDK/Source/GUID-BC498630-E802-5A36-8DB1-D67F739CAD64_d0e317327_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BC498630-E802-5A36-8DB1-D67F739CAD64_d0e323484_href.png Binary file Symbian3/SDK/Source/GUID-BC498630-E802-5A36-8DB1-D67F739CAD64_d0e323484_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BC67F13E-4B5A-5078-AE9B-826304BC14FD.dita --- a/Symbian3/SDK/Source/GUID-BC67F13E-4B5A-5078-AE9B-826304BC14FD.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-BC67F13E-4B5A-5078-AE9B-826304BC14FD.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,36 +1,33 @@ - - - - - -Versit: -Versit Example -
                Description

                This example code first creates a vCard -parser using the CParserVCard class. Then it creates a -NOTE property with a string literal as its value, using CParserGroupedProperty and CParserPropertyValue classes. -The property is associated with the vCard parser using the CParserVCard::AddPropertyL() method. -Finally, the vCard is externalized or exported to a file by calling the CParserVCard::ExternalizeL() method.

                The -example also shows how to internalize or import a vCard from a file. A session -with the file server is established using the RFs class -to read the vCard from the file using a file read stream (RFileReadStream class).

                Note -that the procedure to create a vCal parser using the CParserVCal class -is similar to that of creating a vCard parser.

                -
                Download

                Click on the following link to download -the example: VersitExample.zip

                Click: browse to view the example code.

                -
                Usage

                This is a console application and it builds -an executable called VersitExample.exe in the standard -location (\epoc32\release\winscw\ <build_variant> for -CodeWarrior). After launching the executable, depending on the emulator you -are using, you may need to navigate from the app launcher/shell screen to -view the console.

                -
                Class Summary

                CParserVCard

                CParserGroupedProperty -

                CParserPropertyValue

                -
                See also

                Using -Versit

                + + + + + +Versit: Versit Example +
                Description

                This example code first creates a vCard parser using the CParserVCard class. Then it creates a NOTE property with +a string literal as its value, using CParserGroupedProperty and CParserPropertyValue classes. The property +is associated with the vCard parser using the CParserVCard::AddPropertyL() method. Finally, the vCard is externalized or exported to a file +by calling the CParserVCard::ExternalizeL() method.

                The example also shows how to internalize or import a vCard from +a file. A session with the file server is established using the RFs class to read the vCard from the file using a file +read stream (RFileReadStream class).

                Note +that the procedure to create a vCal parser using the CParserVCal class is similar to that of creating a vCard parser.

                +
                Download

                Click on the following link to download the example: VersitExample.zip

                Click: browse to view the example code.

                +
                Usage

                This is a console application and it builds an executable called VersitExample.exe in the standard location (\epoc32\release\winscw\ <build_variant> for +CodeWarrior). After launching the executable, depending on the emulator +you are using, you may need to navigate from the app launcher/shell +screen to view the console.

                +
                Class +Summary
                  +

                • CParserVCard

                  • +

                • CParserGroupedProperty

                  • +

                • CParserPropertyValue

                  • +
                +
                See +also

                Using Versit

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BC7AFCC5-0052-479E-99AE-F3F982ED1F84-master.png Binary file Symbian3/SDK/Source/GUID-BC7AFCC5-0052-479E-99AE-F3F982ED1F84-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BC7AFCC5-0052-479E-99AE-F3F982ED1F84_d0e67137_href.png Binary file Symbian3/SDK/Source/GUID-BC7AFCC5-0052-479E-99AE-F3F982ED1F84_d0e67137_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BC7AFCC5-0052-479E-99AE-F3F982ED1F84_d0e72805_href.png Binary file Symbian3/SDK/Source/GUID-BC7AFCC5-0052-479E-99AE-F3F982ED1F84_d0e72805_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BCDCB147-865F-58B0-816F-5FBF0E7CCDD7.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-BCDCB147-865F-58B0-816F-5FBF0E7CCDD7.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,307 @@ + + + + + +CryptoSPI +Overview +
                Introduction

                CryptoSPI +(cryptospi.dll) is a library introduced in Symbian^3 +that manages the selection and loading of cryptographic algorithms. Cryptographic +algorithms enable data to be encrypted and decrypted. The services provided +by CryptoSPI are used by the following components: Certman (Certificate Management), +Software Installation, Secure Communication Protocols (for example, SSL, TLS, +IPSEC), and WTLS.

                CryptoSPI also provides a framework that allows +licensees and partners to implement additional cryptographic algorithms as +plug-ins to CryptoSPI.

                The benefits of CryptoSPI are:

                  +

                • Plug-ins can use cryptographic +acceleration hardware, which can improve performance and reduce power consumption. +Client applications do not need to know whether an operation is implemented +in software or hardware.

                  • +

                • Its architecture allows +new algorithms or modes of operation to be added by licensees without impacting +the existing APIs or client code.

                  • +

                • The legacy cryptography +libraries (cryptography.dll, hash.dll and random.dll) +have been preserved. Legacy client code can continue to use them without needing +modification or re-compilation. This is achieved via an internal BC layer +that routes legacy function calls to use the new SPI.

                  • +

                • CryptoSPI adds support +for non-extractable keys, which may be used to protect sensitive or high-value +content.

                  • +

                • CryptoSPI is more secure +against malicious code than the legacy API, because it does not store any +data, it has no server component and plugins must be located in ROM, so cannot +be replaced or eclipsed.

                  • +
                +
                Architectural +relationships

                CryptoSPI was introduced in Symbian^3. Before Symbian^3, +cryptographic algorithms, hash algorithms and random number generation were +implemented by Symbian in cryptography.dll, hash.dll and random.dll. +As shown in the CryptoSPI dependencies diagram, Symbian's legacy implementations +and APIs were retained in Symbian^3, so that existing code does not need to +be modified or recompiled.

                softwarecrypto.dll is +a plug-in module implemented by Symbian that provides software-based implementations +of all the cryptographic algorithms that were previously implemented by the +legacy components (cryptography.dll, hash.dll and random.dll). +The legacy APIs have been re-implemented internally to use the new framework +via shim classes. hardwarecrypto.dll is an arbitrary +name used in the diagram to represent a licensee-provided plug-in module. +The plug-ins and cryptospi.dll have a dependency on cryptography.dll because +it implements big integers.

                + CryptoSPI dependencies + +
                +
                API summary

                The CryptoSpi namespace +is defined for all CryptoSPI classes to differentiate them from the legacy +APIs with the same names.

                CryptoSPI scope

                CryptoSPI +provides equivalent implementations of all algorithms supported by the legacy +APIs, including hashing and random number generation. The following algorithms +are implemented by Symbian in softwarecrypto.dll

                This +section includes summary details of the following:

                  +

                • cryptographic algorithms

                  • +

                • hash algorithms.

                  • +

                • random number generator

                  • +

                Cryptographic algorithms

                  +

                • Symmetric ciphers - The following symmetric algorithms are supported:

                  + + + +Symmetric algorithm +Type +Specified in: + + + + +

                  AES (Advanced Encryption Standard)

                  +

                  Block cipher

                  +

                  FIPS-197

                  +                   + +

                  DES (Data Encryption Standard)

                  +

                  Block cipher

                  +

                  FIPS 46-3

                  +                   + +

                  3DES (Triple Data Encryption Standard)

                  +

                  Block cipher

                  +

                  FIPS 46-3

                  +                   + +

                  RC2-128

                  +

                  Block cipher

                  +

                  RFC +2268

                  +                   + +

                  ARC4 ('alleged' RC4)

                  +

                  Stream cipher

                  +

                  The internet and a posting to sci.crypt in 1994.

                  +                   + + +

                  Note: Algorithm identifiers for MISTY1, MISTY2 and Kasumi +(A5/3) block ciphers are in the cryptography library. These identifiers allow +clients of the cryptography library to request implementations of these algorithms +from the symmetric cipher factory. Symbian does not provide implementations +of these algorithms, so the default behavior is for the factory function to +return an error indicating that there is no implementation available.

                  Note: +Until Symbian^3, the classes implementing the symmetric and asymmetric ciphers +were provided in cryptography.dll.

                  • +

                • Asymmetric ciphers - The following asymmetric algorithms are +supported:

                  + + + +Asymmetric algorithm +What is's used for +Specified in: + + + + +

                  RSA PKCS#1 v1.5

                  +

                  Signing data

                  Key pair generation

                  +

                  PKCS#1 v1.5

                  +                   + +

                  DSA

                  +

                  Signing data

                  Key pair generation

                  +

                  FIPS 186-2 CR1

                  +                   + +

                  Diffie Hellman

                  +

                  Key agreement

                  Key pair generation

                  +

                  PKCS#3

                  +                   + + +
                  • +

                • Hash algorithms - The following hash algorithms are supported:

                  + + + +

                  Hash algorithms

                   +

                  Specified in

                   +                   + + + +

                  MD2

                   +

                  RFC +1319

                   +                   + +

                  MD4

                   +

                  RFC +1320

                   +                   + +

                  MD5

                   +

                  RFC +1321

                   +                   + +

                  SHA1

                   +

                  FIPS +180-1 and RFC +3174

                   +                   + +

                  SHA-224

                   +

                  FIPS 180-2

                   +                   + +

                  SHA-256

                   +

                  FIPS 180-2

                   +                   + +

                  SHA-384

                   +

                  FIPS 180-2

                   +                   + +

                  SHA-512

                   +

                  FIPS 180-2

                   +                   + + +

                  • +

                • Hashes in HMAC mode

                    +

                  • MD2

                    • +

                  • MD4

                    • +

                  • MD5

                    • +

                  • SHA1

                    • +

                  • SHA-224

                    • +

                  • SHA-256

                    • +

                  • SHA-384

                    • +

                  • SHA-512

                    • +

                  HMAC mode is specified in RFC 2104

                  • +

                Instantiating algorithms

                Clients request cryptographic +algorithms using static factory functions.

                For instance, to create +a hash algorithm, use the generic hash factory function CryptoSpi::CHashFactory::CreateHashL(), +specifying the UID of the required algorithm. UIDs are defined in cryptospidef.h, +for instance KMd2Uid, KMd5Uid, KSha1Uid. +CryptoSPI uses a plug-in +selector to search for a plug-in that implements the requested algorithm. +When a plug-in is found, CryptoSPI loads it if required, and calls the function +defined at the relevant ordinal in the plug-in DLL, in this case ECreateHashOrdinal, +to instantiate a hash object, which is returned to the caller.

                Operation +and padding modes

                CryptoSPI has been designed to be simpler and +more compact than the API that it replaces. Rather than defining separate +classes to do encryption and decryption, for instance, C3DESEncryptor and C3DESDecryptor, +CryptoSPI implements a single, generic symmetric cipher class, CryptoSpi::CSymmetricCipher. +The characteristics of the algorithm, for instance whether it does encryption +or decryption, the operation mode for block ciphers (KOperationModeECB, KOperationModeCBC etc.), +and the padding mode (KPaddingModeSSLv3, KPaddingModePKCS7 etc.) +are all passed by the client to the factory function as UIDs — see CryptoSpi::CSymmetricCipherFactory::CreateSymmetricCipherL().

                The client can switch the algorithm between modes by setting a +flag, see for example CSymmetricCipherBase::SetCryptoModeL(), CSymmetricCipherBase::SetPaddingModeL() and CSymmetricCipherBase::SetOperationModeL().

                  +

                • Operation modes

                  Symbian platform provides default software +implementations of the following operation modes:

                    +

                  • ECB

                    • +

                  • CBC

                    • +

                  • CTR (counter)

                    • +

                  They are specified in NIST Special Publication 800-38A.

                  • +

                • Padding modes

                  Symbian platform supports the following +padding modes:

                    +

                  • SSLv3-style padding

                    • +

                  • PKCS#7-style padding

                    • +

                  • PKCS#1 v1.5 Encryption-style +padding

                    • +

                  • PKCS#1 v1.5 Signature-style +padding

                    • +
                  • +

                Asynchronous operation and cancellation

                The legacy +cryptography library only supports synchronous operations. By enabling cryptographic +acceleration hardware, CryptoSPI supports more advanced use cases. In order +for users to be able to cancel potentially long-running operations such as +the decryption of high-quality audio/visual content, CryptoSPI supports both +synchronous and asynchronous interfaces for each cryptographic operation, +the latter providing a Cancel() function.

                Note: +Symbian's software plug-in module (softwarecrypto.dll) +only implements the synchronous interfaces.

                Plug-ins

                A +CryptoSPI plugin DLL can implement zero, one or more algorithms, and may provide +alternative implementations of the same algorithm. The set of plugin DLLs +is defined in a configuration file in ROM (Z:\resource\cryptospi\plug-ins.txt). +CryptoSPI will only load plugins stored in ROM (Z:\sys\bin\), +so plug-in modules cannot be added by third parties after-market.

                cryptospi.dll and +all plug-ins have ALL capabilities, which ensures that they +can be loaded by client applications with any capabilities.

                The abstract +base class for all cryptographic plug-ins is CryptoSpi::MPlugin().

                See +also: How to create +a CryptoSPI plugin.

                UIDs and plug-in characteristics

                Plug-ins +are identified by three UIDs:

                  +

                • the interface supported, +for instance hash (KHashInterfaceUid),

                  • +

                • the algorithm implemented, +for instance MD2 (KMd2Uid), and

                  • +

                • the unique implementation +ID.

                  • +

                These three UIDs are part of the plug-in's characteristics. +Plug-in characteristics are defined at compile time as constant data. They +describe the type and capabilities of a plug-in implementation. Some characteristics +are relevant to all plug-in types, for instance the name and UID of the algorithm +implemented, the name of the plug-in vendor and whether the plug-in uses hardware +acceleration. These are termed common characteristics and are defined +in CryptoSpi::TCommonCharacteristics(). Other characteristics +are specific to a particular interface type, for instance the modes of operation +for a symmetric cipher. These are defined in an interface-specific characteristics +class, for instance CryptoSpi::TSymmetricCipherCharacteristics(), +that have a TCommonCharacteristics data member. Plug-in characteristics +can be retrieved using CCryptoBase::GetCharacteristicsL().

                Plug-ins +may optionally also have 'extended' characteristics. These are set at runtime, +for instance the number of concurrent operations supported by the plug-in, +and can be retrieved using CryptoSpi::MPlugin::GetExtendedCharacteristicsL().

                Selection rules

                Symbian +has implemented a plug-in selector, CryptoSpi::CLegacySelector(), +which is used both by the legacy API and by default by CryptoSPI to select +algorithms implemented in softwarecrypto.dll. In other +words, by default, CryptoSPI and the legacy API use the same algorithm implementations. +The legacy selector works by loading DLLs one by one according to their order +in the ROM configuration file until a suitable implementation is found.

                As +an alternative to using the default selector, clients can specify a rule-based +selector (CryptoSpi::CRuleSelector()). This causes CryptoSPI +to re-generate the list of plug-ins, according to a set of selection rules. +The API is described in How +to use a rule-based selector.

                In general, it is recommended +that applications should not specify selection rules unless it is critical +to the operation of the application. The preferred approach is to use the +plugin chosen by the default selector, which can be assumed to provide good +performance for the most common use cases.

                +                 +Hash (message +digest) algorithms +Generating +random bytes +Basic encryption +and decryption using a symmetric cipher +Signing and +verification +How to use +a rule-based selector +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BD1DBD2B-A4C1-4769-B454-2A9B4D056446_d0e3536_href.png Binary file Symbian3/SDK/Source/GUID-BD1DBD2B-A4C1-4769-B454-2A9B4D056446_d0e3536_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BD1DBD2B-A4C1-4769-B454-2A9B4D056446_d0e4811_href.png Binary file Symbian3/SDK/Source/GUID-BD1DBD2B-A4C1-4769-B454-2A9B4D056446_d0e4811_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BD988DF9-45CA-53F3-816F-6DB81185CE40-GENID-1-8-1-3-1-1-7-1-7-1-7-1.dita --- a/Symbian3/SDK/Source/GUID-BD988DF9-45CA-53F3-816F-6DB81185CE40-GENID-1-8-1-3-1-1-7-1-7-1-7-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,13 +0,0 @@ - - - - - -Control observers

                Each control may have an observer, typically another control, to which it can send events. An observer must:

                • implement the mixin class MCoeControlObserver and

                • be set as the observer for the control (or controls) it is to observe using CCoeControl::SetObserver().

                A control may have one observer only, but an observer may observe more than one control.

                A control sends an event to its observer using CCoeControl::ReportEventL(). The observer receives the event using MCoeControlObserver::HandleControlEventL(). Event types, which are not the same as window server events, are defined by the MCoeControlObserver enum TCoeEvent.

                A typical use of an observer is a compound - control being the observer for its own components. The components send events to their compound control when they receive user input and the compound control manages the interaction between them. For example a control receiving a TPointerEvent::EButton1Down event sends an MCoeControlObserver::EEventRequestFocus event to its observer. This allows the observer to move focus between its components and to update their appearance.

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BD988DF9-45CA-53F3-816F-6DB81185CE40-GENID-1-8-1-6-1-1-4-1-6-1-7-1-7-1.dita --- a/Symbian3/SDK/Source/GUID-BD988DF9-45CA-53F3-816F-6DB81185CE40-GENID-1-8-1-6-1-1-4-1-6-1-7-1-7-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,13 +0,0 @@ - - - - - -Control observers

                Each control may have an observer, typically another control, to which it can send events. An observer must:

                • implement the mixin class MCoeControlObserver and

                • be set as the observer for the control (or controls) it is to observe using CCoeControl::SetObserver().

                A control may have one observer only, but an observer may observe more than one control.

                A control sends an event to its observer using CCoeControl::ReportEventL(). The observer receives the event using MCoeControlObserver::HandleControlEventL(). Event types, which are not the same as window server events, are defined by the MCoeControlObserver enum TCoeEvent.

                A typical use of an observer is a compound - control being the observer for its own components. The components send events to their compound control when they receive user input and the compound control manages the interaction between them. For example a control receiving a TPointerEvent::EButton1Down event sends an MCoeControlObserver::EEventRequestFocus event to its observer. This allows the observer to move focus between its components and to update their appearance.

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BD988DF9-45CA-53F3-816F-6DB81185CE40.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-BD988DF9-45CA-53F3-816F-6DB81185CE40.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,13 @@ + + + + + +Control observers

                Each control may have an observer, typically another control, to which it can send events. An observer must:

                • implement the mixin class MCoeControlObserver and

                • be set as the observer for the control (or controls) it is to observe using CCoeControl::SetObserver().

                A control may have one observer only, but an observer may observe more than one control.

                A control sends an event to its observer using CCoeControl::ReportEventL(). The observer receives the event using MCoeControlObserver::HandleControlEventL(). Event types, which are not the same as window server events, are defined by the MCoeControlObserver enum TCoeEvent.

                A typical use of an observer is a compound + control being the observer for its own components. The components send events to their compound control when they receive user input and the compound control manages the interaction between them. For example a control receiving a TPointerEvent::EButton1Down event sends an MCoeControlObserver::EEventRequestFocus event to its observer. This allows the observer to move focus between its components and to update their appearance.

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BDAC640A-FBFE-4DC2-BB29-1A780BCA8ADA-master.png Binary file Symbian3/SDK/Source/GUID-BDAC640A-FBFE-4DC2-BB29-1A780BCA8ADA-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BDAC640A-FBFE-4DC2-BB29-1A780BCA8ADA_d0e52653_href.png Binary file Symbian3/SDK/Source/GUID-BDAC640A-FBFE-4DC2-BB29-1A780BCA8ADA_d0e52653_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BDAC640A-FBFE-4DC2-BB29-1A780BCA8ADA_d0e58734_href.png Binary file Symbian3/SDK/Source/GUID-BDAC640A-FBFE-4DC2-BB29-1A780BCA8ADA_d0e58734_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BDDDF68F-F7C3-43AF-8B6C-C77C701FD2A9.dita --- a/Symbian3/SDK/Source/GUID-BDDDF68F-F7C3-43AF-8B6C-C77C701FD2A9.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-BDDDF68F-F7C3-43AF-8B6C-C77C701FD2A9.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,72 +1,72 @@ - - - - - -Framework -requirements for GUI applications -

                Applications developed for the Symbian platform can use a number of -different architecture solutions to meet their requirements. One example of -a common approach includes the Model - View - Controller (MVC) pattern used -in GUI-based applications. In this approach, the application is split into -three separate logical parts. Each part contains a different aspect of the -entire application, and has a specific role.

                -Logical dependencies in the MVC pattern -

                In this approach, the model:

                -
                  -

                • contains and manipulates the data in the application

                  -
                  • -

                • is owned by the controller

                  • -

                • is typically implemented in its own class or classes

                  -
                  • -
                -

                the view :

                -
                  -

                • displays the application state known by the model

                  -
                  • -

                • receives user input

                  • -

                • notifies the controller of relevant events

                  • -

                • is implemented either with a CCoeControl derived -class or a CAknView derived class.

                  For more -information on these options, see Traditional -Symbian UI application architecture and View -architecture.

                  • -
                -

                the controller :

                -
                  -

                • handles application-wide events

                  • -

                • commands the model, typically based on user input

                  -
                  • -

                • selects the view to be displayed

                  • -

                • is implemented either with a CAknAppUi-derived -class or a CAknViewAppUi derived class.

                  For -more information on these options, see Traditional -Symbian UI application architecture and View -architecture.

                  • -

                • requires the implementation of CAknApplication and CAknDocument derived -classes.

                  • -
                -

                The pattern is implemented with the following classes.

                -Relationship between the classes that make up a typical Symbian application -

                The CAknApplication-derived class:

                -
                  -

                • provides the application object expected by the application -framework when the application is launched.

                  • -

                • defines the application properties.

                  • -

                • creates the CAknDocument derived class -if it does not exist yet.

                  • -

                • if an instance of the application is already running, switches -to that instance and exits.

                  • -
                -

                The CAknDocument-derived class:

                -
                  -

                • creates the controller class

                  • -

                • is the base class for application documents

                  • -
                + + + + + +Framework +requirements for GUI applications +

                Applications developed for the Symbian platform can use a number of +different architecture solutions to meet their requirements. One example of +a common approach includes the Model - View - Controller (MVC) pattern used +in GUI-based applications. In this approach, the application is split into +three separate logical parts. Each part contains a different aspect of the +entire application, and has a specific role.

                +Logical dependencies in the MVC pattern +

                In this approach, the model:

                +
                  +

                • contains and manipulates the data in the application

                  +
                  • +

                • is owned by the controller

                  • +

                • is typically implemented in its own class or classes

                  +
                  • +
                +

                the view :

                +
                  +

                • displays the application state known by the model

                  +
                  • +

                • receives user input

                  • +

                • notifies the controller of relevant events

                  • +

                • is implemented either with a CCoeControl derived +class or a CAknView derived class.

                  For more +information on these options, see Traditional +Symbian UI application architecture and View +architecture.

                  • +
                +

                the controller :

                +
                  +

                • handles application-wide events

                  • +

                • commands the model, typically based on user input

                  +
                  • +

                • selects the view to be displayed

                  • +

                • is implemented either with a CAknAppUi-derived +class or a CAknViewAppUi derived class.

                  For +more information on these options, see Traditional +Symbian UI application architecture and View +architecture.

                  • +

                • requires the implementation of CAknApplication and CAknDocument derived +classes.

                  • +
                +

                The pattern is implemented with the following classes.

                +Relationship between the classes that make up a typical Symbian application +

                The CAknApplication-derived class:

                +
                  +

                • provides the application object expected by the application +framework when the application is launched.

                  • +

                • defines the application properties.

                  • +

                • creates the CAknDocument derived class +if it does not exist yet.

                  • +

                • if an instance of the application is already running, switches +to that instance and exits.

                  • +
                +

                The CAknDocument-derived class:

                +
                  +

                • creates the controller class

                  • +

                • is the base class for application documents

                  • +
                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BE11D652-3B39-51D2-ACE9-571E8EB71E94_d0e321954_href.png Binary file Symbian3/SDK/Source/GUID-BE11D652-3B39-51D2-ACE9-571E8EB71E94_d0e321954_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BE11D652-3B39-51D2-ACE9-571E8EB71E94_d0e328111_href.png Binary file Symbian3/SDK/Source/GUID-BE11D652-3B39-51D2-ACE9-571E8EB71E94_d0e328111_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BE2D9AAB-203B-471A-984D-91E917611641.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-BE2D9AAB-203B-471A-984D-91E917611641.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,83 @@ + + + + + +Application +Level RoamingApplication-level roaming (ALR) enables your application to roam +to use the best available data connection while operational. +
                Implementation +Considerations

                There is no SDK method for WLAN scanning. Your +application should use Connection Monitor Server API to request the list of +available access points or network names (in the case of a WLAN these are +SSIDs). Connection Monitor Server API also provides notifications about changes +in the access point availability list.

                Handovers between GPRS and WCDMA +radio networks take a long time (from 15 seconds to 2 minutes) and sometimes +fail completely. You should use long application level timers (if any) and +maintain a responsive UI. Note that handovers between GPRS and WCDMA cannot +be controlled by the symbian platform (except with fixed settings). The control +logic is in the cellular modem.

                In ALR, the transfer from one connection +to another always introduces an IP address change and a break in data connection +(even with make-before-break when the break is really short). This is because +the sockets need to be closed and re-opened. This may be problematic for the +applications that maintain a stateful connection with a server in the network. +The workaround for a break is to open a new RConnection handle when receiving PreferredCarrierAvailable() and +establishing the server connection using that (if the application protocol +allows such operation). When that is done and new sockets are created for +the new RConnection, the original RConnection can be closed. There is no workaround +for the IP address change.

                +
                Process Flow +Application-level roaming + +
                +
                Additional +information

                The following APIs are used to implement application-level +roaming:

                  +

                1. Sockets Server Client +API (ESOCK) is the API for all IP-based socket communication. It remains unchanged, +but applications need to be ready to close and open sockets at certain times +to roam for a better connection.

                  2. +

                2. Connection Management +API (RConnection) is a collection of Symbian's connection management-related +functionalities provided by ESOCK. It contains several extensions and one +of them is the mobility extension. The term "mobility API" actually refers +to the mobility extensions that are part of Connection Manager API and defined +in header cs_mobility_apiext.h. With the so-called mobility +API the client application can register for mobility events, receive information +about preferred connections, indicate whether to switch to a new connection +or ignore it. In short, it enables ALR for the applications.

                  3. +

                The mobility extension functionality of the Connection +Manager API is provided by classes MMobilityProtocolResp and CActiveCommsMobilityApiExt.

                Methods +that must be implemented by client (class MMobilityProtocolResp):

                  +

                1. virtual void PreferredCarrierAvailable(TAccessPointInfo +aOldAP, TAccessPointInfo aNewAP, TBool aIsUpgrade, TBool aIsSeamless ); +This method is called by the middleware to notify a client about a new preferred +connection.

                  2. +

                2. virtual void NewCarrierActive(TAccessPointInfo +aNewAP, TBool aIsSeamless ); This method is called by the middleware to +notify a client that a preferred connection has been activated.

                  3. +

                3. virtual void Error(TInt +aError); This method is called by middleware to notify that there are +no suitable connections available.

                  4. +

                Methods provided by ESock (class CActiveCommsMobilityApiExt):

                  +

                1. void MigrateToPreferredCarrier(); Client +can indicate that it wants to start using a new preferred connection as a +response to PreferredCarrierAvailable().

                  2. +

                2. void IgnorePreferredCarrier(); Client +can indicate that it doesn’t want to use a new preferred connection as a response +to PreferredCarrierAvailable().

                  3. +

                3. void NewCarrierAccepted(); Client +indicates that a new connection is working for it.

                  4. +

                4. void NewCarrierRejected(); Client +indicates that a new connection is not working and it wants to use another +connection. In this case it receives PreferredCarrierAvailable() again +with probably the original connection as a preferred one. The non-working +access point is blacklisted for that client and not suggested again.

                  5. +

                +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BE3F31A9-959C-5854-8515-052774D8358E_d0e308465_href.png Binary file Symbian3/SDK/Source/GUID-BE3F31A9-959C-5854-8515-052774D8358E_d0e308465_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BE3F31A9-959C-5854-8515-052774D8358E_d0e314859_href.png Binary file Symbian3/SDK/Source/GUID-BE3F31A9-959C-5854-8515-052774D8358E_d0e314859_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BE66CF87-E750-40BE-A5EB-18A43E927257-master.png Binary file Symbian3/SDK/Source/GUID-BE66CF87-E750-40BE-A5EB-18A43E927257-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BE66CF87-E750-40BE-A5EB-18A43E927257_d0e63571_href.png Binary file Symbian3/SDK/Source/GUID-BE66CF87-E750-40BE-A5EB-18A43E927257_d0e63571_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BE871265-147B-45F3-8772-A4E091223EDB.dita --- a/Symbian3/SDK/Source/GUID-BE871265-147B-45F3-8772-A4E091223EDB.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-BE871265-147B-45F3-8772-A4E091223EDB.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,112 +1,112 @@ - - - - - -Constructing -views in traditional architecture -

                The call on the first phase constructor method of the view occurs in UI controller. The -view serves as the top-level window under the UI controller.

                -

                The methods you need to implement for your CCoeControl-derived -view are as follows:

                -
                  -

                • C++ default constructor, which cannot contain code that leaves. -A common implementation is:

                  - - -CMyAppView::CMyAppView() - { - // No implementation required - } -

                  Comment to reviewers: We will -link these Cleanup stack and new (ELeave) methods to the Symbian Developer -Library API Reference.

                  -                   -
                  • -

                • two-phase constructor, a common implementation is:

                  - -CMyAppView* CMyAppView::NewL( const TRect& aRect ) - { - CMyAppView* self = CMyAppView::NewLC( aRect ); - CleanupStack::Pop( self ); - return self; - } - -CMyAppView* CMyAppView::NewLC( const TRect& aRect ) - { - CMyAppView* self = new ( ELeave ) CMyAppView; - CleanupStack::PushL( self ); - self->ConstructL( aRect ); - return self; - } - -

                  The declarations for CMyAppView::NewL() and CMyAppView::NewLC in -the class header file needs to be public to support the construction method -required. CMyAppView is the default constructor for the CMyAppView class -and it is private.

                  -

                  In this approach, CMyAppView::NewL() is called -from the UI controller. It creates a view object by calling CMyAppView::NewLC(). CMyAppView::NewLC() calls -new (ELeave) on the C++ default constructor CMyAppView to -create the object (and leave if it cannot), pushes a pointer to the clean-up stack in case the second phase construction method -leaves, and then calls the second phase construction method of the object. -When it returns to CMyAppView::NewL(), the pointer pushed -to the cleanup stack is removed.

                  -                   -
                  • -

                • Symbian 2nd phase constructor with code that might leave. -A common implementation is:

                  - -void CMyAppView::ConstructL( const TRect& aRect ) - { - // Create a window for this application view - CreateWindowL(); - - //add construction for other controls if required - - // Set the windows size - SetRect( aRect ); - - // Activate the window, which makes it ready to be drawn - ActivateL(); - } -

                  CMyAppView::ConstructL() is a private class providing -the second phase construction that accepts the rectangle the view is drawn -to.

                  -

                  CCoeControl::CreateWindowL() creates a window for -the control. Note that this window is a child of the UI controller. This method -makes the control a window-owning -control. While the use of window-owning controls is generally discouraged -to prevent the taxing of run-time resources, this is the top-level window -for the UI controller.

                  -

                  This is a simple control that does not contain other controls; other -controls could be added to the control between CCoeControl::CreateWindowL() and CCoeControl::SetRect(aRect). -For more information, see Compound -controls in traditional architecture.

                  -

                  CCoeControl::SetRect(aRect) sets the window size -according to the requirements of the mobile device. The top-level control -rectangle is set to the area that the framework provides for the application. -Calling CCoeControl::SetRect(aRect) calls the CCoeControl::SizeChanged() method, -where the control should set the position and size for any child controls -and thus adjust the control layout to the UI.

                  -

                  CCoeControl::ActivateL() sets the control as ready -to be drawn.

                  -                   -
                  • -
                -

                If required for your application, you may need to implement other methods -for your control. For top-level windows, you would need to implement CCoeControl::SizeChanged() -to respond to changes to the size and position of the contents of this control. -This is called by the platform when a change occurs. A typical implementation -for a compound control is:

                -void CMyAppView::SizeChanged() - { - // Control resize code - iControl->SetExtent( const TPoint &aPosition, const TSize &aSize); - } + + + + + +Constructing +views in traditional architecture +

                The call on the first phase constructor method of the view occurs in UI controller. The +view serves as the top-level window under the UI controller.

                +

                The methods you need to implement for your CCoeControl-derived +view are as follows:

                +
                  +

                • C++ default constructor, which cannot contain code that leaves. +A common implementation is:

                  + + +CMyAppView::CMyAppView() + { + // No implementation required + } +

                  Comment to reviewers: We will +link these Cleanup stack and new (ELeave) methods to the Symbian Developer +Library API Reference.

                  +                   +
                  • +

                • two-phase constructor, a common implementation is:

                  + +static CMyAppView* CMyAppView::NewL( const TRect& aRect ) + { + CMyAppView* self = CMyAppView::NewLC( aRect ); + CleanupStack::Pop( self ); + return self; + } + +static CMyAppView* CMyAppView::NewLC( const TRect& aRect ) + { + CMyAppView* self = new ( ELeave ) CMyAppView; + CleanupStack::PushL( self ); + self->ConstructL( aRect ); + return self; + } + +

                  The declarations for CMyAppView::NewL() and CMyAppView::NewLC in +the class header file needs to be public to support the construction method +required. CMyAppView is the default constructor for the CMyAppView class +and it is private.

                  +

                  In this approach, CMyAppView::NewL() is called +from the UI controller. It creates a view object by calling CMyAppView::NewLC(). CMyAppView::NewLC() calls +new (ELeave) on the C++ default constructor CMyAppView to +create the object (and leave if it cannot), pushes a pointer to the clean-up stack in case the second phase construction method +leaves, and then calls the second phase construction method of the object. +When it returns to CMyAppView::NewL(), the pointer pushed +to the cleanup stack is removed.

                  +                   +
                  • +

                • Symbian 2nd phase constructor with code that might leave. +A common implementation is:

                  + +void CMyAppView::ConstructL( const TRect& aRect ) + { + // Create a window for this application view + CreateWindowL(); + + //add construction for other controls if required + + // Set the windows size + SetRect( aRect ); + + // Activate the window, which makes it ready to be drawn + ActivateL(); + } +

                  CMyAppView::ConstructL() is a private class providing +the second phase construction that accepts the rectangle the view is drawn +to.

                  +

                  CCoeControl::CreateWindowL() creates a window for +the control. Note that this window is a child of the UI controller. This method +makes the control a window-owning +control. While the use of window-owning controls is generally discouraged +to prevent the taxing of run-time resources, this is the top-level window +for the UI controller.

                  +

                  This is a simple control that does not contain other controls; other +controls could be added to the control between CCoeControl::CreateWindowL() and CCoeControl::SetRect(aRect). +For more information, see Compound +controls in traditional architecture.

                  +

                  CCoeControl::SetRect(aRect) sets the window size +according to the requirements of the mobile device. The top-level control +rectangle is set to the area that the framework provides for the application. +Calling CCoeControl::SetRect(aRect) calls the CCoeControl::SizeChanged() method, +where the control should set the position and size for any child controls +and thus adjust the control layout to the UI.

                  +

                  CCoeControl::ActivateL() sets the control as ready +to be drawn.

                  +                   +
                  • +
                +

                If required for your application, you may need to implement other methods +for your control. For top-level windows, you would need to implement CCoeControl::SizeChanged() +to respond to changes to the size and position of the contents of this control. +This is called by the platform when a change occurs. A typical implementation +for a compound control is:

                +void CMyAppView::SizeChanged() + { + // Control resize code + iControl->SetExtent( const TPoint &aPosition, const TSize &aSize); + }                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BEA8B4D3-992B-591E-8E2A-BCAC847E0B6E_d0e322969_href.jpg Binary file Symbian3/SDK/Source/GUID-BEA8B4D3-992B-591E-8E2A-BCAC847E0B6E_d0e322969_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BEA8B4D3-992B-591E-8E2A-BCAC847E0B6E_d0e329126_href.jpg Binary file Symbian3/SDK/Source/GUID-BEA8B4D3-992B-591E-8E2A-BCAC847E0B6E_d0e329126_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BEDF6765-4BF4-532F-A2C7-F052FE8A9CA2_d0e233010_href.png Binary file Symbian3/SDK/Source/GUID-BEDF6765-4BF4-532F-A2C7-F052FE8A9CA2_d0e233010_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BEDF6765-4BF4-532F-A2C7-F052FE8A9CA2_d0e236747_href.png Binary file Symbian3/SDK/Source/GUID-BEDF6765-4BF4-532F-A2C7-F052FE8A9CA2_d0e236747_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BF040EF4-E34C-40A3-AD15-F49426F56AA2.dita --- a/Symbian3/SDK/Source/GUID-BF040EF4-E34C-40A3-AD15-F49426F56AA2.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,56 +0,0 @@ - - - - - -Antiword -Example -

                Antiword is an Open C console-based application. ANTIWORD can be used -for the following purposes:

                -

                converts a MS-word document (i.e. .doc) file in to a plain text(i.e. .txt) -file.

                -

                converts a MS-word document (i.e. .doc) file in to a Adobe acrobat(i.e. -.pdf) file.

                -

                converts MS-word document (i.e. .doc) file in to a post-script (i.e. .ps) -file.

                -

                converts a MS-word document (i.e. .doc) file in to a xml (i.e. .xml) file.

                -
                Download

                Click -on the following link to download the example: antiword.zip

                Click: browse to view the example code.

                -
                Design and -Implementation

                The following sections provide information about -the implementation of the example.

                Capabilities

                The following -program capability is defined in the antiword.mmp file: CAPABILITY -None

                Implementation details of EXE

                This application -uses main() as the entry point for the application. This is simple console -based application. Antiword is C application that is ported on the Open C -which demonstrates the changes made in the application in order to work on -Open C. All changes made to the open source code is under SYMBIAN macro. - Some of the environment variables are set explicitly using the Open C's setenv() -API. The fillArg() subroutine converts the given input command string to -Linux's argv() format. Output of the conversion will be written to destination -file i.e last commandline argument where as the original application expects -the users to use the redirection operators for dumping the output to a target -file. Some status messages will be prompted to the user in case of wrong input -commands. The commandline help will be printed on the stdout using the original -help text. The input data files (font and mapping files for conversion) are -added in the /data/resources directory and this directory will be exported -to the private folder of the Antiword application's, so that /private/A0001323/resources/ -will be used as the ANTIWORD_HOME directory in the application. The application -can be launched by clicking its icon in the emulator as well as in the device.

                Limitations

                Antiword -is not able to convert the embedded image or any other embedded multimedia -objects from the document file. It converts only the text. Some of the related -files, which supports the embedded images are commented in the mmp file as -these files depend on the open source's sprite library.

                -
                Building and -Using

                The Symbian -build process describes how to build this example application.

                To -build the Antiword application, go to the Antiword\group directory and build -the application. The definition for the whole application can be found in -the bld.inf file in the group subdirectory of the applications main directory.
                -                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BF155E49-35AF-5BC1-80C5-8D6C68C464F8_d0e214905_href.png Binary file Symbian3/SDK/Source/GUID-BF155E49-35AF-5BC1-80C5-8D6C68C464F8_d0e214905_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BF155E49-35AF-5BC1-80C5-8D6C68C464F8_d0e218642_href.png Binary file Symbian3/SDK/Source/GUID-BF155E49-35AF-5BC1-80C5-8D6C68C464F8_d0e218642_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BF4E220C-2388-517B-87D8-78AB1EA6382E.dita --- a/Symbian3/SDK/Source/GUID-BF4E220C-2388-517B-87D8-78AB1EA6382E.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-BF4E220C-2388-517B-87D8-78AB1EA6382E.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,52 +1,52 @@ - - - - - -ArchitectureThis topic describes the Network Interface Manager (NifMan) architecture. -
                NifMan Architecture

                The following diagram outlines -the main components in the NifMan architecture:

                - -

                As shown, the NIFMAN configuration daemon architecture consists -of two parts:

                  -

                • An ECom plug-in for -NIFMAN

                  The ECom plug-in manages the interface between NIFMAN and the -configuration daemon. The ECom plug-in is referred to as the configuration -daemon manager.

                  • -

                • The configuration daemon

                  The -configuration daemon is a Symbian platform server that runs in -its own process. It does not run in the NIFMAN thread. Licensees can write -new configuration daemons.

                  • -

                The framework for configuration daemons support the following:

                  -

                • Deregistration events

                  Deregistration -events notify the daemon when the interface is shutting down. For Mobile IP, -the phone can deregister its foreign agent address with the home agent.

                  Alternatively, -the daemon can instruct NIFMAN to maintain the logical state of a user session -and release the resources associated with the wireless connection. This is -called fast dormant mode.

                  • -

                • Progress notifications

                  Mobile -IP reports progress notifications when it registers and deregisters with the -foreign agent. The notifications are passed by NIFMAN to the sockets client -using RConnection::ProgressNotification(), for the current -interface.

                  • -

                The configuration daemon manager handles one outstanding daemon request -at a time. If a request is already being processed, NIFMAN queues a deregistration -request which is processed when the previous request is complete. Other types -of request are not queued. This permits the handling of the following scenarios:

                  -

                • Deregistration notification -during registration.

                  • -

                • Deregistration notification -during an Ioctl request.

                  • -

                • Deregistration notification -when the daemon is being requested to enter fast dormant mode.

                  • -
                -                 -What is Network -Interface Management (NifMan)? + + + + + +ArchitectureThis topic describes the Network Interface Manager (NifMan) architecture. +
                NifMan Architecture

                The following diagram outlines +the main components in the NifMan architecture:

                + +

                As shown, the NIFMAN configuration daemon architecture consists +of two parts:

                  +

                • An ECom plug-in for +NIFMAN

                  The ECom plug-in manages the interface between NIFMAN and the +configuration daemon. The ECom plug-in is referred to as the configuration +daemon manager.

                  • +

                • The configuration daemon

                  The +configuration daemon is a Symbian platform server that runs in +its own process. It does not run in the NIFMAN thread. Licensees can write +new configuration daemons.

                  • +

                The framework for configuration daemons support the following:

                  +

                • Deregistration events

                  Deregistration +events notify the daemon when the interface is shutting down. For Mobile IP, +the phone can deregister its foreign agent address with the home agent.

                  Alternatively, +the daemon can instruct NIFMAN to maintain the logical state of a user session +and release the resources associated with the wireless connection. This is +called fast dormant mode.

                  • +

                • Progress notifications

                  Mobile +IP reports progress notifications when it registers and deregisters with the +foreign agent. The notifications are passed by NIFMAN to the sockets client +using RConnection::ProgressNotification(), for the current +interface.

                  • +

                The configuration daemon manager handles one outstanding daemon request +at a time. If a request is already being processed, NIFMAN queues a deregistration +request which is processed when the previous request is complete. Other types +of request are not queued. This permits the handling of the following scenarios:

                  +

                • Deregistration notification +during registration.

                  • +

                • Deregistration notification +during an Ioctl request.

                  • +

                • Deregistration notification +when the daemon is being requested to enter fast dormant mode.

                  • +
                +                 +What is Network +Interface Management (NifMan)?                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BF626AFA-F8E5-4049-BC3E-E947AD2D39A1_d0e2580_href.png Binary file Symbian3/SDK/Source/GUID-BF626AFA-F8E5-4049-BC3E-E947AD2D39A1_d0e2580_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BF626AFA-F8E5-4049-BC3E-E947AD2D39A1_d0e2684_href.png Binary file Symbian3/SDK/Source/GUID-BF626AFA-F8E5-4049-BC3E-E947AD2D39A1_d0e2684_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BF822A89-F932-400F-82FC-FB998B768EBF_d0e129372_href.png Binary file Symbian3/SDK/Source/GUID-BF822A89-F932-400F-82FC-FB998B768EBF_d0e129372_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BF822A89-F932-400F-82FC-FB998B768EBF_d0e135910_href.png Binary file Symbian3/SDK/Source/GUID-BF822A89-F932-400F-82FC-FB998B768EBF_d0e135910_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BFDDCE4E-FE4F-5815-9D0B-A0967EA53B11.dita --- a/Symbian3/SDK/Source/GUID-BFDDCE4E-FE4F-5815-9D0B-A0967EA53B11.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,24 +0,0 @@ - - - - - - Controlling Still-image Capture

                This document explains how to control the still-image capture process.

                Purpose

                This document explains how to control the overall image capture process and to capture a still image based on given image parameters.

                Introduction

                The Image Capture API allows the client to capture the still image and control the capture operation. This class lets you issue still image capture calls even if the previous capture calls are pending. To do this, you need to create another instance of this class. If you use the same instance, the handle to retrieve the previously captured still image will be lost.

                Using Image Capture

                The following tasks are covered during image capture implementation:

                1. Provide implementation of McameraPreImageCaptureControl::PrepareImageCapture.

                2. Use MpreImageCaptureControlObserver::PrepareImageComplete call-back to pass this to the client to create CCamera::CCameraImageCapture class.

                3. Create CCamera::CCameraImageCapture object and pass it to the client, when it calls CCameraPreImageCaptureControl::PrepareImageCapture.

                  See also Implementation of MCameraPreImageCaptureControl class.

                4. Request still image capture using CCamera::CCameraImageCapture object.

                5. Perform image capture using CCamera::CCameraImageCapture::CaptureImage method. This delays the background processing involved with current image captured, so as to capture next images.

                6. Use MCaptureImageObserver::IndividualImageControlHandle callback to provide client with the handle to control captured individual still images. This callback may be send to the client after the image is exposed to the sensor. For example, client may need to destroy the image even before the completion for some reasons.

                7. Use MCaptureImageObserver::ImageCaptureComplete callback to inform the client that the image capture operation has been completed. This lets to use CCameraImageCapture for next still image capture.

                Note:

                Licensees need to provide concrete implementation of McameraImageCapture interface class.

                The following example code snippets illustrate the use of the PreImageCaptureControl classes.

                static_cast<MCameraPreImageCaptureControl*>(CCamPreImageCaptureControl::NewL(static_cast<CCamUnitTestPlugin&>(*this))); - -CCamera::CCameraImageCapture* cameraImageCapture; - -MPreImageCaptureControlObserver* PreImageCaptureControlObserver() {return iPreImageCaptureControlObserver;} -PreImageCaptureControlObserver()->PrepareImageComplete(cameraImageCapture, err); - -CCamera::CCameraPreImageCaptureControl::TPrepareImageParameters& aPrepareImageParameters; -MCaptureImageObserver& aCaptureImageObserver; - -CreateCaptureImageL(cameraImageCapture, aPrepareImageParameters, aCaptureImageObserver)); - -CaptureImageObserver()->IndividualImageControlHandle(*cameraImageCapture, 1);
                See also

                Controlling Pre-Image Capture

                Controlling Captured Image

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-BFEEECCA-190B-4DDE-8A04-4FE918BE8690.dita --- a/Symbian3/SDK/Source/GUID-BFEEECCA-190B-4DDE-8A04-4FE918BE8690.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-BFEEECCA-190B-4DDE-8A04-4FE918BE8690.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,102 +1,101 @@ - - - - - -Options -menu -

                The Options menu is a tool that offers the user -a set of possible functions in the current context. Pressing the left softkey -labeled Options opens the Options menu.

                - -Options menu - - -

                The Options menu is a menu list displayed in a pop-up -window. An item is selected by pressing either the left softkey (Select) -or the Selection key. The user must either select an item from the list or -cancel the menu; it cannot be left pending during another action (see Navigating in applications).

                -

                The pop-up window is located above the Control -pane, and its height is dynamic; the maximum size is approximately -the size of the standard main pane. The content on the screen outside the -menu pop-up is dimmed, except the Control pane.

                -

                Options menu items that are item-specific and require an item on the screen -to be focused, are not displayed in the Options menu unless user has -opened the Options menu while navigating the UI with hardware keys. The item -specific commands are hidden in the Options menu while moving with -touch, and are made visible when activating the hardware interaction. The -item specific commands are not updated or removed, while the Options menu -is open.

                -

                Items in the Options menu use the single item layout; -that is, they are text-only. The number of items in the menu is not limited, -because the list scrolls as necessary. The Options always -loops, which allows users to easily reach the end of the list.

                -Default touch -events for Options menu - - - -

                User action

                 -

                State change

                 -

                Feedback

                 -                 - - - -

                Touch down (no sub-menu for the item)

                 -

                No effect Submenu behaves similarly as the main menu.

                 -

                Highlight is shown.

                Tactile: Basic list effect and audio -feedback is provided with touch down event.

                 -                 - -

                Touch release (no sub-menu for the item)

                 -

                The focused item is activated and Options menu closed.

                 -

                Highlight disappears.

                Tactile: Basic list effect is provided -with touch release event.

                 -                 - -

                Touch down and release (when sub-menu available for the item)

                 -

                A submenu is opened.

                The Options menu item for which -the submenu was opened from (that is, parent item) must be visible.

                 -

                The parent item stays highlighted while the submenu is open to show -the relation between the two.

                The submenu does not have highlight unless -it was opened with a hardware key.

                Tactile: Basic list effect and audio -feedback is provided with touch down and basic list effect with release event. -For pop-up related tactile feedback, normal pop-up effect when opening and -closing if the theme effects are OFF. If they are ON, then increasing long -touch is used when opening and pop-up close effect when closing.

                 -                 - -

                Touch down on Options menu and move out of the Options menu

                 -

                Refer to Dragging -and flicking events

                 -

                Tactile: Refer to Dragging -and flicking events.

                 -                 - -

                Touch down and release outside the Options menu

                 -

                Inactive

                 -

                If there is hardware highlight, it disappears.

                Tactile: No -effect

                 -                 - -

                Touch down and release outside menu area when sub-menu is open

                 -

                Only the sub-menu is closed, main menu remains open.

                 -

                Highlight disappears from the parent menu item.

                Tactile: -Pop-up effect and sensitive audio feedback is provided with touch down event. -If theme effects are ON, pop-up close effect is given with touch release. -Else, no tactile feedback is provided with touch release.

                 -                 - - -
                -
                Using -the Options menu in C++ applications

                The API to use for the Options menu -is the Options menu API. For implementation information, see Using the Options menu API.

                + + + + + +Options +menu +

                The Options menu is a tool that offers the user +a set of possible functions in the current context. Pressing the left softkey +labeled Options opens the Options menu.

                + +Options menu + + +

                The Options menu is a menu list displayed in a pop-up +window. An item is selected by pressing either the left softkey (Select) +or the Selection key. An item can also be selected directly from the list. +The user must either select an item from the list or cancel the menu; it cannot +be left pending during another action (see Navigating +in applications).

                +

                Options menu items that are item-specific and require +an item on the screen to be focused, are not displayed in the Options menu +unless user has opened the Options menu while navigating the UI with hardware +keys. The item specific commands are hidden in the Options menu while +moving with touch, and are made visible when activating the hardware interaction. +The item specific commands are not updated or removed, while the Options menu +is open.

                +

                Items in the Options menu use the single item layout; +that is, they are text-only. The number of items in the menu is not limited, +because the list scrolls as necessary. The Options always +loops, which allows users to easily reach the end of the list.

                +Default touch +events for Options menu + + + +

                User action

                 +

                State change

                 +

                Feedback

                 +                 + + + + +

                Touch down (no sub-menu for the item)

                 +

                No effect.

                Submenu behaves similarly as the main menu.

                 +

                Highlight is shown.

                Tactile: Basic list effect and audio +feedback is provided with touch down event.

                 +                 + +

                Touch release (no sub-menu for the item)

                 +

                The focused item is activated and Options menu closed.

                 +

                Highlight disappears.

                Tactile: Basic list effect is provided +with touch release event.

                 +                 + +

                Touch down and release (when sub-menu available for the item)

                 +

                A submenu is opened.

                The Options menu item for which +the submenu was opened from (that is, parent item) must be visible.

                 +

                The parent item stays highlighted while the submenu is open to show +the relation between the two.

                The submenu does not have highlight unless +it was opened with a hardware key.

                Tactile: Basic list effect and audio +feedback is provided with touch down and basic list effect with release event. +For pop-up related tactile feedback, normal pop-up effect when opening and +closing if the theme effects are OFF. If they are ON, then increasing long +touch is used when opening and pop-up close effect when closing.

                 +                 + +

                Touch down on Options menu and move out of the Options menu

                 +

                Refer to Dragging +and flicking events

                 +

                Tactile: Refer to Dragging +and flicking events.

                 +                 + +

                Touch down and release outside the Options menu

                 +

                Inactive

                 +

                If there is hardware highlight, it disappears.

                Tactile: No +effect

                 +                 + +

                Touch down and release outside menu area when sub-menu is open

                 +

                Only the sub-menu is closed, main menu remains open.

                 +

                Highlight disappears from the parent menu item.

                Tactile: +Pop-up effect and sensitive audio feedback is provided with touch down event. +If theme effects are ON, pop-up close effect is given with touch release. +Else, no tactile feedback is provided with touch release.

                 +                 + + +
                +
                Using +the Options menu in applications

                The API to use for the Options menu +is the Options menu API. For implementation information, see Using the Options menu API.

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C00FBDE4-EF59-5FED-BA92-625414AF45AE.dita --- a/Symbian3/SDK/Source/GUID-C00FBDE4-EF59-5FED-BA92-625414AF45AE.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,12 +0,0 @@ - - - - - -Crypto Libraries

                Crypto Libraries contains a Weak CryptoSPI and Strong CryptoSPI components together called as CryptoSPI framework. The framework provides software-based implementations of cryptographic algorithms. It allows device creators to include alternative implementations as plug-in DLLs.

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C014FC75-732F-558F-8E6A-77DDAA032930_d0e214465_href.png Binary file Symbian3/SDK/Source/GUID-C014FC75-732F-558F-8E6A-77DDAA032930_d0e214465_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C014FC75-732F-558F-8E6A-77DDAA032930_d0e218202_href.png Binary file Symbian3/SDK/Source/GUID-C014FC75-732F-558F-8E6A-77DDAA032930_d0e218202_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C0498002-7CD9-4B2D-B1F9-FB0908C4C1A5.dita --- a/Symbian3/SDK/Source/GUID-C0498002-7CD9-4B2D-B1F9-FB0908C4C1A5.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-C0498002-7CD9-4B2D-B1F9-FB0908C4C1A5.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,13 +1,19 @@ - - - - - -ReferenceThe Reference provides a detailed description of programming -interfaces and error codes. \ No newline at end of file + + + + + +ReferenceThe Reference provides a detailed description of programming +interfaces and error codes. +

                This section contains the Nokia Symbian^3 C++ API Reference which provides documentation for the public and platform classes +and header files. It is organized according to the Symbian System +Model.

                +

                The reference also contains information for system panics, which are the errors codes used when the system terminates +a program with a serious fault.

                +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C08C9AE9-99A6-4EB7-B665-41E92EDD9747.dita --- a/Symbian3/SDK/Source/GUID-C08C9AE9-99A6-4EB7-B665-41E92EDD9747.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-C08C9AE9-99A6-4EB7-B665-41E92EDD9747.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,66 +1,67 @@ - - - - - -Volume -setting item -

                Volume setting item is used for controlling the volume setting on the mobile -device. -Volume setting item - -Text

                -Default -touch events for volume setting item - - - - - - -

                User action

                 -

                State change

                 -

                Feedback

                 -                 - - - - -

                Touch down

                 -

                The focused value is the new volume level.

                 -

                Tactile: Sensitive slider effect and audio feedback are provided -with touch down event.

                 -                 - -

                Touch release

                 -

                No effect

                 -

                Tactile: No effect

                 -                 - -

                Touch down and move

                 -

                Changes the glider value along with the touch event.

                The -glider control area is the entire main pane area.

                Touch down on glider, -moving and touch release are performed in the glider control area, without -releasing the touch event.

                 -

                Tactile: Sensitive slider effect and audio given tied to the steps, -if there is more than 15 steps then smooth slider effect (no audio) is given -instead.

                 -                 - -

                Touch down and cancel

                 -

                The value of the glider is where it was when the touch left the -control area.

                Touch is moved out from the glider area, without releasing -it.

                If the user drags the touch out of the glider area, and back, the -value will continue to move along with the touch action.

                 -

                Tactile: No touch release feedback given if it is performed outside -slider.

                 -                 - - + + + + + +Volume +setting item +

                Volume setting item is used for controlling the volume setting on the mobile +device. It is a general purpose component and does not directly control device +volume. +Volume setting item + +Text

                +
                Default +touch events for volume setting item + + + + + + +

                User action

                 +

                State change

                 +

                Feedback

                 +                 + + + + +

                Touch down

                 +

                The focused value is the new volume level.

                 +

                Tactile: Sensitive slider effect and audio feedback are provided +with touch down event.

                 +                 + +

                Touch release

                 +

                No effect

                 +

                Tactile: No effect

                 +                 + +

                Touch down and move (dragging)

                 +

                Changes the slider value along with the touch event.

                The +slider control area is the entire main pane area.

                Touch down on slider, +moving and touch release are performed in the slider control area, without +releasing the touch event.

                 +

                Tactile: Sensitive slider effect and audio given tied to the steps, +if there is more than 15 steps then smooth slider effect (no audio) is given +instead.

                 +                 + +

                Touch down and cancel

                 +

                The value of the slider is where it was when the touch left the +control area.

                Touch is moved out from the slider area, without releasing +it.

                If the user drags the touch out of the slider area, and back, the +value will continue to move along with the touch action.

                 +

                Tactile: No touch release feedback given if it is performed outside +slider.

                 +                 + +
                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C0A4DA51-3168-4F99-9A8E-66A326186E29-master.png Binary file Symbian3/SDK/Source/GUID-C0A4DA51-3168-4F99-9A8E-66A326186E29-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C0A4DA51-3168-4F99-9A8E-66A326186E29_d0e65898_href.png Binary file Symbian3/SDK/Source/GUID-C0A4DA51-3168-4F99-9A8E-66A326186E29_d0e65898_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C0A4DA51-3168-4F99-9A8E-66A326186E29_d0e71147_href.png Binary file Symbian3/SDK/Source/GUID-C0A4DA51-3168-4F99-9A8E-66A326186E29_d0e71147_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C0CC6EEF-E95F-4DE1-9E53-2B777D9E433D_d0e81716_href.png Binary file Symbian3/SDK/Source/GUID-C0CC6EEF-E95F-4DE1-9E53-2B777D9E433D_d0e81716_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C0CFFE13-579C-5A93-9B63-DC2DCF98EC61_d0e216896_href.png Binary file Symbian3/SDK/Source/GUID-C0CFFE13-579C-5A93-9B63-DC2DCF98EC61_d0e216896_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C0CFFE13-579C-5A93-9B63-DC2DCF98EC61_d0e220633_href.png Binary file Symbian3/SDK/Source/GUID-C0CFFE13-579C-5A93-9B63-DC2DCF98EC61_d0e220633_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C11AF871-56C8-4EA4-A1E0-E2B23372EF84.dita --- a/Symbian3/SDK/Source/GUID-C11AF871-56C8-4EA4-A1E0-E2B23372EF84.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-C11AF871-56C8-4EA4-A1E0-E2B23372EF84.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,29 +1,30 @@ - - - - - -Touch -down and hold -

                Touch down and hold is used, for example, to open the stylus pop-up menu. -It is also referred as long tap. Applications can use an animation (starts -after 0.15 seconds from the start of a stylus touch down event) to indicate -that a Touch down and hold action has been initiated.

                -

                On the whole, touch down and hold may be difficult for users to find, and -therefore its use should be considered carefully. As in the case of task swapping, -the use of touch down and hold should aim at being analogous to using a long -key press on the hardware keys.

                -
                Using -touch down and hold events in C++ applications

                The API to use for -receiving touch down and hold events in applications or controls is the Touch UI utilities API.

                Use -the class CAknLongTapDetector to receive touch down and hold -events.

                The long tap handler must inherit from the class MAknLongTapDetectorCallBack and -implement the MAknLongTapDetectorCallBack::HandleLongTapEventL() callback -function.

                + + + + + +Touch +down and hold +

                Touch down and hold is used, for example, to open the stylus pop-up menu. +It is also referred as long tap. Applications can use an animation (starts +after 0.15 seconds from the start of a stylus touch down event) to indicate +that a Touch down and hold action has been initiated.

                +

                On the whole, touch down and hold may be difficult for users to find, and +therefore its use should be considered carefully. As in the case of task swapping, +the use of touch down and hold should aim at being analogous to using a long +key press on the hardware keys.

                +
                Using +touch down and hold events in applications

                The API +to use for receiving touch down and hold events in applications or controls +is the Touch UI utilities +API.

                Use the class CAknLongTapDetector to receive +touch down and hold events.

                The long tap handler must inherit from the +class MAknLongTapDetectorCallBack and implement the MAknLongTapDetectorCallBack::HandleLongTapEventL() callback +function.

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C156607A-5929-5971-8077-E8974FA43B3C.dita --- a/Symbian3/SDK/Source/GUID-C156607A-5929-5971-8077-E8974FA43B3C.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-C156607A-5929-5971-8077-E8974FA43B3C.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,21 +1,21 @@ - - - - - -Basics: -Store and Restore Object using Clipboard -
                Download

                Click -on the following link to download the example: Clipboard.zip

                Download some additional files required -by the example: CommonFramework

                Click: browse to view the example code.

                View the additional -files: browse.
                -
                Description

                This is an example of basic clipboard -use.

                -
                Class Summary

                CClipboard

                RStoreWriteStream

                RStoreReadStream

                TStreamId

                + + + + + +Basics: +Store and Restore Object using Clipboard +
                Download

                Click +on the following link to download the example: Clipboard.zip

                Download some additional files required +by the example: CommonFramework

                Click: browse to view the example code.

                View the additional +files: browse.
                +
                Description

                This is an example of basic clipboard +use.

                +
                Class Summary

                CClipboard

                RStoreWriteStream

                RStoreReadStream

                TStreamId

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C193535D-8756-5A2C-BD3A-280F7DDAF73E_d0e396840_href.jpg Binary file Symbian3/SDK/Source/GUID-C193535D-8756-5A2C-BD3A-280F7DDAF73E_d0e396840_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C193535D-8756-5A2C-BD3A-280F7DDAF73E_d0e397002_href.jpg Binary file Symbian3/SDK/Source/GUID-C193535D-8756-5A2C-BD3A-280F7DDAF73E_d0e397002_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C1A6477D-2130-5664-A845-898212F96381_d0e290246_href.png Binary file Symbian3/SDK/Source/GUID-C1A6477D-2130-5664-A845-898212F96381_d0e290246_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C1A6477D-2130-5664-A845-898212F96381_d0e295005_href.png Binary file Symbian3/SDK/Source/GUID-C1A6477D-2130-5664-A845-898212F96381_d0e295005_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C1B080D9-9C6C-520B-B73E-4EB344B1FC5E.dita --- a/Symbian3/SDK/Source/GUID-C1B080D9-9C6C-520B-B73E-4EB344B1FC5E.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-C1B080D9-9C6C-520B-B73E-4EB344B1FC5E.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,91 +1,91 @@ - - - - - -GDI -Collection OverviewThe Graphics Device Interface (GDI) collection is an important -collection within the Graphics subsystem. It provides a suite of abstract -base classes, interfaces and data structures. The suite represents and interacts -with physical graphics hardware such as display screens, off-screen memory -and printers. -
                Architectural Relationship

                The GDI collection provides -base classes and utility functions. Every graphics component ends up using -it. The components in this collection are closely linked and provide important -functionality. The GDI component is a low-level component in this collection, -BitGDI is based on this and DirectGDI is a potentially faster alternative -to BitGDI. The Colour Palette provides coloring indexing operations.

                -
                Description

                GDI consists of a large number of diverse -APIs that cover many different aspects of graphics including graphics device -abstraction, color value handling, linear digital differential analysis, font -description and information, printer devices abstraction, line breaking, text -rendering, handling of bidirectional text, text wrapper and linked font creation.

                Graphics -Device Interface collection includes the following components:

                  -

                • GDI

                  • -

                • BitGDI

                  • -

                • DirectGDI

                  • -

                • Colour Palette

                  • -
                -
                GDI

                GDI -is a low level component. Two key concepts related to GDI are Device (CGraphicsDevice) -and Context (CGraphicsContext). Throughout the Graphics -sub-system a graphics device provides a graphics context through which the -device may be drawn to. The context maintains 'settings', such as the pen -and brush colors and styles in use, and provides a rich API of drawing commands -for creating graphical and textual output.

                Most display devices use -bitmap graphics and the GDI provides specializations of both CGraphicsDevice and CGraphicsContext to -act as base classes for bitmap devices: namely CBitmapDevice and CBitmapContext. -These add, amongst other attributes, pixel awareness, blitting, scanlines -and fading.

                The GDI defines abstract base classes for storing and -manipulating fonts (CFont, CTypefaceStore, CFontCache) -and additional supporting classes and structures.

                The GDI defines -the interface for mapping between device-specific pixels and real-world twips. -A twip is a twentieth of a point and a point is 1/72 of an inch. That makes -a twip 1/1440 of an inch, 1/567 of a centimeter or about 0.018mm.

                The -GDI defines a base class for representing embedded pictures, CPicture, -and supporting classes. It also provides base classes, interfaces and structures -for printing.

                -
                BitGDI

                The BitGDI Component is -used by legacy applications and the Window Server in the non-ScreenPlay -variant. The BitGDI component provides the CFbsScreenDevice and CFbsBitGc APIs, -which are concrete implementations of CGraphicsDevice and CGraphicsContext for -bitmap-based devices. This component enables:

                  -

                • hardware-independent -access to screen attributes

                  • -

                • bitmapped drawing which -holds settings and supports drawing to bitmapped devices and screens independent -of the display.

                  • -
                - -
                -
                Colour -Palette

                The Colour -Palette component provides coloring functionality. A user can specify -the use of a particular color, as described by a TRgb, -and have that color rendered on a machine’s display device as closely as possible -to the color specified. A related functionality allows arrays of colors to -be stored as bitmaps, and displayed at a later date in the same manner.

                Color -palettes also provide user-definable palette support to the GDI. A palette -is a user-defined set of colors, which is a subset of the full range of 24-bit -colors. This allows users the advantages of having a low bpp color mode whilst -being able to specify the colors available in that mode. Only a palette of -16 colors enables changing the palette. Palettes are also used to allow 24-bit -bitmaps to be stored in a more compressed form by finding the actual number -of different colors used in the bitmap. This creates a palette that allows -mapping of colors to a smaller index space. The pixels of the bitmaps are -encoded using indexes to this new index space. A palette has a size which -is set at its creation and cannot alter the number of entries in the palette. -Each entry in a palette is a mapping between that entry's index and a TRgb value. -Palette entries can be got and set at any time between the palette's creation -and destruction. The GDI's palette support also provides functions to find -the nearest palette color to a requested TRgb color.

                -                 -Graphics -Device Interface (GDI) Collection + + + + + +GDI +Collection OverviewThe Graphics Device Interface (GDI) collection is an important +collection within the Graphics subsystem. It provides a suite of abstract +base classes, interfaces and data structures. The suite represents and interacts +with physical graphics hardware such as display screens, off-screen memory +and printers. +
                Architectural Relationship

                The GDI collection provides +base classes and utility functions. Every graphics component ends up using +it. The components in this collection are closely linked and provide important +functionality. The GDI component is a low-level component in this collection, +BitGDI is based on this and DirectGDI is a potentially faster alternative +to BitGDI. The Colour Palette provides coloring indexing operations.

                +
                Description

                GDI consists of a large number of diverse +APIs that cover many different aspects of graphics including graphics device +abstraction, color value handling, linear digital differential analysis, font +description and information, printer devices abstraction, line breaking, text +rendering, handling of bidirectional text, text wrapper and linked font creation.

                Graphics +Device Interface collection includes the following components:

                  +

                • GDI

                  • +

                • BitGDI

                  • +

                • DirectGDI

                  • +

                • Colour Palette

                  • +
                +
                GDI

                GDI +is a low level component. Two key concepts related to GDI are Device (CGraphicsDevice) +and Context (CGraphicsContext). Throughout the Graphics +sub-system a graphics device provides a graphics context through which the +device may be drawn to. The context maintains 'settings', such as the pen +and brush colors and styles in use, and provides a rich API of drawing commands +for creating graphical and textual output.

                Most display devices use +bitmap graphics and the GDI provides specializations of both CGraphicsDevice and CGraphicsContext to +act as base classes for bitmap devices: namely CBitmapDevice and CBitmapContext. +These add, amongst other attributes, pixel awareness, blitting, scanlines +and fading.

                The GDI defines abstract base classes for storing and +manipulating fonts (CFont, CTypefaceStore, CFontCache) +and additional supporting classes and structures.

                The GDI defines +the interface for mapping between device-specific pixels and real-world twips. +A twip is a twentieth of a point and a point is 1/72 of an inch. That makes +a twip 1/1440 of an inch, 1/567 of a centimeter or about 0.018mm.

                The +GDI defines a base class for representing embedded pictures, CPicture, +and supporting classes. It also provides base classes, interfaces and structures +for printing.

                +
                BitGDI

                The BitGDI Component is +used by legacy applications and the Window Server in the non-ScreenPlay +variant. The BitGDI component provides the CFbsScreenDevice and CFbsBitGc APIs, +which are concrete implementations of CGraphicsDevice and CGraphicsContext for +bitmap-based devices. This component enables:

                  +

                • hardware-independent +access to screen attributes

                  • +

                • bitmapped drawing which +holds settings and supports drawing to bitmapped devices and screens independent +of the display.

                  • +
                + +
                +
                Colour +Palette

                The Colour +Palette component provides coloring functionality. A user can specify +the use of a particular color, as described by a TRgb, +and have that color rendered on a machine’s display device as closely as possible +to the color specified. A related functionality allows arrays of colors to +be stored as bitmaps, and displayed at a later date in the same manner.

                Color +palettes also provide user-definable palette support to the GDI. A palette +is a user-defined set of colors, which is a subset of the full range of 24-bit +colors. This allows users the advantages of having a low bpp color mode whilst +being able to specify the colors available in that mode. Only a palette of +16 colors enables changing the palette. Palettes are also used to allow 24-bit +bitmaps to be stored in a more compressed form by finding the actual number +of different colors used in the bitmap. This creates a palette that allows +mapping of colors to a smaller index space. The pixels of the bitmaps are +encoded using indexes to this new index space. A palette has a size which +is set at its creation and cannot alter the number of entries in the palette. +Each entry in a palette is a mapping between that entry's index and a TRgb value. +Palette entries can be got and set at any time between the palette's creation +and destruction. The GDI's palette support also provides functions to find +the nearest palette color to a requested TRgb color.

                +                 +Graphics +Device Interface (GDI) Collection                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C213B26D-32EC-5CD9-956E-1C2143E5D0CA_d0e272131_href.jpg Binary file Symbian3/SDK/Source/GUID-C213B26D-32EC-5CD9-956E-1C2143E5D0CA_d0e272131_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C213B26D-32EC-5CD9-956E-1C2143E5D0CA_d0e275812_href.jpg Binary file Symbian3/SDK/Source/GUID-C213B26D-32EC-5CD9-956E-1C2143E5D0CA_d0e275812_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C218732C-E675-5116-96FE-2604495C2C92-master.png Binary file Symbian3/SDK/Source/GUID-C218732C-E675-5116-96FE-2604495C2C92-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C218732C-E675-5116-96FE-2604495C2C92_d0e383225_href.png Binary file Symbian3/SDK/Source/GUID-C218732C-E675-5116-96FE-2604495C2C92_d0e383225_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C21BB0E4-7AF7-58E5-AAD6-8CE67399460C.dita --- a/Symbian3/SDK/Source/GUID-C21BB0E4-7AF7-58E5-AAD6-8CE67399460C.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-C21BB0E4-7AF7-58E5-AAD6-8CE67399460C.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,82 +1,73 @@ - - - - - -MessageQueue -ExampleThis example application shows the use of message queue in interprocess -communication using the RMsgQueue class. -
                Download

                Click -on the following link to download the example: MessageQueueExample.zip.

                Click: browse to view the example code.

                -
                Description

                The -example describes the global message queue. The following sections provide -more information.

                MessageQueueExample

                The example -comprises two processes: a Collector, which collects words from the user via -the console, and an Inverter, which periodically reverses the order of the -collected words. The Collector and the Inverter pass words to each other using -two message queues: InverterInQ and InverterOutQ. The Collector is the main -process which starts the Inverter process. The Collector process takes user -input in form of different words and sends to the Inverter process via message -queue. The Inverter process receives messages at a regular interval of 10 -seconds, inverts the words in the message and sends it back to the Collector.

                The -Collector creates an active object to collect words from the user and another -active object to receive words from the Inverter. Each active object has its -own console for display. More information about running the example is given -in the build section of this document.

                Design

                The following -block diagram describes the example in more detail.

                - -

                CCollector.exe is the Collector process. The -user starts the Collector and creates an active scheduler and two global message -queues. It also starts the Inverter process called Inverter.exe. -The Collector creates one active object to collect words from the user and -another active object to monitor its input queue (InverterOutQ). The active -object to collect words is an object of class CCollector and the active object -which monitors InverterOutQ is an object of class CMsgQActive. -The two active objects have different consoles (one for user input and one -for displaying the output message).

                The user inputs words in the console. -The set of words goes to the InverterInQ when the "Enter" -key is pressed. If the "ESC" key is pressed, the system stops -and sends the command to the Inverter process to stop.

                The Inverter -is another process which opens the global message queues. It creates an active -scheduler and implements a periodic timer. The timer wakes every 10 seconds -to receive the words from the InverterInQ. It also checks -for a stop command, which closes the message queue and the two process. The -Inverter inverts the received words and sends the result to InverterOutQ.

                In -the Collector process, the active object that monitors the InveterOutQ opens -the message queue, receives the received words and displays them in its console. -It uses the NotifyDataAvailable() API to monitor the queue -for the next set of data.

                The Class diagram of the example is shown -below

                - -
                -
                Class summary
                  -

                • CPeriodic - Periodic timer active object.

                  • -

                • RMsgQueue - A handle to a message queue.

                  • -

                • RProcessA handle to a process.

                  • -

                • CActive - The core class of the active object abstraction.

                  • -
                -
                Build

                The Symbian build -process describes how to build this example application.

                The -example builds an executable called Inverter.exe and Collector.exe in -the standard locations.

                To run the example, first build Inverter.exe and -start Collector.exe from the file system or from your -IDE. After launching the .exes (and depending on the emulator you are using) -you may need to navigate away from the application launcher or shell screen -to view the console.

                A message input console is used for user input -and an output message console is used to display inverted words. The output -message console that is displayed at startup. The user can switch between -two consoles by Ctrl+Shift+Alt+t combination.

                The -input message console is used to input words. A user presses enter to send -the words to the Inverter and presses ESC to exit the application. -When a user presses "Enter" the words go to the InverterInQ. -The Inverter opens the InverterInQ at periodic intervals -of 10 secs and inverts the words which it sends to the collector via InverterOutQ. -The Collector opens the InverterOutQ and display the words -in the output message console.

                + + + + + +MessageQueue ExampleThis example application shows the use of message queue +in interprocess communication using the RMsgQueue class. +
                Download

                Click on the following link to download the example: MessageQueueExample.zip.

                Click: browse to view the example code.

                +
                Description

                The example describes the global message queue. The following +sections provide more information.

                MessageQueueExample

                The example comprises two processes: a Collector, which +collects words from the user via the console, and an Inverter, which +periodically reverses the order of the collected words. The Collector +and the Inverter pass words to each other using two message queues: +InverterInQ and InverterOutQ. The Collector is the main process which +starts the Inverter process. The Collector process takes user input +in form of different words and sends to the Inverter process via message +queue. The Inverter process receives messages at a regular interval +of 10 seconds, inverts the words in the message and sends it back +to the Collector.

                The Collector creates an active object to +collect words from the user and another active object to receive words +from the Inverter. Each active object has its own console for display. +More information about running the example is given in the build section +of this document.

                Design

                The following block +diagram describes the example in more detail.

                + +

                CCollector.exe is the Collector process. +The user starts the Collector and creates an active scheduler and +two global message queues. It also starts the Inverter process called Inverter.exe. The Collector creates one active object +to collect words from the user and another active object to monitor +its input queue (InverterOutQ). The active object to collect words +is an object of class CCollector and the active object which monitors InverterOutQ is an object of class CMsgQActive. The two active objects have different consoles (one for user input +and one for displaying the output message).

                The user inputs +words in the console. The set of words goes to the InverterInQ when the "Enter" key is pressed. If the "ESC" key is pressed, the system stops and sends the command +to the Inverter process to stop.

                The Inverter is another process +which opens the global message queues. It creates an active scheduler +and implements a periodic timer. The timer wakes every 10 seconds +to receive the words from the InverterInQ. It also +checks for a stop command, which closes the message queue and the +two process. The Inverter inverts the received words and sends the +result to InverterOutQ.

                In the Collector process, +the active object that monitors the InveterOutQ opens +the message queue, receives the received words and displays them +in its console. It uses the NotifyDataAvailable(TRequestStatus&) API to monitor the queue for the next set of data.

                The Class diagram of the example is shown below

                + +
                +
                Class +summary
                  +

                • CPeriodic - Periodic timer active object.

                  • +

                • RMsgQueue - A handle to a message queue.

                  • +

                • RProcess - A handle to a process.

                  • +

                • CActive - The core class of the active +object abstraction.

                  • +
                +
                Build

                The Symbian +build process describes how to build this example application.

                The example builds an executable called Inverter.exe and Collector.exe in the standard locations.

                To run the example, first build Inverter.exe and start Collector.exe from the file system +or from your IDE. After launching the .exes (and depending on the +emulator you are using) you may need to navigate away from the application +launcher or shell screen to view the console.

                A message input +console is used for user input and an output message console is used +to display inverted words. The output message console that is displayed +at startup. The user can switch between two consoles by Ctrl+Shift+Alt+t combination.

                The input message console is used to input +words. A user presses enter to send the words to the Inverter and +presses ESC to exit the application. When a user +presses "Enter" the words go to the InverterInQ. +The Inverter opens the InverterInQ at periodic intervals +of 10 secs and inverts the words which it sends to the collector via InverterOutQ. The Collector opens the InverterOutQ and display the words in the output message console.

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C23196E8-FDD3-4A10-9DA2-DA83A2AD49D9.dita --- a/Symbian3/SDK/Source/GUID-C23196E8-FDD3-4A10-9DA2-DA83A2AD49D9.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-C23196E8-FDD3-4A10-9DA2-DA83A2AD49D9.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,34 +1,34 @@ - - - - - -Applications -with a user interface -

                If you are developing an application with a user interface, consider -the following issues:

                -
                  -

                • Other applications may have access to the information that -the user inputs.

                  • -

                • A hostile application may lure the user to enter information -that belongs to another application.

                  • -
                -

                Password dialogs in particular should be designed so that the user easily -recognizes the currently running application.

                -
                User input -

                It is possible for the user to unintentionally enter incorrect data -that can interfere with the normal operation of the application. All input -should be checked and validated before processing. A one-time check may not -be enough because the content of data can change during processing, so it -is therefore advisable to quickly check the data every time it is used.

                -

                The following figure shows an example of input processing phases.

                -Examples of input processing -

                -

                + + + + + +Applications +with a user interface +

                If you are developing an application with a user interface, consider +the following issues:

                +
                  +

                • Other applications may have access to the information that +the user inputs.

                  • +

                • A hostile application may lure the user to enter information +that belongs to another application.

                  • +
                +

                Password dialogs in particular should be designed so that the user easily +recognizes the currently running application.

                +
                User input +

                It is possible for the user to unintentionally enter incorrect data +that can interfere with the normal operation of the application. All input +should be checked and validated before processing. A one-time check may not +be enough because the content of data can change during processing, so it +is therefore advisable to quickly check the data every time it is used.

                +

                The following figure shows an example of input processing phases.

                +Examples of input processing +

                +

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C253D792-7470-5D9F-B39B-1CF42438215A_d0e16601_href.png Binary file Symbian3/SDK/Source/GUID-C253D792-7470-5D9F-B39B-1CF42438215A_d0e16601_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C253D792-7470-5D9F-B39B-1CF42438215A_d0e22179_href.png Binary file Symbian3/SDK/Source/GUID-C253D792-7470-5D9F-B39B-1CF42438215A_d0e22179_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C28FDA4B-0099-4258-8255-6CF7C44FD4E8-master.png Binary file Symbian3/SDK/Source/GUID-C28FDA4B-0099-4258-8255-6CF7C44FD4E8-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C28FDA4B-0099-4258-8255-6CF7C44FD4E8_d0e67775_href.png Binary file Symbian3/SDK/Source/GUID-C28FDA4B-0099-4258-8255-6CF7C44FD4E8_d0e67775_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C28FDA4B-0099-4258-8255-6CF7C44FD4E8_d0e72928_href.png Binary file Symbian3/SDK/Source/GUID-C28FDA4B-0099-4258-8255-6CF7C44FD4E8_d0e72928_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C29FE12C-C412-40A8-A067-27C63A519D71.dita --- a/Symbian3/SDK/Source/GUID-C29FE12C-C412-40A8-A067-27C63A519D71.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-C29FE12C-C412-40A8-A067-27C63A519D71.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,41 +1,42 @@ - - - - - -Choice -list APIThe Choice list API is used for providing a vertical list of selectable -items. - -Choice list - - -

                You can use the Choice list API in all GUI applications. It is a library -API that provides an interface for constructing and using the choice list -UI component.

                -

                You can use the choice list in two ways, with or without the current selection.

                -

                If the current selection is displayed, there is an label showing the currently -selected item and an arrow button indicating that a list is available.

                -

                If without current selection, the choice list must be created with providing -a generic button to the list. This button will be used to open the list for -selection. The label of the button is defined by the client application when -creating the button and will not be changed by the choice list.

                -

                For implementation information, see Providing -a vertical list of selectable items.

                -

                For the Choice list API classes and header files, see Classes -and definitions.

                -
                Error handling

                The -leave mechanism of the Symbian platform environment is used to handle memory -exhaustion.

                -                 -Related APIs -Generic button -API - + + + + + +Choice +list APIThe Choice list API is used for providing a vertical list of selectable +items. + +Choice list + + +

                You can use the Choice list API in all GUI applications. It is a library +API that provides an interface for constructing and using the choice list +UI component.

                +

                You can use the choice list in two ways, with or without the current selection.

                +

                If the current selection is displayed, there is an label showing the currently +selected item and an arrow button indicating that a list is available.

                +

                If without current selection, the choice list must be created with providing +a generic button to the list. This button will be used to open the list for +selection. The label of the button is defined by the client application when +creating the button and will not be changed by the choice list.

                +

                For implementation information, see Providing +a vertical list of selectable items.

                +

                For the Choice list API classes and header files, see Classes and definitions.

                +
                Changes and release information

                The Choice list +API is an SDK API and first released in S60 5th Edition.

                +
                Error handling

                The +leave mechanism of the Symbian platform environment is used to handle memory +exhaustion.

                +                 +Related APIs +Generic button +API +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C2D6BAB9-89BA-4E8D-82B4-2FAE04B9086C-master.png Binary file Symbian3/SDK/Source/GUID-C2D6BAB9-89BA-4E8D-82B4-2FAE04B9086C-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C2D6BAB9-89BA-4E8D-82B4-2FAE04B9086C_d0e48752_href.png Binary file Symbian3/SDK/Source/GUID-C2D6BAB9-89BA-4E8D-82B4-2FAE04B9086C_d0e48752_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C2D99C88-09C7-55FA-AF95-3F689BA27484_d0e304448_href.jpg Binary file Symbian3/SDK/Source/GUID-C2D99C88-09C7-55FA-AF95-3F689BA27484_d0e304448_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C2D99C88-09C7-55FA-AF95-3F689BA27484_d0e310463_href.jpg Binary file Symbian3/SDK/Source/GUID-C2D99C88-09C7-55FA-AF95-3F689BA27484_d0e310463_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C31DA918-8DEA-5816-B0A6-4AE90B06DD0D_d0e169089_href.jpg Binary file Symbian3/SDK/Source/GUID-C31DA918-8DEA-5816-B0A6-4AE90B06DD0D_d0e169089_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C31DA918-8DEA-5816-B0A6-4AE90B06DD0D_d0e175690_href.jpg Binary file Symbian3/SDK/Source/GUID-C31DA918-8DEA-5816-B0A6-4AE90B06DD0D_d0e175690_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C37790B3-967C-489C-8753-0434938CBE2B.dita --- a/Symbian3/SDK/Source/GUID-C37790B3-967C-489C-8753-0434938CBE2B.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-C37790B3-967C-489C-8753-0434938CBE2B.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,21 +1,21 @@ - - - - - -Secure -Sockets -

                In addition to VPN and IPSec, the Symbian platform provides a generic -client interface for communication through end points known as Secure Sockets. -The required security protocol modules can be plugged into the Secure Sockets -interface.

                -

                The following figure shows the relationship between applications, secure -socket classes, and secure socket plug-ins.

                -Relationship between applications and secure socket + + + + + +Secure +Sockets +

                In addition to VPN and IPSec, the Symbian platform provides a generic +client interface for communication through end points known as Secure Sockets. +The required security protocol modules can be plugged into the Secure Sockets +interface.

                +

                The following figure shows the relationship between applications, secure +socket classes, and secure socket plug-ins.

                +Relationship between applications and secure socket                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C3A3D9CF-4826-4BEB-8778-ECD8E6B6463C.dita --- a/Symbian3/SDK/Source/GUID-C3A3D9CF-4826-4BEB-8778-ECD8E6B6463C.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-C3A3D9CF-4826-4BEB-8778-ECD8E6B6463C.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,85 +1,85 @@ - - - - - -Image Processor OverviewIntroduction to topic for overview page or search -

                This document introduces to the Image Processor library.

                -
                Purpose

                Image Processor is specially developed -for imaging on mobile devices. The main objective is to create powerful applications:

                  -

                • Photo editors

                  • -

                • Viewers

                  • -

                • Cameras.

                  • -
                -
                Image Processor library details

                The DLL that provides -the functionality and the library to which your code must link is identified -below.

                - - - -DLL -LIB -Short Description - - - - -

                imageprocessor.dll

                -

                imageprocessor.lib

                -

                These files are used for implementing Image Processor operations.

                -                 - - -
                -
                Architectural relationship

                Image Processor is designed -with hardware constraints often associated with mobile devices in mind. The -Image Processor framework minimizes both memory consumption and the CPU power -required.

                The diagrammatic representation of the Image Processor library -is as follows:

                -

                The architectural relationship diagram for the Image Processor library

                - -
                -
                Image Processor

                Image Processor is a high-level -library and framework. Image Processor encapsulates all the internal processing -and basic functionality required to create applications. Basic functions include

                  -

                • initiate image processing

                  • -

                • decode images

                  • -

                • zoom images

                  • -

                • pan images

                  • -

                • render images to screen or file.

                  • -

                The Image Processor library also allows some geometrical operations -to the image:

                  -

                • rotate or flip

                  • -

                • crop.

                  • -

                Optionally, the Image Processor library supports

                  -

                • effects

                  • -

                • overlays.

                  • -
                -
                Image Processor Adaptation Plug-in

                The Image Processor -adaptation plug-in is an attachable component which implements the features -of the Image Processor library. The Image Processor adaptation plug-ins are -dependant on the Image Processor library, and will not function as standalone -components.

                Note: You must write your own Image Processor adaptation -plug-in, because the Image Processor adaptation plug-in is not provided.

                -
                Key Image Processor Class

                The principal classes -of the Image Processor library are as follows:

                  -

                • ImageProcessor::CImgProcessor, which provides a -convenient interface to process images.

                  • -

                • ImageProcessor::TEffect, which is the parent class -of all effects, for example, ImageProcessor::TEffectAntique.

                  • -
                -
                Using Image Processor

                Image Processor is used for -the following:

                  -

                • To initialize and process an input image

                  • -

                • To apply effects and filters to the image.

                  • -

                • Overlay images onto an image.

                  • -

                • To render a low resolution preview of the image for display on screen.

                  • -

                • To render a high resolution compressed image to disk or memory.

                  • -
                + + + + + +Image Processor OverviewIntroduction to topic for overview page or search +

                This document introduces to the Image Processor library.

                +
                Purpose

                Image Processor is specially developed +for imaging on mobile devices. The main objective is to create powerful applications:

                  +

                • Photo editors

                  • +

                • Viewers

                  • +

                • Cameras.

                  • +
                +
                Image Processor library details

                The DLL that provides +the functionality and the library to which your code must link is identified +below.

                + + + +DLL +LIB +Short Description + + + + +

                imageprocessor.dll

                +

                imageprocessor.lib

                +

                These files are used for implementing Image Processor operations.

                +                 + + +
                +
                Architectural relationship

                Image Processor is designed +with hardware constraints often associated with mobile devices in mind. The +Image Processor framework minimizes both memory consumption and the CPU power +required.

                The diagrammatic representation of the Image Processor library +is as follows:

                +

                The architectural relationship diagram for the Image Processor library

                + +
                +
                Image Processor

                Image Processor is a high-level +library and framework. Image Processor encapsulates all the internal processing +and basic functionality required to create applications. Basic functions include

                  +

                • initiate image processing

                  • +

                • decode images

                  • +

                • zoom images

                  • +

                • pan images

                  • +

                • render images to screen or file.

                  • +

                The Image Processor library also allows some geometrical operations +to the image:

                  +

                • rotate or flip

                  • +

                • crop.

                  • +

                Optionally, the Image Processor library supports

                  +

                • effects

                  • +

                • overlays.

                  • +
                +
                Image Processor Adaptation Plug-in

                The Image Processor +adaptation plug-in is an attachable component which implements the features +of the Image Processor library. The Image Processor adaptation plug-ins are +dependant on the Image Processor library, and will not function as standalone +components.

                Note: You must write your own Image Processor adaptation +plug-in, because the Image Processor adaptation plug-in is not provided.

                +
                Key Image Processor Class

                The principal classes +of the Image Processor library are as follows:

                  +

                • ImageProcessor::CImgProcessor, which provides a +convenient interface to process images.

                  • +

                • ImageProcessor::TEffect, which is the parent class +of all effects, for example, ImageProcessor::TEffectAntique.

                  • +
                +
                Using Image Processor

                Image Processor is used for +the following:

                  +

                • To initialize and process an input image

                  • +

                • To apply effects and filters to the image.

                  • +

                • Overlay images onto an image.

                  • +

                • To render a low resolution preview of the image for display on screen.

                  • +

                • To render a high resolution compressed image to disk or memory.

                  • +
                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C3A8290D-44BA-5AAD-8F0D-745FF3F10E0B_d0e308998_href.png Binary file Symbian3/SDK/Source/GUID-C3A8290D-44BA-5AAD-8F0D-745FF3F10E0B_d0e308998_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C3A8290D-44BA-5AAD-8F0D-745FF3F10E0B_d0e315392_href.png Binary file Symbian3/SDK/Source/GUID-C3A8290D-44BA-5AAD-8F0D-745FF3F10E0B_d0e315392_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C3B6E5F6-74DC-5C0E-94C8-B4822F4A2EB6.dita --- a/Symbian3/SDK/Source/GUID-C3B6E5F6-74DC-5C0E-94C8-B4822F4A2EB6.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-C3B6E5F6-74DC-5C0E-94C8-B4822F4A2EB6.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,76 +1,76 @@ - - - - - -Power -API Tutorial This tutorial explains how to use the Power API of the HWRM. -
                Introduction

                Power API methods can be used by constructing -an instance of CHWRMPower and calling -its functions. However, to use its full functionality write a class which -implements one or more of the observer interfaces described in the following -table. Then, construct an instance of CHWRMPower and -provide it with pointers to observers.

                - - - -Interface -Notification -Method to override - - - - -

                MHWRMBatteryPowerObserver

                -

                Average battery voltage and current consumption

                -

                PowerMeasurement

                -                 - -

                MHWRMBatteryChargingStatusObserver

                -

                Charging status

                -

                ChargingStatusChange

                -                 - -

                MHWRMBatteryChargingCurrentObserver

                -

                Average charging current

                -

                AverageChargingCurrentChange

                -                 - -

                MHWRMBatteryFullChargingTimeObserver

                -

                Remaining charging time

                -

                BatteryFullChargingTimeChange

                -                 - - -

                For example, if the application requires periodic measurements -of average battery voltage and current consumption, it must implement MHWRMBatteryPowerObserver and instantiate a CHWRMPower object using the CHWRMPower::NewL(NULL, -MHWRMBatteryPowerObserver *) method.

                Note: The battery -charging observers cannot be passed to CHWRMPower using -a NewL() function. Call the dedicated -function, CHRMPower::SetBatteryChargingObserver().

                -
                Procedure
                  -

                1. Derive -a class from one or more of the above interfaces.

                  2. -

                2. Implement -the appropriate observer functions.

                  3. -

                3. Create -a power client using CHWRMPower::NewL() or NewLC().

                  You -can retrieve the battery voltage or consumption information.

                  4. -

                4. Call CHRMPower::SetBatteryChargingObserver(), if -necessary.

                  5. -

                5. Start -receiving notification using the appropriate start function(s).

                  6. -

                6. Stop -receiving notification using the appropriate stop function(s).

                  7. -

                Note: If the notification period exceeds the maximum reporting -period, set when the HWRM server starts, notification is cancelled.

                -                 -Power API - + + + + + +Power +API Tutorial This tutorial explains how to use the Power API of the HWRM. +
                Introduction

                Power API methods can be used by constructing +an instance of CHWRMPower and calling +its functions. However, to use its full functionality write a class which +implements one or more of the observer interfaces described in the following +table. Then, construct an instance of CHWRMPower and +provide it with pointers to observers.

                + + + +Interface +Notification +Method to override + + + + +

                MHWRMBatteryPowerObserver

                +

                Average battery voltage and current consumption

                +

                PowerMeasurement

                +                 + +

                MHWRMBatteryChargingStatusObserver

                +

                Charging status

                +

                ChargingStatusChange

                +                 + +

                MHWRMBatteryChargingCurrentObserver

                +

                Average charging current

                +

                AverageChargingCurrentChange

                +                 + +

                MHWRMBatteryFullChargingTimeObserver

                +

                Remaining charging time

                +

                BatteryFullChargingTimeChange

                +                 + + +

                For example, if the application requires periodic measurements +of average battery voltage and current consumption, it must implement MHWRMBatteryPowerObserver and instantiate a CHWRMPower object using the CHWRMPower::NewL(NULL, +MHWRMBatteryPowerObserver *) method.

                Note: The battery +charging observers cannot be passed to CHWRMPower using +a NewL() function. Call the dedicated +function, CHRMPower::SetBatteryChargingObserver().

                +
                Procedure
                  +

                1. Derive +a class from one or more of the above interfaces.

                  2. +

                2. Implement +the appropriate observer functions.

                  3. +

                3. Create +a power client using CHWRMPower::NewL() or NewLC().

                  You +can retrieve the battery voltage or consumption information.

                  4. +

                4. Call CHRMPower::SetBatteryChargingObserver(), if +necessary.

                  5. +

                5. Start +receiving notification using the appropriate start function(s).

                  6. +

                6. Stop +receiving notification using the appropriate stop function(s).

                  7. +

                Note: If the notification period exceeds the maximum reporting +period, set when the HWRM server starts, notification is cancelled.

                +                 +Power API +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C3D0BA4A-AEC5-5002-916E-CB3F9FE5AC27_d0e200042_href.png Binary file Symbian3/SDK/Source/GUID-C3D0BA4A-AEC5-5002-916E-CB3F9FE5AC27_d0e200042_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C3D0BA4A-AEC5-5002-916E-CB3F9FE5AC27_d0e205050_href.png Binary file Symbian3/SDK/Source/GUID-C3D0BA4A-AEC5-5002-916E-CB3F9FE5AC27_d0e205050_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C459D462-772A-58FC-8C46-B7559436C12C-GENID-1-8-1-3-1-1-3-1-3-1-3-1.dita --- a/Symbian3/SDK/Source/GUID-C459D462-772A-58FC-8C46-B7559436C12C-GENID-1-8-1-3-1-1-3-1-3-1-3-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,14 +0,0 @@ - - - - - -Control and -animation framework examplesThis section provides example code for the Control and Animation -framework. \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C459D462-772A-58FC-8C46-B7559436C12C-GENID-1-8-1-6-1-1-4-1-9-1.dita --- a/Symbian3/SDK/Source/GUID-C459D462-772A-58FC-8C46-B7559436C12C-GENID-1-8-1-6-1-1-4-1-9-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,14 +0,0 @@ - - - - - -Control and -animation framework examplesThis section provides example code for the Control and Animation -framework. \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C459D462-772A-58FC-8C46-B7559436C12C.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-C459D462-772A-58FC-8C46-B7559436C12C.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,14 @@ + + + + + +Control and +animation framework examplesThis section provides example code for the Control and Animation +framework. \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C47514B1-2DD2-5E75-962A-B8E6358E9880_d0e244786_href.png Binary file Symbian3/SDK/Source/GUID-C47514B1-2DD2-5E75-962A-B8E6358E9880_d0e244786_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C47514B1-2DD2-5E75-962A-B8E6358E9880_d0e248523_href.png Binary file Symbian3/SDK/Source/GUID-C47514B1-2DD2-5E75-962A-B8E6358E9880_d0e248523_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C4805C18-9BE7-47BA-9E50-D5F9CAAD36B7-master.png Binary file Symbian3/SDK/Source/GUID-C4805C18-9BE7-47BA-9E50-D5F9CAAD36B7-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C4805C18-9BE7-47BA-9E50-D5F9CAAD36B7_d0e58870_href.png Binary file Symbian3/SDK/Source/GUID-C4805C18-9BE7-47BA-9E50-D5F9CAAD36B7_d0e58870_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C4805C18-9BE7-47BA-9E50-D5F9CAAD36B7_d0e59093_href.png Binary file Symbian3/SDK/Source/GUID-C4805C18-9BE7-47BA-9E50-D5F9CAAD36B7_d0e59093_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C4805C18-9BE7-47BA-9E50-D5F9CAAD36B7_d0e64417_href.png Binary file Symbian3/SDK/Source/GUID-C4805C18-9BE7-47BA-9E50-D5F9CAAD36B7_d0e64417_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C4805C18-9BE7-47BA-9E50-D5F9CAAD36B7_d0e64639_href.png Binary file Symbian3/SDK/Source/GUID-C4805C18-9BE7-47BA-9E50-D5F9CAAD36B7_d0e64639_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C4C8395E-F982-4D6A-88D3-28EDC494817F.dita --- a/Symbian3/SDK/Source/GUID-C4C8395E-F982-4D6A-88D3-28EDC494817F.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-C4C8395E-F982-4D6A-88D3-28EDC494817F.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,85 +1,85 @@ - - - - - -Requesting -RAM AsynchronouslyThis section describes how an application can request for free -RAM asynchronously. -

                Perform the steps -described in Allowing -Large Memory Allocation.

                 -

                Requesting -free RAM asynchronously is recommended as the application is not blocked during -the method call handling.

                 - -Start an asynchronous -request for a block of memory. -CMemoryAllocatingObject::StartFunctionalityRequiringAllocationL() - { - User::LeaveIfError(iOomMonitorSession.Connect()); - iMemoryRequester = CMemoryRequester::NewL(iOomMonitorSession, *this); - iMemoryRequester->Start(KLargeValueToAllocate); - } - - -Implement the active -object and request for free memory. -void CMemoryRequester::Start(TInt aBytesRequested) - { - iOomMonitorSession.RequestFreeMemory(aBytesRequested, iStatus); - SetActive(); - } - - - -

                The following code snippet illustrates an asynchronous request -for free RAM allocation:

                const TInt KLargeValueToAllocate = 2097152; //2MB - -// Start an asynchronous request for block of memory -CMemoryAllocatingObject::StartFunctionalityRequiringAllocationL() - { - User::LeaveIfError(iOomMonitorSession.Connect()); - iMemoryRequester = CMemoryRequester::NewL(iOomMonitorSession, *this); - iMemoryRequester->Start(KLargeValueToAllocate); - } - -// Called when the asynchronous request is completed -CMemoryAllocatingObject::MemoryRequestCompleteL(TInt aResult) - { - if (aResult == KErrNone) - { - DoFunctionRequiring_KLargeValueToAllocate_BytesL(); - } - iOomMonitorSession.Close(); - } -The active object implementation is the following: - -// Start an asynchronous request for block of memory -void CMemoryRequester::Start(TInt aBytesRequested) - { - iOomMonitorSession.RequestFreeMemory(aBytesRequested, iStatus); - SetActive(); - } - - -// Called when the asynchronous request is completed -void CMemoryRequester::RunL() - { - iObserver.MemoryRequestCompleteL(iStatus.Int()); - } -                 -                 -OOM Monitor -Priority -OOM Monitor -Overview -OOM Monitor -Reference + + + + + +Requesting +RAM AsynchronouslyThis section describes how an application can request for free +RAM asynchronously. +

                Perform the steps +described in Allowing +Large Memory Allocation.

                 +

                Requesting +free RAM asynchronously is recommended as the application is not blocked during +the method call handling.

                 + +Start an asynchronous +request for a block of memory. +CMemoryAllocatingObject::StartFunctionalityRequiringAllocationL() + { + User::LeaveIfError(iOomMonitorSession.Connect()); + iMemoryRequester = CMemoryRequester::NewL(iOomMonitorSession, *this); + iMemoryRequester->Start(KLargeValueToAllocate); + } + + +Implement the active +object and request for free memory. +void CMemoryRequester::Start(TInt aBytesRequested) + { + iOomMonitorSession.RequestFreeMemory(aBytesRequested, iStatus); + SetActive(); + } + + + +

                The following code snippet illustrates an asynchronous request +for free RAM allocation:

                const TInt KLargeValueToAllocate = 2097152; //2MB + +// Start an asynchronous request for block of memory +CMemoryAllocatingObject::StartFunctionalityRequiringAllocationL() + { + User::LeaveIfError(iOomMonitorSession.Connect()); + iMemoryRequester = CMemoryRequester::NewL(iOomMonitorSession, *this); + iMemoryRequester->Start(KLargeValueToAllocate); + } + +// Called when the asynchronous request is completed +CMemoryAllocatingObject::MemoryRequestCompleteL(TInt aResult) + { + if (aResult == KErrNone) + { + DoFunctionRequiring_KLargeValueToAllocate_BytesL(); + } + iOomMonitorSession.Close(); + } +The active object implementation is the following: + +// Start an asynchronous request for block of memory +void CMemoryRequester::Start(TInt aBytesRequested) + { + iOomMonitorSession.RequestFreeMemory(aBytesRequested, iStatus); + SetActive(); + } + + +// Called when the asynchronous request is completed +void CMemoryRequester::RunL() + { + iObserver.MemoryRequestCompleteL(iStatus.Int()); + } +                 +                 +OOM Monitor +Priority +OOM Monitor +Overview +OOM Monitor +Reference                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C4D0B083-CCF9-52BD-A6BC-5187BEF3B0CB_d0e165576_href.png Binary file Symbian3/SDK/Source/GUID-C4D0B083-CCF9-52BD-A6BC-5187BEF3B0CB_d0e165576_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C4D0B083-CCF9-52BD-A6BC-5187BEF3B0CB_d0e172177_href.png Binary file Symbian3/SDK/Source/GUID-C4D0B083-CCF9-52BD-A6BC-5187BEF3B0CB_d0e172177_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C4D0F943-442D-5F3B-BB5E-6B52C33ABBC6_d0e169146_href.jpg Binary file Symbian3/SDK/Source/GUID-C4D0F943-442D-5F3B-BB5E-6B52C33ABBC6_d0e169146_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C4D0F943-442D-5F3B-BB5E-6B52C33ABBC6_d0e175747_href.jpg Binary file Symbian3/SDK/Source/GUID-C4D0F943-442D-5F3B-BB5E-6B52C33ABBC6_d0e175747_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C4E728B4-3E84-49A4-83CB-DF146420D78A.dita --- a/Symbian3/SDK/Source/GUID-C4E728B4-3E84-49A4-83CB-DF146420D78A.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-C4E728B4-3E84-49A4-83CB-DF146420D78A.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,109 +1,107 @@ - - - - - -Stylus -pop-up menu -

                Stylus pop-up menu is the primary menu for showing item-specific options. -Item-specific options are placed in the stylus pop-up menu that is activated -with touch down and hold on an item. It can be attached to almost all the -items.

                - -Stylus pop-up menu opened from a preview pop-up. A tap on any other -name or even anywhere else on the screen closes the stylus pop-up menu without -moving the focus. - - -

                It is a separate pop-up mainly used when a view cannot offer dynamic functions, -and the pop-up only offers tap-enabled functions. The stylus pop-up menu can -also be used directly on top of applications. For example, on an image in -Browser, the stylus pop-up menu can be used for offering Save as… and -similar options.

                -

                Following are the guidelines to be followed while designing the menu:

                -
                  -

                • Item-specific pop-up menu should not be used with buttons and multi-selection -list or grid items.

                  • -

                • Stylus pop-up menu should have only six items.

                  • -

                • If used for items other than item-specific menu items, it is recommended -to open the pop-up with touch down and hold.

                  • -

                • Stylus pop-up menu has no sub-menus.

                  • -

                • Functions that are performed via touch down and release are not duplicated -in the stylus pop-up menu. For example, 'Open' or 'Change' should not be in -the stylus pop-up menu.

                  • -
                -

                Background is not dimmed when the stylus pop-up menu is shown. The menu -disappears automatically after six seconds (or as soon as the user selects -an item or taps outside the pop-up area).

                -

                The stylus pop-up menu is scrollable and a scrollbar is added if the number -of items exceeds what fits the component.

                -Default touch -events for Stylus pop-up menu - - - -

                User action

                 -

                State change

                 -

                Feedback

                 -                 - - - -

                Touch down

                 -

                No effect

                 -

                Highlight is shown.

                Tactile: Basic list effect and audio -feedback is provided with touch down event.

                 -                 - -

                Touch release

                 -

                The item is activated.

                 -

                Highlight disappears and stylus pop-up is closed.

                Tactile: -Basic list effect is provided with touch release event.

                 -                 - -

                Touch down and hold

                 -

                Inactive

                 -

                Tactile: No effect

                 -                 - -

                Touch down and move inside the stylus pop-up

                 -

                Refer to Dragging -and flicking events

                 -

                Tactile: Refer to Dragging -and flicking events.

                 -                 - -

                Touch down and move out of the stylus pop-up menu

                 -

                Refer to Dragging -and flicking events

                 -

                Tactile: Refer to Dragging -and flicking events.

                 -                 - -

                Touch down and release out of menu area

                 -

                Stylus pop-up menu disappears. No selection is made.

                 -

                Tactile: Opens via long touch, provides only the increasing long -touch effect during the touch down and hold event. No additional pop-up effect -is provided when the menu opens.

                 -                 - -

                Touch down and move horizontally

                 -

                Inactive

                 -

                Highlight stays on the item that is touched down before moving horizontally.

                Tactile: -No effect

                 -                 - - -
                -
                Using -stylus pop-up menus in C++ applications

                The API to use for creating -a stylus pop-up menu is the Stylus -pop-up menu API.

                For implementation information, see Displaying -commands in a context menu.

                + + + + + +Stylus +pop-up menu +

                Stylus pop-up menu is the primary menu for showing item-specific options. +Application only needs to tag items to be item-specific and the application +framework handles the remaining tasks. Item-specific options can +be attached to almost all the items.

                + +Stylus pop-up menu opened from a list. + + +

                Stylus pop-up is mainly used to offer dynamic functions, and the functions +supported by touch-enabled devices. The stylus pop-up menu can also be used +directly on top of applications. For example, on an image in Browser, the +stylus pop-up menu can be used for offering Save as… and +similar options.

                +

                Following are the guidelines to be followed while designing the menu:

                +
                  +

                • Item-specific pop-up menu should not be used with buttons and multi-selection +list or grid items.

                  • +

                • Stylus pop-up menu should have only six items.

                  • +

                • If used for items other than item-specific menu items, it is recommended +to open the pop-up with touch down and hold.

                  • +

                • Stylus pop-up menu has no sub-menus.

                  • +

                • Functions that are performed via touch down and release are not duplicated +in the stylus pop-up menu. For example, 'Open' or 'Change' should not be in +the stylus pop-up menu.

                  • +
                +

                Background is not dimmed when the stylus pop-up menu is shown. The menu +disappears automatically after six seconds (or as soon as the user selects +an item or taps outside the pop-up area).

                +

                The stylus pop-up menu is scrollable and a scrollbar is added if the number +of items exceeds what fits the component.

                +Default touch +events for Stylus pop-up menu + + + +

                User action

                 +

                State change

                 +

                Feedback

                 +                 + + + +

                Touch down

                 +

                No effect

                 +

                Highlight is shown.

                Tactile: Basic list effect and audio +feedback is provided with touch down event.

                 +                 + +

                Touch release

                 +

                The item is activated.

                 +

                Highlight disappears and stylus pop-up is closed.

                Tactile: +Basic list effect is provided with touch release event.

                 +                 + +

                Touch down and hold

                 +

                Inactive

                 +

                Tactile: No effect

                 +                 + +

                Touch down and move inside the stylus pop-up

                 +

                Refer to Dragging +and flicking events

                 +

                Tactile: Refer to Dragging +and flicking events.

                 +                 + +

                Touch down and move out of the stylus pop-up menu

                 +

                Refer to Dragging +and flicking events

                 +

                Tactile: Refer to Dragging +and flicking events.

                 +                 + +

                Touch down and release out of menu area

                 +

                Stylus pop-up menu disappears. No selection is made.

                 +

                Tactile: Opens via long touch, provides only the increasing long +touch effect during the touch down and hold event. No additional pop-up effect +is provided when the menu opens.

                 +                 + +

                Touch down and move horizontally

                 +

                Inactive

                 +

                Highlight stays on the item that is touched down before moving horizontally.

                Tactile: +No effect

                 +                 + + +
                +
                Using +stylus pop-up menus in applications

                The API to use for creating +a stylus pop-up menu is the Stylus +pop-up menu API.

                For implementation information, see Displaying +commands in a context menu.

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C4FDDBD9-2B29-5A59-AA29-855D1BE1354A.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-C4FDDBD9-2B29-5A59-AA29-855D1BE1354A.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,27 @@ + + + + + +Scroll: +simple scrolling +
                Description

                The Scroll example +demonstrates simple scrolling using pointer repeat events. It uses RWindowBase::RequestPointerRepeatEvent(), +which ensures that holding down the pointer (or either mouse button on the +Emulator) results in a smooth scroll.

                +
                Download

                Click +on the following link to download the example: Scroll.zip

                Click: browse to view the example code.

                +
                Class Summary

                RWindowHandle

                RWindowTreeNode

                RWindowBase

                RWindowGroup

                CWindowGc

                +
                Running on the emulator

                Clicking the left mouse +button causes the line to scroll up, clicking the right mouse button causes +it to scroll down.

                +
                Running on the target phone

                Tapping on the numbered +window causes the line to scroll up. The behaviour invoked by the right mouse +button click is unavailable on the target phone.

                +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C549EC51-D81F-5AEC-80EA-EF83B2D9AF51.dita --- a/Symbian3/SDK/Source/GUID-C549EC51-D81F-5AEC-80EA-EF83B2D9AF51.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-C549EC51-D81F-5AEC-80EA-EF83B2D9AF51.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,27 +1,27 @@ - - - - - -Structure -of a heapA heap consists of two lists of cells; the list of allocated cells -and the list of free cells. -

                A heap simply consists of two lists of cells; one is the list of allocated -cells and the other the list of free cells. Each list is anchored in the heap -object.

                -

                A cell consists of a cell header followed by the body of the cell itself. -The body of the cell is the area of memory which is considered allocated.

                -

                The cell header is a struct of type RHeap::SCell defined -as part of the RHeap class in e32std.h.

                -

                The following diagram shows a typical mix of free and allocated cells.

                - -Example of the allocated and free cells in a heap - - + + + + + +Structure +of a heapA heap consists of two lists of cells; the list of allocated cells +and the list of free cells. +

                A heap simply consists of two lists of cells; one is the list of allocated +cells and the other the list of free cells. Each list is anchored in the heap +object.

                +

                A cell consists of a cell header followed by the body of the cell itself. +The body of the cell is the area of memory which is considered allocated.

                +

                The cell header is a struct of type RHeap::SCell defined +as part of the RHeap class in e32std.h.

                +

                The following diagram shows a typical mix of free and allocated cells.

                + +Example of the allocated and free cells in a heap + +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C588B869-6940-42B2-84F9-71467F6A4306_d0e4697_href.png Binary file Symbian3/SDK/Source/GUID-C588B869-6940-42B2-84F9-71467F6A4306_d0e4697_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C588B869-6940-42B2-84F9-71467F6A4306_d0e5972_href.png Binary file Symbian3/SDK/Source/GUID-C588B869-6940-42B2-84F9-71467F6A4306_d0e5972_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C5AC5FAF-A55F-44B5-BB43-858861BAB11E-master.png Binary file Symbian3/SDK/Source/GUID-C5AC5FAF-A55F-44B5-BB43-858861BAB11E-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C5C42C02-1C22-5537-B966-0F5F78E4D7BE_d0e230564_href.png Binary file Symbian3/SDK/Source/GUID-C5C42C02-1C22-5537-B966-0F5F78E4D7BE_d0e230564_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C5C42C02-1C22-5537-B966-0F5F78E4D7BE_d0e234301_href.png Binary file Symbian3/SDK/Source/GUID-C5C42C02-1C22-5537-B966-0F5F78E4D7BE_d0e234301_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C5DDFD3F-7778-56D6-A10B-741959206C5F_d0e314550_href.png Binary file Symbian3/SDK/Source/GUID-C5DDFD3F-7778-56D6-A10B-741959206C5F_d0e314550_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C5DDFD3F-7778-56D6-A10B-741959206C5F_d0e320944_href.png Binary file Symbian3/SDK/Source/GUID-C5DDFD3F-7778-56D6-A10B-741959206C5F_d0e320944_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C60DAE3D-7FB9-5619-9E5D-476A430705AF.dita --- a/Symbian3/SDK/Source/GUID-C60DAE3D-7FB9-5619-9E5D-476A430705AF.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-C60DAE3D-7FB9-5619-9E5D-476A430705AF.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,104 +1,104 @@ - - - - - -Querying -a databaseThis tutorial shows you how to create a simple SQL database query. -
                Introduction

                This -tutorial shows you how to wrap a SQL query statement into an RSqlStatement object -to query a database.

                The SQL statement used for the tutorial is shown -here:

                SELECT name FROM countries WHERE population > 10

                The (SELECT) -results of the query will be the value in the 'name' column FROM the -'countries' table WHERE the value of the -'population' column of the same record is > the -value specified.

                -
                Procedure
                  -

                1. Prepare the Statement:

                  The -steps to prepare a SQL statement are shown here.

                    -

                  1. Set up some constants -used by the SQL statement object to define the SQL query:

                    _LIT(kName,"name"); -_LIT(kPopulation,"population"); -_LIT(kVal,":Value"); -_LIT(kQueryString,"SELECT name FROM countries WHERE population > :Value");

                    This -defines the query parameters.

                    2. -

                  2. Instantiate the RSqlStatement SQL -statement:

                    RSqlStatement myStatement;

                    3. -

                  3. Define the indices to -be used in the search:

                    TInt nameIndex = myStatement.ColumnIndex(kName); -TInt populationIndex = myStatement.ColumnIndex(kPopulation);

                    4. -

                  4. Set the 32-bit integer -value for the SQL parameter 'value':

                    TInt parameterIndex = myStatement.ParameterIndex(kVal); -err = myStatement.BindInt(parameterIndex,10);

                    The SQL -parameter to which the integer is being assigned is identified by the constant kVal from:

                    _LIT(kVal,":Value"); -... -...WHERE population > :Value")

                    The parameter plus constant, -along with other parts of the statement, are converted into:

                    in SQL -syntax.

                    5. -

                  5. Prepare the statement:

                    TInt err; -err = myStatement.Prepare(countriesDatabase,kQueryString);

                    This -creates a parameterised SQL statement executable.

                    6. -
                  2. -

                2. Run the SQL query:

                    -

                  1. Search the records until -a match is found:

                    while((err = myStatement.Next()) == KSqlAtRow) - { - Do something with the query results - }

                    Next() fires the executable SQL statement and stops -at and returns the matched record.

                    Do something if no results are -found.

                    if(err == KSqlAtEnd) - <OK - no more records>; -else - <process the error>;

                    2. -
                  3. -

                3. The query is done and -you have the results. In this section we look at a simple way to do something -with the results and we close the SQL statement object.

                    -

                  1. Get the results of the -search:

                    TPtrC myData; -myData = myStatement.ColumnTextL(nameIndex); -RDebug::Print(_L("Name=%d\n"), myData);

                    2. -

                  2. Close the SQL search -statement:

                    err = myStatement.Close();

                    When -the database search is finished the object should be closed to free up resources.

                    3. -
                  4. -

                This section deals with finding and returning the first matching -record

                only. Getting all matches in a database is briefly discussed -at the end of this

                section.

                - -

                Now that you have -performed a basic database query you can start thinking about more advanced -querying options. The following will show you how:

                  -

                • Querying -Databases: Basic

                  • -

                • Reading -to a buffer

                  • -

                • Reading -to memory

                  • -

                • Reading -to a data stream

                  • -
                -                 -SQL Overview - -Inserting -a row into a table -Deleting -Rows from a Table -Reading to -a buffer -Reading to -memory -Reading to -a data stream -Writing to -a data stream -Scalar queries - + + + + + +Querying +a databaseThis tutorial shows you how to create a simple SQL database query. +
                Introduction

                This +tutorial shows you how to wrap a SQL query statement into an RSqlStatement object +to query a database.

                The SQL statement used for the tutorial is shown +here:

                SELECT name FROM countries WHERE population > 10

                The (SELECT) +results of the query will be the value in the 'name' column FROM the +'countries' table WHERE the value of the +'population' column of the same record is > the +value specified.

                +
                Procedure
                  +

                1. Prepare the Statement:

                  The +steps to prepare a SQL statement are shown here.

                    +

                  1. Set up some constants +used by the SQL statement object to define the SQL query:

                    _LIT(kName,"name"); +_LIT(kPopulation,"population"); +_LIT(kVal,":Value"); +_LIT(kQueryString,"SELECT name FROM countries WHERE population > :Value");

                    This +defines the query parameters.

                    2. +

                  2. Instantiate the RSqlStatement SQL +statement:

                    RSqlStatement myStatement;

                    3. +

                  3. Define the indices to +be used in the search:

                    TInt nameIndex = myStatement.ColumnIndex(kName); +TInt populationIndex = myStatement.ColumnIndex(kPopulation);

                    4. +

                  4. Set the 32-bit integer +value for the SQL parameter 'value':

                    TInt parameterIndex = myStatement.ParameterIndex(kVal); +err = myStatement.BindInt(parameterIndex,10);

                    The SQL +parameter to which the integer is being assigned is identified by the constant kVal from:

                    _LIT(kVal,":Value"); +... +...WHERE population > :Value")

                    The parameter plus constant, +along with other parts of the statement, are converted into:

                    in SQL +syntax.

                    5. +

                  5. Prepare the statement:

                    TInt err; +err = myStatement.Prepare(countriesDatabase,kQueryString);

                    This +creates a parameterised SQL statement executable.

                    6. +
                  2. +

                2. Run the SQL query:

                    +

                  1. Search the records until +a match is found:

                    while((err = myStatement.Next()) == KSqlAtRow) + { + Do something with the query results + }

                    Next() fires the executable SQL statement and stops +at and returns the matched record.

                    Do something if no results are +found.

                    if(err == KSqlAtEnd) + <OK - no more records>; +else + <process the error>;

                    2. +
                  3. +

                3. The query is done and +you have the results. In this section we look at a simple way to do something +with the results and we close the SQL statement object.

                    +

                  1. Get the results of the +search:

                    TPtrC myData; +myData = myStatement.ColumnTextL(nameIndex); +RDebug::Print(_L("Name=%d\n"), myData);

                    2. +

                  2. Close the SQL search +statement:

                    err = myStatement.Close();

                    When +the database search is finished the object should be closed to free up resources.

                    3. +
                  4. +

                This section deals with finding and returning the first matching +record

                only. Getting all matches in a database is briefly discussed +at the end of this

                section.

                + +

                Now that you have +performed a basic database query you can start thinking about more advanced +querying options. The following will show you how:

                  +

                • Querying +Databases: Basic

                  • +

                • Reading +to a buffer

                  • +

                • Reading +to memory

                  • +

                • Reading +to a data stream

                  • +
                +                 +SQL Overview + +Inserting +a row into a table +Deleting +Rows from a Table +Reading to +a buffer +Reading to +memory +Reading to +a data stream +Writing to +a data stream +Scalar queries +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C60DC070-572B-5960-B394-550426FDB909.dita --- a/Symbian3/SDK/Source/GUID-C60DC070-572B-5960-B394-550426FDB909.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-C60DC070-572B-5960-B394-550426FDB909.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,199 +1,199 @@ - - - - - - Advanced -Pointer TutorialThis tutorial provides step-by-step instructions and sample code -to help you write applications using advanced pointers. -

                Variant: ScreenPlay. Target -audience: Application developers.

                -
                Required background

                This topic builds on the material -in the following topics:

                  -

                • Advanced -Pointer Overview

                  • -

                • Advanced -Pointer States and Event Communication

                  • -
                -
                Using advanced pointers

                This topic covers the following:

                  -

                • Enabling multi-touch for a window

                  • -

                • Getting Z coordinates from TPointerEvent

                  • -

                • Pinch zooming

                  • -
                -
                Enabling multi-touch -in a window
                  -

                1. RWindow provides -a handle to a standard window. Call RWindow to create an -instance of a window.

                  -RWindow window(ws); - -User::LeaveIfError(window.Construct(wg, reinterpret_cast<TUint32>(&wg) + 1)); -
                  2. -

                2. Call RWindow::EnableAdvancedPointers() to -enable advanced pointers. Then call RWindowBase::Activate() to -display the window and enable the window to receive events. RWindow inherits -from RWindowBase, so you can call the Activate() function -on RWindow.

                  -window.EnableAdvancedPointers(); -window.Activate(); -

                  When an application needs to receive advanced pointer events -in a window, it must call RWindowBase::EnableAdvancedPointers() for -the window before it is activated.

                  If advanced pointers are -not enabled for a window, it receives only standard TPointerEvent information -from a single pointer with no pressure and proximity data. The single pointer -environment rules describe the way in which pointer events coming from many -pointers in the multi-pointer model are transformed into events of one pointer. -They are necessary to ensure that old single-pointer applications work in -a multi-touch environment intuitively and as expected by the user.

                  However, -the new TPointerEvent types, EEnterCloseProximity, EExitCloseProximity, EEnterHighPressure and EExitHighPressure, are delivered to all windows, -even to those that do not enable advanced pointers.

                  3. -
                -
                Getting Z coordinates -from TPointerEvent
                  -

                1. Call TPointerEvent::AdvancedPointerEvent() on -a TPointerEvent to return a pointer to a TAdvancedPointerEvent.

                  -TZType aZType; -TPointerEvent& aPointerEvent; -TInt* aZ; -TInt* aPoint3D; - -TAdvancedPointerEvent *advancedP = aPointerEvent.AdvancedPointerEvent(); -

                  TPointerEvent is a struct that contains -details of a pointer event. TZType is a struct provided by -the programmer containing members to hold proximity, pressure, and "proximity -and pressure" data.

                  2. -

                2. Now we need to test -whether the pointer event contains advanced pointer data. If it is not an -advanced pointer, the code leaves.

                  If it is an advanced pointer, we -call functions to detect proximity, pressure, "proximity and pressure" data -and coordinates.

                  -if(!advancedP) - { - // The TPointerEvent isn't an instance of TAdvancedPointerEvent - User::Leave(KErrArgument); - } - -switch(aZType) - { - case EZTypeProximity: - aZ = advancedP->Proximity(); - aPoint3D = advancedP->Proximity3D(); - break; - case EZTypePressure: - aZ = advancedP->Pressure(); - aPoint3D = advancedP->Pressure3D(); - break; - case EZTypeProximityAndPressure: - aZ = advancedP->ProximityAndPressure(); - aPoint3D = advancedP->ProximityAndPressure3D(); - break; - default: - User::Leave(KErrArgument); - break; - } -
                    -

                  • TAdvancedPointerEvent::Proximity() returns -the proximity.

                    • -

                  • TAdvancedPointerEvent::Pressure() returns -the pressure.

                    • -

                  • TAdvancedPointerEvent::ProximityAndPressure() returns -the proximity and pressure combined.

                    • -

                  • TAdvancedPointerEvent:: -Position3D() returns the proximity and the X, Y and Z coordinates.

                    • -

                  • TAdvancedPointerEvent::Pressure3D() returns -the pressure and the X and Y coordinates.

                    • -

                  Proximity is always negative and pressure is always positive. -Internally they are combined together as a Z coordinate. When Z > 0, the proximity -is 0 and the Z value represents the pressure. When Z < 0, the pressure -is 0 and the Z value represents the proximity. Some APIs use only a Z coordinate -(such as the threshold getters and setters and TAdvancedPointerEvent::ProximityAndPressure()). -In these, the Z coordinate is interpreted in terms of pressure and proximity.

                  3. -
                - Relationships between the pointer proximity, pressure and Z - coordinate - -
                -
                Pinch zooming

                This -example shows an easy way to pinch zoom an image when the screen receives -pointer events from two pointers. There are two functions in this code that -must be implemented by the programmer: BitmapCoordinates() and MoveBitmap(). -They are not included in the example because they involve complex calculations -that are not related to advanced pointers.

                The high-level steps to -perform pinch zooming are:

                  -

                1. Define the coordinates, -equivalent to the given on-screen coordinates. In the code example, this is -done using the function BitmapCoordinates().

                  2. -

                2. Define the ID of the -pointer by using TAdvancedPointerEvent::PointerNumber(). -If the device can handle two pointers (two fingers) at the same time, their -numbers are 0 and 1. The pointer number enables you to distinguish a given -pointer from other pointers.

                  3. -

                3. For each pointer assign -its coordinates to a local variable. We assume there are only two pointers -handled by the system here.

                  4. -

                4. Use the MoveBitmap() function -to achieve the zoom effect.

                  -/** -Receives pointer events from two pointers to perform Pinch Zoom of the image. -Function will finish when EButton1Up is received for any of the pointers. -@param aPointer1 Coordinates of pointer number 1 when zoom is started -@param aPointer2 Coordinates of pointer number 2 when zoom is started -*/ - -void PinchZoom(TPoint aPointer1, TPoint aPointer2) - { - TPoint actualP1 = aPointer1; - TPoint actualP2 = aPointer2; - - // translate on-screen pointer coordinates to coordinates of displayed bitmap - TPoint bitmapCatching1 = BitmapCoordinates(aPointer1); - TPoint bitmapCatching2 = BitmapCoordinates(aPointer2); - - TBool repaint = EFalse; - - while (ETrue) - { - TAdvancedPointerEvent event = GetNextPointerEvent(); - - if (event.iType == TPointerEvent::EDrag) - { - if (event.PointerNumber() == 1) - { - actualP1 = event.iPosition; - repaint = ETrue; - } - else if (event.PointerNumber() == 2) - { - actualP2 = event.iPosition; - repaint = ETrue; - } - } - else if (event.iType == TPointerEvent::EButton1Up) - { - break; - } - - if (repaint) - { - // move bitmap on the screen in the way that - // bitmapCatching1 point of the bitmap will be displayed at actualP1 screen coordinate, - // bitmapCatching2 point of the bitmap will be displayed at actualP2 screen coordinate. - MoveBitmap(bitmapCatching1, actualP1, bitmapCatching2, actualP2); - repaint = EFalse; - } - } - } -
                  5. -
                -                 -Advanced -Pointer Overview -Advanced -Pointer States and Event Communication + + + + + + Advanced +Pointer TutorialThis tutorial provides step-by-step instructions and sample code +to help you write applications using advanced pointers. +

                Variant: ScreenPlay. Target +audience: Application developers.

                +
                Required background

                This topic builds on the material +in the following topics:

                  +

                • Advanced +Pointer Overview

                  • +

                • Advanced +Pointer States and Event Communication

                  • +
                +
                Using advanced pointers

                This topic covers the following:

                  +

                • Enabling multi-touch for a window

                  • +

                • Getting Z coordinates from TPointerEvent

                  • +

                • Pinch zooming

                  • +
                +
                Enabling multi-touch +in a window
                  +

                1. RWindow provides +a handle to a standard window. Call RWindow to create an +instance of a window.

                  +RWindow window(ws); + +User::LeaveIfError(window.Construct(wg, reinterpret_cast<TUint32>(&wg) + 1)); +
                  2. +

                2. Call RWindow::EnableAdvancedPointers() to +enable advanced pointers. Then call RWindowBase::Activate() to +display the window and enable the window to receive events. RWindow inherits +from RWindowBase, so you can call the Activate() function +on RWindow.

                  +window.EnableAdvancedPointers(); +window.Activate(); +

                  When an application needs to receive advanced pointer events +in a window, it must call RWindowBase::EnableAdvancedPointers() for +the window before it is activated.

                  If advanced pointers are +not enabled for a window, it receives only standard TPointerEvent information +from a single pointer with no pressure and proximity data. The single pointer +environment rules describe the way in which pointer events coming from many +pointers in the multi-pointer model are transformed into events of one pointer. +They are necessary to ensure that old single-pointer applications work in +a multi-touch environment intuitively and as expected by the user.

                  However, +the new TPointerEvent types, EEnterCloseProximity, EExitCloseProximity, EEnterHighPressure and EExitHighPressure, are delivered to all windows, +even to those that do not enable advanced pointers.

                  3. +
                +
                Getting Z coordinates +from TPointerEvent
                  +

                1. Call TPointerEvent::AdvancedPointerEvent() on +a TPointerEvent to return a pointer to a TAdvancedPointerEvent.

                  +TZType aZType; +TPointerEvent& aPointerEvent; +TInt* aZ; +TInt* aPoint3D; + +TAdvancedPointerEvent *advancedP = aPointerEvent.AdvancedPointerEvent(); +

                  TPointerEvent is a struct that contains +details of a pointer event. TZType is a struct provided by +the programmer containing members to hold proximity, pressure, and "proximity +and pressure" data.

                  2. +

                2. Now we need to test +whether the pointer event contains advanced pointer data. If it is not an +advanced pointer, the code leaves.

                  If it is an advanced pointer, we +call functions to detect proximity, pressure, "proximity and pressure" data +and coordinates.

                  +if(!advancedP) + { + // The TPointerEvent isn't an instance of TAdvancedPointerEvent + User::Leave(KErrArgument); + } + +switch(aZType) + { + case EZTypeProximity: + aZ = advancedP->Proximity(); + aPoint3D = advancedP->Proximity3D(); + break; + case EZTypePressure: + aZ = advancedP->Pressure(); + aPoint3D = advancedP->Pressure3D(); + break; + case EZTypeProximityAndPressure: + aZ = advancedP->ProximityAndPressure(); + aPoint3D = advancedP->ProximityAndPressure3D(); + break; + default: + User::Leave(KErrArgument); + break; + } +
                    +

                  • TAdvancedPointerEvent::Proximity() returns +the proximity.

                    • +

                  • TAdvancedPointerEvent::Pressure() returns +the pressure.

                    • +

                  • TAdvancedPointerEvent::ProximityAndPressure() returns +the proximity and pressure combined.

                    • +

                  • TAdvancedPointerEvent:: +Position3D() returns the proximity and the X, Y and Z coordinates.

                    • +

                  • TAdvancedPointerEvent::Pressure3D() returns +the pressure and the X and Y coordinates.

                    • +

                  Proximity is always negative and pressure is always positive. +Internally they are combined together as a Z coordinate. When Z > 0, the proximity +is 0 and the Z value represents the pressure. When Z < 0, the pressure +is 0 and the Z value represents the proximity. Some APIs use only a Z coordinate +(such as the threshold getters and setters and TAdvancedPointerEvent::ProximityAndPressure()). +In these, the Z coordinate is interpreted in terms of pressure and proximity.

                  3. +
                + Relationships between the pointer proximity, pressure and Z + coordinate + +
                +
                Pinch zooming

                This +example shows an easy way to pinch zoom an image when the screen receives +pointer events from two pointers. There are two functions in this code that +must be implemented by the programmer: BitmapCoordinates() and MoveBitmap(). +They are not included in the example because they involve complex calculations +that are not related to advanced pointers.

                The high-level steps to +perform pinch zooming are:

                  +

                1. Define the coordinates, +equivalent to the given on-screen coordinates. In the code example, this is +done using the function BitmapCoordinates().

                  2. +

                2. Define the ID of the +pointer by using TAdvancedPointerEvent::PointerNumber(). +If the device can handle two pointers (two fingers) at the same time, their +numbers are 0 and 1. The pointer number enables you to distinguish a given +pointer from other pointers.

                  3. +

                3. For each pointer assign +its coordinates to a local variable. We assume there are only two pointers +handled by the system here.

                  4. +

                4. Use the MoveBitmap() function +to achieve the zoom effect.

                  +/** +Receives pointer events from two pointers to perform Pinch Zoom of the image. +Function will finish when EButton1Up is received for any of the pointers. +@param aPointer1 Coordinates of pointer number 1 when zoom is started +@param aPointer2 Coordinates of pointer number 2 when zoom is started +*/ + +void PinchZoom(TPoint aPointer1, TPoint aPointer2) + { + TPoint actualP1 = aPointer1; + TPoint actualP2 = aPointer2; + + // translate on-screen pointer coordinates to coordinates of displayed bitmap + TPoint bitmapCatching1 = BitmapCoordinates(aPointer1); + TPoint bitmapCatching2 = BitmapCoordinates(aPointer2); + + TBool repaint = EFalse; + + while (ETrue) + { + TAdvancedPointerEvent event = GetNextPointerEvent(); + + if (event.iType == TPointerEvent::EDrag) + { + if (event.PointerNumber() == 1) + { + actualP1 = event.iPosition; + repaint = ETrue; + } + else if (event.PointerNumber() == 2) + { + actualP2 = event.iPosition; + repaint = ETrue; + } + } + else if (event.iType == TPointerEvent::EButton1Up) + { + break; + } + + if (repaint) + { + // move bitmap on the screen in the way that + // bitmapCatching1 point of the bitmap will be displayed at actualP1 screen coordinate, + // bitmapCatching2 point of the bitmap will be displayed at actualP2 screen coordinate. + MoveBitmap(bitmapCatching1, actualP1, bitmapCatching2, actualP2); + repaint = EFalse; + } + } + } +
                  5. +
                +                 +Advanced +Pointer Overview +Advanced +Pointer States and Event Communication                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C64D200D-32A9-5F50-ACF1-4D93DDD0B0A4_d0e333524_href.png Binary file Symbian3/SDK/Source/GUID-C64D200D-32A9-5F50-ACF1-4D93DDD0B0A4_d0e333524_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C64D200D-32A9-5F50-ACF1-4D93DDD0B0A4_d0e339681_href.png Binary file Symbian3/SDK/Source/GUID-C64D200D-32A9-5F50-ACF1-4D93DDD0B0A4_d0e339681_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C6B65A53-BE0A-4C35-B355-379D9FE494F8_d0e66731_href.png Binary file Symbian3/SDK/Source/GUID-C6B65A53-BE0A-4C35-B355-379D9FE494F8_d0e66731_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C6DDF01D-DF54-5C65-9FAC-D3693D30819F_d0e268483_href.png Binary file Symbian3/SDK/Source/GUID-C6DDF01D-DF54-5C65-9FAC-D3693D30819F_d0e268483_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C6DDF01D-DF54-5C65-9FAC-D3693D30819F_d0e272191_href.png Binary file Symbian3/SDK/Source/GUID-C6DDF01D-DF54-5C65-9FAC-D3693D30819F_d0e272191_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C6E29524-AD59-4EBB-9004-13F731FA1F3C.dita --- a/Symbian3/SDK/Source/GUID-C6E29524-AD59-4EBB-9004-13F731FA1F3C.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-C6E29524-AD59-4EBB-9004-13F731FA1F3C.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,52 +1,124 @@ - - - - - -Other -Options menus -

                Certain Options menus are accessed in other ways than by using the Options -softkey. The usage of these menus is similar to the normal Options menu. Examples -of such menus are:

                -Other Options -menus - - - -Menu -Description - - - - -

                Context sensitive Options menu

                 -

                The Selection key opens this context sensitive Options menu when -there is no single intuitive function (such as opening the item in focus) -for it. The context sensitive Options menu only lists functions that:

                  -

                • Affect only the item in focus.

                  • -

                • Could be regarded as potentially intuitive.

                  • -

                • Are competing for the topmost place of the menu.

                  • -

                Other functions can be accessed through the Options softkey. The number -of items in the context sensitive Options menu is usually two or three; it -should never be more than four. As an example, in a message editor, the functions -in the context sensitive Options menu could be Send and Add recipient.

                In -case there are marked items in a list, the context sensitive Options menu -should include the Mark/Unmark functions. When a list is empty, it may make -sense to offer a Create new type of option in the context sensitive Options -menu, but only when it would be an appropriate function in the context.

                 -                 - -

                Editing menu

                 -

                Opened by pressing the Edit key in a text editor. Contains only -editing commands. See Editing -menu.

                 -                 - - + + + + + +Other +Options menus +

                Certain Options menus are accessed in other ways than by using the Options +softkey. The usage of these menus is similar to the normal Options menu. Examples +of such menus are:

                +
                Other Options +menus + + + +Menu +Description + + + + +

                Context sensitive Options menu

                 +

                In touch enabled devices, it is possible that touch release can +open a context specific options menu, if the user is browsing, for example, +a form or an editor or application specific layout. The Selection key can +also open this context sensitive Options menu (also known as CS menu) +when there is no single intuitive function (such as opening the item in focus) +for it.

                The context sensitive Options menu only lists functions that:

                  +

                • Affect only the item in focus.

                  • +

                • Could be regarded as potentially intuitive.

                  • +

                • Are competing for the topmost place of the menu.

                  • +

                The context-sensitive menu is a shorter version of the normal options +menu. It contains only the items that act upon the object touched or items +marked. It does not contain state-specific or application-specific items. +Context specific options menu should be used only if there is more than one +item in it but not more than four. As an example, in a message editor, the +functions in the context sensitive Options menu could be Send and Add recipient.

                Other +functions can be accessed through the Options softkey.

                In case there +are marked items in a list, the context sensitive Options menu should include +the Mark/Unmark functions. When a list is empty, it may make sense to offer +a Create new type of option in the context sensitive Options menu, but only +when it would be an appropriate function in the context.

                 +                 + +

                Editing menu

                 +

                Opened by pressing the Edit key in a text editor. Contains only +editing commands. See Editing +menu.

                 +                 + +

                Menu List

                 +

                Menu list is a temporary list, and typically displayed in a pop-up +window. Menu lists are used to select an item and do nothing else. Hence, +there are no Options menu available when a menu list is being browsed +(the Options menu itself is a menu list).

                If a high-priority event, +such as an incoming call, occurs when a menu list is open, the list is cancelled +and the new event takes control.

                +Menu list + +

                The API to use for menu lists is the Lists API. For implementation information, see Using the Lists API.

                 +                 + + +
                +

                +

                The default keypad functions in a menu list are the following:

                +Default key events +in a menu list + + + + + +Key +Action + + + + +

                Arrow up / down

                 +

                Moves the focus in the list.

                 +                 + +

                Arrow left / right

                 +

                Ignored (unless there is a submenu; see Submenus).

                 +                 + +

                Selection key

                 +

                Selects the item, does the associated function.

                 +                 + +

                Left softkey (Select)

                 +

                Selects the item, does the associated function.

                 +                 + +

                Right softkey (Cancel)

                 +

                Dismisses the menu; returns to the state preceding the opening of +the menu.

                 +                 + +

                Call creation key, Edit key

                 +

                Ignored.

                 +                 + +

                Numeric keypad

                 +

                Ignored.

                 +                 + +

                Clear key

                 +

                Ignored.

                 +                 + +

                Other keys

                 +

                Dismiss the menu and do the default action of the key.

                 +                 + +
                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C6E9D609-E82C-4FAC-9265-F6A4FF61049C.dita --- a/Symbian3/SDK/Source/GUID-C6E9D609-E82C-4FAC-9265-F6A4FF61049C.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-C6E9D609-E82C-4FAC-9265-F6A4FF61049C.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,97 +1,97 @@ - - - - - -Drawing -in the view architecture -

                The Symbian platform calls CCoeControl::Draw() when -a control area needs to be updated on the display. Controls may implement CCoeControl::Draw() or -leave the drawing to their child controls. For more information on control -hierarchies, see The -run-time control hierarchy.

                -

                The Symbian platform calls CCoeControl::Draw() for -the parent control first, and then recursively for each control.

                -

                Controls should override CCoeControl::Draw() to draw -their content. The override should do nothing else and should be as fast as -possible. For example, it is bad design to create fonts dynamically, and read -any bitmaps or resources while drawing. A good rule of thumb is that there -should not be trap handlers in the method override; any time-consuming functionality -that can be done beforehand should be cached.

                -

                In most cases controls are drawn on the display using the screen device -graphics context, accessed with CCoeControl::SystemGc(). -The graphics context provides a wide set of GDI (Graphics -Device Interface - common Symbian platform graphics API) drawing primitives -that can be used for drawing virtually anything on screen.

                -

                An example of a basic override of CCoeControl::Draw() for -a control that is a top-level window in an application is as follows:

                -void CMyAppView::Draw( const TRect& /*aRect*/ ) const - { - // Get the standard graphics context - CWindowGc& gc = SystemGc(); - gc.SetPenStyle( CGraphicsContext::ENullPen ); - gc.SetBrushColor( KRgbWhite); - gc.SetBrushStyle( CGraphicsContext::ESolidBrush ); - - // Gets the control's extent - TRect rect( Rect()); - - { - gc.Clear( rect ); - } - } - -

                , where

                -
                  -

                • CWindowGc& gc = SystemGc(); gets -the graphics context that is used when drawing the control.

                  • -

                • CWindowGc::SetPenStyle(), CWindowGc::SetBrushColor(), -and CWindowGc::SetBrushStyle() are used to set the drawing -primatives for the context.

                  • -

                • TRect gets the size of the control rectangle.

                  -
                  • -

                • CWindowGc:Clear(rect) clears the control -rectangle.

                  • -
                -
                Drawing with -caches -

                For controls that perform intensive drawing operations, the drawing -should be cached: a process also known as double-buffering. Here the drawing -is done to a memory context first and then in the CCoeControl::Draw() method -only the context's bitmap is passed to screen. In the Symbian platform, the -easiest way to implement a double buffer is to create a CFbsBitmap and -then bind a graphics context to that - this makes it possible to use the -same GDI interface for drawing as the display context. The drawing is done -to a memory bitmap buffer, and when the Symbian platform updates the invalidated -screen area, the memory buffer is copied to it. Double-buffering is a common -paradigm used in games, but can also be utilized in any application when performance -of drawing controls is important.

                -

                The following is a short example of how a double buffer is created and -used:

                -iGcBmp = new (ELeave) CWsBitmap(iEikonEnv->WsSession()); -User::LeaveIfError(iGcBmp->Create(aClientRect.Size(), iEikonEnv->ScreenDevice()->DisplayMode())); -iGcDevice = CFbsBitmapDevice::NewL(iGcBmp); -User::LeaveIfError(iGcDevice->CreateBitmapContext(iGc)); - -

                iGcBmp is a pointer to CWsBitmap, -the bitmap memory buffer, that is created with the same width and height as -the top-level window and with the same color bit depth as the display. iGcDevice is -a pointer to the CBitmapDevice device class and the context iGc holds -the CBitmapContext instance. iGc is -then used instead of CScreenGc, obtained from the CCoeControl::SystemGc() method, -when the control draws itself. The double-buffer drawing should be done outside -of the CCoeControl::Draw() method and can be called directly -when needed. Only at the end of the off-screen drawing is the memory buffer -flushed to the screen by calling CCoeControl::DrawDeferred()

                -void CMyDrawingExample::Draw(const TRect& /*aRect*/) const - { - SystemGc().BitBlt(TPoint(0, 0), iGcBmp); - } -
                + + + + + +Drawing +in the view architecture +

                The Symbian platform calls CCoeControl::Draw() when +a control area needs to be updated on the display. Controls may implement CCoeControl::Draw() or +leave the drawing to their child controls. For more information on control +hierarchies, see The +run-time control hierarchy.

                +

                The Symbian platform calls CCoeControl::Draw() for +the parent control first, and then recursively for each control.

                +

                Controls should override CCoeControl::Draw() to draw +their content. The override should do nothing else and should be as fast as +possible. For example, it is bad design to create fonts dynamically, and read +any bitmaps or resources while drawing. A good rule of thumb is that there +should not be trap handlers in the method override; any time-consuming functionality +that can be done beforehand should be cached.

                +

                In most cases controls are drawn on the display using the screen device +graphics context, accessed with CCoeControl::SystemGc(). +The graphics context provides a wide set of GDI (Graphics +Device Interface - common Symbian platform graphics API) drawing primitives +that can be used for drawing virtually anything on screen.

                +

                An example of a basic override of CCoeControl::Draw() for +a control that is a top-level window in an application is as follows:

                +void CMyAppView::Draw( const TRect& /*aRect*/ ) const + { + // Get the standard graphics context + CWindowGc& gc = SystemGc(); + gc.SetPenStyle( CGraphicsContext::ENullPen ); + gc.SetBrushColor( KRgbWhite); + gc.SetBrushStyle( CGraphicsContext::ESolidBrush ); + + // Gets the control's extent + TRect rect( Rect()); + + { + gc.Clear( rect ); + } + } + +

                , where

                +
                  +

                • CWindowGc& gc = SystemGc(); gets +the graphics context that is used when drawing the control.

                  • +

                • CWindowGc::SetPenStyle(), CWindowGc::SetBrushColor(), +and CWindowGc::SetBrushStyle() are used to set the drawing +primatives for the context.

                  • +

                • TRect gets the size of the control rectangle.

                  +
                  • +

                • CWindowGc:Clear(rect) clears the control +rectangle.

                  • +
                +
                Drawing with +caches +

                For controls that perform intensive drawing operations, the drawing +should be cached: a process also known as double-buffering. Here the drawing +is done to a memory context first and then in the CCoeControl::Draw() method +only the context's bitmap is passed to screen. In the Symbian platform, the +easiest way to implement a double buffer is to create a CFbsBitmap and +then bind a graphics context to that - this makes it possible to use the +same GDI interface for drawing as the display context. The drawing is done +to a memory bitmap buffer, and when the Symbian platform updates the invalidated +screen area, the memory buffer is copied to it. Double-buffering is a common +paradigm used in games, but can also be utilized in any application when performance +of drawing controls is important.

                +

                The following is a short example of how a double buffer is created and +used:

                +iGcBmp = new (ELeave) CWsBitmap(iEikonEnv->WsSession()); +User::LeaveIfError(iGcBmp->Create(aClientRect.Size(), iEikonEnv->ScreenDevice()->DisplayMode())); +iGcDevice = CFbsBitmapDevice::NewL(iGcBmp); +User::LeaveIfError(iGcDevice->CreateBitmapContext(iGc)); + +

                iGcBmp is a pointer to CWsBitmap, +the bitmap memory buffer, that is created with the same width and height as +the top-level window and with the same color bit depth as the display. iGcDevice is +a pointer to the CBitmapDevice device class and the context iGc holds +the CBitmapContext instance. iGc is +then used instead of CScreenGc, obtained from the CCoeControl::SystemGc() method, +when the control draws itself. The double-buffer drawing should be done outside +of the CCoeControl::Draw() method and can be called directly +when needed. Only at the end of the off-screen drawing is the memory buffer +flushed to the screen by calling CCoeControl::DrawDeferred()

                +void CMyDrawingExample::Draw(const TRect& /*aRect*/) const + { + SystemGc().BitBlt(TPoint(0, 0), iGcBmp); + } +
                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C71311A7-F747-57EB-B31F-6E634D5976A3.dita --- a/Symbian3/SDK/Source/GUID-C71311A7-F747-57EB-B31F-6E634D5976A3.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-C71311A7-F747-57EB-B31F-6E634D5976A3.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,44 +1,44 @@ - - - - - - Character -Conversion (Charconv) Framework Overview -

                The Symbian platform uses UTF-16 encoded Unicode text. The Charconv Framework -provides the APIs and converters to -convert characters between foreign encodings and Unicode (UTF-16).

                -

                -
                Architecture

                The Character Conversion Framework -comprises two components:

                  -

                • The Character Encoding -and Conversion Framework component is also referred to as Charconv Framework. -It contains built-in converters for many languages. It also provides APIs -for selecting built-in or plug-in converters.

                  • -

                • The Character Encoding -and Conversion Plug-ins component, also referred to as Charconv Plug-ins, -contains ECom plug-in -converters for various languages not supported by the built-in converters. -Device creators can write additional plug-in converters by implementing the CCharacterSetConverterPluginInterface interface.

                  • -
                - Charconv Framework collection - -

                -
                Using the Character Conversion Framework

                Application -developers can use the Charconv API to convert text between various encodings -and Unicode.

                Device creators can also write additional -plug-in converters for specific encodings.

                -                 -Character -Conversion (Charconv) Framework Concepts -Character -Encoding and Conversion Framework Component -Character -Encoding and Conversion Plug-ins Component + + + + + + Character +Conversion (Charconv) Framework Overview +

                The Symbian platform uses UTF-16 encoded Unicode text. The Charconv Framework +provides the APIs and converters to +convert characters between foreign encodings and Unicode (UTF-16).

                +

                +
                Architecture

                The Character Conversion Framework +comprises two components:

                  +

                • The Character Encoding +and Conversion Framework component is also referred to as Charconv Framework. +It contains built-in converters for many languages. It also provides APIs +for selecting built-in or plug-in converters.

                  • +

                • The Character Encoding +and Conversion Plug-ins component, also referred to as Charconv Plug-ins, +contains ECom plug-in +converters for various languages not supported by the built-in converters. +Device creators can write additional plug-in converters by implementing the CCharacterSetConverterPluginInterface interface.

                  • +
                + Charconv Framework collection + +

                +
                Using the Character Conversion Framework

                Application +developers can use the Charconv API to convert text between various encodings +and Unicode.

                Device creators can also write additional +plug-in converters for specific encodings.

                +                 +Character +Conversion (Charconv) Framework Concepts +Character +Encoding and Conversion Framework Component +Character +Encoding and Conversion Plug-ins Component                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C7560CDB-E8F4-55E8-953C-3731B690CF76_d0e272103_href.jpg Binary file Symbian3/SDK/Source/GUID-C7560CDB-E8F4-55E8-953C-3731B690CF76_d0e272103_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C7560CDB-E8F4-55E8-953C-3731B690CF76_d0e275784_href.jpg Binary file Symbian3/SDK/Source/GUID-C7560CDB-E8F4-55E8-953C-3731B690CF76_d0e275784_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C75726D3-E815-503D-8267-26DA27AD4787.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-C75726D3-E815-503D-8267-26DA27AD4787.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,122 @@ + + + + + +Big integers +
                  +

                • What does the big integer library do?

                  • +

                • How do I use the big integer library?

                  • +

                • Base classes and their derived classes

                    +

                  • RInteger class

                    • +
                  • +
                +
                What does the +big integer library do?

                Some types of cryptography require the handling +of finite arbitrary length integers. This big integer library attempts to +provide support for that requirement.

                It is capable of representing +both negative and positive integers with an absolute value of less than 2^(237).

                +
                How do I use +the big integer library?

                There are four categories of exposed APIs:

                  +

                1. Creation of new integers +given some other representation (descriptor, TUint, etc). RInteger::NewL()

                  2. +

                2. Creation of new integers +given some criteria (range, bitcount, prime). RInteger::NewRandomL(), RInteger::NewPrimeL()

                  3. +

                3. Exporting of previously +created integers to descriptors. TInteger::BufferLC()

                  4. +

                4. Querying attributes +about the size of a previously created integer. TInteger::BitCount(), TInteger::ByteCount(), TInteger::WordCount().

                  5. +

                The following code demonstrates how to create an RInteger from +a bit string representation of a big integer.

                +//This creates an RInteger from the following binary hexadecimal (base 16) +//descriptor. Note that the number is written overall in big endian (most +//significant digit is first, least significant digit (ones digit) is last). +//P.S. The hexadecimal binary descriptor below is the base 16 representation +//of the base 10 number 123456789012345678901234567890. +RInteger integer = RInteger::NewL(_L8("18EE90FF6C373E0EE4E3F0AD2")); +CleanupStack::PushL(integer); + +//This next line converts the number stored by an RInteger into a binary, big +//endian, hexadecimal descriptor. +HBufC8* descriptor = integer.BufferLC(); +CleanupStack::Pop(descriptor); +CleanupStack::PopAndDestroy(integer); +//descriptor is the same as the original _L8 input value now. +

                For more information on integers, including important memory +management information and additional creation overloads, see RInteger in +the Cryptography API Reference material.

                +
                Base classes +and their derived classes

                The diagram below shows the main classes +used in bigint and which are implemented in cryptography.dll. +The color of the boxes indicates the type of Symbian class, that is, M, C, R or T class. For detailed information on each component see the Cryptography API +Reference material.

                +The inheritance diagram above shows the <codeph>TInteger</codeph> and <codeph>RInteger</codeph> classes. + +

                RInteger class

                RInteger is +a TInteger derived class allowing the construction of variable +length big integers.

                This class follows standard R class +rules. As a quick refresher, the following rules apply to RInteger s:

                  +

                • You can construct an +empty RInteger.

                  +RInteger integer; +

                  This is a constructed, but uninitialized integer. It does +not own memory and no operations can be performed on it. It is useful, mostly, +to assign the result of another integer operation to. Push ing +and then PopAndDestroy ing an empty RInteger works, +although it's not needed.

                  • +

                • RInteger s +can be bitwised copied (the default assignment operator and copy constructor +are valid), but you need to be careful you don't lose your original memory +in the process. You should only use the assignment operator on a newly declared +integer. To set an RInteger to another value without losing +memory see TInteger::Set().

                  +RInteger a = anotherInteger; // OK -- you now have two integers that point to the same memory +RInteger b = RInteger::NewL(aDesc); // OK +b = a; // NOT OK, b's original memory has been lost +
                  • +

                • You own any RInteger returned +by value from a TInteger function.

                  +RInteger integer = a.MinusL(b); // We now own integer +CleanupStack::PushL(integer); +
                  • +

                • You must call Close() on +all RInteger s that own memory before they go out of scope. +(The cleanup stack can do this for you as well, see further bullet points +below).

                  +void foo(void) + { + RInteger integer = a.TimesL(TInteger::Two); + //< all sorts of non-leaving code here > + integer.Close(); + } +
                  • +

                • RInteger has +a operator TCleanupItem() cast function that allows you to +call CleanupStack::PushL(RInteger&). Use this in preference +to CleanupClosePushL(RInteger&), which although it does +the same thing, generates more code.

                  +RInteger integer = a.ModularExponentiateL(b, p); +CleanupStack::PushL(integer); +//< all sorts of leaving code here > +CleanupStack::PopAndDestroy(&integer); +
                  • +

                • Be careful calling TInteger::Set(). +After calling this, two RInteger s have a pointer to the +same heap-based integer. Calling Close() on one, either explicitly +or through the cleanup stack, leaves a dangling pointer to the other. You +probably want to use code similar to the following:

                  +RInteger first = RInteger::NewL(298728); +CleanupStack::PushL(first); +//< all sorts of leaving code here > +RInteger second.Set(first); +CleanupStack::Pop(first); +CleanupStack::PushL(second); +
                  • +
                +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C7C5F7B8-F024-57F0-968B-1839E1E07DAA.dita --- a/Symbian3/SDK/Source/GUID-C7C5F7B8-F024-57F0-968B-1839E1E07DAA.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-C7C5F7B8-F024-57F0-968B-1839E1E07DAA.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,40 +1,43 @@ - - - - - -BmpAnim: -Bitmap Animation exampleThis example shows how to create an animation using the Bitmap -Animation framework. -
                Purpose

                This -example demonstrates the Bitmap Animation API. For more information about -this example, see Bitmap -Animation Overview which is based around code snippets taken from the -example.

                -
                Download

                Click -on the following link to download the example: BmpAnimGui.zip

                Click: browse to view the example code.

                -
                Class Summary

                CFbsBitmapNote

                CBitmapFrameDataEncapsulates

                CBitmapAnimClientDataEncapsulates

                RBitmapAnimEnables

                RAnimDllClient

                -
                Building and -configuring

                To build the example:

                  -

                • You can build the example -from your IDE or the command line.

                  If you use an IDE, import the bld.inf file -of the example into your IDE, and use the build command of the IDE.

                  If -you use the command line, open a command prompt, and set the current directory -to the source code directory of the example. You can then build the example -with the SBSv1 build tools with the following commands:

                  bldmake -bldfiles

                  abld build

                  How to use bldmake and How to use abld describe -how to use the SBSv1 build tools.

                  • -

                • For the emulator, the -example builds an executable called bmpanimgui.exe in -the epoc32\release\winscw\<udeb or urel>\ folder.

                  • -
                -                 -Bitmap Animation -Overview + + + + + +BmpAnim: Bitmap Animation exampleThis example shows how to create an animation using the +Bitmap Animation framework. +
                Purpose

                This example demonstrates the Bitmap Animation API. For more +information about this example, see Bitmap Animation +Overview which is based around code snippets taken from the +example.

                +
                Download

                Click on the following link to download the example: BmpAnimGui.zip

                Click: browse to view the example code.

                +
                Class Summary
                  +

                • CFbsBitmapNote

                  • +

                • CBitmapFrameDataEncapsulates

                  • +

                • CBitmapAnimClientDataEncapsulates

                  • +

                • RBitmapAnimEnables

                  • +

                • RAnimDllClient

                  • +
                +
                Building +and configuring

                To build the example:

                  +

                • You can build +the example from your IDE or the command line.

                  If you use +an IDE, import the bld.inf file of the example +into your IDE, and use the build command of the IDE.

                  If you +use the command line, open a command prompt, and set the current directory +to the source code directory of the example. You can then build the +example with the SBSv1 build tools with the following commands:

                  bldmake bldfiles

                  abld +build

                  How to use bldmake and How to +use abld describe how to use the SBSv1 build tools.

                  • +

                • For the emulator, +the example builds an executable called bmpanimgui.exe in the epoc32\release\winscw\<udeb or urel>\ folder.

                  • +
                +                 +Bitmap +Animation Overview                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C7D026AF-9C07-4221-AEDE-8CC0654A9D57.dita --- a/Symbian3/SDK/Source/GUID-C7D026AF-9C07-4221-AEDE-8CC0654A9D57.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-C7D026AF-9C07-4221-AEDE-8CC0654A9D57.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,31 +1,31 @@ - - - - - -Selecting -text -

                A longer stretch of text can be selected by using the Hash key (#) and -keeping it pressed while using the Arrow keys. The selected text is highlighted -and the Cut and Copy functions -are available on the softkeys when some text has been selected. It is also -possible to start selections by going to the Options menu -and selecting Copy mode.

                -

                The same function is done with the Edit key in devices -that have one.

                - -Text selection in an editor - - -

                If the user presses an Arrow key alone when there is a text selection, -the selection disappears and the cursor reappears in the respective position.

                -

                For more information on editing text -on touch devices, see Cut, -copy, and paste.

                + + + + + +Selecting +text +

                A longer stretch of text can be selected by using the Hash key (#) and +keeping it pressed while using the Arrow keys. The selected text is highlighted +and the Cut and Copy functions +are available on the softkeys when some text has been selected. It is also +possible to start selections by going to the Options menu +and selecting Copy mode.

                +

                The same function is done with the Edit key in devices +that have one.

                + +Text selection in an editor + + +

                If the user presses an Arrow key alone when there is a text selection, +the selection disappears and the cursor reappears in the respective position.

                +

                For more information on editing text +on touch devices, see Cut, +copy, and paste.

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C7F900F4-7C8E-4922-8785-D6EF9AE23B22.dita --- a/Symbian3/SDK/Source/GUID-C7F900F4-7C8E-4922-8785-D6EF9AE23B22.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-C7F900F4-7C8E-4922-8785-D6EF9AE23B22.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,76 +1,76 @@ - - - - - -List -setting item -

                List setting item (for example, radio button setting) works -with a touch down and release. A touch down and release directly moves the -mark in radio button list and closes the pop-up. In multi-selection list, -first touch down and release only checks or unchecks the item. Touch down -and release second time activates the item and the pop-up closes.

                - - - -The default touch -events for list selection item - - - - - - -

                User action

                 -

                State change

                 -

                Feedback

                 -                 - - - -

                Touch down on setting item, first time

                 -

                No change

                 -

                The item is highlighted.

                Tactile: Sensitive list effect and -audio feedback are provided with touch down event.

                 -                 - -

                Touch release on setting item, first time

                 -

                In multi-selection list marks/unmarks the item. In radio button -selection, activates the item and closes the pop-up.

                 -

                Highlight disappears.

                Tactile: No effect in multi-selection -list is provided. In radio button, selection basic list effect is provided -with touch down release event.

                 -                 - -

                Touch down on setting item, second time

                 -

                No change

                 -

                The item is highlighted

                Tactile: Basic list effect and audio -given with touch down event.

                 -                 - -

                Touch release on setting item, second time

                 -

                In multi-selection list marks/unmarks the item.

                 -

                Highlight disappears.

                Tactile: Basic list effect given with -touch down release event.

                 -                 - -

                Touch down and move inside pop-up setting item list

                 -

                Refer to Dragging -and flicking events.

                 -

                Tactile: Refer to Dragging -and flicking events.

                 -                 - -

                Touch down and release outside the setting item.

                 -

                Inactive

                 -

                Tactile: No effect

                 -                 - - + + + + + +List +setting item +

                List setting item (for example, radio button setting) works +with a touch down and release. A touch down and release directly moves the +mark in radio button list and closes the pop-up. In multi-selection list, +first touch down and release only checks or unchecks the item. Touch down +and release second time activates the item and the pop-up closes.

                + + + +
                The default touch +events for list selection item + + + + + + +

                User action

                 +

                State change

                 +

                Feedback

                 +                 + + + +

                Touch down on setting item, first time

                 +

                No change

                 +

                The item is highlighted.

                Tactile: Sensitive list effect and +audio feedback are provided with touch down event.

                 +                 + +

                Touch release on setting item, first time

                 +

                In multi-selection list marks/unmarks the item. In radio button +selection, activates the item and closes the pop-up.

                 +

                Highlight disappears.

                Tactile: No effect in multi-selection +list is provided. In radio button, selection basic list effect is provided +with touch down release event.

                 +                 + +

                Touch down on setting item, second time

                 +

                No change

                 +

                The item is highlighted

                Tactile: Basic list effect and audio +given with touch down event.

                 +                 + +

                Touch release on setting item, second time

                 +

                In multi-selection list marks/unmarks the item.

                 +

                Highlight disappears.

                Tactile: Basic list effect given with +touch down release event.

                 +                 + +

                Touch down and move inside pop-up setting item list

                 +

                Refer to Dragging +and flicking events.

                 +

                Tactile: Refer to Dragging +and flicking events.

                 +                 + +

                Touch down and release outside the setting item.

                 +

                Inactive

                 +

                Tactile: No effect

                 +                 + +
                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832.dita --- a/Symbian3/SDK/Source/GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-C85EECD6-2CFD-5BA9-A60B-F7AF3A74E832.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,125 +1,118 @@ - - - - - -rbufexample: -Using resizable buffer descriptorsThis example application demonstrates how to use the RBuf class. -

                RBuf is a resizable buffer descriptor. It is part of -the user library. It is used to contain strings and binary data when the maximum -size of the data is not known until run time.

                -

                This overview contains the following sections:

                -
                  -

                • Download

                  • -

                • Description

                  • -

                • Class summary

                  • -

                • Build

                  • -

                • See also

                  • -
                -
                Download

                Click -on the following link to download the example: rbufexample.zip.

                Click: browse to view the example code.

                -
                Description
                  -

                • Creating an RBuf

                  • -

                • Swapping two RBufs

                  • -

                • Copying data to an RBuf using the assignment operator

                  • -

                • Reallocating an RBuf

                  • -

                • Replacing and modifying the data in an RBuf

                  • -

                Creating an RBuf

                The -example demonstrates creating an RBuf in the following -ways:

                  -

                1. Using RBuf::Create() -or RBuf::CreateL(): These functions create either an empty descriptor, -or one with data copied from another descriptor.

                  2. -

                2. Using RBuf::CreateMax() -or RBuf::CreateMaxL(): These functions set the buffer's current length -to be the same as its maximum length.

                  3. -

                3. By assigning from -an HBufC: RBuf::Assign() transfers ownership of the -heap descriptor. It is not possible to access the original heap descriptor -once ownership has been transferred.

                  4. -

                4. By assigning some -previously allocated memory: RBuf::Assign() transfers -ownership of allocated memory. It is then not possible to access the original -memory.

                  5. -

                5. Using RReadStream: The -example writes some text to a file stream (RFileWriteStream). -Then it creates the buffer by passing the open stream object to RBuf::CreateL().

                  6. -

                Related APIs

                  -

                • RBuf - Defines a build-independent resizable buffer -descriptor.

                  • -

                • RBuf::Assign()

                  • -

                • RBuf::Create()

                  • -

                • RBuf::CreateL()

                  • -

                • RBuf::CreateMax()

                  • -

                • RBuf::CreateMaxL()

                  • -

                Swapping two RBufs

                The -example creates two resizable buffers using RBuf::Create(). -Then it swaps the contents of them using RBuf::Swap().

                Note: When -you swap data between two RBuf s ensure that the maximum -length of the target RBuf is sufficient to hold the data, -otherwise a panic (User 11) occurs.

                Related APIs

                  -

                • RBuf::Create()

                  • -

                • RBuf::Swap()

                  • -

                Copying data to -an RBuf using the assignment operator

                The example creates two -resizable buffers and allocates memory using RBuf::Create(). -It then copies data to these buffers. It also copies data from the first buffer -to the second buffer using the assignment operator.

                Notes:

                  -

                • When you use RBuf::Assign(), -ownership of the buffer is transferred. Assign() neither -checks nor frees any pre-existing owned allocated memory. If this descriptor -already owns some allocated memory, RBuf16::Close() should -be invoked on it before calling RBuf::Assign(), otherwise -a memory leak will occur.

                  • -

                • When you use the assignment -operator, you must make sure the target descriptor's maximum length is equal -to or greater than the length of the source descriptor, otherwise a User -11 panic (descriptor overflow) occurs. Any existing data in the target -descriptor is replaced.

                  • -

                Related APIs

                  -

                • RBuf16::Close()

                  • -

                • RBuf::Assign()

                  • -

                • RBuf::Create()

                  • -

                Reallocating an -RBuf

                The example creates a resizable buffer descriptor, then it -resizes it using RBuf::ReAlloc(). The old and new lengths -are printed to the console to show how ReAlloc() does not -change the length of the descriptor, but only its maximum length. Calling RBuf::ReAlloc() with -a value of zero frees the memory and sets the length and maximum length to -zero.

                Related APIs

                  -

                • RBuf::ReAlloc()

                  • -

                Replacing and -modifying the data in an RBuf

                The example creates a resizable -buffer descriptor and replaces a portion of the data in it using RBuf::Replace(). -The start position and length of the data to be replaced, and the replacement -text are passed as parameters. RBuf::Delete() is then used -to delete the replacement text, by specifying the position and length of the -data to be deleted.

                Related APIs

                  -

                • RBuf::Delete()

                  • -

                • RBuf::Replace()

                  • -
                -
                Class summary
                  -

                • RBuf - Defines a build-independent resizable buffer -descriptor.

                  • -

                • HBufC - Defines a build-independent heap descriptor.

                  • -

                • RFileWriteStream - Supports the writing of a stream -to a file.

                  • -

                • RFileReadStream - Supports the reading of a stream -from a file.

                  • -

                • RFs

                  • -
                -
                Build

                The Symbian build process describes -how to build this example application. The example builds an executable file -called rbufexample.exe in the standard location (\epoc32\release\winscw\<build_variant> for -the emulator). After launching the executable, depending on the emulator you -are using, you may need to navigate away from the application launcher/shell -screen to view the console.

                -
                See also

                How to use the resizable -buffer descriptor - RBuf

                + + + + + +rbufexample: Using resizable buffer descriptorsThis example application demonstrates how to use the RBuf class. +

                RBuf is a resizable buffer descriptor. It is +part of the user library. It is used to contain strings and binary +data when the maximum size of the data is not known until run time.

                +

                This overview contains the following sections:

                +
                  +

                • Download

                  • +

                • Description

                  • +

                • Class summary

                  • +

                • Build

                  • +

                • See also

                  • +
                +
                Download

                Click on the following link to download the example: rbufexample.zip.

                Click: browse to view the example code.

                +
                Description
                  +

                • Creating an RBuf

                  • +

                • Swapping two RBufs

                  • +

                • Copying data to an RBuf using the assignment operator

                  • +

                • Reallocating an RBuf

                  • +

                • Replacing and modifying the data in an RBuf

                  • +

                Creating +an RBuf

                The example demonstrates creating an RBuf in the following ways:

                  +

                1. Using RBuf::Create() +or RBuf::CreateL(): These functions create either an empty descriptor, +or one with data copied from another descriptor.

                  2. +

                2. Using RBuf::CreateMax() +or RBuf::CreateMaxL(): These functions set the buffer's current +length to be the same as its maximum length.

                  3. +

                3. By assigning +from an HBufC: RBuf::Assign(HBufC8*) transfers +ownership of the heap descriptor. It is not possible to access the +original heap descriptor once ownership has been transferred.

                  4. +

                4. By assigning +some previously allocated memory: RBuf::Assign(const +RBuf8& ) transfers ownership of allocated memory. It +is then not possible to access the original memory.

                  5. +

                5. Using RReadStream: The example writes some text to a file stream (RFileWriteStream). Then it creates the buffer by passing the open stream object to RBuf::CreateL(TInt).

                  6. +

                Related APIs

                  +

                • RBuf - Defines a build-independent resizable +buffer descriptor.

                  • +

                • RBuf::Assign(const RBuf8&)

                  • +

                • RBuf::Create(const TDesC8&)

                  • +

                • RBuf::CreateL(const TDesC8&)

                  • +

                • RBuf::CreateMax(TInt)

                  • +

                • RBuf::CreateMaxL(TInt)

                  • +

                Swapping +two RBufs

                The example creates two resizable buffers using RBuf::Create(const TDesC8&). Then it swaps the contents +of them using RBuf::Swap(RBuf8&).

                Note: When you swap data between two RBuf s +ensure that the maximum length of the target RBuf is sufficient to hold the data, otherwise a panic (User +11) occurs.

                Related APIs

                  +

                • RBuf::Create(const TDesC8&)

                  • +

                • RBuf::Swap(RBuf8&)

                  • +

                Copying +data to an RBuf using the assignment operator

                The example +creates two resizable buffers and allocates memory using RBuf::Create(const TDesC8&). It then copies +data to these buffers. It also copies data from the first buffer to +the second buffer using the assignment operator.

                Notes:

                  +

                • When you use RBuf::Assign(const RBuf8&), ownership of the buffer +is transferred. Assign(const RBuf8&) neither +checks nor frees any pre-existing owned allocated memory. If this +descriptor already owns some allocated memory, RBuf16::Close() should be invoked on it before calling RBuf::Assign(const +RBuf8&), otherwise a memory leak will occur.

                  • +

                • When you use +the assignment operator, you must make sure the target descriptor's +maximum length is equal to or greater than the length of the source +descriptor, otherwise a User 11 panic (descriptor +overflow) occurs. Any existing data in the target descriptor is replaced.

                  • +

                Related APIs

                  +

                • RBuf16::Close()

                  • +

                • RBuf::Assign(const RBuf8&)

                  • +

                • RBuf::Create(TInt)

                  • +

                Reallocating +an RBuf

                The example creates a resizable buffer descriptor, +then it resizes it using RBuf::ReAlloc(TInt). The +old and new lengths are printed to the console to show how ReAlloc() does not change the length of the descriptor, +but only its maximum length. Calling RBuf::ReAlloc(TInt) with a value of zero frees the memory and sets the length and maximum +length to zero.

                Related APIs

                  +

                • RBuf::ReAlloc(TInt)

                  • +

                Replacing +and modifying the data in an RBuf

                The example creates +a resizable buffer descriptor and replaces a portion of the data in +it using RBuf::Replace(TInt ,TInt ,const TDesC16&). The start position and length of the data to be replaced, and the +replacement text are passed as parameters. RBuf::Delete(TInt +, TInt) is then used to delete the replacement text, by +specifying the position and length of the data to be deleted.

                Related APIs

                  +

                • RBuf::Delete(TInt , TInt)

                  • +

                • RBuf::Replace(TInt ,TInt ,const TDesC16&)

                  • +
                +
                Class +summary
                  +

                • RBuf - Defines a build-independent resizable +buffer descriptor.

                  • +

                • HBufC - Defines a build-independent heap +descriptor.

                  • +

                • RFileWriteStream - Supports the writing +of a stream to a file.

                  • +

                • RFileReadStream - Supports the reading of +a stream from a file.

                  • +

                • RFs

                  • +
                +
                Build

                The Symbian +build process describes how to build this example application. +The example builds an executable file called rbufexample.exe in the standard location (\epoc32\release\winscw\<build_variant> for the emulator). After launching the executable, depending on +the emulator you are using, you may need to navigate away from the +application launcher/shell screen to view the console.

                +
                See +also

                How to use the resizable buffer descriptor - RBuf

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C8938826-52F7-5040-B59C-3C06DAEB6F03_d0e134273_href.jpg Binary file Symbian3/SDK/Source/GUID-C8938826-52F7-5040-B59C-3C06DAEB6F03_d0e134273_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C8938826-52F7-5040-B59C-3C06DAEB6F03_d0e140807_href.jpg Binary file Symbian3/SDK/Source/GUID-C8938826-52F7-5040-B59C-3C06DAEB6F03_d0e140807_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C893C9E6-47B8-5149-9808-0274C61CF3D7.dita --- a/Symbian3/SDK/Source/GUID-C893C9E6-47B8-5149-9808-0274C61CF3D7.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-C893C9E6-47B8-5149-9808-0274C61CF3D7.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,56 +1,55 @@ - - - - - -OCSP-SWI -Integration

                The Symbian platform provides the ability to validate and manage X.509 certificates. -This ability is integrated into the software installation process to provide -Secure Software Install (SWI) with the functionality of performing certificate -checking at installation time. During installation, SWI checks whether the -certificates associated with the application to be installed have been revoked. -It performs this check by using Online Certificate Status Protocol (OCSP).

                You -can configure SWI to enable or disable the revocation status check of certificates. -In addition, SWI can also be configured to supply the OCSP client with a default -Uniform Resource Identifier (URI) for the OCSP server.

                 -

                You can configure SWI to enable or disable the revocation status check -of certificates. In addition, SWI can also be configured to supply the OCSP -client with a default Uniform Resource Identifier (URI) for the OCSP server.

                -
                Installing software based on OCSP check

                SWI validates -the certificate in the install file. As part of validation, it carries out -revocation check, depending on the setting of the OcspEnabled parameter -in the swipolicy.ini file. If the revocation check option -is not enabled, a warning is displayed giving options to carry out revocation -check, to continue without revocation check or to cancel the installation. -If the option is enabled, all certificates in the chain except the root are -checked.

                Note: For details on how certificates are validated, -see Certificate Validation -in PKIX.

                The results of revocation check decide whether the -application can be installed. The following are the scenarios associated with -the certificate revocation check:

                  -

                • If the OCSP client indicates -that no certificates are revoked and the operation completes successfully -with no errors or warnings, the software can be installed.

                  • -

                • If OCSP indicates that -any of the certificates is revoked or if the signature on the OCSP response -is invalid, a security error is issued and the software cannot be installed.

                  • -

                • If the revocation status -of a certificate cannot be determined (because of reasons like lack of network -access or OCSP responder error), SWI behaves as if the software were unsigned. -The setting of the AllowUnsigned parameter in the swipolicy.ini file -determines whether the unsigned software can be installed or not. If the parameter -value is true, SWI issues a warning before installing but allows installation -of the software. Otherwise it issues an error and does not allow installation.

                  • -

                Note: For details of the various parameters in swipolicy.ini, -see Secure Software -Install Reference.

                -                 -Online Certificate -Status Protocol + + + + + +OCSP-SWI Integration

                The Symbian platform provides the ability to validate +and manage X.509 certificates. This ability is integrated into the software +installation process to provide Secure Software Install (SWI) with +the functionality of performing certificate checking at installation +time. During installation, SWI checks whether the certificates associated +with the application to be installed have been revoked. It performs +this check by using Online Certificate Status Protocol (OCSP).

                You can configure SWI to enable or disable the revocation status +check of certificates. In addition, SWI can also be configured to +supply the OCSP client with a default Uniform Resource Identifier +(URI) for the OCSP server.

                 +

                You can configure SWI to enable or disable the revocation status +check of certificates. In addition, SWI can also be configured to +supply the OCSP client with a default Uniform Resource Identifier +(URI) for the OCSP server.

                +
                Installing software based on OCSP check

                SWI validates the certificate in the install file. As part of validation, +it carries out revocation check, depending on the setting of the OcspEnabled parameter in the swipolicy.ini file. If the revocation check option is enabled, a +warning is displayed giving options to carry out revocation check, +to continue without revocation check or to cancel the installation. +If the option is enabled, all certificates in the chain except the root are checked.

                Note: For details on how certificates are validated, +see Certificate +Validation in PKIX.

                The results of revocation check +decide whether the application can be installed. The following are +the scenarios associated with the certificate revocation check:

                  +

                • If the OCSP +client indicates that no certificates are revoked and the operation +completes successfully with no errors or warnings, the software can +be installed.

                  • +

                • If OCSP indicates +that any of the certificates is revoked or if the signature on the +OCSP response is invalid, a security error is issued and the software +cannot be installed.

                  • +

                • If the revocation +status of a certificate cannot be determined (because of reasons like +lack of network access or OCSP responder error), SWI behaves as if +the software were unsigned. The setting of the AllowUnsigned parameter in the swipolicy.ini file determines +whether the unsigned software can be installed or not. If the parameter +value is true, SWI issues a warning before installing but allows installation +of the software. Otherwise it issues an error and does not allow installation.

                  • +

                Note: For details of the various parameters in swipolicy.ini, see Secure Software Install +Reference.

                +                 +Online +Certificate Status Protocol                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C8C804F9-860D-590D-B247-FBB1714604B7_d0e185271_href.png Binary file Symbian3/SDK/Source/GUID-C8C804F9-860D-590D-B247-FBB1714604B7_d0e185271_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C8C804F9-860D-590D-B247-FBB1714604B7_d0e191867_href.png Binary file Symbian3/SDK/Source/GUID-C8C804F9-860D-590D-B247-FBB1714604B7_d0e191867_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C8D04D54-D391-5505-9E80-596589410179_d0e333754_href.png Binary file Symbian3/SDK/Source/GUID-C8D04D54-D391-5505-9E80-596589410179_d0e333754_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C8D04D54-D391-5505-9E80-596589410179_d0e339911_href.png Binary file Symbian3/SDK/Source/GUID-C8D04D54-D391-5505-9E80-596589410179_d0e339911_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C8D5B104-3F34-513B-BA08-5F2FEE60265C_d0e7071_href.png Binary file Symbian3/SDK/Source/GUID-C8D5B104-3F34-513B-BA08-5F2FEE60265C_d0e7071_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C8D5B104-3F34-513B-BA08-5F2FEE60265C_d0e8346_href.png Binary file Symbian3/SDK/Source/GUID-C8D5B104-3F34-513B-BA08-5F2FEE60265C_d0e8346_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C9429505-EEE7-4E64-BE0A-BC5D57D5B42C_d0e37243_href.png Binary file Symbian3/SDK/Source/GUID-C9429505-EEE7-4E64-BE0A-BC5D57D5B42C_d0e37243_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C9429505-EEE7-4E64-BE0A-BC5D57D5B42C_d0e42810_href.png Binary file Symbian3/SDK/Source/GUID-C9429505-EEE7-4E64-BE0A-BC5D57D5B42C_d0e42810_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C95D0D29-E14F-5E34-B295-F3CBB38F85FF.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-C95D0D29-E14F-5E34-B295-F3CBB38F85FF.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,12 @@ + + + + + +TCP/IP ExamplesThis describes the example code for TCP/IP. \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C9823942-CE52-53E3-B183-3B1F6509749F-GENID-1-8-1-3-1-1-8-1-3-1.dita --- a/Symbian3/SDK/Source/GUID-C9823942-CE52-53E3-B183-3B1F6509749F-GENID-1-8-1-3-1-1-8-1-3-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,38 +0,0 @@ - - - - - -UI -graphics utilities overview -
                Purpose

                Provides miscellaneous user interface utility -functions, relating to fonts, colours, and drawing.

                -
                Architectural relationships

                The API is a simple -library that is used by applications and other UI framework APIs.

                -
                Description

                Colour utilities

                Colour -utilities are available from CColorArray, CColorList, -and ColorUtils.

                Font utilities

                Font -utilities are available from CCleanupStackableFont, FontUtils, ResourceUtils, -and TLogicalFont. A family of classes derived from TFindWidthOfWidestTextItem find -the pixel width for common items, such as days and digits, using a particular -font.

                Icon utility

                CGulIcon packages -two bitmaps, one each for an icon image and its mask.

                Text and -drawing utilities

                Text and drawing utilities are available from TextUtils and DrawUtils.

                  -

                • Utilities for help with -finding text are available from CTulAddressStringTokenizer.

                  • -

                • Utilities for help with -loading and formatting resource strings are available from TulTextResourceUtils

                  • -

                • Utilities for help with -parsing and validating phone numbers are available from TulPhoneNumberUtils

                  • -

                • Utilities for help with -reading strings from resource files are available from CTulStringResourceReader

                  • -

                • Utilities for help with -rectangular areas are provided by TGulAlignment and TGulBorder.

                  • -
                -                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C9823942-CE52-53E3-B183-3B1F6509749F-GENID-1-8-1-6-1-1-4-1-7-1-3-1.dita --- a/Symbian3/SDK/Source/GUID-C9823942-CE52-53E3-B183-3B1F6509749F-GENID-1-8-1-6-1-1-4-1-7-1-3-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,38 +0,0 @@ - - - - - -UI -graphics utilities overview -
                Purpose

                Provides miscellaneous user interface utility -functions, relating to fonts, colours, and drawing.

                -
                Architectural relationships

                The API is a simple -library that is used by applications and other UI framework APIs.

                -
                Description

                Colour utilities

                Colour -utilities are available from CColorArray, CColorList, -and ColorUtils.

                Font utilities

                Font -utilities are available from CCleanupStackableFont, FontUtils, ResourceUtils, -and TLogicalFont. A family of classes derived from TFindWidthOfWidestTextItem find -the pixel width for common items, such as days and digits, using a particular -font.

                Icon utility

                CGulIcon packages -two bitmaps, one each for an icon image and its mask.

                Text and -drawing utilities

                Text and drawing utilities are available from TextUtils and DrawUtils.

                  -

                • Utilities for help with -finding text are available from CTulAddressStringTokenizer.

                  • -

                • Utilities for help with -loading and formatting resource strings are available from TulTextResourceUtils

                  • -

                • Utilities for help with -parsing and validating phone numbers are available from TulPhoneNumberUtils

                  • -

                • Utilities for help with -reading strings from resource files are available from CTulStringResourceReader

                  • -

                • Utilities for help with -rectangular areas are provided by TGulAlignment and TGulBorder.

                  • -
                -                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C9823942-CE52-53E3-B183-3B1F6509749F.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-C9823942-CE52-53E3-B183-3B1F6509749F.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,38 @@ + + + + + +UI +graphics utilities overview +
                Purpose

                Provides miscellaneous user interface utility +functions, relating to fonts, colours, and drawing.

                +
                Architectural relationships

                The API is a simple +library that is used by applications and other UI framework APIs.

                +
                Description

                Colour utilities

                Colour +utilities are available from CColorArray, CColorList, +and ColorUtils.

                Font utilities

                Font +utilities are available from CCleanupStackableFont, FontUtils, ResourceUtils, +and TLogicalFont. A family of classes derived from TFindWidthOfWidestTextItem find +the pixel width for common items, such as days and digits, using a particular +font.

                Icon utility

                CGulIcon packages +two bitmaps, one each for an icon image and its mask.

                Text and +drawing utilities

                Text and drawing utilities are available from TextUtils and DrawUtils.

                  +

                • Utilities for help with +finding text are available from CTulAddressStringTokenizer.

                  • +

                • Utilities for help with +loading and formatting resource strings are available from TulTextResourceUtils

                  • +

                • Utilities for help with +parsing and validating phone numbers are available from TulPhoneNumberUtils

                  • +

                • Utilities for help with +reading strings from resource files are available from CTulStringResourceReader

                  • +

                • Utilities for help with +rectangular areas are provided by TGulAlignment and TGulBorder.

                  • +
                +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-C9F4AF3A-158C-4438-930D-9E351B89280C.dita --- a/Symbian3/SDK/Source/GUID-C9F4AF3A-158C-4438-930D-9E351B89280C.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,16 +0,0 @@ - - - - - -Changes -and release information -

                The Tactile feedback client API is an SDK API and first released in S60 -5th Edition.

                -                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CA1CE18E-DB40-5608-BE09-3767FB094AB2_d0e432235_href.png Binary file Symbian3/SDK/Source/GUID-CA1CE18E-DB40-5608-BE09-3767FB094AB2_d0e432235_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CA1CE18E-DB40-5608-BE09-3767FB094AB2_d0e432397_href.png Binary file Symbian3/SDK/Source/GUID-CA1CE18E-DB40-5608-BE09-3767FB094AB2_d0e432397_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CA2AACD9-A99D-4C34-80AF-C1B61AC9331F.dita --- a/Symbian3/SDK/Source/GUID-CA2AACD9-A99D-4C34-80AF-C1B61AC9331F.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-CA2AACD9-A99D-4C34-80AF-C1B61AC9331F.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,54 +1,54 @@ - - - - - -Clock -paneClock pane displays the current time as set in Date and time settings. -

                Clock pane cannot have a focus. The only possible interaction with clock -pane is with touch.

                - -Clock pane - - -Default -touch events for clock pane - - - - - - -

                User action

                 -

                State change

                 -

                Feedback

                 -                 - - - -

                Touch down on a clock item

                 -

                No change

                 -

                Tactile: Sensitive button effect and audio feedback are provided -with touch down event.

                 -                 - -

                Touch down and hold on clock item

                 -

                Inactive

                 -

                Tactile: No effect

                 -                 - -

                Touch release on clock item

                 -

                Opens the Universal -indicator pop-up

                 -

                Tactile: Sensitive button effect is provided with touch release. -No pop-up effect is provided to avoid double feedback.

                 -                 - - + + + + + +Clock +paneClock pane displays the current time as set in Date and time settings. +

                Clock pane cannot have a focus. The only possible interaction with clock +pane is with touch.

                + +Clock pane + + +
                Default +touch events for clock pane + + + + + + +

                User action

                 +

                State change

                 +

                Feedback

                 +                 + + + +

                Touch down on a clock item

                 +

                No change

                 +

                Tactile: Sensitive button effect and audio feedback are provided +with touch down event.

                 +                 + +

                Touch down and hold on clock item

                 +

                Inactive

                 +

                Tactile: No effect

                 +                 + +

                Touch release on clock item

                 +

                Opens the Universal +indicator pop-up

                 +

                Tactile: Sensitive button effect is provided with touch release. +No pop-up effect is provided to avoid double feedback.

                 +                 + +
                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CA7B2B53-B0DD-4830-90CF-15FD101C66F1_d0e40313_href.png Binary file Symbian3/SDK/Source/GUID-CA7B2B53-B0DD-4830-90CF-15FD101C66F1_d0e40313_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CA7B2B53-B0DD-4830-90CF-15FD101C66F1_d0e45876_href.png Binary file Symbian3/SDK/Source/GUID-CA7B2B53-B0DD-4830-90CF-15FD101C66F1_d0e45876_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CAB2A21A-B2EE-4B49-AC97-7F70BDC95755_d0e2587_href.png Binary file Symbian3/SDK/Source/GUID-CAB2A21A-B2EE-4B49-AC97-7F70BDC95755_d0e2587_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CAB2A21A-B2EE-4B49-AC97-7F70BDC95755_d0e2691_href.png Binary file Symbian3/SDK/Source/GUID-CAB2A21A-B2EE-4B49-AC97-7F70BDC95755_d0e2691_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CAB30473-7829-5F2E-9F45-A2344DEDFC35_d0e250496_href.jpg Binary file Symbian3/SDK/Source/GUID-CAB30473-7829-5F2E-9F45-A2344DEDFC35_d0e250496_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CAB30473-7829-5F2E-9F45-A2344DEDFC35_d0e254228_href.jpg Binary file Symbian3/SDK/Source/GUID-CAB30473-7829-5F2E-9F45-A2344DEDFC35_d0e254228_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CAD36EEF-42CF-52AE-A619-64F988FF342D.dita --- a/Symbian3/SDK/Source/GUID-CAD36EEF-42CF-52AE-A619-64F988FF342D.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-CAD36EEF-42CF-52AE-A619-64F988FF342D.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,35 +1,30 @@ - - - - - -Legal -Notices -

                This page provides copyright and acknowledgement information.

                -
                Copyright

                Copyright -© 2007-2010 Nokia Corporation and/or its subsidiary(-ies). All rights reserved. This -component and the accompanying materials are made available under the terms -of "Eclipse Public License v1.0" which accompanies this distribution, and -is available at the URL http://www.eclipse.org/legal/epl-v10.html.

                Initial -Contributors:

                Nokia Corporation - initial contribution

                -
                Trademarks

                These -trademarks, and others, are acknowledged. Conventional abbreviations of these -trademarks are used throughout this documentation.

                Nokia and Nokia -Connecting People are registered trademarks of Nokia Corporation.

                S60 -and logo is a trademark of Nokia Corporation.

                Symbian OS is a trademark -of Nokia Corporation.

                ARM and Thumb are registered trademarks of ARM -Limited.

                Java and all Java-based marks are trademarks or registered -trademarks of Sun Microsystems, Inc.

                Microsoft®, Microsoft® Windows®, -Microsoft® Visual C++®, Microsoft® Visual Studio® are registered trademarks -of Microsoft Corporation.

                OpenGL® ES is a registered trademark of -Silicon Graphics, Inc. in the United States and/or other countries worldwide. -The Symbian Foundation is independent of Silicon Graphics, Inc.

                Khronos, -OpenVG and OpenMAX are trademarks of the Khronos Group Inc.

                The Bluetooth -word mark and logos are owned by the Bluetooth SIG, Inc.

                + + + + + +Legal Notices +

                This page provides copyright and acknowledgement information.

                +
                Copyright

                Copyright © 2007-2010 Nokia Corporation and/or its subsidiary(-ies). +All rights reserved. This component and the accompanying materials +are made available under the terms of "Eclipse Public License v1.0" +which accompanies this distribution, and is available at the URL http://www.eclipse.org/legal/epl-v10.html.

                Initial +Contributors:

                Nokia Corporation - initial contribution

                +
                Trademarks

                These trademarks, and others, are acknowledged. Conventional +abbreviations of these trademarks are used throughout this documentation.

                Nokia and Nokia Connecting People are registered trademarks of +Nokia Corporation.

                S60 and logo is a trademark of Nokia Corporation.

                Symbian OS is a trademark of Nokia Corporation.

                ARM and +Thumb are registered trademarks of ARM Limited.

                Java and all +Java-based marks are trademarks or registered trademarks of Sun Microsystems, +Inc.

                Microsoft®, Microsoft® Windows®, Microsoft® Visual C++®, +Microsoft® Visual Studio® are registered trademarks of Microsoft Corporation.

                OpenGL® ES is a registered trademark of Silicon Graphics, Inc. +in the United States and/or other countries worldwide. The Symbian +Foundation is independent of Silicon Graphics, Inc.

                Khronos, +OpenVG and OpenMAX are trademarks of the Khronos Group Inc.

                The Bluetooth word mark and logos are owned by the Bluetooth SIG, +Inc.

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CADAFAF2-24E9-5007-9C2F-5453E8062074.dita --- a/Symbian3/SDK/Source/GUID-CADAFAF2-24E9-5007-9C2F-5453E8062074.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-CADAFAF2-24E9-5007-9C2F-5453E8062074.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,152 +1,152 @@ - - - - - -Initializing -DevSound Functionality TutorialDevSound provides a common interface to the audio hardware for -all audio functionality. DevSound is responsible for providing access to available -audio resources, initialization and configuration of hardware devices, and -playing and recording audio. - -
                Required background

                Before -you start, you must:

                  -

                • Understand the A3F DevSound Component to -which the DevSound library belongs.

                  • -

                • Understand the architectural -relationship of the DevSound. For information see DevSound -Overview.

                  • -
                -
                Introduction

                DevSound's functionality is provided -by the CMMFDevSound class.

                Construction -and initialization

                Each client using audio resources must have -an instance of the CMMFDevSound class associated with it. -The CMMFDevSound::NewL() method is used to construct a -new instance of DevSound.

                static IMPORT_C CMMFDevSound *NewL();

                Once -created, the CMMFDevSound::InitializeL() method is used -to initialize DevSound to play and record. There are three versions of the CMMFDevSound::InitializeL() method, -differing in type and number of parameters. The three versions are:

                  -

                • CMMFDevSound::InitializeL() - -initializes CMMFDevSound object to play and record PCM16 raw audio data with -sampling rate of 8 KHz.

                  IMPORT_C void InitializeL(MDevSoundObserver &aDevSoundObserver, TMMFState -aMode);

                  This method has two parameters:

                    -

                  • MDevSoundObserver - -a reference to a DevSound Observer instance.

                    • -

                  • TMMFState - -the mode for which this object is to be used, for example, EMMFStatePlaying.

                    • -
                  • -

                • CMMFDevSound::InitializeL() - -initializes DevSound object for the mode aMode for processing -audio data with hardware device aHWDev.

                  IMPORT_C void InitializeL(MDevSoundObserver &aDevSoundObserver, TUid aHWDev, -TMMFState aMode);

                  This method has three parameters:

                    -

                  • MDevSoundObserver - -a reference to a DevSound Observer instance.

                    • -

                  • TUid - -the CMMFHwDevice implementation identifier.

                    • -

                  • TMMFState - -the mode for which this object is to be used, for example, EMMFStatePlaying.

                    • -
                  • -

                • CMMFDevSound::InitializeL() - -initializes DevSound object for the mode aMode for processing -audio data with hardware device supporting FourCC aDesiredFourCC.

                  IMPORT_C void InitializeL(MDevSoundObserver &aDevSoundObserver, TFourCC -aDesiredFourCC, TMMFState aMode);

                  This method has three parameters:

                    -

                  • MDevSoundObserver - -a reference to a DevSound Observer instance.

                    • -

                  • TFourCC - -the CMMFHwDevice implementation FourCC code.

                    • -

                  • TMMFState - -the mode for which this object is to be used, for example, EMMFStatePlaying.

                    • -
                  • -

                All versions of CMMFDevSound::InitializeL() require -a reference to a DevSound Observer instance. As soon as initialization of -DevSound has completed, successfully or otherwise, the callback function MDevSoundObserver::InitializeComplete() is -called.

                The -DevSound Observer

                Most methods in the CMMFDevSound class are asynchronous. -Callbacks occur through the MDevSoundObserver class. MDevSoundObserver is -an interface to a set of DevSound callback functions. It serves as the method -of communication between the client and the DevSound. A class that uses DevSound -will typically inherit from MDevSoundObserver.

                MDevSoundObserver handles -the MDevSoundObserver::InitializeComplete() initialization -completion event.

                -
                Purpose

                Refer to the following sections for detailed -information on how to use the main features of DevSound:

                  -

                • Playing -Audio

                  • -

                • Recording -Audio

                  • -

                • Playing -Tones

                  • -
                -
                Example uses

                These examples describe some different -uses of DevSound:

                Recording -a WAV file

                In this example, a client application wants to record -a WAV file. As WAV is a standard file format supported by the MMF controller -framework, the CMdaAudioRecorderUtility client API is used -to interact with DevSound.

                The main steps in recording the WAV file -are:

                  -

                1. The client application -gives a request to record to the MMF CMdaAudioRecorderUtility client -API.

                  2. -

                2. The MMF CMdaAudioRecorderUtility client -API passes the command down through the controller framework to the MMF controller -plug-in.

                  3. -

                3. The MMF controller plug-in -initializes DevSound for recording.

                  4. -

                4. Recording starts and -continues until the client stops the recording or the limit on the file size -is reached.

                  5. -

                5. Upon completion, the -client gives a request to the MMF controller framework to stop the recording. -The controller framework passes the command down to the MMF controller plug-in.

                  6. -

                6. The MMF controller plug-in -stops DevSound and sends the completion event back to the client via controller -framework.

                  7. -

                Playing -a DTMF tone

                In this example, a client application wants to play -a Dual-Tone Multi-Frequency (DTMF) tone. The MMF CMdaAudioToneUtility client -API is used to play the DTMF tone. Unlike other MMF APIs, the CMdaAudioToneUtility does -not require a controller plug-in. This is because the input and output of -the API is already in a known data format and does not require encoding or -decoding. The CMdaAudioToneUtility communicates directly -with DevSound.

                The main steps in playing the DTMF tone are:

                  -

                1. The client application -prepares the CMdaAudioToneUtility to play a DTMF tone.

                  2. -

                2. The client application -asks the CMdaAudioToneUtility to start playing the tone.

                  3. -

                3. The CMdaAudioToneUtility asks -DevSound to play the tone.

                  4. -

                4. The CMdaAudioToneUtility informs -the client application that the playing of the tone is complete.

                  5. -

                Playing -an AVI file

                In this example, a client application wants to play -an Audio Video Interleaved (AVI) file; output is to a screen and speakers. -The AVI file contains audio and video data, so the CVideoPlayerUtility class -that can manipulate both types of data is used.

                The main steps in -playing the AVI file are:

                  -

                1. The client application -requests to play an AVI file to the MMF CVideoPlayerUtility class.

                  2. -

                2. The MMF CVideoPlayerUtility -class passes the request to the MMF controller framework. The controller framework -loads the AVI controller

                  3. -

                3. The AVI controller plug-in -initializes the DevSound and DevVideo.

                  4. -

                4. The AVI controller plug-in -reads the data in the AVI file and sends the audio data to DevSound and the -video data to DevVideo.

                  5. -

                5. DevSound outputs the -audio data.

                  6. -

                6. DevVideo sends the video -data to be decoded to the corresponding codec. The decoded video data is then -displayed on the screen.

                  7. -
                AVI files support Dolby audio also. The client application requests -for Dolby play back are processed in the similar way.
                -                 -DevSound -Overview + + + + + +Initializing +DevSound Functionality TutorialDevSound provides a common interface to the audio hardware for +all audio functionality. DevSound is responsible for providing access to available +audio resources, initialization and configuration of hardware devices, and +playing and recording audio. + +
                Required background

                Before +you start, you must:

                  +

                • Understand the A3F DevSound Component to +which the DevSound library belongs.

                  • +

                • Understand the architectural +relationship of the DevSound. For information see DevSound +Overview.

                  • +
                +
                Introduction

                DevSound's functionality is provided +by the CMMFDevSound class.

                Construction +and initialization

                Each client using audio resources must have +an instance of the CMMFDevSound class associated with it. +The CMMFDevSound::NewL() method is used to construct a +new instance of DevSound.

                static IMPORT_C CMMFDevSound *NewL();

                Once +created, the CMMFDevSound::InitializeL() method is used +to initialize DevSound to play and record. There are three versions of the CMMFDevSound::InitializeL() method, +differing in type and number of parameters. The three versions are:

                  +

                • CMMFDevSound::InitializeL() - +initializes CMMFDevSound object to play and record PCM16 raw audio data with +sampling rate of 8 KHz.

                  IMPORT_C void InitializeL(MDevSoundObserver &aDevSoundObserver, TMMFState +aMode);

                  This method has two parameters:

                    +

                  • MDevSoundObserver - +a reference to a DevSound Observer instance.

                    • +

                  • TMMFState - +the mode for which this object is to be used, for example, EMMFStatePlaying.

                    • +
                  • +

                • CMMFDevSound::InitializeL() - +initializes DevSound object for the mode aMode for processing +audio data with hardware device aHWDev.

                  IMPORT_C void InitializeL(MDevSoundObserver &aDevSoundObserver, TUid aHWDev, +TMMFState aMode);

                  This method has three parameters:

                    +

                  • MDevSoundObserver - +a reference to a DevSound Observer instance.

                    • +

                  • TUid - +the CMMFHwDevice implementation identifier.

                    • +

                  • TMMFState - +the mode for which this object is to be used, for example, EMMFStatePlaying.

                    • +
                  • +

                • CMMFDevSound::InitializeL() - +initializes DevSound object for the mode aMode for processing +audio data with hardware device supporting FourCC aDesiredFourCC.

                  IMPORT_C void InitializeL(MDevSoundObserver &aDevSoundObserver, TFourCC +aDesiredFourCC, TMMFState aMode);

                  This method has three parameters:

                    +

                  • MDevSoundObserver - +a reference to a DevSound Observer instance.

                    • +

                  • TFourCC - +the CMMFHwDevice implementation FourCC code.

                    • +

                  • TMMFState - +the mode for which this object is to be used, for example, EMMFStatePlaying.

                    • +
                  • +

                All versions of CMMFDevSound::InitializeL() require +a reference to a DevSound Observer instance. As soon as initialization of +DevSound has completed, successfully or otherwise, the callback function MDevSoundObserver::InitializeComplete() is +called.

                The +DevSound Observer

                Most methods in the CMMFDevSound class are asynchronous. +Callbacks occur through the MDevSoundObserver class. MDevSoundObserver is +an interface to a set of DevSound callback functions. It serves as the method +of communication between the client and the DevSound. A class that uses DevSound +will typically inherit from MDevSoundObserver.

                MDevSoundObserver handles +the MDevSoundObserver::InitializeComplete() initialization +completion event.

                +
                Purpose

                Refer to the following sections for detailed +information on how to use the main features of DevSound:

                  +

                • Playing +Audio

                  • +

                • Recording +Audio

                  • +

                • Playing +Tones

                  • +
                +
                Example uses

                These examples describe some different +uses of DevSound:

                Recording +a WAV file

                In this example, a client application wants to record +a WAV file. As WAV is a standard file format supported by the MMF controller +framework, the CMdaAudioRecorderUtility client API is used +to interact with DevSound.

                The main steps in recording the WAV file +are:

                  +

                1. The client application +gives a request to record to the MMF CMdaAudioRecorderUtility client +API.

                  2. +

                2. The MMF CMdaAudioRecorderUtility client +API passes the command down through the controller framework to the MMF controller +plug-in.

                  3. +

                3. The MMF controller plug-in +initializes DevSound for recording.

                  4. +

                4. Recording starts and +continues until the client stops the recording or the limit on the file size +is reached.

                  5. +

                5. Upon completion, the +client gives a request to the MMF controller framework to stop the recording. +The controller framework passes the command down to the MMF controller plug-in.

                  6. +

                6. The MMF controller plug-in +stops DevSound and sends the completion event back to the client via controller +framework.

                  7. +

                Playing +a DTMF tone

                In this example, a client application wants to play +a Dual-Tone Multi-Frequency (DTMF) tone. The MMF CMdaAudioToneUtility client +API is used to play the DTMF tone. Unlike other MMF APIs, the CMdaAudioToneUtility does +not require a controller plug-in. This is because the input and output of +the API is already in a known data format and does not require encoding or +decoding. The CMdaAudioToneUtility communicates directly +with DevSound.

                The main steps in playing the DTMF tone are:

                  +

                1. The client application +prepares the CMdaAudioToneUtility to play a DTMF tone.

                  2. +

                2. The client application +asks the CMdaAudioToneUtility to start playing the tone.

                  3. +

                3. The CMdaAudioToneUtility asks +DevSound to play the tone.

                  4. +

                4. The CMdaAudioToneUtility informs +the client application that the playing of the tone is complete.

                  5. +

                Playing +an AVI file

                In this example, a client application wants to play +an Audio Video Interleaved (AVI) file; output is to a screen and speakers. +The AVI file contains audio and video data, so the CVideoPlayerUtility class +that can manipulate both types of data is used.

                The main steps in +playing the AVI file are:

                  +

                1. The client application +requests to play an AVI file to the MMF CVideoPlayerUtility class.

                  2. +

                2. The MMF CVideoPlayerUtility +class passes the request to the MMF controller framework. The controller framework +loads the AVI controller

                  3. +

                3. The AVI controller plug-in +initializes the DevSound and DevVideo.

                  4. +

                4. The AVI controller plug-in +reads the data in the AVI file and sends the audio data to DevSound and the +video data to DevVideo.

                  5. +

                5. DevSound outputs the +audio data.

                  6. +

                6. DevVideo sends the video +data to be decoded to the corresponding codec. The decoded video data is then +displayed on the screen.

                  7. +
                AVI files support Dolby audio also. The client application requests +for Dolby play back are processed in the similar way.
                +                 +DevSound +Overview                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CB163645-CB5E-4DB5-9830-B97D12FDCBF5.dita --- a/Symbian3/SDK/Source/GUID-CB163645-CB5E-4DB5-9830-B97D12FDCBF5.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-CB163645-CB5E-4DB5-9830-B97D12FDCBF5.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,79 +1,75 @@ - - - - - -Volume -Control pop-up -

                In case the hardware has no dedicated volume keys, the audio volume is -adjusted using the Arrow up and Arrow down keys. When the user is controlling -the volume, the key event brings the Volume Control pop-up to the view, and -the pop-up disappears after a time-out when the user has done the adjustment.

                -

                The application may need up/down key events for controlling some other -component, such as list. In this case it needs to be decided whether that -view can be left without Volume Control or whether the Volume Control component -is accessed via the Options menu or toolbar.

                -

                In touch UI it is possible to activate Volume Control via universal indicator -pane. Volume is adjusted with touch by dragging the slider handle and audio -can be muted by tapping the icon in the UI component, refer to Touch -support for common UI components.

                -

                The Volume Control UI component may also be always available in the view. -In this case it is fixed in the layout.

                - -Volume control UI component - - -Default touch events for volume pop-up - - - - - - -

                User action

                 -

                State change

                 -

                Feedback

                 -                 - - - -

                Touch down and release on arrow

                 -

                Increases/decreases the volume level by an increment.

                The -volume slider is updated accordingly.

                 -

                Tactile: Basic button effect and audio feedback is provided on the -touch down and no effect is provided on touch release.

                 -                 - -

                Touch down and hold

                 -

                Activates key repeat, which performs a continuous operation and -increases/decreases the volume faster.

                The volume slider is updated -accordingly.

                 -

                Tactile: Sensitive button effect and audio feedback is provided -with steps in key repeat.

                 -                 - -

                Touch down and release on mute/unmute icon

                 -

                Mutes/unmutes the volume.

                 -

                Tactile: Basic button effect and audio given with touch down and -basic button effect on release events.

                 -                 - -

                Touch down on slider item

                 -

                Functionality as specified in the Volume setting item.

                 -

                Tactile: Feedback as specified in the Volume setting item.

                 -                 - -

                Touch down and release on percentage field

                 -

                Dismisses the volume pop-up

                 -

                Tactile: Pop-up close effect is provided with touch -down event.

                 -                 - - + + + + + +Volume +Control pop-up +

                In case the hardware has no dedicated volume keys, the audio volume is +adjusted using the Arrow up and Arrow down keys. When the user is controlling +the volume, the key event brings the Volume Control pop-up to the view, and +the pop-up disappears after a time-out when the user has done the adjustment.

                +

                The application may need up/down key events for controlling some other +component, such as list. In this case it needs to be decided whether that +view can be left without Volume Control or whether the Volume Control component +is accessed via the Options menu or toolbar.

                +

                Volume is adjusted with touch by dragging the slider handle and audio can +be muted by tapping the icon in the UI component, refer to Touch +support for common UI components.

                +

                The Volume Control UI component may also be always available in the view. +In this case it is fixed in the layout.

                + +Volume control UI component + + +
                Default touch +events for volume pop-up + + + +

                User action

                 +

                State change

                 +

                Feedback

                 +                 + + + +

                Touch down and release on arrow

                 +

                Increases/decreases the volume level by an increment.

                The +volume slider is updated accordingly.

                 +

                Tactile: Basic button effect and audio feedback is provided on the +touch down and no effect is provided on touch release.

                 +                 + +

                Touch down and hold

                 +

                Activates key repeat, which performs a continuous operation and +increases/decreases the volume faster.

                The volume slider is updated +accordingly.

                 +

                Tactile: Sensitive button effect and audio feedback is provided +with steps in key repeat.

                 +                 + +

                Touch down and release on mute/unmute icon

                 +

                Mutes/unmutes the volume.

                 +

                Tactile: Basic button effect and audio given with touch down and +basic button effect on release events.

                 +                 + +

                Touch down on slider item

                 +

                Functionality as specified in the Volume setting item.

                 +

                Tactile: Feedback as specified in the Volume setting item.

                 +                 + +

                Touch down and release on percentage field

                 +

                Dismisses the volume pop-up

                 +

                Tactile: Pop-up close effect is provided with touch down event.

                 +                 + +
                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CB3FC449-7994-5510-BD78-F1638CD48A9D.dita --- a/Symbian3/SDK/Source/GUID-CB3FC449-7994-5510-BD78-F1638CD48A9D.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-CB3FC449-7994-5510-BD78-F1638CD48A9D.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,98 +1,98 @@ - - - - - -Overview -

                The SIP Profile API provides the SIP registration service for applications. -This API allows an application to register through a profile. The profile -holds the information to provide the required registration behaviour. The -behaviour of the registration service depends on the profile type used.

                -

                Each standard has an associated profile type such as 3GPP R5 IMS, IETF, -or proprietary. Each profile has a one-to-one communication with each SIP -registration. The API allows more than one application to share the same profile -and the same SIP registration. The implementation of the API stores SIP profiles -in persistent store.

                -

                A profile stores the following main parameters:

                -
                  -

                • The user-friendly name -of the service provider.

                  • -

                • The type of the profile, -for example 3GPP R5 IMS, IETF or proprietary.

                  • -

                • The registered public -name of the user (SIP AOR).

                  • -

                • The access provider -identifier of the IAP used.

                  • -

                • The address of the SIP -registrar server, with optional connection and security parameters.

                  • -

                • The address of the SIP -proxy server, with optional connection and security parameters.

                  • -

                • The compression and -security preferences.

                  • -

                • An indication if the -profile is always registered automatically, or registered when it is used -by an application.

                  • -

                • Any extension parameters -stored as key-value pairs.

                  • -
                -
                Architectural -Relationships

                The interface allows clients to share the common -resources, profiles and SIP registrations through the client-server mechanism. -It also gives access to permanently stored profiles and allows the reading -of profile configuration values.

                All lengthy operations are asynchronous.

                Capability information

                The -following table describes the capabilities the user must have to use the SIP -Profile API.

                - - - -

                Capability

                -                 - -

                NetworkControl

                -                 - -

                NetworkServices

                -                 - -

                ReadUserData

                -                 - - -

                Extending -the API

                The API cannot be extended.

                -
                SIP Profile -API class structure

                The client must create a CSIP object, -and must implement the callback functions defined by the MSIPProfileRegistryObserver class. -A client of the SIP Profile API must then create a CSIPProfileRegistry object.

                A CSIPProfile object -is created using one of the retrieval functions that can be accessed through -the CSIPProfileRegistry class. Profile data is copied from -the permanent store into the new object. The copied values can be accessed -using the access functions of CSIPProfile.

                The -client must enable a profile before you can use it. A profile can be enabled -in the following ways:

                  -

                • provide an implementation -of the MSIPConnectionObserver class

                  • -

                • call CSIPProfileRegistry::EnableL()

                  • -

                When you enable a profile it is automatically registered. If the -profile is not registered before it is enabled the client is notified about -the registration status through the MSIPProfileRegistryObserver::ProfileRegistryEventOccurred() callback -function.

                When a profile is enabled, the client indicates that the -profile is in use, and cannot be removed. You can update the profile but, -it is not recommended.

                If required, the client can disable a profile. -The client can then delete the CSIPProfile object.

                The -following illustration shows the SDP Profile API class structure.

                - -
                -
                Memory used

                The -amount of memory used by a profile depends on its content. A normal usage -is approximately 0.2 KB for each profile. The SIP Profile server monitors -all instantiated profiles to send the asynchronous events to clients when -required. It is recommended that clients create the minimum number of profiles -required, and delete instances immediately when they are no longer required.

                + + + + + +Overview +

                The SIP Profile API provides the SIP registration service for applications. +This API allows an application to register through a profile. The profile +holds the information to provide the required registration behaviour. The +behaviour of the registration service depends on the profile type used.

                +

                Each standard has an associated profile type such as 3GPP R5 IMS, IETF, +or proprietary. Each profile has a one-to-one communication with each SIP +registration. The API allows more than one application to share the same profile +and the same SIP registration. The implementation of the API stores SIP profiles +in persistent store.

                +

                A profile stores the following main parameters:

                +
                  +

                • The user-friendly name +of the service provider.

                  • +

                • The type of the profile, +for example 3GPP R5 IMS, IETF or proprietary.

                  • +

                • The registered public +name of the user (SIP AOR).

                  • +

                • The access provider +identifier of the IAP used.

                  • +

                • The address of the SIP +registrar server, with optional connection and security parameters.

                  • +

                • The address of the SIP +proxy server, with optional connection and security parameters.

                  • +

                • The compression and +security preferences.

                  • +

                • An indication if the +profile is always registered automatically, or registered when it is used +by an application.

                  • +

                • Any extension parameters +stored as key-value pairs.

                  • +
                +
                Architectural +Relationships

                The interface allows clients to share the common +resources, profiles and SIP registrations through the client-server mechanism. +It also gives access to permanently stored profiles and allows the reading +of profile configuration values.

                All lengthy operations are asynchronous.

                Capability information

                The +following table describes the capabilities the user must have to use the SIP +Profile API.

                + + + +

                Capability

                +                 + +

                NetworkControl

                +                 + +

                NetworkServices

                +                 + +

                ReadUserData

                +                 + + +

                Extending +the API

                The API cannot be extended.

                +
                SIP Profile +API class structure

                The client must create a CSIP object, +and must implement the callback functions defined by the MSIPProfileRegistryObserver class. +A client of the SIP Profile API must then create a CSIPProfileRegistry object.

                A CSIPProfile object +is created using one of the retrieval functions that can be accessed through +the CSIPProfileRegistry class. Profile data is copied from +the permanent store into the new object. The copied values can be accessed +using the access functions of CSIPProfile.

                The +client must enable a profile before you can use it. A profile can be enabled +in the following ways:

                  +

                • provide an implementation +of the MSIPConnectionObserver class

                  • +

                • call CSIPProfileRegistry::EnableL()

                  • +

                When you enable a profile it is automatically registered. If the +profile is not registered before it is enabled the client is notified about +the registration status through the MSIPProfileRegistryObserver::ProfileRegistryEventOccurred() callback +function.

                When a profile is enabled, the client indicates that the +profile is in use, and cannot be removed. You can update the profile but, +it is not recommended.

                If required, the client can disable a profile. +The client can then delete the CSIPProfile object.

                The +following illustration shows the SDP Profile API class structure.

                + +
                +
                Memory used

                The +amount of memory used by a profile depends on its content. A normal usage +is approximately 0.2 KB for each profile. The SIP Profile server monitors +all instantiated profiles to send the asynchronous events to clients when +required. It is recommended that clients create the minimum number of profiles +required, and delete instances immediately when they are no longer required.

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CB4E1B33-470F-581A-BC32-99752C2A0DFE_d0e323040_href.jpg Binary file Symbian3/SDK/Source/GUID-CB4E1B33-470F-581A-BC32-99752C2A0DFE_d0e323040_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CB4E1B33-470F-581A-BC32-99752C2A0DFE_d0e329197_href.jpg Binary file Symbian3/SDK/Source/GUID-CB4E1B33-470F-581A-BC32-99752C2A0DFE_d0e329197_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CB548959-A1D6-4585-B8E3-B09E37E0CB43.dita --- a/Symbian3/SDK/Source/GUID-CB548959-A1D6-4585-B8E3-B09E37E0CB43.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-CB548959-A1D6-4585-B8E3-B09E37E0CB43.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,40 +1,40 @@ - - - - - -List -layouts -

                List items can in general be more complex (contain more elements) than -grid items. Certain layout rules apply to all lists:

                -
                  -

                • All items in a list have equal height on the screen (forms do not follow -this rule in the Edit state, see Forms).

                  • -

                • The column structure of all items in a list must be similar. It is -not possible to combine e.g. single-column items to a three-column item list -(however, it is possible to use some different item types having the same -general appearance), see Column -structure of lists for columns.

                  • -

                • Partial items are not visible: when the list/grid pane area does not -exactly correspond to an integer number of items, the remaining area outside -the last fully visible item appears empty, displaying the background of the -particular pane.

                  • -
                -

                In landscape layout, all two row lists can be stretched to be displayed -in one row. This enables displaying more items in the list. In list stretching, -the second row is moved next to the first row. List stretching is ON by default, -but application can decide to disable it.

                - -Two row list in stretched mode in landscape layout - - -
                Using -list layouts in C++ applications

                The API to use for lists is the Lists API. For implementation information, see Using the Lists API.

                For grids, the APIs to use -are the Grids API and the Lists API. For implementation information, see Using the Grids API and Using the Lists API.

                + + + + + +List +layouts +

                List items can in general be more complex (contain more elements) than +grid items. Certain layout rules apply to all lists:

                +
                  +

                • All items in a list have equal height on the screen (forms do not follow +this rule in the Edit state, see Forms).

                  • +

                • The column structure of all items in a list must be similar. It is +not possible to combine e.g. single-column items to a three-column item list +(however, it is possible to use some different item types having the same +general appearance), see Column +structure of lists for columns.

                  • +

                • Partial items are not visible: when the list/grid pane area does not +exactly correspond to an integer number of items, the remaining area outside +the last fully visible item appears empty, displaying the background of the +particular pane.

                  • +
                +

                In landscape layout, all two row lists can be stretched to be displayed +in one row. This enables displaying more items in the list. In list stretching, +the second row is moved next to the first row. List stretching is ON by default, +but application can decide to disable it.

                + +Two row list in stretched mode in landscape layout + + +
                Using +list layouts in applications

                The API to use for lists is the Lists API. For implementation information, see Using the Lists API.

                For grids, the APIs to use +are the Grids API and the Lists API. For implementation information, see Using the Grids API and Using the Lists API.

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CBD78250-3EF4-5DF0-B356-19996E15BBBD_d0e172711_href.png Binary file Symbian3/SDK/Source/GUID-CBD78250-3EF4-5DF0-B356-19996E15BBBD_d0e172711_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CBD78250-3EF4-5DF0-B356-19996E15BBBD_d0e179306_href.png Binary file Symbian3/SDK/Source/GUID-CBD78250-3EF4-5DF0-B356-19996E15BBBD_d0e179306_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CBE1CE3A-5C8B-475D-9F5E-8ACD839EB7E6_d0e3422_href.png Binary file Symbian3/SDK/Source/GUID-CBE1CE3A-5C8B-475D-9F5E-8ACD839EB7E6_d0e3422_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CBE1CE3A-5C8B-475D-9F5E-8ACD839EB7E6_d0e3543_href.png Binary file Symbian3/SDK/Source/GUID-CBE1CE3A-5C8B-475D-9F5E-8ACD839EB7E6_d0e3543_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CBE1CE3A-5C8B-475D-9F5E-8ACD839EB7E6_d0e4697_href.png Binary file Symbian3/SDK/Source/GUID-CBE1CE3A-5C8B-475D-9F5E-8ACD839EB7E6_d0e4697_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CBE1CE3A-5C8B-475D-9F5E-8ACD839EB7E6_d0e4818_href.png Binary file Symbian3/SDK/Source/GUID-CBE1CE3A-5C8B-475D-9F5E-8ACD839EB7E6_d0e4818_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CBF1D046-92D4-5936-9946-71BB8FC51AB2_d0e205483_href.png Binary file Symbian3/SDK/Source/GUID-CBF1D046-92D4-5936-9946-71BB8FC51AB2_d0e205483_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CBF1D046-92D4-5936-9946-71BB8FC51AB2_d0e210493_href.png Binary file Symbian3/SDK/Source/GUID-CBF1D046-92D4-5936-9946-71BB8FC51AB2_d0e210493_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CC4CA423-0A14-457C-8CBE-4A9F0E8D0B96_d0e36616_href.png Binary file Symbian3/SDK/Source/GUID-CC4CA423-0A14-457C-8CBE-4A9F0E8D0B96_d0e36616_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CC4CA423-0A14-457C-8CBE-4A9F0E8D0B96_d0e42183_href.png Binary file Symbian3/SDK/Source/GUID-CC4CA423-0A14-457C-8CBE-4A9F0E8D0B96_d0e42183_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CCC5BE18-E90D-4B81-AE6F-333B96E7A3F7.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-CCC5BE18-E90D-4B81-AE6F-333B96E7A3F7.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,150 @@ + + + + + +Choice +list +

                Choice list is a list type, which allows selection from different choices. +Choice list can either be closed (by default) state or opened state. In case +the choice list is empty, the opening button is dimmed and is inactive.

                +

                Choice list displays currently selected value by default in closed state. +When the choice list is opened, choice list pop-up displays the list of available +options (with currently selected focused). Choice list can contain text, icons +or combination of both text and icons. It is recommendation use only text +in the choice list.

                +

                It is possible to dynamically add and remove items in choice list. The +user can browse through the list with scroll keys or with the touch event.

                + +Example of Choice list + + +Default key events in a choice list + + + +

                Key

                 +

                Action

                 +                 + + + +

                Enter

                 +

                Selects the focused item and closes the choice list.

                 +                 + +

                Left selection key (Select)

                 +

                Choice list item is selected.

                 +                 + +

                Right selection key (Close)

                 +

                Choice list is closed without making a new selection.

                 +                 + +

                Arrow left / right keys

                 +

                Closes the choice list, with focused item selected.

                 +                 + +

                Arrow up / down keys

                 +

                Scrolls through the choice list. Choice list is looping.

                 +                 + + +
                +

                +Default touch events for choice list interaction in closed state + + + +

                User action

                 +

                State change

                 +

                Feedback

                 +                 + + + +

                Touch down

                 +

                Inactive, tooltip is shown.

                 +

                Tactile:

                  +

                • Basic tactile feedback is provided with touch down event.

                  • +

                • Basic list effect given with touch down event.

                  • +

                 +                 + +

                Touch release

                 +

                Opens the choice list pop-up

                 +

                Tactile: Pop-up open effect is given. If pop-up owns NGA effect +and they are ON, then increasing long touch effect is provided with touch +release.

                 +                 + +

                Touch release

                 +

                Inactive

                 + +                 + +

                Touch down and move out of the list

                 +

                List continues its movement.

                 +

                Basic tactile feedback is provided with touch down event.

                Refer +to Dragging and flicking events.

                 +                 + + +
                +

                +Default touch events for choice list interaction in opened state + + + +

                User action

                 +

                State change

                 +

                Feedback

                 +                 + + + +

                Touch down and release

                 +

                Touch down moves the focus.

                 +

                Pressed down highlight.

                Tactile:

                  +

                • Basic tactile feedback is provided with touch down event.

                  • +

                • Basic list effect is provided with touch down event.

                  • +

                 +                 + +

                Touch release

                 +

                Selects the focused item and closes the choice list.

                 +

                Tactile: Basic list effect is provided with touch release event.

                 +                 + +

                Touch down and move inside the choice list.

                 +

                The whole list moves along with the finger.

                Refer to Dragging and flicking events

                 +

                Tactile: Basic tactile feedback is provided with touch down event.

                Refer +to Dragging and flicking events.

                 +                 + +

                Touch down and move out of the choice list

                 +

                The list continues its movement according to the finger movements +outside the pop-up.

                 +

                Tactile: Basic tactile feedback is provided with touch down event.

                Refer +to Dragging and flicking events.

                 +                 + +

                Touch down and release outside the opened choice list.

                 +

                Inactive

                 +

                Basic tactile feedback given with touch down event. No advanced +tactile feedback.

                 +                 + + +
                +

                Using choice +list in applications

                The API to use for choice list is the Choice list API. For +implementation information, see Providing +a vertical list of selectable items.

                +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CCE5DBCC-41D6-53D0-B929-ADB478B53F12.dita --- a/Symbian3/SDK/Source/GUID-CCE5DBCC-41D6-53D0-B929-ADB478B53F12.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-CCE5DBCC-41D6-53D0-B929-ADB478B53F12.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,74 +1,74 @@ - - - - - -Exporting and Importing Classes

                This document discusses importing and exporting of classes.

                In particular this document describes:

                • Class exporting rules:

                  • DLL-derivation

                  • Non-sharable classes

                  • The Simple Rule

                  • Class impedimenta

                  • Boundary cases where importing and exporting symbols are illegal, which some ABI compilers accept without warnings or errors

                • The ARM ABI Thunk Offset Problem

                • The Shared DEF File Problem

                The information described in this document is valid for RVCT 2.1 build 416 or later and for any compiler that is compliant with the ARM ABI v2.0 and higher.

                Definitions

                Terminology and Background

                • For all of this section it is assumed that the user intends to derive class D from class C and that both classes reside in different DLLs.

                • Class C is called DLL-derivable, if class D can be derived from C.

                • Class C is called non-sharable if it is marked using __ declspec(notshared) or using the macros NONSHARABLE_CLASS(x) or NONSHARABLE_ STRUCT(x). It is not possible to DLL-derive from a non-sharable class. Otherwise class C is called sharable.

                • Class Impedimenta are entities that are emitted by the compiler for any class, but do not have a direct representation in source. Examples of class impedimenta are:

                  • the class’s virtual table, or

                  • a virtual table’s thunks, or

                  • the class’s run-time type information

                  Class impedimenta are a key element of the ABI and are identified through ELF symbols. They play a crucial role in enabling polymorphism, RTTI and derivation. This means that they also play a key role in DLL-derivation. In fact, if the Class Impedimenta of class C are not exported, it is not possible to DLL derive from class C or in other words class C is non-sharable.

                  This raises the interesting question as to how it is possible to export Class Impedimenta – and thus enable DLL-derivation – if they have no representation in source. The answer to this question is given in The Simple Rule – Sharable Classes section.

                • Non-callable exports are Class Impedimenta that are exported. They are often used as synonym for Class Impedimenta in this document.

                • A key function is the first non-inline, non-pure virtual function of a class.

                Symbian Conventions

                Symbian defines macros for exporting and importing classes to hide implementation details:

                Macro

                RVCT Implementation

                IMPORT_C func-declaration

                __declspec(dllimport) func-declaration

                EXPORT_C func-definition

                __declspec(dllexport) func-definition

                NONSHARABLE_CLASS(x)

                class __declspec(notshared) x

                NONSHARABLE_STRUCT(x)

                struct __declspec(notshared) x

                class NONSHARABLE name struct NONSHARABLE name

                __declspec(notshared)

                This macro does not yet exist in the Symbian platform source code. However all known ABI compliant compiler support the notations

                • struct __declspec(notshared) x

                • class __declspec(notshared) x

                which means that it is safe to define a simpler macro which does not require an argument. That macro could also be used in conjunction with templates.

                Class Exporting Rules

                This section is a programmer’s summary of the Class Exporting Rules.

                Exporting Objects

                A function, method of a class or data item is exported by marking its definition using the EXPORT_C macro. A function, method of a class or data item is imported by marking its declaration using the IMPORT_C macro. If an object is declared IMPORT_C and used in code, the linker will error if the definition of this object is not marked EXPORT_C.

                Although not required by the class exporting rules it is good practice to

                • Always mark all declarations of an exported object with IMPORT_C.

                • Never mark objects that are not exported with IMPORT_C.

                The Simple Rule – Sharable Classes

                The compiler will automatically export allClass Impedimenta, i.e. compiler implementation specific symbols of a class C such as run-time-type-information and virtual tables, that are required to enable DLL-derivation from class C. This means that all classes are by default sharable.

                The compiler will not export these symbols for classes that are marked as non-sharable using the macros NONSHARABLE_CLASS(x) or NONSHARABLE_STRUCT(x). Symbian requires that all classes that are derived from a non-sharable class are also marked non-sharable.

                Other methods or functions in classes are not automatically exported. They have to be explicitly exported as described in Exporting objects section. Note that a class with virtual functions or virtual may not be DLL-derivable if the conditions in Dll derivable classes section do not hold.

                Example: The following example shows the correct syntax to define a class as non-sharable:

                NONSHARABLE_CLASS(NonSharableClass) : public BaseClass …

                Note: The Simple Rule has consequences in terms of how many entries are present in DEF files and for shared DEF files. See The Shared DEF File Problem section for more details.

                DLL-Derivable Classes

                The Simple Rule alone does not guarantee that the class C is DLL-derivable. Depending on the form of the class, additional conditions on exporting members of class C apply. This section outlines the conditions under which class C is DLL-derivable.

                C has no Virtual Base

                For class C to be DLL-derivable,

                • Class C has to be sharable AND

                • Every virtual function in C or C's bases that is not overridden in D needs to be exported

                • If the class C has no key function, i.e. it only has pure virtuals or inlined virtuals, all bases of C also have to be DLL-derivable.

                C has one or several Virtual Bases

                For class C to be DLL-derivable,

                • Class C has to be sharable AND

                • Every virtual function in C or C's bases, virtual or otherwise, needs to be exported AND

                • All bases of C, virtual or otherwise, have to be DLL-derivable

                Note that link errors will occur if an attempt is made to DLL-derive a class from a base class that is not DLL-derivable.

                Boundary cases where Importing and Exporting Symbols is Illegal

                Static Symbols and Symbols in Anonymous Namespaces

                The following code examples are illegal. But note that not all ABI compliant compilers produce an error or a warning in these situations. This is because the behaviour of export and import is neither defined by the C++ standard, nor is it defined by the ABI for the ARM Architecture. The ABI describes a binary interface and is not concerned with matters of syntax.

                Exporting/importing static symbols

                Foo.cpp

                static IMPORT_C int i; -static EXPORT_C int j;

                Exporting/importing symbols defined in anonymous namespaces

                Foo.cpp

                namespace { // anonymous namespace -class CTest { -public: - IMPORT_C CTest() { m = 0; }; - EXPORT_C int get() { return m; }; -private: - int m; -}; -}

                Why is this illegal?

                These patterns are illegal because they do not make sense. In fact it is impossible to write any C or C++ client code outside the compile unit in which the imports/exports are defined (e.g. Foo.cpp), that makes use of any statically defined object or an object defined in an anonymous namespace.

                This means that it is impossible that any of the exported symbols in the above examples can ever be used by client code that is in another DLL.

                What happens if I use these patterns?

                The symbols that have been exported will appear in DEF files even though it is impossible to ever link against these symbols. Further the symbols contain a magic number. In the case of symbols in anonymous namespaces the symbol contains a filename and a magic number. For example:

                _ZN30_GLOBAL__N__7_ Foo_cpp _5b46ece4 5CTestE

                Where Foo_cpp is the filename and 5b46ece4 is the magic number.

                The ABI specifies that the magic number is unique. The creation of the magic number depends on the compiler. RVCT creates the magic number by computing a hash from the modification time-stamp of the source file and the top-level source directory.

                This means that in essence, the DEF file can never be frozen. If it is frozen, the Symbian toolchain will produce link errors, every single time the symbol changes. For RVCT this will happen every single time the source is changed, or when the user tries to build the source from a different source location than the person who froze the DEF file. Because the exported symbols can never be used, this is a trade-off without benefit.

                Classes in Anonymous Namespaces

                Because of the Simple Rule (see The Simple Rule – Sharable Classes) any class or structure that is defined in an anonymous namespace will export its Class Impedimenta. This means that by default, the compiler exports symbols that can never be used and cause a series of problems (see Static Symbols and Symbols in Anonymous Namespaces).

                The ABI for the ARM architecture v2.0 specifies this behaviour, which is at the very least unintuitive, if not incorrect.

                The following code snippet will by default export the Class Impedimenta of the shown class and structure and thus gives rise to the problems described in Static Symbols and Symbols in Anonymous Namespaces section. Note that the exported Class Impedimenta can never be used by any client code. In fact by default, any class that is defined in an anonymous namespace is non-sharable. This is true, regardless of whether Class Impedimenta are exported or not.

                Foo.cpp (incorrect)

                namespace { // anonymous namespace -class CTest {…}; -struct STest {…}; -}

                Thus, if you use anonymous namespaces, you must make sure to define them as non-sharable. For example:

                Foo.cpp

                namespace { // anonymous namespace -class NONSHARABLE_CLASS(CTest) {…}; -struct NONSHARABLE_STRUCT(STest) {…}; -}

                This has no draw-backs and avoids any difficulties with frozen DEF files. If you have used anonymous namespaces incorrectly in the past, add the relevant NONSHARABLE macro and re-freeze your DEF file using abld freeze - –r armv5. This will re-freeze the DEF file, leaving gaps where the removed exports would have been and thus does not affect binary compatibility.

                Auto-Exporting

                The Simple Rule only covers compiler implementation specific data items that are required to enable DLL-derivation. However the compiler may also emit and export implementation specific functions. This process is called auto-exporting. This section describes under which circumstances the compiler auto-exports. Note that the compiler also may generate symbols for EABI library functions (these start with __cxa or __eabi).

                Constructors and Destructors

                For each constructor/destructor in source, the compiler may create several instances of constructors/destructors in the object file, depending on how the constructor and destructors are used. If the constructor/destructor is exported, then all of the generated constructors/destructors are auto-exported. In such a case the following symbols may appear in your DEF file:

                _ZN…C1… complete object constructor

                _ZN…C2… base object constructor

                _ZN…C3… complete allocating constructor

                _ZN…D0… deleting destructor

                _ZN…D1… complete object destructor

                _ZN…D2… base object destructor

                Thunks

                Under the C++ ABI thunks occur in the presence of multiple inheritance or virtual inheritance. They are used to adjust the this pointer of a class before calling virtual functions. Details can be looked up in the ABI. The export of a thunk is triggered, when a virtual function that needs a thunk is exported. Thunks have the form _ZTh… or _ZTv…

                Class Impedimenta

                When checking DEF files non-callable exports and other compiler specific symbols may be present. The following list shows what some of these symbols mean:

                _ZTV… Virtual Table (VTABLE)

                _ZTI… Run-time Type Information (RTTI)

                _ZTT… Construction VTABLE

                _ZTh… Thunk emitted using multiple inheritance

                _ZTv… Thunk emitted using virtual inheritance

                ARM ABI Thunk Offset Problem

                Symptoms of the ARM ABI Thunk Offset Problem

                The "EABI Thunk Offset Problem" is the name that Symbian uses to describe a particular kind of build error which arises when multiple inheritance is used, and the size of a base class is changed. Here is an example of a typical symptom:

                MAKEDEF ERROR: 1 Frozen Export(s) missing from object files: -\src\example\MyDLLU.DEF(3) : _ZThn8_N7Derived3fooEv @2 -MAKEDEF WARNING: 1 export(s) not yet Frozen in \src\example\MyDLLU.DEF: -..\..\..\EPOC32\BUILD\src\example\group\MyDLL\ARMV5\MyDll{000a0000}.def(7) : _ZThn12_N7Derived3fooEv @6

                This shows a problem with a frozen DEF file: the export at ordinal 2 is missing, and a new unfrozen export has been added at ordinal 6. When comparing the two symbols, they look suspiciously similar to each other, and to a third symbol in the DEF file:

                _ZN7Derived3fooEv @1 -_ZThn8_N7Derived3fooEv @2 // this one is missing -_ZThn12_N7Derived3fooEv @6 // this one has appeared

                The exports beginning with _ZTh are compiler generated functions called thunks (see Class Impedimenta), and the information between _ZTh and the next underscore is the offset associated with the thunk. Our problem is that for some reason, the offset associated with the thunk has changed from –8 to –12 (the n denotes a negative offset). Note that there is another variant of this problem that involves thunks beginning with _ZTv.

                These generated functions are a feature of the Itanium C++ ABI, on which the ABI for the ARM architecture builds upon. Hence the name "ARM ABI Thunk Offset Problem".

                What causes this problem?

                The problem is caused because the symbol name generated for the thunk contains an offset number. More details can be found in http://www.codesourcery.com/cxx-abi/abi.html under section 5.1.4. This offset may change, when the signature of the base class is changed. For example when a data member is added or removed.

                Another condition to trigger the problem needs to hold as well: multiple inheritance with virtual functions in more than one of the base classes. If this condition does not hold, the compiler will not generate a thunk and thus there is no problem.

                Note that this is always a Binary Compatibility break, which shows up as a change to symbols in DEF files.

                How do I fix it?

                There are three choices to fix it:

                1. The first option is to refreeze the DEF file: this would be OK if you are not maintaining a frozen interface, and your customers will in any case need to rebuild because of the Binary Compatibility break. The easiest way to refreeze is to delete all of the exports from your existing DEF file, build again, and then use "abld freeze armv5 " to update the DEF file. After updating the DEF file, build again: this time it should build cleanly.

                2. The second option is to use the attached script to fix the ABI Thunk Offsets. It expects to read a build log containing the MAKEDEF errors and warnings and will modify the DEF file to replace each missing export with the corresponding unfrozen export. Run the script with no arguments to get further details.

                  After fixing the DEF file, you will need to rebuild the DLL which uses the DEF file.

                3. The last option is that you could change your mind about adding that extra member data. This will only be an option if it is your change which causes the problem: if your supplier has changed the size of a class that they own and caused this problem, then you are forced to change your DEF file.

                  If you own the class which has the extra member data, it is worth noting that this change is likely to affect your customers as well. They will have to rebuild because of the BC break. Adding to this they will also see the ABI Thunk Offset Problem if they derive from your class. This includes simple inheritance from a class which shows the problem, if it re-implements any of the virtual functions which require thunks.

                  When Symbian breaks compatibility in a way likely to cause this problem, the corresponding entry in the Compatibility Break spreadsheet will say "BC+ Break: Rebuild & Check/Fix Def-File EABI Thunk Offsets".

                Tell me the full details: What is a thunk? What causes its offset to change?

                In a C++ class hierarchy involving both virtual functions and multiple inheritance, objects can be accessed as though they were several different types. A typical Symbian platform example would be a CBase-derived class which also derives from an M-class, perhaps to provide an observer interface: for example CCoeControl, which derives from both CBase and MObjectProvider.

                The virtual functions which can be called on an object depends on the type it currently appears to be.A CCoeControl object can be viewed as a CBase object, in which case it has one set of virtual functions, or as an MObjectProvider, in which case it has another. The compiler constructs separate virtual tables for each of the possible interfaces, and these tables contain information about how to convert back to the underlying CCoeControl object. When converting from a CCoeControl pointer to an MObjectProvider pointer, the compiler will adjust the value of the pointer, so that it points to the "MObjectProvider" part of the object, and not the full CCoeControl object.

                The MObjectProvider class defines a pure virtual function MopSupplyObject, which is implemented in CCoeControl. Even when the object is presenting it's MObjectProvider interface, the vtable must use the correct implementation of MopSupplyObject, which expects to be used in the context of a CCoeControl. The solution used by the compiler is to create a virtual function override thunk function which makes any necessary adjustments between the calling context (a pointer to MObjectProvider) and the execution context (a pointer to CCoeControl).

                This could have been implemented using the names of the two contexts, but instead the ABI uses the amount by which the this pointer needs to be adjusted to make the switch: this is the offset encoded in the name.

                Here is a small example:

                eabi_thunk_offset_problem.cpp

                #ifndef COUNT -#define COUNT 1 -#endif - -class Base -{ -public: - int iBaseMember[COUNT]; - virtual ~Base(); -}; - -class MInterface -{ -public: - virtual int foo(); -}; - -class Derived : public Base, public MInterface -{ -public: - virtual int foo(); - int iDerived; -}; - -class MoreDerived : public Derived -{ -public: - virtual int foo(); - int iMoreDerived; -}; - -int Derived::foo() { return iDerived; } -Derived* fun1() { return new Derived; } -MInterface* fun2() { return new Derived; } - -int MoreDerived::foo() { return iMoreDerived; } -MoreDerived* fun3() { return new MoreDerived; } -MInterface* fun4() { return new MoreDerived; } -

                Compile this with armcc -S eabi_thunk_offset_problem.cpp to get an assembly listing. Compile it again with an extra argument "-DCOUNT=2" to change the size of the base class, and compare the two files: there will be various differences in the code, but also differences in the _ZTh symbols - including the differences used in the "typical symptom" above.

                If you use virtual inheritance, then you may see another version of the problem. With virtual inheritance, there are two offsets involved and the thunk symbols will begin with _ZTv. The same symbol may appear in several thunks, each with different offsets.

                The Shared DEF File Problem

                What is the Problem with Shared DEF Files?

                The class exporting rules (see Class Exporting Rules) by default will generate non-callable exports for all classes that are not marked non-sharable in source. Say two DLLs, A and B share one DEF file, in effect implementing similar but different functionality towards the same public interface. Further say, no classes are marked non-sharable. Say there are some classes that are shared between DLL A and DLL B and that these classes have names of the form CShared<xyz>. Classes that are specific to DLL A have names of the form CA<xyz>, classes specific to DLL B have names of the form CB<xyz>. When DLL A is built, DEF file entries for non-callable exports from CShared<xyz> and CA<XYZ> are automatically added to the DEF file. When DLL B is built, exports from CShared<xyz> and CB<XYZ> are added. So in fact the DEF file would be the sum of all non-callable exports from CShared<xyz>, CA<xyz> and CB<XYZ>. It also will contain symbols from functions that are marked for export using EXPORT_C. However, this means that neither A or B can be linked. This is because when A is built, the code linking against the non-callable exports of CB<XYZ> do not exist in A and vice versa.

                Use-cases for Fixing Shared DEF Files

                Use-Case 1: Polymorphic “Plug-ins”

                Several DLLs are built using the same DLL interface (DEF file). Typically the DEF file has very few entries (1 or 2) and is maintained manually. This means that new functions are added by editing the shared DEF file. Also typically no import libraries are needed as the knowledge about the DLL interface is hard-coded into the client code of the "plug-in". The plug-ins do not have to be loaded at run-time. Some are always built but not always included in the ROM.

                The Fix:

                1. If the shared DEF file is in \epoc32\include\def\EABI then locate the original DEF file by searching all BLD.INF files for the appropriate line in PRJ_EXPORTS

                2. Remove all non-callable exports that have caused warnings or errors from the original DEF file.

                3. Add NOEXPORTLIBRARY to all MMP files that share that component, ensuring that the build system does NOT try and re-freeze these automatically the next time you build. Otherwise the build system will re-introduce these non-callable exports.

                Note:

                If you want to use the re-freeze mechanism – say to add a new export, you have to temporarily remove NOEXPORTLIBRARY from the MMP file, then generate a new DEF file by re-building the component, re-freeze, possibly edit (to remove unwanted non-callable exports) and then insert the keyword NOEXPORTLIBRARY into the MMP file again.

                Use-Case 2: Polymorphic “Plug-ins” on which Other Components Depend

                This is very similar to use-case 1, except that some other component depends on one of the plug-ins. This means that an import library is required.

                The Fix: The build structure must be such that

                • One MMP file generates the import library from the shared DEF file using the target type IMPLIB. It may be necessary to create a new MMP file which does this.

                • All the other MMP files use NOEXPORTLIBRARY as described in use-case 1

                Note:

                If you want to use the re-freeze mechanism – say to add a new export, you have to temporarily remove NOEXPORTLIBRARY from the MMP file, then generate a new DEF file by re-building the component, re-freeze, possibly edit (to remove unwanted non-callable exports) and then insert the keyword NOEXPORTLIBRARY into the MMP file again.

                Use-Case 3: Annotate Classes as Non-sharable

                Where a DEF file must be shared between components for whatever reason and none of the above use-cases can be applied, the build would fail for at least one component. An example of this may be a class MyPrivateClass that exists in the debug build (UDEV) of the OS, but not in the release build (UREL).

                In such a case all classes that should not contribute to the DEF file, i.e. that are really private to the implementation of a component, must be annotated in the source as NONSHARABLE_CLASS(X) or NONSHARABLE_STRUCT(X). As a result no non-callable exports will be generated for such a class. Say for example, class MyPrivateClass is truly private to a component that must share a DEF file with another component. Then it should be declared:

                NONSHARABLE_CLASS(MyPrivateClass) - { - ... + + + + + +Exporting and Importing Classes

                This document discusses importing and exporting of classes.

                In particular this document describes:

                • Class exporting rules:

                  • DLL-derivation

                  • Non-sharable classes

                  • The Simple Rule

                  • Class impedimenta

                  • Boundary cases where importing and exporting symbols are illegal, which some ABI compilers accept without warnings or errors

                • The ARM ABI Thunk Offset Problem

                • The Shared DEF File Problem

                The information described in this document is valid for RVCT 2.1 build 416 or later and for any compiler that is compliant with the ARM ABI v2.0 and higher.

                Definitions

                Terminology and Background

                • For all of this section it is assumed that the user intends to derive class D from class C and that both classes reside in different DLLs.

                • Class C is called DLL-derivable, if class D can be derived from C.

                • Class C is called non-sharable if it is marked using __ declspec(notshared) or using the macros NONSHARABLE_CLASS(x) or NONSHARABLE_ STRUCT(x). It is not possible to DLL-derive from a non-sharable class. Otherwise class C is called sharable.

                • Class Impedimenta are entities that are emitted by the compiler for any class, but do not have a direct representation in source. Examples of class impedimenta are:

                  • the class’s virtual table, or

                  • a virtual table’s thunks, or

                  • the class’s run-time type information

                  Class impedimenta are a key element of the ABI and are identified through ELF symbols. They play a crucial role in enabling polymorphism, RTTI and derivation. This means that they also play a key role in DLL-derivation. In fact, if the Class Impedimenta of class C are not exported, it is not possible to DLL derive from class C or in other words class C is non-sharable.

                  This raises the interesting question as to how it is possible to export Class Impedimenta – and thus enable DLL-derivation – if they have no representation in source. The answer to this question is given in The Simple Rule – Sharable Classes section.

                • Non-callable exports are Class Impedimenta that are exported. They are often used as synonym for Class Impedimenta in this document.

                • A key function is the first non-inline, non-pure virtual function of a class.

                Symbian Conventions

                Symbian defines macros for exporting and importing classes to hide implementation details:

                Macro

                RVCT Implementation

                IMPORT_C func-declaration

                __declspec(dllimport) func-declaration

                EXPORT_C func-definition

                __declspec(dllexport) func-definition

                NONSHARABLE_CLASS(x)

                class __declspec(notshared) x

                NONSHARABLE_STRUCT(x)

                struct __declspec(notshared) x

                class NONSHARABLE name struct NONSHARABLE name

                __declspec(notshared)

                This macro does not yet exist in the Symbian platform source code. However all known ABI compliant compiler support the notations

                • struct __declspec(notshared) x

                • class __declspec(notshared) x

                which means that it is safe to define a simpler macro which does not require an argument. That macro could also be used in conjunction with templates.

                Class Exporting Rules

                This section is a programmer’s summary of the Class Exporting Rules.

                Exporting Objects

                A function, method of a class or data item is exported by marking its definition using the EXPORT_C macro. A function, method of a class or data item is imported by marking its declaration using the IMPORT_C macro. If an object is declared IMPORT_C and used in code, the linker will error if the definition of this object is not marked EXPORT_C.

                Although not required by the class exporting rules it is good practice to

                • Always mark all declarations of an exported object with IMPORT_C.

                • Never mark objects that are not exported with IMPORT_C.

                The Simple Rule – Sharable Classes

                The compiler will automatically export allClass Impedimenta, i.e. compiler implementation specific symbols of a class C such as run-time-type-information and virtual tables, that are required to enable DLL-derivation from class C. This means that all classes are by default sharable.

                The compiler will not export these symbols for classes that are marked as non-sharable using the macros NONSHARABLE_CLASS(x) or NONSHARABLE_STRUCT(x). Symbian requires that all classes that are derived from a non-sharable class are also marked non-sharable.

                Other methods or functions in classes are not automatically exported. They have to be explicitly exported as described in Exporting objects section. Note that a class with virtual functions or virtual may not be DLL-derivable if the conditions in Dll derivable classes section do not hold.

                Example: The following example shows the correct syntax to define a class as non-sharable:

                NONSHARABLE_CLASS(NonSharableClass) : public BaseClass …

                Note: The Simple Rule has consequences in terms of how many entries are present in DEF files and for shared DEF files. See The Shared DEF File Problem section for more details.

                DLL-Derivable Classes

                The Simple Rule alone does not guarantee that the class C is DLL-derivable. Depending on the form of the class, additional conditions on exporting members of class C apply. This section outlines the conditions under which class C is DLL-derivable.

                C has no Virtual Base

                For class C to be DLL-derivable,

                • Class C has to be sharable AND

                • Every virtual function in C or C's bases that is not overridden in D needs to be exported

                • If the class C has no key function, i.e. it only has pure virtuals or inlined virtuals, all bases of C also have to be DLL-derivable.

                C has one or several Virtual Bases

                For class C to be DLL-derivable,

                • Class C has to be sharable AND

                • Every virtual function in C or C's bases, virtual or otherwise, needs to be exported AND

                • All bases of C, virtual or otherwise, have to be DLL-derivable

                Note that link errors will occur if an attempt is made to DLL-derive a class from a base class that is not DLL-derivable.

                Boundary cases where Importing and Exporting Symbols is Illegal

                Static Symbols and Symbols in Anonymous Namespaces

                The following code examples are illegal. But note that not all ABI compliant compilers produce an error or a warning in these situations. This is because the behaviour of export and import is neither defined by the C++ standard, nor is it defined by the ABI for the ARM Architecture. The ABI describes a binary interface and is not concerned with matters of syntax.

                Exporting/importing static symbols

                Foo.cpp

                static IMPORT_C int i; +static EXPORT_C int j;

                Exporting/importing symbols defined in anonymous namespaces

                Foo.cpp

                namespace { // anonymous namespace +class CTest { +public: + IMPORT_C CTest() { m = 0; }; + EXPORT_C int get() { return m; }; +private: + int m; +}; +}

                Why is this illegal?

                These patterns are illegal because they do not make sense. In fact it is impossible to write any C or C++ client code outside the compile unit in which the imports/exports are defined (e.g. Foo.cpp), that makes use of any statically defined object or an object defined in an anonymous namespace.

                This means that it is impossible that any of the exported symbols in the above examples can ever be used by client code that is in another DLL.

                What happens if I use these patterns?

                The symbols that have been exported will appear in DEF files even though it is impossible to ever link against these symbols. Further the symbols contain a magic number. In the case of symbols in anonymous namespaces the symbol contains a filename and a magic number. For example:

                _ZN30_GLOBAL__N__7_ Foo_cpp _5b46ece4 5CTestE

                Where Foo_cpp is the filename and 5b46ece4 is the magic number.

                The ABI specifies that the magic number is unique. The creation of the magic number depends on the compiler. RVCT creates the magic number by computing a hash from the modification time-stamp of the source file and the top-level source directory.

                This means that in essence, the DEF file can never be frozen. If it is frozen, the Symbian toolchain will produce link errors, every single time the symbol changes. For RVCT this will happen every single time the source is changed, or when the user tries to build the source from a different source location than the person who froze the DEF file. Because the exported symbols can never be used, this is a trade-off without benefit.

                Classes in Anonymous Namespaces

                Because of the Simple Rule (see The Simple Rule – Sharable Classes) any class or structure that is defined in an anonymous namespace will export its Class Impedimenta. This means that by default, the compiler exports symbols that can never be used and cause a series of problems (see Static Symbols and Symbols in Anonymous Namespaces).

                The ABI for the ARM architecture v2.0 specifies this behaviour, which is at the very least unintuitive, if not incorrect.

                The following code snippet will by default export the Class Impedimenta of the shown class and structure and thus gives rise to the problems described in Static Symbols and Symbols in Anonymous Namespaces section. Note that the exported Class Impedimenta can never be used by any client code. In fact by default, any class that is defined in an anonymous namespace is non-sharable. This is true, regardless of whether Class Impedimenta are exported or not.

                Foo.cpp (incorrect)

                namespace { // anonymous namespace +class CTest {…}; +struct STest {…}; +}

                Thus, if you use anonymous namespaces, you must make sure to define them as non-sharable. For example:

                Foo.cpp

                namespace { // anonymous namespace +class NONSHARABLE_CLASS(CTest) {…}; +struct NONSHARABLE_STRUCT(STest) {…}; +}

                This has no draw-backs and avoids any difficulties with frozen DEF files. If you have used anonymous namespaces incorrectly in the past, add the relevant NONSHARABLE macro and re-freeze your DEF file using abld freeze + –r armv5. This will re-freeze the DEF file, leaving gaps where the removed exports would have been and thus does not affect binary compatibility.

                Auto-Exporting

                The Simple Rule only covers compiler implementation specific data items that are required to enable DLL-derivation. However the compiler may also emit and export implementation specific functions. This process is called auto-exporting. This section describes under which circumstances the compiler auto-exports. Note that the compiler also may generate symbols for EABI library functions (these start with __cxa or __eabi).

                Constructors and Destructors

                For each constructor/destructor in source, the compiler may create several instances of constructors/destructors in the object file, depending on how the constructor and destructors are used. If the constructor/destructor is exported, then all of the generated constructors/destructors are auto-exported. In such a case the following symbols may appear in your DEF file:

                _ZN…C1… complete object constructor

                _ZN…C2… base object constructor

                _ZN…C3… complete allocating constructor

                _ZN…D0… deleting destructor

                _ZN…D1… complete object destructor

                _ZN…D2… base object destructor

                Thunks

                Under the C++ ABI thunks occur in the presence of multiple inheritance or virtual inheritance. They are used to adjust the this pointer of a class before calling virtual functions. Details can be looked up in the ABI. The export of a thunk is triggered, when a virtual function that needs a thunk is exported. Thunks have the form _ZTh… or _ZTv…

                Class Impedimenta

                When checking DEF files non-callable exports and other compiler specific symbols may be present. The following list shows what some of these symbols mean:

                _ZTV… Virtual Table (VTABLE)

                _ZTI… Run-time Type Information (RTTI)

                _ZTT… Construction VTABLE

                _ZTh… Thunk emitted using multiple inheritance

                _ZTv… Thunk emitted using virtual inheritance

                ARM ABI Thunk Offset Problem

                Symptoms of the ARM ABI Thunk Offset Problem

                The "EABI Thunk Offset Problem" is the name that Symbian uses to describe a particular kind of build error which arises when multiple inheritance is used, and the size of a base class is changed. Here is an example of a typical symptom:

                MAKEDEF ERROR: 1 Frozen Export(s) missing from object files: +\src\example\MyDLLU.DEF(3) : _ZThn8_N7Derived3fooEv @2 +MAKEDEF WARNING: 1 export(s) not yet Frozen in \src\example\MyDLLU.DEF: +..\..\..\EPOC32\BUILD\src\example\group\MyDLL\ARMV5\MyDll{000a0000}.def(7) : _ZThn12_N7Derived3fooEv @6

                This shows a problem with a frozen DEF file: the export at ordinal 2 is missing, and a new unfrozen export has been added at ordinal 6. When comparing the two symbols, they look suspiciously similar to each other, and to a third symbol in the DEF file:

                _ZN7Derived3fooEv @1 +_ZThn8_N7Derived3fooEv @2 // this one is missing +_ZThn12_N7Derived3fooEv @6 // this one has appeared

                The exports beginning with _ZTh are compiler generated functions called thunks (see Class Impedimenta), and the information between _ZTh and the next underscore is the offset associated with the thunk. Our problem is that for some reason, the offset associated with the thunk has changed from –8 to –12 (the n denotes a negative offset). Note that there is another variant of this problem that involves thunks beginning with _ZTv.

                These generated functions are a feature of the Itanium C++ ABI, on which the ABI for the ARM architecture builds upon. Hence the name "ARM ABI Thunk Offset Problem".

                What causes this problem?

                The problem is caused because the symbol name generated for the thunk contains an offset number. More details can be found in http://www.codesourcery.com/cxx-abi/abi.html under section 5.1.4. This offset may change, when the signature of the base class is changed. For example when a data member is added or removed.

                Another condition to trigger the problem needs to hold as well: multiple inheritance with virtual functions in more than one of the base classes. If this condition does not hold, the compiler will not generate a thunk and thus there is no problem.

                Note that this is always a Binary Compatibility break, which shows up as a change to symbols in DEF files.

                How do I fix it?

                There are three choices to fix it:

                1. The first option is to refreeze the DEF file: this would be OK if you are not maintaining a frozen interface, and your customers will in any case need to rebuild because of the Binary Compatibility break. The easiest way to refreeze is to delete all of the exports from your existing DEF file, build again, and then use "abld freeze armv5 " to update the DEF file. After updating the DEF file, build again: this time it should build cleanly.

                2. The second option is to use the attached script to fix the ABI Thunk Offsets. It expects to read a build log containing the MAKEDEF errors and warnings and will modify the DEF file to replace each missing export with the corresponding unfrozen export. Run the script with no arguments to get further details.

                  After fixing the DEF file, you will need to rebuild the DLL which uses the DEF file.

                3. The last option is that you could change your mind about adding that extra member data. This will only be an option if it is your change which causes the problem: if your supplier has changed the size of a class that they own and caused this problem, then you are forced to change your DEF file.

                  If you own the class which has the extra member data, it is worth noting that this change is likely to affect your customers as well. They will have to rebuild because of the BC break. Adding to this they will also see the ABI Thunk Offset Problem if they derive from your class. This includes simple inheritance from a class which shows the problem, if it re-implements any of the virtual functions which require thunks.

                  When Symbian breaks compatibility in a way likely to cause this problem, the corresponding entry in the Compatibility Break spreadsheet will say "BC+ Break: Rebuild & Check/Fix Def-File EABI Thunk Offsets".

                Tell me the full details: What is a thunk? What causes its offset to change?

                In a C++ class hierarchy involving both virtual functions and multiple inheritance, objects can be accessed as though they were several different types. A typical Symbian platform example would be a CBase-derived class which also derives from an M-class, perhaps to provide an observer interface: for example CCoeControl, which derives from both CBase and MObjectProvider.

                The virtual functions which can be called on an object depends on the type it currently appears to be.A CCoeControl object can be viewed as a CBase object, in which case it has one set of virtual functions, or as an MObjectProvider, in which case it has another. The compiler constructs separate virtual tables for each of the possible interfaces, and these tables contain information about how to convert back to the underlying CCoeControl object. When converting from a CCoeControl pointer to an MObjectProvider pointer, the compiler will adjust the value of the pointer, so that it points to the "MObjectProvider" part of the object, and not the full CCoeControl object.

                The MObjectProvider class defines a pure virtual function MopSupplyObject, which is implemented in CCoeControl. Even when the object is presenting it's MObjectProvider interface, the vtable must use the correct implementation of MopSupplyObject, which expects to be used in the context of a CCoeControl. The solution used by the compiler is to create a virtual function override thunk function which makes any necessary adjustments between the calling context (a pointer to MObjectProvider) and the execution context (a pointer to CCoeControl).

                This could have been implemented using the names of the two contexts, but instead the ABI uses the amount by which the this pointer needs to be adjusted to make the switch: this is the offset encoded in the name.

                Here is a small example:

                eabi_thunk_offset_problem.cpp

                #ifndef COUNT +#define COUNT 1 +#endif + +class Base +{ +public: + int iBaseMember[COUNT]; + virtual ~Base(); +}; + +class MInterface +{ +public: + virtual int foo(); +}; + +class Derived : public Base, public MInterface +{ +public: + virtual int foo(); + int iDerived; +}; + +class MoreDerived : public Derived +{ +public: + virtual int foo(); + int iMoreDerived; +}; + +int Derived::foo() { return iDerived; } +Derived* fun1() { return new Derived; } +MInterface* fun2() { return new Derived; } + +int MoreDerived::foo() { return iMoreDerived; } +MoreDerived* fun3() { return new MoreDerived; } +MInterface* fun4() { return new MoreDerived; } +

                Compile this with armcc -S eabi_thunk_offset_problem.cpp to get an assembly listing. Compile it again with an extra argument "-DCOUNT=2" to change the size of the base class, and compare the two files: there will be various differences in the code, but also differences in the _ZTh symbols - including the differences used in the "typical symptom" above.

                If you use virtual inheritance, then you may see another version of the problem. With virtual inheritance, there are two offsets involved and the thunk symbols will begin with _ZTv. The same symbol may appear in several thunks, each with different offsets.

                The Shared DEF File Problem

                What is the Problem with Shared DEF Files?

                The class exporting rules (see Class Exporting Rules) by default will generate non-callable exports for all classes that are not marked non-sharable in source. Say two DLLs, A and B share one DEF file, in effect implementing similar but different functionality towards the same public interface. Further say, no classes are marked non-sharable. Say there are some classes that are shared between DLL A and DLL B and that these classes have names of the form CShared<xyz>. Classes that are specific to DLL A have names of the form CA<xyz>, classes specific to DLL B have names of the form CB<xyz>. When DLL A is built, DEF file entries for non-callable exports from CShared<xyz> and CA<XYZ> are automatically added to the DEF file. When DLL B is built, exports from CShared<xyz> and CB<XYZ> are added. So in fact the DEF file would be the sum of all non-callable exports from CShared<xyz>, CA<xyz> and CB<XYZ>. It also will contain symbols from functions that are marked for export using EXPORT_C. However, this means that neither A or B can be linked. This is because when A is built, the code linking against the non-callable exports of CB<XYZ> do not exist in A and vice versa.

                Use-cases for Fixing Shared DEF Files

                Use-Case 1: Polymorphic “Plug-ins”

                Several DLLs are built using the same DLL interface (DEF file). Typically the DEF file has very few entries (1 or 2) and is maintained manually. This means that new functions are added by editing the shared DEF file. Also typically no import libraries are needed as the knowledge about the DLL interface is hard-coded into the client code of the "plug-in". The plug-ins do not have to be loaded at run-time. Some are always built but not always included in the ROM.

                The Fix:

                1. If the shared DEF file is in \epoc32\include\def\EABI then locate the original DEF file by searching all BLD.INF files for the appropriate line in PRJ_EXPORTS

                2. Remove all non-callable exports that have caused warnings or errors from the original DEF file.

                3. Add NOEXPORTLIBRARY to all MMP files that share that component, ensuring that the build system does NOT try and re-freeze these automatically the next time you build. Otherwise the build system will re-introduce these non-callable exports.

                Note:

                If you want to use the re-freeze mechanism – say to add a new export, you have to temporarily remove NOEXPORTLIBRARY from the MMP file, then generate a new DEF file by re-building the component, re-freeze, possibly edit (to remove unwanted non-callable exports) and then insert the keyword NOEXPORTLIBRARY into the MMP file again.

                Use-Case 2: Polymorphic “Plug-ins” on which Other Components Depend

                This is very similar to use-case 1, except that some other component depends on one of the plug-ins. This means that an import library is required.

                The Fix: The build structure must be such that

                • One MMP file generates the import library from the shared DEF file using the target type IMPLIB. It may be necessary to create a new MMP file which does this.

                • All the other MMP files use NOEXPORTLIBRARY as described in use-case 1

                Note:

                If you want to use the re-freeze mechanism – say to add a new export, you have to temporarily remove NOEXPORTLIBRARY from the MMP file, then generate a new DEF file by re-building the component, re-freeze, possibly edit (to remove unwanted non-callable exports) and then insert the keyword NOEXPORTLIBRARY into the MMP file again.

                Use-Case 3: Annotate Classes as Non-sharable

                Where a DEF file must be shared between components for whatever reason and none of the above use-cases can be applied, the build would fail for at least one component. An example of this may be a class MyPrivateClass that exists in the debug build (UDEV) of the OS, but not in the release build (UREL).

                In such a case all classes that should not contribute to the DEF file, i.e. that are really private to the implementation of a component, must be annotated in the source as NONSHARABLE_CLASS(X) or NONSHARABLE_STRUCT(X). As a result no non-callable exports will be generated for such a class. Say for example, class MyPrivateClass is truly private to a component that must share a DEF file with another component. Then it should be declared:

                NONSHARABLE_CLASS(MyPrivateClass) + { + ... };

                This will prevent the compiler from exporting non-callables for MyPrivateClass. However this means that it is not possible to DLL-derive (for the definition of DLL-derive see Terminology and Background) from MyPrivateClass and that all classes derived from MyPrivateClass must also be marked non-sharable (see Terminology and Background).

                Use-Case 4: Optimisation

                A consequence of the Simple Rule (see The Simple Rule – Sharable Classes) is that some components may emit entries in their DEF files which are not needed. In the worst case the overhead is 8 bytes of ROM size per class (2 DLL entry points). In the typical case an increase of 4 bytes will occur and in some cases no increase at all.

                For code that is private to an implementation, i.e. where it is known that a class would never be used outside of that component, this footprint increase is unnecessary. In order to avoid the footprint increase mark all private classes (and classes derived from them) in the source as NONSHARABLE_CLASS(X) or NONSHARABLE_STRUCT(X) as described for use-case 3.

                Use-Case 5: The Build Tools Automatically Ignore Non-callable Exports

                For most components the build tools automatically ignore all non-callable exports. This is the case because the build tools know the situations when non-callable exports cannot be needed. Non-callable exports are only needed, if:

                • The target type is either DLL, EXEDLL or EXEXP and the MMP file has no NOEXPORTLIBRARY keyword

                • If the MMP file contains the DEFFILE keyword and the MMP file has no NOEXPORTLIBRARY keyword

                The reason for this is that target types, such as APP, always map directly onto one of the above use-cases. For example the target type APP is an example of use-case 1, i.e. the APP is a DLL that always has the same DEF file. However no other DLL but the APP loader will ever link against this binary, unless its MMP file contains the DEFFILE keyword.

                Use-Case 6: Best Practice

                Note that it is good practice to avoid unnecessary footprint increases by marking private classes as non-sharable as outlined in use-case 4. Further note, that at some point in the future Symbian may add this to the Symbian Coding Standards or withdraw tools support for some of the cases described above.

                Optimisation

                This section discusses advantages of marking “private” classes as described in use-cases 4 and 6 in the previous section as non-sharable

                Reasons for Optimisation:

                • Small footprint saving

                • DEF files are more “pretty”, i.e. they will have fewer entries for non-callable exports in it and may have fewer holes in them.

                • When changing code that is private to a module as described in use-case 4 and not marked non-sharable, DEF file changes are required when:

                  • Renaming a private class

                  • Removing a private class

                  • Adding a private class

                  This makes it harder to maintain DEF files and will ultimately lead to less “pretty” DEF files when Binary Compatibility must be maintained.

                • More non-sharable classes mean that it is less likely to have problems with shared DEF files as outlined in use-cases 1 and 2 in the previous section.

                When not to use Optimisation:

                It is not advisable to use optimisation in the following circumstances, as the build tools suppress non-callable exports automatically in these cases:

                • The target type of the component containing private classes is neither DLL, EXEDLL nor EXEXP and no DEFFILE keyword is contained the components MMP file

                • The MMP file of the component contains the NOEXPORTLIBRARY keyword.

                  If the NOEXPORTLIBRARY keyword has been introduced to work around problems introduced by shared DEF files and the Simple Rule it may be better to remove the NOEXPORTLIBRARY keyword and mark private classes as non-sharable instead.

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CCE61F55-DDCC-566B-B4C6-E094E8E8B073_d0e316250_href.png Binary file Symbian3/SDK/Source/GUID-CCE61F55-DDCC-566B-B4C6-E094E8E8B073_d0e316250_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CCE61F55-DDCC-566B-B4C6-E094E8E8B073_d0e322407_href.png Binary file Symbian3/SDK/Source/GUID-CCE61F55-DDCC-566B-B4C6-E094E8E8B073_d0e322407_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CCE6DC36-625C-487C-9AD8-F1BF8E36080A.dita --- a/Symbian3/SDK/Source/GUID-CCE6DC36-625C-487C-9AD8-F1BF8E36080A.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-CCE6DC36-625C-487C-9AD8-F1BF8E36080A.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,245 +1,202 @@ - - - - - -UI -components -

                This table has been filtered for -PDK, SDK and Internal publications. The conditions applied for each row can -be viewed in the Document Map on the left hand pane (they have attribute mark).

                - - - - -

                Component

                 -

                Example image

                 -

                C++ APIs for implementation

                 -                 - - - - - -

                Stylus -pop-up menu

                 - - - -

                Stylus pop-up menu API

                 -                 - -

                Toolbar

                -                 - - - -

                Toolbar -API, Generic -button API for buttons

                 -                 - -

                Choice list

                 - - - -

                Choice list -API

                 -                 - -

                Forms

                -                 - - - -

                Form API

                 -                 - -

                Form -items

                  -

                • Text field

                  • -

                • Pop-up field

                  • -

                • Slider

                  • -
                 - - - -

                Form API

                 -                 - -

                Grouped -soft notification, List -query, Grid -query

                 - - - -

                Queries API

                 -                 - -

                Left/Right arrows in the Navi -pane

                 - - - -

                Navigation pane API

                 -                 - -

                Markable -list

                Selection -list

                 - - - -

                Lists API

                 -                 - -

                Menu list (e.g., Options -menu and submenus)

                 - - - -

                Options menu API

                 -                 - -

                Multi-selection -list

                 - - - -

                Lists API

                 -                 - -

                Preview -pop-up

                 - - - -

                Information preview pop-up API

                 -                 - -

                Scroll -pane

                 - - - -

                Scroller API

                 -                 - -

                Setting items -

                - -

                Setting pages API

                 -                 - -

                Pop-up setting

                 - - - -

                - - -

                Multi-selection list setting

                 - - - -

                - - -

                Text setting

                 - - - -

                - - -

                Slider setting

                 - - - -

                - - -

                Setting -list

                 - - - -

                Setting pages API, Lists API

                 -                 - -

                Softkeys (left and right) in the Control -pane

                There is no middle softkey label in Touch -UI                 - - - -

                Buttons API

                 -                 - -

                Tabs in the Navi -pane

                 - - - -

                Tabs API, Navigation pane API (container)

                 -                 - -

                Status -pane

                  -

                • Title -pane

                  • -

                • Navi -pane

                  • -

                • Battery -pane

                  • -

                • Universal -indicator pane

                  • -

                • Signal -pane

                  • -
                 - - - -
                  -

                • Status pane API for the entire status pane

                  • -

                • Title pane API for the title pane

                  • -

                • Title Pane Touch Observer API for title pane touch events

                  • -

                • Navigation pane API for the entire navi pane

                  • -

                • Tabs API for tabs in the navi pane

                  • -

                • HWRM power state API for a publish and subscribe interface to battery -status

                  • -

                • Indicators API for the indicator pane

                  • -

                • The signal pane is not accessible to applications.

                  • -
                 -                 - -

                Slider -pop-up

                  -

                • Volume Controller

                  • -
                 - - - - -                 - -

                Universal -indicator pop-up

                 - - - - -                 - - -
                -

                For details on touch support of these components, see Touch -support for UI components

                + + + + + +UI components +

                This table has been filtered for +PDK, SDK and Internal publications. The conditions applied for each row can +be viewed in the Document Map on the left hand pane (they have attribute mark).

                + + + + +

                Component

                 +

                Example image

                 +

                C++ APIs for implementation

                 +                 + + + + + + + + + + + + + +

                Toolbar

                +                 + + + +

                Toolbar +API, Generic +button API for buttons

                 +                 + +

                Choice list

                 + + + +

                Choice list +API

                 +                 + +

                Forms

                +                 + + + +

                Form API

                 +                 + +

                Form +items

                  +

                • Text field

                  • +

                • Pop-up field

                  • +

                • Slider

                  • +
                 + + + +

                Form API

                 +                 + +

                Grouped +soft notification, List +query, Grid +query

                 + + + +

                Queries API

                 +                 + +

                Left/Right arrows in the Navi +pane

                 + + + +

                Navigation pane API

                 +                 + +

                Markable +list

                Selection +list

                 + + + +

                Lists API

                 +                 + +

                Multi-selection +list

                 + + + +

                Lists API

                 +                 + +

                Scrollbar

                +                 + + + +

                Scroller API

                 +                 + +

                Setting items

                 + +

                Setting pages API

                 +                 + +

                Pop-up setting

                 + + + +

                + + +

                Multi-selection list setting

                 + + + +

                + + +

                Text setting

                 + + + +

                + + +

                Slider setting

                 + + + +

                + + +

                Setting +list

                 + + + +

                Setting pages API, Lists API

                 +                 + +

                Softkeys (left and right) in the Control +pane

                There is no middle softkey label in Touch +UI                 + + + +

                Buttons API

                 +                 + +

                Status +pane

                  +

                • Title +pane

                  • +

                • Navi +pane

                  • +

                • Battery +pane

                  • +

                • Universal +indicator pane

                  • +

                • Signal +pane

                  • +

                • Clock Pane

                  • +
                 + + + +
                  +

                • Status pane API for the entire status pane

                  • +

                • Title pane API for the title pane

                  • +

                • Title Pane Touch Observer API for title pane touch events

                  • +

                • Navigation pane API for the entire navi pane

                  • +

                • Tabs API for tabs in the navi pane

                  • +

                • HWRM power state API for a publish and subscribe interface to battery +status

                  • +

                • Indicators API for the indicator pane

                  • +

                • The signal pane is not accessible to applications.

                  • +
                 +                 + + +
                +

                For details on touch support of these components, see Touch +support for UI components

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CCEE3988-C10A-538A-8107-E2636594443B_d0e320575_href.png Binary file Symbian3/SDK/Source/GUID-CCEE3988-C10A-538A-8107-E2636594443B_d0e320575_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CCEE3988-C10A-538A-8107-E2636594443B_d0e326732_href.png Binary file Symbian3/SDK/Source/GUID-CCEE3988-C10A-538A-8107-E2636594443B_d0e326732_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CD2BF0EE-5437-4ADA-A447-4B06147754A8.dita --- a/Symbian3/SDK/Source/GUID-CD2BF0EE-5437-4ADA-A447-4B06147754A8.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-CD2BF0EE-5437-4ADA-A447-4B06147754A8.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,45 +1,45 @@ - - - - - -Local -connectivity -

                Local connectivity has fewer security issues due to its short range. -However, general rules of communication security apply to local connectivity -as well. This section discusses Bluetooth and infrared.

                -
                Bluetooth -

                The Bluetooth wireless technology is a short range and low power network -for data and voice communication in any place of the world. The figure below -illustrates the relationships between the different Symbian Bluetooth classes.

                -

                For more information, see Bluetooth -Management Collection.

                -Bluetooth API -

                Use the Bluetooth Security Manager to set the appropriate security requirements -(authentication, authorization, and encryption) that incoming connections -to the device's Bluetooth services must meet. For more information, see Using Bluetooth Security -Manager.

                -

                The Bluetooth stack will not by default enforce any particular Bluetooth -security for outgoing socket connections. If the remote device requires -authentication or encryption to connect, it will be handled automatically -by the Bluetooth stack. For more information, see Using -security on outgoing sockets.

                -
                -
                Infrared -

                Infrared provides a means for short-range communication between devices. -Symbian implements the Infrared Data Association (IrDA) stack for infrared -connections. Infrared connections are handled through general Serial or Socket -Server interfaces.

                -

                The IrDA standard does not specify any security features for data transfer, -but since the devices attempting infrared connection are in visual contact, -it is easier to control communication and access to the device. Implement -authentication, authorization, encryption, or any other security features -needed in the application level.

                -
                + + + + + +Local +connectivity +

                Local connectivity has fewer security issues due to its short range. +However, general rules of communication security apply to local connectivity +as well. This section discusses Bluetooth and infrared.

                +
                Bluetooth +

                The Bluetooth wireless technology is a short range and low power network +for data and voice communication in any place of the world. The figure below +illustrates the relationships between the different Symbian Bluetooth classes.

                +

                For more information, see Bluetooth +Management Collection.

                +Bluetooth API +

                Use the Bluetooth Security Manager to set the appropriate security requirements +(authentication, authorization, and encryption) that incoming connections +to the device's Bluetooth services must meet. For more information, see Using Bluetooth Security +Manager.

                +

                The Bluetooth stack will not by default enforce any particular Bluetooth +security for outgoing socket connections. If the remote device requires +authentication or encryption to connect, it will be handled automatically +by the Bluetooth stack. For more information, see Using +security on outgoing sockets.

                +
                +
                Infrared +

                Infrared provides a means for short-range communication between devices. +Symbian implements the Infrared Data Association (IrDA) stack for infrared +connections. Infrared connections are handled through general Serial or Socket +Server interfaces.

                +

                The IrDA standard does not specify any security features for data transfer, +but since the devices attempting infrared connection are in visual contact, +it is easier to control communication and access to the device. Implement +authentication, authorization, encryption, or any other security features +needed in the application level.

                +
                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CD7F507C-CDD5-5612-BA1B-72641D28FA4A_d0e254198_href.png Binary file Symbian3/SDK/Source/GUID-CD7F507C-CDD5-5612-BA1B-72641D28FA4A_d0e254198_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CD7F507C-CDD5-5612-BA1B-72641D28FA4A_d0e257906_href.png Binary file Symbian3/SDK/Source/GUID-CD7F507C-CDD5-5612-BA1B-72641D28FA4A_d0e257906_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CE79D1B9-2770-5494-A741-D98DE3EBFA05_d0e345485_href.png Binary file Symbian3/SDK/Source/GUID-CE79D1B9-2770-5494-A741-D98DE3EBFA05_d0e345485_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CE79D1B9-2770-5494-A741-D98DE3EBFA05_d0e345918_href.png Binary file Symbian3/SDK/Source/GUID-CE79D1B9-2770-5494-A741-D98DE3EBFA05_d0e345918_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CE79D1B9-2770-5494-A741-D98DE3EBFA05_d0e345997_href.png Binary file Symbian3/SDK/Source/GUID-CE79D1B9-2770-5494-A741-D98DE3EBFA05_d0e345997_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CE79D1B9-2770-5494-A741-D98DE3EBFA05_d0e346170_href.png Binary file Symbian3/SDK/Source/GUID-CE79D1B9-2770-5494-A741-D98DE3EBFA05_d0e346170_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CE79D1B9-2770-5494-A741-D98DE3EBFA05_d0e351566_href.png Binary file Symbian3/SDK/Source/GUID-CE79D1B9-2770-5494-A741-D98DE3EBFA05_d0e351566_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CE79D1B9-2770-5494-A741-D98DE3EBFA05_d0e351999_href.png Binary file Symbian3/SDK/Source/GUID-CE79D1B9-2770-5494-A741-D98DE3EBFA05_d0e351999_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CE79D1B9-2770-5494-A741-D98DE3EBFA05_d0e352078_href.png Binary file Symbian3/SDK/Source/GUID-CE79D1B9-2770-5494-A741-D98DE3EBFA05_d0e352078_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CE79D1B9-2770-5494-A741-D98DE3EBFA05_d0e352251_href.png Binary file Symbian3/SDK/Source/GUID-CE79D1B9-2770-5494-A741-D98DE3EBFA05_d0e352251_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CE7C84A5-D2E6-5151-BBC7-6AF9C8A0D978-GENID-1-8-1-3-1-1-8-1-4-1.dita --- a/Symbian3/SDK/Source/GUID-CE7C84A5-D2E6-5151-BBC7-6AF9C8A0D978-GENID-1-8-1-3-1-1-8-1-4-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,88 +0,0 @@ - - - - - -Address -string tokenizer overview -
                Purpose

                The -Address String Tokenizer offers methods for parsing phone numbers, email addresses, -URL and URI addresses from given text. It provides an interface for applications -that, for example, want to create/use their own GUI for displaying found items.

                -
                Architectural -Relationships

                All functionality is implemented in the CTulAddressStringTokenizer class. -The interface can be accessed through the tuladdressstringtokenizer.h file. -The binaries are linked to the etul.lib (Text Utilities - -part of Egul component) library.

                - Subsystem dependencies - -
                -
                Description

                Usage

                In -order to use the Address String Tokenizer, the user has to create an instance -of CTulAddressStringTokenizer by -using the factory method CTulAddressStringTokenizer::NewL().

                For -example:

                CTulAddressStringTokenizer* addressStringTokenizer = CTulAddressStringTokenizer::NewL(text, searchCase);

                The method takes two parameters of type TDesC& and TTokenizerSearchCase which is -defined in tuladdressstringtokenizer.h.

                The first -parameter defines the text to be searched from.

                The second parameter -tells what exactly is being looked for. It is an enum which describes the -type of text being searched for. The types available are phone number, email -address, fixed start URL or generic URI.

                The passed text is parsed -in construction, and found items can be fetched using the ItemArray() method. ItemArray() returns a constant -array containing all the found items.

                The interface also offers helper -functions for handling the item array by itself.

                For more information -on individual methods, please see the reference API for CTulAddressStringTokenizer.

                Example

                This sample code explains a few simple use cases that -search for items from a text string:

                // Some text -TBufC<256> strSomeText(_L("Mail to me@someplace.com or call 040 1234567. - You can also tune in to audio feed at rtsp://someplace.com/somefeed.ra.")); - -// SFoundItem instance -CTulAddressStringTokenizer::SFoundItem item; - -// Create an instance of CTulAddressStringTokenizer and search for URLs. -CTulAddressStringTokenizer* singleSearch = CTulAddressStringTokenizer::NewL - (strSomeText, CTulAddressStringTokenizer::EFindItemSearchScheme); - -// Get count of found items -TInt count(singleSearch->ItemCount()); - -// Get currently selected item (rtsp://someplace.com/somefeed.ra) to the result -// variable -singleSearch->Item(item); -TPtrC16 result(strSomeText.Mid(item.iStartPos, item.iLength)); - -// Deallocate memory -delete singleSearch; - -// Look for all possible things (cases work as binary mask) -CTulAddressStringTokenizer* multiSearch = CTulAddressStringTokenizer::NewL - (strSomeText, (CTulAddressStringTokenizer:: TTokenizerSearchCase) - (CTulAddressStringTokenizer::EFindItemSearchPhoneNumberBin | - CTulAddressStringTokenizer::EFindItemSearchURLBin | - CTulAddressStringTokenizer::EFindItemSearchMailAddressBin | - CTulAddressStringTokenizer::EFindItemSearchScheme)); - -// Debug print all items and their type -count = multiSearch->ItemCount(); -multiSearch->Item(item); - -for(TInt i=0; i<count; i++) - { - result.Set(strSomeText.Mid(item.iStartPos, item.iLength)); - RDebug::Print(_L("Found type %d item:"), item.iItemType); - RDebug::Print(_L("%S"), &result) - multiSearch->NextItem(item); - } - -// Deallocate memory -delete multiSearch; -

                Sequence Diagram

                - Sequence of events for CTulAddressStringTokenizer - -
                -                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CE7C84A5-D2E6-5151-BBC7-6AF9C8A0D978-GENID-1-8-1-6-1-1-4-1-7-1-4-1.dita --- a/Symbian3/SDK/Source/GUID-CE7C84A5-D2E6-5151-BBC7-6AF9C8A0D978-GENID-1-8-1-6-1-1-4-1-7-1-4-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,88 +0,0 @@ - - - - - -Address -string tokenizer overview -
                Purpose

                The -Address String Tokenizer offers methods for parsing phone numbers, email addresses, -URL and URI addresses from given text. It provides an interface for applications -that, for example, want to create/use their own GUI for displaying found items.

                -
                Architectural -Relationships

                All functionality is implemented in the CTulAddressStringTokenizer class. -The interface can be accessed through the tuladdressstringtokenizer.h file. -The binaries are linked to the etul.lib (Text Utilities - -part of Egul component) library.

                - Subsystem dependencies - -
                -
                Description

                Usage

                In -order to use the Address String Tokenizer, the user has to create an instance -of CTulAddressStringTokenizer by -using the factory method CTulAddressStringTokenizer::NewL().

                For -example:

                CTulAddressStringTokenizer* addressStringTokenizer = CTulAddressStringTokenizer::NewL(text, searchCase);

                The method takes two parameters of type TDesC& and TTokenizerSearchCase which is -defined in tuladdressstringtokenizer.h.

                The first -parameter defines the text to be searched from.

                The second parameter -tells what exactly is being looked for. It is an enum which describes the -type of text being searched for. The types available are phone number, email -address, fixed start URL or generic URI.

                The passed text is parsed -in construction, and found items can be fetched using the ItemArray() method. ItemArray() returns a constant -array containing all the found items.

                The interface also offers helper -functions for handling the item array by itself.

                For more information -on individual methods, please see the reference API for CTulAddressStringTokenizer.

                Example

                This sample code explains a few simple use cases that -search for items from a text string:

                // Some text -TBufC<256> strSomeText(_L("Mail to me@someplace.com or call 040 1234567. - You can also tune in to audio feed at rtsp://someplace.com/somefeed.ra.")); - -// SFoundItem instance -CTulAddressStringTokenizer::SFoundItem item; - -// Create an instance of CTulAddressStringTokenizer and search for URLs. -CTulAddressStringTokenizer* singleSearch = CTulAddressStringTokenizer::NewL - (strSomeText, CTulAddressStringTokenizer::EFindItemSearchScheme); - -// Get count of found items -TInt count(singleSearch->ItemCount()); - -// Get currently selected item (rtsp://someplace.com/somefeed.ra) to the result -// variable -singleSearch->Item(item); -TPtrC16 result(strSomeText.Mid(item.iStartPos, item.iLength)); - -// Deallocate memory -delete singleSearch; - -// Look for all possible things (cases work as binary mask) -CTulAddressStringTokenizer* multiSearch = CTulAddressStringTokenizer::NewL - (strSomeText, (CTulAddressStringTokenizer:: TTokenizerSearchCase) - (CTulAddressStringTokenizer::EFindItemSearchPhoneNumberBin | - CTulAddressStringTokenizer::EFindItemSearchURLBin | - CTulAddressStringTokenizer::EFindItemSearchMailAddressBin | - CTulAddressStringTokenizer::EFindItemSearchScheme)); - -// Debug print all items and their type -count = multiSearch->ItemCount(); -multiSearch->Item(item); - -for(TInt i=0; i<count; i++) - { - result.Set(strSomeText.Mid(item.iStartPos, item.iLength)); - RDebug::Print(_L("Found type %d item:"), item.iItemType); - RDebug::Print(_L("%S"), &result) - multiSearch->NextItem(item); - } - -// Deallocate memory -delete multiSearch; -

                Sequence Diagram

                - Sequence of events for CTulAddressStringTokenizer - -
                -                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CE7C84A5-D2E6-5151-BBC7-6AF9C8A0D978.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-CE7C84A5-D2E6-5151-BBC7-6AF9C8A0D978.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,89 @@ + + + + + +Address +string tokenizer overview +
                Purpose

                The +Address String Tokenizer offers methods for parsing phone numbers, E-mail +addresses, URL and URI addresses from given text. It provides an interface +for applications that, for example, want to create/use their own GUI for displaying +found items.

                +
                Architectural +Relationships

                All functionality is implemented in the CTulAddressStringTokenizer class. +The interface can be accessed through the tuladdressstringtokenizer.h file. +The binaries are linked to the etul.lib (Text Utilities - +part of Egul component) library.

                + Subsystem dependencies + +
                +
                Description

                Usage

                In +order to use the Address String Tokenizer, the user has to create an instance +of CTulAddressStringTokenizer by +using the factory method CTulAddressStringTokenizer::NewL().

                For +example:

                CTulAddressStringTokenizer* addressStringTokenizer = CTulAddressStringTokenizer::NewL(text, searchCase);

                The method takes two parameters of type TDesC& and TTokenizerSearchCase which is +defined in tuladdressstringtokenizer.h.

                The first +parameter defines the text to be searched from.

                The second parameter +tells what exactly is being looked for. It is an enum which describes the +type of text being searched for. The types available are phone number, email +address, fixed start URL or generic URI.

                The passed text is parsed +in construction, and found items can be fetched using the ItemArray() method. ItemArray() returns a constant +array containing all the found items.

                The interface also offers helper +functions for handling the item array by itself.

                For more information +on individual methods, please see the reference API for CTulAddressStringTokenizer.

                Example

                This sample code explains a few simple use cases that +search for items from a text string:

                // Some text +TBufC<256> strSomeText(_L("Mail to me@someplace.com or call 040 1234567. + You can also tune in to audio feed at rtsp://someplace.com/somefeed.ra.")); + +// SFoundItem instance +CTulAddressStringTokenizer::SFoundItem item; + +// Create an instance of CTulAddressStringTokenizer and search for URLs. +CTulAddressStringTokenizer* singleSearch = CTulAddressStringTokenizer::NewL + (strSomeText, CTulAddressStringTokenizer::EFindItemSearchScheme); + +// Get count of found items +TInt count(singleSearch->ItemCount()); + +// Get currently selected item (rtsp://someplace.com/somefeed.ra) to the result +// variable +singleSearch->Item(item); +TPtrC16 result(strSomeText.Mid(item.iStartPos, item.iLength)); + +// Deallocate memory +delete singleSearch; + +// Look for all possible things (cases work as binary mask) +CTulAddressStringTokenizer* multiSearch = CTulAddressStringTokenizer::NewL + (strSomeText, (CTulAddressStringTokenizer::TTokenizerSearchCase) + (CTulAddressStringTokenizer::EFindItemSearchPhoneNumberBin | + CTulAddressStringTokenizer::EFindItemSearchURLBin | + CTulAddressStringTokenizer::EFindItemSearchMailAddressBin | + CTulAddressStringTokenizer::EFindItemSearchScheme)); + +// Debug print all items and their type +count = multiSearch->ItemCount(); +multiSearch->Item(item); + +for(TInt i=0; i<count; i++) + { + result.Set(strSomeText.Mid(item.iStartPos, item.iLength)); + RDebug::Print(_L("Found type %d item:"), item.iItemType); + RDebug::Print(_L("%S"), &result) + multiSearch->NextItem(item); + } + +// Deallocate memory +delete multiSearch; +

                Sequence Diagram

                + Sequence of events for <codeph>CTulAddressStringTokenizer</codeph> + +
                +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CE7CF024-4898-551A-841B-38EC57A3EC82.dita --- a/Symbian3/SDK/Source/GUID-CE7CF024-4898-551A-841B-38EC57A3EC82.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-CE7CF024-4898-551A-841B-38EC57A3EC82.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,86 +1,86 @@ - - - - - -Ordinal -PositionAll windows in the Window Server have an ordinal - position which describes their z-order—that is, their ordering -from nearest the viewer to furthest away from the viewer. Each window’s ordinal -position is relative to its parent window and is unique among its siblings. -

                Variant: Both (ScreenPlay and non-ScreenPlay). Target audience: -Application developers.

                -

                Ordinal positions are positive integers starting at 0, with 0 being the -front-most position. A window with an ordinal position of 0 is displayed in -the foreground, i.e., in front of all its sibling windows. -The ordinal position of other windows increases by one for each position behind -this window.

                -

                When a window is created, it is automatically given an ordinal position -of 0 within its parent window. Then, when another child of the same parent -is created, the first window’s ordinal position changes to 1, and the new -window’s position is 0. These ordinal positions can be changed after the windows -have been created, using functions provided by the RWindowTreeNode class.

                -

                When a window's ordinal position is changed, its order in the sibling list -is also changed, so that the window with ordinal position 0 is always first -in the sibling list, the window with ordinal position 1 is next in the list, -and so on. Changing the ordinal position of windows therefore affects the -result of the RWindowTreeNode::Parent(), RWindowTreeNode::Child(), RWindowTreeNode::NextSibling() and RWindowTreeNode::PrevSibling() functions.

                -

                To give an illustration of how ordinal positions work, the diagram below -shows three windows, A, B and C, all belonging to the same window group. Their -ordinal positions are as follows: A=0; B=1; C=2.

                - - - -

                This would be the default ordering of the windows if they were created -in the order CBA. Many sibling windows within an application may not overlap -in practice: nevertheless, each window has a unique ordinal position, even -though this will not be evident in the way they are displayed.

                -

                If a window’s ordinal position is changed, its position on the screen will -change. All its child windows also move with it, although their ordinal positions, -which are relative to the parent, don’t change.

                -
                Moving a window to the front

                A window is moved -to the front (i.e., to the foreground) by giving it an -ordinal position of 0. The diagram below shows windows A, B and C, but window -B has now been given an ordinal position of 0. A’s position has been incremented -to 1, and C’s remains as 2.

                - -

                The diagram below shows the same three windows as above, except -that window B now contains a child window, D. Window D’s ordinal position -is 0, relative to its parent window, B.

                - -

                If window A is now moved to the front, window B moves behind it, -as shown in the diagram below. Window D’s ordinal position is still 0, but -because its position is relative to its parent window, it moves with window -B to behind window A.

                - -
                -
                Moving a window to the back

                If a window is given -an ordinal position greater than all its siblings, it is moved to the back -of them. For convenience, the functions for setting ordinal position allow -a negative ordinal position to be specified, which sends the window to the -back and sets its ordinal position to be the highest among its siblings.

                -
                Ordinal position of window groups

                The ordinal position -of a window group has special significance because there is normally one window -group per application. As a result, the z-order of applications on the screen -is typically determined by the ordinal positions of their window groups. For -example, giving a window group an ordinal position of 0 typically brings an -application to the front of the screen. Note, however, that window groups -also have a priority, which overrides ordinal position. Ordinal position only -applies among window groups of the same priority.

                The ordinal position -of window groups is typically controlled by a shell or similar application. -The RWsSession class provides functions for -such applications to set window group ordinal positions.

                -
                Keyboard focus and window group ordinal position

                When -a window group is given an ordinal position of 0, it is automatically given -keyboard focus, unless it has disabled keyboard focus by calling EnableReceiptOfFocus(EFalse), -or another window group has a higher priority.

                -                 -Window Types - + + + + + +Ordinal +PositionAll windows in the Window Server have an ordinal + position which describes their z-order—that is, their ordering +from nearest the viewer to furthest away from the viewer. Each window’s ordinal +position is relative to its parent window and is unique among its siblings. +

                Variant: Both (ScreenPlay and non-ScreenPlay). Target audience: +Application developers.

                +

                Ordinal positions are positive integers starting at 0, with 0 being the +front-most position. A window with an ordinal position of 0 is displayed in +the foreground, i.e., in front of all its sibling windows. +The ordinal position of other windows increases by one for each position behind +this window.

                +

                When a window is created, it is automatically given an ordinal position +of 0 within its parent window. Then, when another child of the same parent +is created, the first window’s ordinal position changes to 1, and the new +window’s position is 0. These ordinal positions can be changed after the windows +have been created, using functions provided by the RWindowTreeNode class.

                +

                When a window's ordinal position is changed, its order in the sibling list +is also changed, so that the window with ordinal position 0 is always first +in the sibling list, the window with ordinal position 1 is next in the list, +and so on. Changing the ordinal position of windows therefore affects the +result of the RWindowTreeNode::Parent(), RWindowTreeNode::Child(), RWindowTreeNode::NextSibling() and RWindowTreeNode::PrevSibling() functions.

                +

                To give an illustration of how ordinal positions work, the diagram below +shows three windows, A, B and C, all belonging to the same window group. Their +ordinal positions are as follows: A=0; B=1; C=2.

                + + + +

                This would be the default ordering of the windows if they were created +in the order CBA. Many sibling windows within an application may not overlap +in practice: nevertheless, each window has a unique ordinal position, even +though this will not be evident in the way they are displayed.

                +

                If a window’s ordinal position is changed, its position on the screen will +change. All its child windows also move with it, although their ordinal positions, +which are relative to the parent, don’t change.

                +
                Moving a window to the front

                A window is moved +to the front (i.e., to the foreground) by giving it an +ordinal position of 0. The diagram below shows windows A, B and C, but window +B has now been given an ordinal position of 0. A’s position has been incremented +to 1, and C’s remains as 2.

                + +

                The diagram below shows the same three windows as above, except +that window B now contains a child window, D. Window D’s ordinal position +is 0, relative to its parent window, B.

                + +

                If window A is now moved to the front, window B moves behind it, +as shown in the diagram below. Window D’s ordinal position is still 0, but +because its position is relative to its parent window, it moves with window +B to behind window A.

                + +
                +
                Moving a window to the back

                If a window is given +an ordinal position greater than all its siblings, it is moved to the back +of them. For convenience, the functions for setting ordinal position allow +a negative ordinal position to be specified, which sends the window to the +back and sets its ordinal position to be the highest among its siblings.

                +
                Ordinal position of window groups

                The ordinal position +of a window group has special significance because there is normally one window +group per application. As a result, the z-order of applications on the screen +is typically determined by the ordinal positions of their window groups. For +example, giving a window group an ordinal position of 0 typically brings an +application to the front of the screen. Note, however, that window groups +also have a priority, which overrides ordinal position. Ordinal position only +applies among window groups of the same priority.

                The ordinal position +of window groups is typically controlled by a shell or similar application. +The RWsSession class provides functions for +such applications to set window group ordinal positions.

                +
                Keyboard focus and window group ordinal position

                When +a window group is given an ordinal position of 0, it is automatically given +keyboard focus, unless it has disabled keyboard focus by calling EnableReceiptOfFocus(EFalse), +or another window group has a higher priority.

                +                 +Window Types +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CE94AD48-B79B-403A-98E9-F69494D052F9.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-CE94AD48-B79B-403A-98E9-F69494D052F9.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,116 @@ + + + + + +HDMI OverviewHDMI (High Definition Multimedia Interface) is a compact +audio or video connector interface to transmit uncompressed digital +data. +
                Introduction

                HDMI is a digital standard, which provides +an alternative to various analog standards like radio frequency (RF) +coaxial cable, composite video, component video, S-video (super video), +D-terminal (D-tanshi terminal) and VGA (video graphics array).

                HDMI connects, using a single cable, a digital audio or video +source like a mobile phone, a set-top box, a blue-ray disc player, +or a PC to a compatible digital output device, for instance a computer +monitor, or a digital television.

                In general HDMI supports +standard, enhanced, and high-definition (HD) video, and up to 6 channels +of digital audio, which provides the highest-quality home theater +experience. In Symbian^3 the HDMI features are based on HDMI 1.3a +software specifications for the device creator to adapt it to the +platform.

                +
                Purpose

                HDMI provides communication between a mobile device and the HD +device. In Symbian^3 HDMI supports some functionality such as setting +and getting screen configuration information, which enables plug and +play without any need for configuration by the end user.

                In +Symbian^3 HDMI supports the following features:

                  +

                1. Maximum progressive +scan HD resolution of 1280 x 720 pixels. Progressive scan is a method +to display moving images.

                  2. +

                2. Multi-channel +digital uncompressed audio data.

                  3. +

                3. EDID (Extended +Display Identification Data). This is a data structure provided by +a computer display to describe its capabilities to a graphics card. +EDID is defined by a standard published by the Video Electronics Standards +Association (VESA).

                  4. +

                4. HDCP (High-bandwidth +Digital Content Protection). This prevents copying audio and video +content. HDCP is invisible to the end-user unless a problem occurs. +If HDCP reports a problem an image related to DRM (Digital rights +management) failure and an error message are displayed, instead of +the video content and audio is muted.

                  5. +
                In Symbian^3 the HDMI uses two modes such as non-HD (High Definition) +compliant view and HD compliant view. In Symbian^4 the +dual display mode will be implemented.

                The HDMI modes are listed +below:

                  +

                • Clone mode or Non-HD compliant view

                  In this mode, +the mobile device and the HD display show the same information.

                  • +

                • Native mode or HD compliant view

                  This mode takes +full advantage of HDMI, and reproduces mobile device content in the +maximum HD resolution available with HDMI. For example if a mobile +device displays a video clip, including its title and a progress bar, +the HD display might just show the video clip in full screen, (excluding +the others content).

                  • +

                • Dual display mode

                  In this mode, the mobile devices's +display and the HD display are treated as separate displays by an +application like the photo gallery. The application controls what +is displayed in each.

                  • +

                The diagram +below shows the subsystems that need to be modified in order to adapt +HDMI in the Symbian platform by the device creator.

                +HDMI architectural relationship with the subsystem + +

                  +

                1. Application +layer

                  To use HDMI in an application no changes are required +in this layer. For example to play a video use the CVideoPlayerUtility2 API from the Video Client Library in the Multimedia framework (MMF).

                  2. +

                2. Middleware +layer

                  To support high-definition resolutions, WMA (Windows +Media Audio) hardware device and multi-channel WMA to play video the Helix as the MMF controller plug-in is used.

                  3. +

                3. OS Extension +layer

                  In order to play audio with support for HDCP use +the DevSound +library extension and the DRM APIs . +The Accessory +Server API provides the policy for audio routing.

                  4. +

                4. OS layer +(Symbian)

                  To play video in HDMI mode use the Window Server to check the render stage policy of the graphics surface in the +video.

                  5. +

                5. Adaptation +layer

                  For the audio adaptation use the CHdmiAudioLink API to play multi-channel audio. For the video adaptation use the CIveVideoDecodeVC1HwDevice API to play a video in fullscreen +and high resolution. The display driver is used to support display +modes like clone, dual and native modes. The system adaptation detects +HDMI protocols, and transfers the protocols to the HDMI driver.

                  6. +

                6. HDMI driver

                  This driver transfers all data and initialization of the HDMI +chip from the adaptation layer to the hardware layer.

                  7. +

                7. Hardware +layer

                  The HDMI chip is in the hardware layer. The chip is +used to receive and transmit the high performance video and audio +between the mobile device and the HDMI display.

                  8. +
                +
                Description

                HDMI is used to implement the following use-cases:

                  +

                • Play video in full screen and high resolution.

                  • +

                • Play audio with DRM supported.

                  • +

                • View images including zooming and rotating in full screen.

                  • +

                • Play audio with HDCP support to restricted audio output.

                  • +

                For example in order to play a video the following diagram +demonstrates the HDMI feature implementation:

                +HDMI video play use-case + +

                In order to play video the CVideoPlayerUtility2 API is used as the Video Client library, which plays sampled video data on graphics surfaces. In the MMF +layer, the RMMFController and the CHXNGAUtility APIs are used as the MMF controller framework, which initializes +the DevVideo API. The DevVideo uses the CMMFDevVideoPlay API +to play the video. The CIveVideoDecodeVC1HwDevice API provides video adaptation to the hardware layer. In the video +adaptation, a decision making engine chooses the graphics surface +on which to display the video on the HD display. The Window Server +API is used for dynamic resolution switching. The HDMI driver +transfers all video data to the HDMI chip, which is in the hardware +adaptation layer (the physical layer). The hardware layer transmits +video data to the HD display through a single cable.

                +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CF17532E-5E90-5124-8F05-AA72B848F17F.dita --- a/Symbian3/SDK/Source/GUID-CF17532E-5E90-5124-8F05-AA72B848F17F.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-CF17532E-5E90-5124-8F05-AA72B848F17F.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,423 +1,423 @@ - - - - - -SIP -Example: Usage of the SIP Stack -

                The SIP sample application is a game that can be played between two users -that use two different machines. The following figure illustrates the sample -application.

                - - - -

                All users who want to play the game must register to the server with their -identities. This informs the server that the user is active and prepared to -participate in the game. If User 1 wants to play the game with User 2 then -it must send a request to User 2 through the server. When User 2 accepts the -request and acknowledges it then the two users can start playing. A user can -disconnect from playing the game by sending a message. If a user wants to -be deactivated then it can deregister from the server.

                -

                This application is developed using the key features of the Symbian SIP -stack. It shows how to create profiles and do SIP registration using the profiles, -how to set up a SIP session and send an instant message using the SIP. For -example you can set up the SIP server using Brekeke and you can download the -same from http://www.brekeke.com/download/download_sip_2_0.php.

                -
                Features of the game

                The main features of the game -are:

                  -

                • Register or deregister - -A user registers to the server with a unique identity before playing the game. -This identity is the SIP URI of the user. The user registers by sending a -SIP REGISTER message to the SIP server and is active. A user deactivates by -deregistering to the server. This activity is done by sending the SIP REGISTER -message with the expires header set to 0. For more information on registering -or deregistering to the server see, Registering -or deregistering an user.

                  • -

                • Invite another user - -A user invites another user to play the game by entering the SIP URI of the -other user in the INVITE message. For more information on inviting another -user to play the game see, Inviting -a participant for session setup.

                  • -

                • Send a message to -another user - A user can send an instant message to another user. For -more information on how to send an instant message to another user see, Sending -an instant message.

                  • -

                • Disconnect from -playing the game - A user can disconnect from playing the game by sending -a SIP BYE message to the other user.

                  • -
                -
                How to play -the game

                The following snapshot shows the different tabs available -in the game.

                - -

                The following list describes the different tabs available in the -game:

                  -

                • Invite for game - -This tab allows you to invite a user to play the game. When you invoke this -tab, a UI screen appears which asks the user to provide the SIP URI of the -second user with whom the user wants to play the game. The SIP URI of the -second user is then sent to the SIP stack which passes on the invite request -to the second user. The second user can accept or reject the invite. If the -second user accepts the invite then it acknowledges by sending a message that -it is prepared to start playing the game. If the second user rejects the invite -then it cannot play the game.

                  • -

                • Enable profile - -This tab allows you to enable a profile. When you invoke this tab, a UI screen -appears where the user enters the values. A profile is created using these -values and the user registers with the SIP server.

                  • -

                • Send instant msg - -This tab allows you to send a message to another user. When you invoke this -tab, a message with the address of the recipient is sent to the SIP stack. -The SIP stack sends this message to the recipient address.

                  • -

                • End game - This -tab allows you to disconnect from playing the game. When you invoke this tab, -a BYE message is sent to the other user and the game is terminated.

                  • -
                -
                Registering -or deregistering an user

                An application can register to the SIP -Server using:

                  -

                • the CSIPRegistrationBinding class -and its methods

                  • -

                • the SIP Profile Agent

                  • -

                This sample application uses the SIP Profile Agent method to do SIP -registration. To use this method you need a SIP profile setting, and you must -create a SIP profile before you start using the application. Note: -A list of SIP profile settings can be found in the CSIPProfile class.

                The -SIP profile agent method provides APIs for:

                  -

                • Registering and Deregistering

                  • -

                • Listening to registration -events

                  • -

                • Creating, modifying, -and deleting the SIP profile settings that the profile agent plug-in implementations -use for SIP registration.

                  • -

                The following code from SIPExProfileQueryDlg.cpp shows -how the sample application stores the settings entered by users on the SIP -profile store.

                //Create a new profile - CSIPManagedProfile* profile = iMProfileRegistry->CreateL(iProfileData.iServiceProfile); - -//Copy attributes entered by the user to the new profile - iNewProfile = profile; - profile = CopyDataToProfileL(); - -//Set the profile to default and save some settings - TInt err= profile->SetParameter(KSIPDefaultProfile,ETrue); - -//Save the profile to persistent store - iMProfileRegistry->SaveL( *profile ); -

                The applications can start SIP registration or deregistration -using the Enable or Disable methods from -the SIP profile API.

                The following code from SIPExSIPEngine.cpp shows -how to register using the profile agent.

                //Check for the existing profile - if ( iProfile ) - { - delete iProfile; - iProfile = NULL; - } - TBool registered( EFalse ); - -//Leaves with KErrNotFound if default profile is not found - iProfile = iProfileRegistry->DefaultProfileL(); - else - { - const TDesC8* aor = NULL; - iProfile->GetParameter( KSIPUserAor, aor ); - iProfileRegistry->EnableL( *iProfile, *this ); - - //Check if the profile was immediately set to the registered state - iProfile->GetParameter( KSIPProfileRegistered, registered ); - } -

                The following code from SIPExSIPEngine.cpp shows -how to deregister using the profile agent.

                if ( iProfile ) - { - iProfileRegistry->Disable( *iProfile ); - delete iProfile; - iProfile = NULL; - }

                The SIP profile API also provides a notification -method that is used by an application to monitor profile related events.

                The -following code from SIPExProfileQueryDlg.cpp shows the -profile related events that the sample applications monitors.

                void ProfileRegistryEventOccurred( - TUint32 aProfileId, - TEvent aEvent ) - { - switch (aEvent) - { - case MSIPProfileRegistryObserver::EProfileRegistered: - { - HandleProfileRegistered( aProfileId ); - break; - } - case MSIPProfileRegistryObserver::EProfileDeregistered: - { - HandleProfileDeregistered( aProfileId ); - break; - } - case MSIPProfileRegistryObserver::EProfileDestroyed: - { - HandleProfileDestroyed( aProfileId ); - break; - } - default: - { - // MSIPProfileRegistryObserver::EProfileCreated and MSIPProfileRegistryObserver::EProfileUpdated are ignored - break; - } - } - } -void ProfileRegistryErrorOccurred( - TUint32 /* aSIPProfileId */, - TInt aError ) - { - iObserver->ProfileError( aError ); - } -

                Classes containing APIs in scope

                CSIPProfile, CSIPManagedProfile, CSIPProfileRegistry, CSIPManagedProfileRegistry, MSIPProfileRegistryObserver.

                -
                Inviting a -participant for session setup

                The sample application uses the SIP -INVITE method to setup a session between two users. In this case, the application -does not accept any SDP parameters from the user and instead sends fixed SDP -values.

                The following code from SIPExSIPIdleState.cpp shows -how the application sends an INVITE message.

                void SendInviteL( - CSIPExSIPEngine& aEngine, - const TDesC8& aSipUri ) - { - //Retrieve the active profile and connection - CSIPProfile& prof = aEngine.Profile(); - CSIPConnection& conn = aEngine.ConnectionL(); - - //Create CUri8 from the passed descriptor. This value is given by the user - CUri8* uri8 = aEngine.ConvertToUri8LC( aSipUri ); - - //Get dialog association, save for future use - //The ownership of uri8 is transferred - CSIPInviteDialogAssoc* dialogAssoc = - CSIPInviteDialogAssoc::NewL( conn, uri8, prof ); - aEngine.SetDialogAssoc( *dialogAssoc ); //Ownership is transferred!! - - //Create the necessary message elements - CSIPMessageElements* msgElements = aEngine.CreateMessageElementsLC(); - - //Send the INVITE in the dialog - //The ownership of msgElements is transferred - INVITE SENT OUT - CSIPClientTransaction* tx = dialogAssoc->SendInviteL( msgElements ); - } -
                -
                Handling an -incoming invite

                An application that wants to receive an incoming -invite outside the dialog must implement the Client Resolver API. The CSipResolvedClient (SipResolvedClient.h) interface is implemented by clients to enable a client resolution mechanism -when the SIP requests are received outside the SIP dialog. The application -must state the capabilities, that is the supported content types and media -formats. This is done using the SIP headers and SDP m-lines either in the -code of the plug-in, that is in const KCapabilities or in -the opaque_data field of the resource file.

                The capabilities can be -provided to the plug-ins in two ways:

                  -

                • The data is provided -in the ECOM resource file.

                  • -

                • In the interface implementation -from where it is used to determine the target client.

                  • -

                The following code from SIPExResolverPlugin.cpp shows -how the data is provided in the ECOM resource file.

                #include <RegistryInfo.rh> -RESOURCE REGISTRY_INFO theInfo - { - // UID for the DLL - dll_uid = 0xA00001EC; - // Declare array of interface info - interfaces = - { - INTERFACE_INFO - { - // UID of interface that is implemented - interface_uid = 0x102010DD; - implementations = - { - IMPLEMENTATION_INFO - { - implementation_uid = 0xA00001EC; - version_no = 1; - // SIPEx UID: Must match to the one SIPEx passes to CSIP::NewL. - default_data = "A00001EB"; - } - }; - } - }; - }

                The following code from SIPExResolverPlugin.cpp shows -how the capabilities are defined in the plug-in.

                //Code for defining capabilities in plugin -//File : SIPExResolverPlugin.cpp - -_LIT8(KCapabilities, -"<SIP_CLIENT ALLOW_STARTING=\"YES\">\ -<SIP_HEADERS>\ -<ACCEPT value=\"application/sdp\"/>\ -<ACCEPT value=\"SIPEx/InstantMessage\"/>\ -</SIP_HEADERS>\ -<SDP_LINES>\ -<LINE name=\"m\" value=\"application 0 TCP SIPEx\"/>\ -</SDP_LINES>\ -</SIP_CLIENT>"); - - -

                When there is an incoming Invite Request with -SDP parameters the SIP stack passes the request to the Client Resolver to -get the resolved client for that request. The Client Resolver gets the capabilities -for all the applications that implement the Client Resolver API.

                The -following code from SIPExResolverPlugin.cpp shows how -to get the capabilities for an application.

                //Code for obtaining capabilities for an application -//File : SIPExResolverPlugin.cpp - -const TDesC8& CSIPExResolverPlugin::Capabilities() - { - return KCapabilities; - }

                When the target client is identified, the Client Resolver -gets the ChannelID from the plug-in implementation and requests the resolved -client to connect to the SIP implementation on that UID. Note: The -ChannelID is same as Application UID3

                The following code from SIPExResolverPlugin.cpp shows -how to get ChannelID for an application.

                //Code for obtaining ChannelID for an application -//File : SIPExResolverPlugin.cpp - - TUid CSIPExResolverPlugin::ChannelL( RStringF /*aMethod*/, - const TDesC8& /*aRequestUri*/, - const RPointerArray<CSIPHeaderBase>& /*aHeaders*/, - const TDesC8& /*aContent*/, - const CSIPContentTypeHeader* /*aContentType*/) - { - return iApplicationUID; - } - -//Code for asking an application to connect on UID -//File : SIPExResolverPlugin.cpp - - void CSIPExResolverPlugin::ConnectL( TUid aUid ) - { - //Launch application is based on UID passed from the SIP stack - - TApaAppInfo appInfo; - User::LeaveIfError( iApaSession.GetAppInfo( appInfo, aUid ) ); - CApaCommandLine* cmdLine = CApaCommandLine::NewLC(); -#ifdef EKA2 - cmdLine->SetExecutableNameL( appInfo.iFullName ); -#else - cmdLine->SetLibraryNameL( appInfo.iFullName ); -#endif - User::LeaveIfError( iApaSession.StartApp( *cmdLine ) ); - CleanupStack::PopAndDestroy( cmdLine ); - }

                When the resolved client connects, the INVITE is forwarded -to the client and it starts ringing (180 Ringing) and sends the provisional -response to the calling party. This part is implemented in InviteReceivedL as -shown in the following code.

                The following code from SIPExSIPIdleState.cpp shows -how the application gets the INVITE and how the provisional response is sent.

                /Code for CSIPExSIPIdleState::InviteReceivedL()... -//File : SIPExSIPIdleState.cpp - -void CSIPExSIPIdleState::InviteReceivedL( - CSIPExSIPEngine& aEngine, - CSIPServerTransaction* aTransaction ) - { - _LIT8( KLogEntry, "180 Ringing sent" ); - .. - .. - aEngine.Observer()->WriteLog( KLogEntry ); - .. - }

                From this stage, the INVITE is sent to InviteReceived of CSIPExEngine in SIPExGameEngine.cpp from where it asks from the game observer if the user has accepted the invitation -or not. The game starts or does not start depends on action taken.

                The -following code from SIPExStateRegistered.cpp shows how -the acceptance is asked from the game observer.

                //The acceptance is asked from the user and if accepted the game is reset, start -//listening socket and signal the SIP engine to send Accepted to the remote peer. - -//File : SIPExStateRegistered.cpp - -void TSIPExStateRegistered::InviteReceived( - CSIPExEngine* aContext, - const TDesC8& aFrom, - const TUint32 aIapId ) - { - iEnded = EFalse; - - TBool retVal( EFalse ); - TRAPD( ignore, retVal = aContext->AcceptInvitationL( aFrom ) ); - if ( iEnded ) - { - return; - } - if( retVal ) - { - StatusInfo( aContext, KGameStarting() ); - ChangeState( aContext, aContext->iStateAcceptingSIP ); - aContext->ResetGame(); - aContext->SetPeer( CSIPExEngine::EServer ); - Info( aContext, KListening() ); - TInetAddr addr; - TRAP( ignore, addr = - aContext->SocketEngineL()->StartListeningL( aIapId ) ); - Info( aContext, KAccepting() ); - TRAP( ignore, aContext->SIPEngine()->AcceptInviteL( addr ) ); - Info( aContext, KWaitingRemoteConn() ); - } - else - { - TRAP( ignore, aContext->SIPEngine()->DeclineInviteL() ); - Info( aContext, KInviteDeclined() ); - } - } -

                When the game observer accepts the invitation the following -code from SIPExGameEngine.cpp is run.

                //File : SIPExGameEngine.cpp - -TBool CSIPExEngine::AcceptInvitationL( const TDesC8& aFrom ) - { - HBufC* from = HBufC::NewLC( aFrom.Length() ); - from->Des().Copy( aFrom ); - TBool retVal = iGameObserver.AcceptInvitationL( *from ); - CleanupStack::PopAndDestroy( from ); - return retVal; - }
                -
                Sending an -instant message

                This sample application allows a user to send an -Instant Message (IM) to another user. The user requires SIP URI of the other -user and the message content that the user must enter. The application then -creates a MESSAGE (request message) with these parameters and uses SendRequestL() to -send it.

                The following code from SIPExSIPEngine.cpp shows -how to send an instant message.

                //Create and send an instant message to a recipient defined with the parameters. -//This is implemented with the MESSAGE method and is sent outside of a dialog. - -CreateIML(const TDesC8& aMessage, - const TDesC8& aSipUri ) - { - _LIT8( KMediaType, "SIPEx" ); // Part of content type - _LIT8( KMediaSubType, "InstantMessage" ); // Part of content type - -//Create the necessary elements of the IM - -CSIPRequestElements* reqElem = CreateReqElementsLC( aSipUri ); - CSIPToHeader* toHeader = CreateToHeaderLC( aSipUri ); - reqElem->SetToHeaderL( toHeader ); - -//Create the fromHeader value using the information from the profile - - const TDesC8* aor = NULL; - iProfile->GetParameter( KSIPUserAor, aor ); - CSIPAddress* addr = CSIPAddress::DecodeL( *aor ); - CSIPFromHeader* fromHeader = CSIPFromHeader::NewL( addr ); - reqElem->SetFromHeaderL( fromHeader ); - reqElem->SetMethodL( SIPStrings::StringF( SipStrConsts::EMessage ) ); - -//Get reference to the message elements from the request elements, create and insert content type header (ownership of the content type object is transferred) - - CSIPMessageElements& msgElem = reqElem->MessageElements(); - CSIPContentTypeHeader* ct = CSIPContentTypeHeader::NewLC( KMediaType, KMediaSubType ); - msgElem.SetContentL( aMessage.AllocL(), ct ); - -//Get the current connection - -CSIPConnection& conn = ConnectionL(); - -//Send the request using the connection (ownership of the request elements object is transferred) - - CSIPClientTransaction* ctx = conn.SendRequestL( reqElem ); - delete ctx; - } - -

                Classes containing APIs in scope

                CSIPRequestElements, CSIPToHeader, CSIPFromHeader, CSIPAddress, CSIPMessageElements, CSIPClientTransaction.

                + + + + + +SIP +Example: Usage of the SIP Stack +

                The SIP sample application is a game that can be played between two users +that use two different machines. The following figure illustrates the sample +application.

                + + + +

                All users who want to play the game must register to the server with their +identities. This informs the server that the user is active and prepared to +participate in the game. If User 1 wants to play the game with User 2 then +it must send a request to User 2 through the server. When User 2 accepts the +request and acknowledges it then the two users can start playing. A user can +disconnect from playing the game by sending a message. If a user wants to +be deactivated then it can deregister from the server.

                +

                This application is developed using the key features of the Symbian SIP +stack. It shows how to create profiles and do SIP registration using the profiles, +how to set up a SIP session and send an instant message using the SIP. For +example you can set up the SIP server using Brekeke and you can download the +same from http://www.brekeke.com/download/download_sip_2_0.php.

                +
                Features of the game

                The main features of the game +are:

                  +

                • Register or deregister - +A user registers to the server with a unique identity before playing the game. +This identity is the SIP URI of the user. The user registers by sending a +SIP REGISTER message to the SIP server and is active. A user deactivates by +deregistering to the server. This activity is done by sending the SIP REGISTER +message with the expires header set to 0. For more information on registering +or deregistering to the server see, Registering +or deregistering an user.

                  • +

                • Invite another user - +A user invites another user to play the game by entering the SIP URI of the +other user in the INVITE message. For more information on inviting another +user to play the game see, Inviting +a participant for session setup.

                  • +

                • Send a message to +another user - A user can send an instant message to another user. For +more information on how to send an instant message to another user see, Sending +an instant message.

                  • +

                • Disconnect from +playing the game - A user can disconnect from playing the game by sending +a SIP BYE message to the other user.

                  • +
                +
                How to play +the game

                The following snapshot shows the different tabs available +in the game.

                + +

                The following list describes the different tabs available in the +game:

                  +

                • Invite for game - +This tab allows you to invite a user to play the game. When you invoke this +tab, a UI screen appears which asks the user to provide the SIP URI of the +second user with whom the user wants to play the game. The SIP URI of the +second user is then sent to the SIP stack which passes on the invite request +to the second user. The second user can accept or reject the invite. If the +second user accepts the invite then it acknowledges by sending a message that +it is prepared to start playing the game. If the second user rejects the invite +then it cannot play the game.

                  • +

                • Enable profile - +This tab allows you to enable a profile. When you invoke this tab, a UI screen +appears where the user enters the values. A profile is created using these +values and the user registers with the SIP server.

                  • +

                • Send instant msg - +This tab allows you to send a message to another user. When you invoke this +tab, a message with the address of the recipient is sent to the SIP stack. +The SIP stack sends this message to the recipient address.

                  • +

                • End game - This +tab allows you to disconnect from playing the game. When you invoke this tab, +a BYE message is sent to the other user and the game is terminated.

                  • +
                +
                Registering +or deregistering an user

                An application can register to the SIP +Server using:

                  +

                • the CSIPRegistrationBinding class +and its methods

                  • +

                • the SIP Profile Agent

                  • +

                This sample application uses the SIP Profile Agent method to do SIP +registration. To use this method you need a SIP profile setting, and you must +create a SIP profile before you start using the application. Note: +A list of SIP profile settings can be found in the CSIPProfile class.

                The +SIP profile agent method provides APIs for:

                  +

                • Registering and Deregistering

                  • +

                • Listening to registration +events

                  • +

                • Creating, modifying, +and deleting the SIP profile settings that the profile agent plug-in implementations +use for SIP registration.

                  • +

                The following code from SIPExProfileQueryDlg.cpp shows +how the sample application stores the settings entered by users on the SIP +profile store.

                //Create a new profile + CSIPManagedProfile* profile = iMProfileRegistry->CreateL(iProfileData.iServiceProfile); + +//Copy attributes entered by the user to the new profile + iNewProfile = profile; + profile = CopyDataToProfileL(); + +//Set the profile to default and save some settings + TInt err= profile->SetParameter(KSIPDefaultProfile,ETrue); + +//Save the profile to persistent store + iMProfileRegistry->SaveL( *profile ); +

                The applications can start SIP registration or deregistration +using the Enable or Disable methods from +the SIP profile API.

                The following code from SIPExSIPEngine.cpp shows +how to register using the profile agent.

                //Check for the existing profile + if ( iProfile ) + { + delete iProfile; + iProfile = NULL; + } + TBool registered( EFalse ); + +//Leaves with KErrNotFound if default profile is not found + iProfile = iProfileRegistry->DefaultProfileL(); + else + { + const TDesC8* aor = NULL; + iProfile->GetParameter( KSIPUserAor, aor ); + iProfileRegistry->EnableL( *iProfile, *this ); + + //Check if the profile was immediately set to the registered state + iProfile->GetParameter( KSIPProfileRegistered, registered ); + } +

                The following code from SIPExSIPEngine.cpp shows +how to deregister using the profile agent.

                if ( iProfile ) + { + iProfileRegistry->Disable( *iProfile ); + delete iProfile; + iProfile = NULL; + }

                The SIP profile API also provides a notification +method that is used by an application to monitor profile related events.

                The +following code from SIPExProfileQueryDlg.cpp shows the +profile related events that the sample applications monitors.

                void ProfileRegistryEventOccurred( + TUint32 aProfileId, + TEvent aEvent ) + { + switch (aEvent) + { + case MSIPProfileRegistryObserver::EProfileRegistered: + { + HandleProfileRegistered( aProfileId ); + break; + } + case MSIPProfileRegistryObserver::EProfileDeregistered: + { + HandleProfileDeregistered( aProfileId ); + break; + } + case MSIPProfileRegistryObserver::EProfileDestroyed: + { + HandleProfileDestroyed( aProfileId ); + break; + } + default: + { + // MSIPProfileRegistryObserver::EProfileCreated and MSIPProfileRegistryObserver::EProfileUpdated are ignored + break; + } + } + } +void ProfileRegistryErrorOccurred( + TUint32 /* aSIPProfileId */, + TInt aError ) + { + iObserver->ProfileError( aError ); + } +

                Classes containing APIs in scope

                CSIPProfile, CSIPManagedProfile, CSIPProfileRegistry, CSIPManagedProfileRegistry, MSIPProfileRegistryObserver.

                +
                Inviting a +participant for session setup

                The sample application uses the SIP +INVITE method to setup a session between two users. In this case, the application +does not accept any SDP parameters from the user and instead sends fixed SDP +values.

                The following code from SIPExSIPIdleState.cpp shows +how the application sends an INVITE message.

                void SendInviteL( + CSIPExSIPEngine& aEngine, + const TDesC8& aSipUri ) + { + //Retrieve the active profile and connection + CSIPProfile& prof = aEngine.Profile(); + CSIPConnection& conn = aEngine.ConnectionL(); + + //Create CUri8 from the passed descriptor. This value is given by the user + CUri8* uri8 = aEngine.ConvertToUri8LC( aSipUri ); + + //Get dialog association, save for future use + //The ownership of uri8 is transferred + CSIPInviteDialogAssoc* dialogAssoc = + CSIPInviteDialogAssoc::NewL( conn, uri8, prof ); + aEngine.SetDialogAssoc( *dialogAssoc ); //Ownership is transferred!! + + //Create the necessary message elements + CSIPMessageElements* msgElements = aEngine.CreateMessageElementsLC(); + + //Send the INVITE in the dialog + //The ownership of msgElements is transferred + INVITE SENT OUT + CSIPClientTransaction* tx = dialogAssoc->SendInviteL( msgElements ); + } +
                +
                Handling an +incoming invite

                An application that wants to receive an incoming +invite outside the dialog must implement the Client Resolver API. The CSipResolvedClient (SipResolvedClient.h) interface is implemented by clients to enable a client resolution mechanism +when the SIP requests are received outside the SIP dialog. The application +must state the capabilities, that is the supported content types and media +formats. This is done using the SIP headers and SDP m-lines either in the +code of the plug-in, that is in const KCapabilities or in +the opaque_data field of the resource file.

                The capabilities can be +provided to the plug-ins in two ways:

                  +

                • The data is provided +in the ECOM resource file.

                  • +

                • In the interface implementation +from where it is used to determine the target client.

                  • +

                The following code from SIPExResolverPlugin.cpp shows +how the data is provided in the ECOM resource file.

                #include <RegistryInfo.rh> +RESOURCE REGISTRY_INFO theInfo + { + // UID for the DLL + dll_uid = 0xA00001EC; + // Declare array of interface info + interfaces = + { + INTERFACE_INFO + { + // UID of interface that is implemented + interface_uid = 0x102010DD; + implementations = + { + IMPLEMENTATION_INFO + { + implementation_uid = 0xA00001EC; + version_no = 1; + // SIPEx UID: Must match to the one SIPEx passes to CSIP::NewL. + default_data = "A00001EB"; + } + }; + } + }; + }

                The following code from SIPExResolverPlugin.cpp shows +how the capabilities are defined in the plug-in.

                //Code for defining capabilities in plugin +//File : SIPExResolverPlugin.cpp + +_LIT8(KCapabilities, +"<SIP_CLIENT ALLOW_STARTING=\"YES\">\ +<SIP_HEADERS>\ +<ACCEPT value=\"application/sdp\"/>\ +<ACCEPT value=\"SIPEx/InstantMessage\"/>\ +</SIP_HEADERS>\ +<SDP_LINES>\ +<LINE name=\"m\" value=\"application 0 TCP SIPEx\"/>\ +</SDP_LINES>\ +</SIP_CLIENT>"); + + +

                When there is an incoming Invite Request with +SDP parameters the SIP stack passes the request to the Client Resolver to +get the resolved client for that request. The Client Resolver gets the capabilities +for all the applications that implement the Client Resolver API.

                The +following code from SIPExResolverPlugin.cpp shows how +to get the capabilities for an application.

                //Code for obtaining capabilities for an application +//File : SIPExResolverPlugin.cpp + +const TDesC8& CSIPExResolverPlugin::Capabilities() + { + return KCapabilities; + }

                When the target client is identified, the Client Resolver +gets the ChannelID from the plug-in implementation and requests the resolved +client to connect to the SIP implementation on that UID. Note: The +ChannelID is same as Application UID3

                The following code from SIPExResolverPlugin.cpp shows +how to get ChannelID for an application.

                //Code for obtaining ChannelID for an application +//File : SIPExResolverPlugin.cpp + + TUid CSIPExResolverPlugin::ChannelL( RStringF /*aMethod*/, + const TDesC8& /*aRequestUri*/, + const RPointerArray<CSIPHeaderBase>& /*aHeaders*/, + const TDesC8& /*aContent*/, + const CSIPContentTypeHeader* /*aContentType*/) + { + return iApplicationUID; + } + +//Code for asking an application to connect on UID +//File : SIPExResolverPlugin.cpp + + void CSIPExResolverPlugin::ConnectL( TUid aUid ) + { + //Launch application is based on UID passed from the SIP stack + + TApaAppInfo appInfo; + User::LeaveIfError( iApaSession.GetAppInfo( appInfo, aUid ) ); + CApaCommandLine* cmdLine = CApaCommandLine::NewLC(); +#ifdef EKA2 + cmdLine->SetExecutableNameL( appInfo.iFullName ); +#else + cmdLine->SetLibraryNameL( appInfo.iFullName ); +#endif + User::LeaveIfError( iApaSession.StartApp( *cmdLine ) ); + CleanupStack::PopAndDestroy( cmdLine ); + }

                When the resolved client connects, the INVITE is forwarded +to the client and it starts ringing (180 Ringing) and sends the provisional +response to the calling party. This part is implemented in InviteReceivedL as +shown in the following code.

                The following code from SIPExSIPIdleState.cpp shows +how the application gets the INVITE and how the provisional response is sent.

                /Code for CSIPExSIPIdleState::InviteReceivedL()... +//File : SIPExSIPIdleState.cpp + +void CSIPExSIPIdleState::InviteReceivedL( + CSIPExSIPEngine& aEngine, + CSIPServerTransaction* aTransaction ) + { + _LIT8( KLogEntry, "180 Ringing sent" ); + .. + .. + aEngine.Observer()->WriteLog( KLogEntry ); + .. + }

                From this stage, the INVITE is sent to InviteReceived of CSIPExEngine in SIPExGameEngine.cpp from where it asks from the game observer if the user has accepted the invitation +or not. The game starts or does not start depends on action taken.

                The +following code from SIPExStateRegistered.cpp shows how +the acceptance is asked from the game observer.

                //The acceptance is asked from the user and if accepted the game is reset, start +//listening socket and signal the SIP engine to send Accepted to the remote peer. + +//File : SIPExStateRegistered.cpp + +void TSIPExStateRegistered::InviteReceived( + CSIPExEngine* aContext, + const TDesC8& aFrom, + const TUint32 aIapId ) + { + iEnded = EFalse; + + TBool retVal( EFalse ); + TRAPD( ignore, retVal = aContext->AcceptInvitationL( aFrom ) ); + if ( iEnded ) + { + return; + } + if( retVal ) + { + StatusInfo( aContext, KGameStarting() ); + ChangeState( aContext, aContext->iStateAcceptingSIP ); + aContext->ResetGame(); + aContext->SetPeer( CSIPExEngine::EServer ); + Info( aContext, KListening() ); + TInetAddr addr; + TRAP( ignore, addr = + aContext->SocketEngineL()->StartListeningL( aIapId ) ); + Info( aContext, KAccepting() ); + TRAP( ignore, aContext->SIPEngine()->AcceptInviteL( addr ) ); + Info( aContext, KWaitingRemoteConn() ); + } + else + { + TRAP( ignore, aContext->SIPEngine()->DeclineInviteL() ); + Info( aContext, KInviteDeclined() ); + } + } +

                When the game observer accepts the invitation the following +code from SIPExGameEngine.cpp is run.

                //File : SIPExGameEngine.cpp + +TBool CSIPExEngine::AcceptInvitationL( const TDesC8& aFrom ) + { + HBufC* from = HBufC::NewLC( aFrom.Length() ); + from->Des().Copy( aFrom ); + TBool retVal = iGameObserver.AcceptInvitationL( *from ); + CleanupStack::PopAndDestroy( from ); + return retVal; + }
                +
                Sending an +instant message

                This sample application allows a user to send an +Instant Message (IM) to another user. The user requires SIP URI of the other +user and the message content that the user must enter. The application then +creates a MESSAGE (request message) with these parameters and uses SendRequestL() to +send it.

                The following code from SIPExSIPEngine.cpp shows +how to send an instant message.

                //Create and send an instant message to a recipient defined with the parameters. +//This is implemented with the MESSAGE method and is sent outside of a dialog. + +CreateIML(const TDesC8& aMessage, + const TDesC8& aSipUri ) + { + _LIT8( KMediaType, "SIPEx" ); // Part of content type + _LIT8( KMediaSubType, "InstantMessage" ); // Part of content type + +//Create the necessary elements of the IM + +CSIPRequestElements* reqElem = CreateReqElementsLC( aSipUri ); + CSIPToHeader* toHeader = CreateToHeaderLC( aSipUri ); + reqElem->SetToHeaderL( toHeader ); + +//Create the fromHeader value using the information from the profile + + const TDesC8* aor = NULL; + iProfile->GetParameter( KSIPUserAor, aor ); + CSIPAddress* addr = CSIPAddress::DecodeL( *aor ); + CSIPFromHeader* fromHeader = CSIPFromHeader::NewL( addr ); + reqElem->SetFromHeaderL( fromHeader ); + reqElem->SetMethodL( SIPStrings::StringF( SipStrConsts::EMessage ) ); + +//Get reference to the message elements from the request elements, create and insert content type header (ownership of the content type object is transferred) + + CSIPMessageElements& msgElem = reqElem->MessageElements(); + CSIPContentTypeHeader* ct = CSIPContentTypeHeader::NewLC( KMediaType, KMediaSubType ); + msgElem.SetContentL( aMessage.AllocL(), ct ); + +//Get the current connection + +CSIPConnection& conn = ConnectionL(); + +//Send the request using the connection (ownership of the request elements object is transferred) + + CSIPClientTransaction* ctx = conn.SendRequestL( reqElem ); + delete ctx; + } + +

                Classes containing APIs in scope

                CSIPRequestElements, CSIPToHeader, CSIPFromHeader, CSIPAddress, CSIPMessageElements, CSIPClientTransaction.

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CF34E1C9-48E5-5B91-A48E-C68E647116A0_d0e17625_href.png Binary file Symbian3/SDK/Source/GUID-CF34E1C9-48E5-5B91-A48E-C68E647116A0_d0e17625_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CF34E1C9-48E5-5B91-A48E-C68E647116A0_d0e47970_href.png Binary file Symbian3/SDK/Source/GUID-CF34E1C9-48E5-5B91-A48E-C68E647116A0_d0e47970_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CF34E1C9-48E5-5B91-A48E-C68E647116A0_d0e53527_href.png Binary file Symbian3/SDK/Source/GUID-CF34E1C9-48E5-5B91-A48E-C68E647116A0_d0e53527_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CF6355EF-3241-5196-AEBC-1337E1AE2259.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-CF6355EF-3241-5196-AEBC-1337E1AE2259.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,26 @@ + + + + + +BitmapSprite: creating a sprite by loading a bitmap file +

                Note: This example is designed to work properly only with +Techview, there is no guarantee that it will work properly with other +interfaces.

                +
                Description

                The BitmapSprite example creates an animated sprite by loading a bitmap (.mbm) file. The sprite is a rotating windmill which can +be moved around the screen using the arrow keys.

                As in the +previous example, the sprite is created by setting up the sprite members +to contain bitmaps, then appending them to the sprite. In this example, +however, the bitmaps are loaded from a file rather than created using +off-screen bitmaps drawn to using a graphics context.

                +
                Download

                Click on the following link to download the example: BitmapSprite.zip

                Click: browse to view the example code.

                +
                Classes defined

                CSprite: Uses class RWsSprite by setting up the sprite +members to contain bitmaps then appending them to the sprite. In this +example, the bitmaps are loaded from a file.

                +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CF890168-0FCA-5BFD-AC86-E355B611A6B0.dita --- a/Symbian3/SDK/Source/GUID-CF890168-0FCA-5BFD-AC86-E355B611A6B0.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-CF890168-0FCA-5BFD-AC86-E355B611A6B0.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,20 +1,20 @@ - - - - - - Nodes in the Communications FrameworkThis topic describes the concept of a Node in the Communications Framework.

                The Communications Framework separates its implementation into horizontal and vertical divisions - the concept of Layers and Planes. Each of the separate entities is a Node. These entities form part of the Communications stack and are named Stack Nodes. Stack Nodes belong to a single Layer and a single Plane. Stack Nodes also provide Access Point services.

                Stack Nodes

                There are four Stack Nodes:

                MetaConnection Provider (MCPR) Node

                The MCPR Node uses the configuration and policy specifications to manage the Layer. A phone creator can replace this Node. The replacement or the configuration of this Node allows a phone creator to change the configuration of the Communications Infrastructure without a change to the software.

                Connection Provider (CPR) Node

                The CPR Node manages the connections.

                SubConnection Provider (SCPR) Node

                The SCPR Node manages the subconnections. Each subconnection represents a logical data channel. The Communications Framework has the concept of a default subconnection. A default SCPR always exists to represent the default subconnection. A connection uses the default subconnection if a subconnection is not specified.

                Flow Node

                The Flow Node manages the data stream.

                - Stack Nodes -

                Each type of Node is related to a specific Plane in the Comms Stack. The following diagram shows that:

                • the Flow Node has a one-to-one relationship with the Data Plane.

                • the MCPR (MetaConnection Provider) Node has a one-to-one relationship with the Management Plane.

                • the Control Plane contains both the SCPR Node and the CPR Node.

                • the SCPR Node can have many instances in operation at the same time.

                • the MCPR Node can connect to resources outside the Communications stack. The offset grey box around the text MCPR represents this fact.

                - How Nodes related to Planes in the Comms Stack -
                Other Nodes

                The Communications Framework has two other types of Node: Tier Manager and Factory Container.

                Tier manager Node

                A Tier is an alternative to Access Points. A Tier gives users a different method to access the services of the Communications Infrastructure. A Tier represents a higher level communications technology or a collection of technologies. Each communications technology belongs to a Tier, but a Tier can contain more than one technology. When a user selects a technology, a Tier shows the appropriate group of technologies from which the user can select. The Tier handles the selection of the Access Point. A Tier manager Node manages each Tier in the Communications Framework.

                Factory Container Node

                Factory Containers create Nodes. The Communications Framework supplies a Factory Container for each type of Node. The Factory Containers have published addresses and Nodes use these addresses to find and communicate with the Factory Containers. A Node can create another Node. A Node sends a request to the correct Factory Container to create the other Node. The Factory Container tries to create the new Node and reports status to the Node that made the request.

                The following diagram shows the connection between the Stack Nodes and the Tier Manager and Factory Container Nodes.

                - Connection between the Stack Nodes and the Tier Manager and Factory - Container Nodes -
                Access + + + + + + Nodes in the Communications FrameworkThis topic describes the concept of a Node in the Communications Framework.

                The Communications Framework separates its implementation into horizontal and vertical divisions - the concept of Layers and Planes. Each of the separate entities is a Node. These entities form part of the Communications stack and are named Stack Nodes. Stack Nodes belong to a single Layer and a single Plane. Stack Nodes also provide Access Point services.

                Stack Nodes

                There are four Stack Nodes:

                MetaConnection Provider (MCPR) Node

                The MCPR Node uses the configuration and policy specifications to manage the Layer. A phone creator can replace this Node. The replacement or the configuration of this Node allows a phone creator to change the configuration of the Communications Infrastructure without a change to the software.

                Connection Provider (CPR) Node

                The CPR Node manages the connections.

                SubConnection Provider (SCPR) Node

                The SCPR Node manages the subconnections. Each subconnection represents a logical data channel. The Communications Framework has the concept of a default subconnection. A default SCPR always exists to represent the default subconnection. A connection uses the default subconnection if a subconnection is not specified.

                Flow Node

                The Flow Node manages the data stream.

                + Stack Nodes +

                Each type of Node is related to a specific Plane in the Comms Stack. The following diagram shows that:

                • the Flow Node has a one-to-one relationship with the Data Plane.

                • the MCPR (MetaConnection Provider) Node has a one-to-one relationship with the Management Plane.

                • the Control Plane contains both the SCPR Node and the CPR Node.

                • the SCPR Node can have many instances in operation at the same time.

                • the MCPR Node can connect to resources outside the Communications stack. The offset grey box around the text MCPR represents this fact.

                + How Nodes related to Planes in the Comms Stack +
                Other Nodes

                The Communications Framework has two other types of Node: Tier Manager and Factory Container.

                Tier manager Node

                A Tier is an alternative to Access Points. A Tier gives users a different method to access the services of the Communications Infrastructure. A Tier represents a higher level communications technology or a collection of technologies. Each communications technology belongs to a Tier, but a Tier can contain more than one technology. When a user selects a technology, a Tier shows the appropriate group of technologies from which the user can select. The Tier handles the selection of the Access Point. A Tier manager Node manages each Tier in the Communications Framework.

                Factory Container Node

                Factory Containers create Nodes. The Communications Framework supplies a Factory Container for each type of Node. The Factory Containers have published addresses and Nodes use these addresses to find and communicate with the Factory Containers. A Node can create another Node. A Node sends a request to the correct Factory Container to create the other Node. The Factory Container tries to create the new Node and reports status to the Node that made the request.

                The following diagram shows the connection between the Stack Nodes and the Tier Manager and Factory Container Nodes.

                + Connection between the Stack Nodes and the Tier Manager and Factory + Container Nodes +
                Access Points Layers Planes Tiers                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CF8FA653-5A3B-5D57-8875-0BC6BDCC1D0A.dita --- a/Symbian3/SDK/Source/GUID-CF8FA653-5A3B-5D57-8875-0BC6BDCC1D0A.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-CF8FA653-5A3B-5D57-8875-0BC6BDCC1D0A.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,229 +1,229 @@ - - - - - -Schedule -Send MTM Overview -

                This section provides an overview of the Schedule Send MTM component.

                -
                Purpose

                The Schedule Send MTM allows Message Type -Modules (MTM) to send messages at scheduled times. For example, the SMS MTM uses this -functionality to allow scheduled sending of SMS messages.

                -
                Architecture

                The Schedule Send functionality is -delivered by four components:

                  -

                • Server MTM base -class

                  The base class provides support to Server MTMs that wish -to support scheduled operations.

                  • -

                • Data structures

                  Classes -used to represent the data associated with a scheduled operation.

                  • -

                • Schedule Send Executable

                  The -Schedule Send Executable is run by the task scheduler at the scheduled time.

                  • -

                • Task Scheduler

                  The -component is part of the Generic OS Services.

                  • -

                Clients request the Server MTM schedule operations; this is passed -to the Server MTM through the Message Server. The Server MTM packages the -operation ID, a selection of message IDs, how often to poll for progress and -an MTM specific buffer. It then passes this package of data to the task scheduler -requesting that it launches the Schedule Send executable at the correct time -with the packaged information. When the task scheduler launches the Schedule -Send executable, it unpacks the schedule information and uses the messaging -client API to request the Server MTM to perform an operation.

                - Schedule Send architecture - -

                The executable to run by the Task Scheduler is specified in the -schedule send settings. This allows different executables for different message -types, as a set of schedule send settings are defined for each message type -that uses the schedule send support. The executable is normally the schedule-send -exe (schsendexe.exe).

                Each task contains some -repeat and priority information and a payload of data. In the case of schedules -created by CMsvScheduleSend, and the payload contains the TMsvId of -the scheduled message and ID of the command to be applied to that message.

                -
                Description

                The Schedule Send component is an extension -to the Messaging Framework that provides the messaging client with functionality -to schedule messages. It provides the following scheduling functionality:

                  -

                • Schedule a selection -of messages

                  • -

                • Reschedule a selection -of messages

                  • -

                • Check the schedule information -for a selection of messages

                  • -

                • Delete the schedule(s) -for a selection of messages

                  • -

                It also provides status information, such as whether a message is -currently scheduled, or failed.

                There are two types of schedules: -conditions-schedules and time-schedules. Both are stored in the file system -and persist across a reboot of a device. A schedule contains several pieces -of information, such as the schedule trigger (for example, the scheduled time), -the executable to run when the trigger occurs, and a list of tasks.

                Schedule -Send supports a retry mechanism if the operation fails. The Server MTM has -a resource file containing a mapping from the error codes the operation can -fail with and actions to be performed. For example, the SMS resource file -has a mapping such that if the operation fails with an error code indicating -a bad phone number, the SMS is set to failed and left in the outbox. Whereas, -if it fails with an error code indicating temporary network failure, the send -operation is scheduled to be resent later with a maximum of three retries.

                -
                API summary

                The following are the main classes -of the Schedule Send component:

                  -

                • The CMsvScheduleSend is -the main API that provides the Schedule Send support. This API provides the -following scheduling functionality:

                    -

                  • Schedule a selection -of messages

                    • -

                  • Reschedule a selection -of messages

                    • -

                  • Check the schedule information -for a selection of messages

                    • -

                  • Delete the schedules -for a selection of messages

                    • -

                  Scheduling is performed by the task scheduler. The CMsvScheduleSend class -uses the task scheduler RScheduler API to create persistent -schedules and add tasks to that schedule. Each task contains some repeat and -priority information, and a payload of data. In the case of schedules created -by CMsvScheduleSend, the payload contains the TMsvId of -the scheduled message and the ID of the command to be applied to that message.

                  • -

                • The CMsvSysAgentActions class -is used to specify what (system agent) conditions need to be checked before -sending a message.

                  • -

                • The CMsvSendErrorActions class -has a set of actions associated with error codes. It also provides a method -to populate itself from a resource file, RestoreFromResourceL.

                  This -is used in the CScheduleBaseServerMtm::RestoreSettings method, -where the error actions are populated from the resource file for a message -type.

                  • -

                • The CMsvScheduleSettings class -encapsulates settings for the Schedule Send. This contains information, such -as, the length of short and long time intervals that are used -to calculate the next schedule time for a message being rescheduled.

                  • -
                -
                Typical uses - - - -Main task -Sub-tasks -Description - - - - -

                Scheduling a message

                -

                 -

                Schedules a selection of messages. The messages must be of the same -type. They must also be scheduled for the same date and if applicable, for -the same off-peak time.

                The first step of scheduling a message is -to set the different parameters that allows determining the exact time the -message is sent and what to do if the message cannot be sent. The following -settings are per message and two parameters must be set for each message.

                -                 - -

                 -

                Set the date

                -

                Client applications can set the schedule date for a message.

                -                 - -

                 -

                Select off-peak sending

                -

                Client applications can select to send messages during off-peak -periods.

                -                 - -

                Delete the schedule for messages

                -

                 -

                Client applications can delete a schedule for a specified message -from the task scheduler. The messages themselves are not deleted.

                -                 - -

                Re-schedule messages

                -

                 -

                Client applications can determine when messages should be rescheduled -on the task scheduler.

                -                 - -

                Send scheduled messages

                -

                 -

                Client applications can send messages immediately that are previously -scheduled, that is, override the scheduling.

                -                 - -

                Check the schedule of messages

                -

                 -

                Client applications can verify that the schedule information stored -in specified messages is the same as the one actually in use.

                -                 - -

                Configuring a Schedule Send message

                - -

                Client applications can configure the build-time configuration parameters, -which are time-related parameters, off-peak period definitions and error actions.

                -                 - - -

                Validity period

                -

                The time period that the messages are valid (the message is not -sent after the validity period has expired). This is ignored if a message -has to be sent off-peak.

                -                 - - -

                Next attempt intervals

                -

                The messaging client uses this setting to define the time to wait -before attempting to resend a message.

                After a failed attempt, a message -can be sent immediately or later. The short interval and long interval define -the delays before a new attempt.

                -                 - - -

                Latency

                -

                The minimum amount of time between now and when the message is sent.

                A -message scheduled in the past will actually be scheduled to be sent Latency -seconds after the current time.

                -                 - - -

                Start of off-peak period

                -

                The day of the week, hour of the day and minute of the hour when -the off-peak period starts.

                -                 - - -

                Duration of off-peak period

                -

                The length (in minutes) of the off-peak period time. Must be less -than 24 hours.

                -                 - - -

                Add an error action

                -

                Client applications can add an error-action to the configuration -of the subsystem (for a type of message). That is, the error-action is configured -for the number of retries or type of retry spacing to a particular error.

                -                 - - -

                Remove an error-action

                -

                Client applications can remove an error-action from the list sustained -by the Messaging Middleware module.

                -                 - - -

                Set a list of error-actions

                -

                 -                 - - -

                Load the error-actions from a resource file

                -

                Client applications can restore the list of error-actions from a -resource file.

                -                 - - -
                -                 -Message Type -Module + + + + + +Schedule +Send MTM Overview +

                This section provides an overview of the Schedule Send MTM component.

                +
                Purpose

                The Schedule Send MTM allows Message Type +Modules (MTM) to send messages at scheduled times. For example, the SMS MTM uses this +functionality to allow scheduled sending of SMS messages.

                +
                Architecture

                The Schedule Send functionality is +delivered by four components:

                  +

                • Server MTM base +class

                  The base class provides support to Server MTMs that wish +to support scheduled operations.

                  • +

                • Data structures

                  Classes +used to represent the data associated with a scheduled operation.

                  • +

                • Schedule Send Executable

                  The +Schedule Send Executable is run by the task scheduler at the scheduled time.

                  • +

                • Task Scheduler

                  The +component is part of the Generic OS Services.

                  • +

                Clients request the Server MTM schedule operations; this is passed +to the Server MTM through the Message Server. The Server MTM packages the +operation ID, a selection of message IDs, how often to poll for progress and +an MTM specific buffer. It then passes this package of data to the task scheduler +requesting that it launches the Schedule Send executable at the correct time +with the packaged information. When the task scheduler launches the Schedule +Send executable, it unpacks the schedule information and uses the messaging +client API to request the Server MTM to perform an operation.

                + Schedule Send architecture + +

                The executable to run by the Task Scheduler is specified in the +schedule send settings. This allows different executables for different message +types, as a set of schedule send settings are defined for each message type +that uses the schedule send support. The executable is normally the schedule-send +exe (schsendexe.exe).

                Each task contains some +repeat and priority information and a payload of data. In the case of schedules +created by CMsvScheduleSend, and the payload contains the TMsvId of +the scheduled message and ID of the command to be applied to that message.

                +
                Description

                The Schedule Send component is an extension +to the Messaging Framework that provides the messaging client with functionality +to schedule messages. It provides the following scheduling functionality:

                  +

                • Schedule a selection +of messages

                  • +

                • Reschedule a selection +of messages

                  • +

                • Check the schedule information +for a selection of messages

                  • +

                • Delete the schedule(s) +for a selection of messages

                  • +

                It also provides status information, such as whether a message is +currently scheduled, or failed.

                There are two types of schedules: +conditions-schedules and time-schedules. Both are stored in the file system +and persist across a reboot of a device. A schedule contains several pieces +of information, such as the schedule trigger (for example, the scheduled time), +the executable to run when the trigger occurs, and a list of tasks.

                Schedule +Send supports a retry mechanism if the operation fails. The Server MTM has +a resource file containing a mapping from the error codes the operation can +fail with and actions to be performed. For example, the SMS resource file +has a mapping such that if the operation fails with an error code indicating +a bad phone number, the SMS is set to failed and left in the outbox. Whereas, +if it fails with an error code indicating temporary network failure, the send +operation is scheduled to be resent later with a maximum of three retries.

                +
                API summary

                The following are the main classes +of the Schedule Send component:

                  +

                • The CMsvScheduleSend is +the main API that provides the Schedule Send support. This API provides the +following scheduling functionality:

                    +

                  • Schedule a selection +of messages

                    • +

                  • Reschedule a selection +of messages

                    • +

                  • Check the schedule information +for a selection of messages

                    • +

                  • Delete the schedules +for a selection of messages

                    • +

                  Scheduling is performed by the task scheduler. The CMsvScheduleSend class +uses the task scheduler RScheduler API to create persistent +schedules and add tasks to that schedule. Each task contains some repeat and +priority information, and a payload of data. In the case of schedules created +by CMsvScheduleSend, the payload contains the TMsvId of +the scheduled message and the ID of the command to be applied to that message.

                  • +

                • The CMsvSysAgentActions class +is used to specify what (system agent) conditions need to be checked before +sending a message.

                  • +

                • The CMsvSendErrorActions class +has a set of actions associated with error codes. It also provides a method +to populate itself from a resource file, RestoreFromResourceL.

                  This +is used in the CScheduleBaseServerMtm::RestoreSettings method, +where the error actions are populated from the resource file for a message +type.

                  • +

                • The CMsvScheduleSettings class +encapsulates settings for the Schedule Send. This contains information, such +as, the length of short and long time intervals that are used +to calculate the next schedule time for a message being rescheduled.

                  • +
                +
                Typical uses + + + +Main task +Sub-tasks +Description + + + + +

                Scheduling a message

                +

                 +

                Schedules a selection of messages. The messages must be of the same +type. They must also be scheduled for the same date and if applicable, for +the same off-peak time.

                The first step of scheduling a message is +to set the different parameters that allows determining the exact time the +message is sent and what to do if the message cannot be sent. The following +settings are per message and two parameters must be set for each message.

                +                 + +

                 +

                Set the date

                +

                Client applications can set the schedule date for a message.

                +                 + +

                 +

                Select off-peak sending

                +

                Client applications can select to send messages during off-peak +periods.

                +                 + +

                Delete the schedule for messages

                +

                 +

                Client applications can delete a schedule for a specified message +from the task scheduler. The messages themselves are not deleted.

                +                 + +

                Re-schedule messages

                +

                 +

                Client applications can determine when messages should be rescheduled +on the task scheduler.

                +                 + +

                Send scheduled messages

                +

                 +

                Client applications can send messages immediately that are previously +scheduled, that is, override the scheduling.

                +                 + +

                Check the schedule of messages

                +

                 +

                Client applications can verify that the schedule information stored +in specified messages is the same as the one actually in use.

                +                 + +

                Configuring a Schedule Send message

                + +

                Client applications can configure the build-time configuration parameters, +which are time-related parameters, off-peak period definitions and error actions.

                +                 + + +

                Validity period

                +

                The time period that the messages are valid (the message is not +sent after the validity period has expired). This is ignored if a message +has to be sent off-peak.

                +                 + + +

                Next attempt intervals

                +

                The messaging client uses this setting to define the time to wait +before attempting to resend a message.

                After a failed attempt, a message +can be sent immediately or later. The short interval and long interval define +the delays before a new attempt.

                +                 + + +

                Latency

                +

                The minimum amount of time between now and when the message is sent.

                A +message scheduled in the past will actually be scheduled to be sent Latency +seconds after the current time.

                +                 + + +

                Start of off-peak period

                +

                The day of the week, hour of the day and minute of the hour when +the off-peak period starts.

                +                 + + +

                Duration of off-peak period

                +

                The length (in minutes) of the off-peak period time. Must be less +than 24 hours.

                +                 + + +

                Add an error action

                +

                Client applications can add an error-action to the configuration +of the subsystem (for a type of message). That is, the error-action is configured +for the number of retries or type of retry spacing to a particular error.

                +                 + + +

                Remove an error-action

                +

                Client applications can remove an error-action from the list sustained +by the Messaging Middleware module.

                +                 + + +

                Set a list of error-actions

                +

                 +                 + + +

                Load the error-actions from a resource file

                +

                Client applications can restore the list of error-actions from a +resource file.

                +                 + + +
                +                 +Message Type +Module                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CF9EF400-DE1F-55F7-BD33-C4CD80462971_d0e206241_href.png Binary file Symbian3/SDK/Source/GUID-CF9EF400-DE1F-55F7-BD33-C4CD80462971_d0e206241_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CF9EF400-DE1F-55F7-BD33-C4CD80462971_d0e211044_href.png Binary file Symbian3/SDK/Source/GUID-CF9EF400-DE1F-55F7-BD33-C4CD80462971_d0e211044_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CFC21A23-0299-4420-BB60-584D10C8913A.dita --- a/Symbian3/SDK/Source/GUID-CFC21A23-0299-4420-BB60-584D10C8913A.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-CFC21A23-0299-4420-BB60-584D10C8913A.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,40 +1,36 @@ - - - - - -Updating -the platform UIDThis topic describes how to update the platform UID. -

                When porting applications from S60 5th Edition to Symbian^3, you can include -the Symbian^3 platform UID in your application's .pkg file -and create a new .sis installation package using the modified .pkg file. -The platform UID for Symbian^3 is 0x20022E6D.

                - If you do not include the Symbian^3 platform UID in your package file -and create a new .sis installation package, the user gets -a compatibility warning when installing the application. The warning may result -in the user canceling the installation. -

                To add Symbian^3 UID, include the following line in the .pkg file -of your application:

                -[0x20022E6D], 0, 0, 0, {"Series60ProductID"} -

                If you have verified that the same binary can be used on multiple Symbian -platform releases, you can include platform UIDs for multiple Symbian platform -releases in your package file as illustrated by the following example:

                -;Supports S60 3.0 -[0x101F7961], 0, 0, 0, {"Series60ProductID"} - -;Supports S60 5th Edition -[0x1028315F], 0, 0, 0, {"Series60ProductID"} - -;Supports Symbian^3 -[0x20022E6D], 0, 0, 0, {"Series60ProductID"} - -

                For more information and a list of the platform UIDs used in earlier Symbian -platform releases, see Platform -UID.

                + + + + + +Updating the platform UIDThis topic describes how to update the platform UID. +

                When porting applications from S60 5th Edition to Symbian^3, you +can include the Symbian^3 platform UID in your application's .pkg file and create a new .sis installation +package using the modified .pkg file. The platform +UID for Symbian^3 is 0x20022E6D.

                + If you do not include the Symbian^3 platform UID in your package +file and create a new .sis installation package, +the user gets a compatibility warning when installing the application. +The warning may result in the user canceling the installation. +

                To add Symbian^3 UID, include the following line in the .pkg file of your application:

                +[0x20022E6D], 0, 0, 0, {"Series60ProductID"} +

                If you have verified that the same binary can be used on multiple +Symbian platform releases, you can include platform UIDs for multiple +Symbian platform releases in your package file as illustrated by the +following example:

                +;Supports S60 3.0 +[0x101F7961], 0, 0, 0, {"Series60ProductID"} + +;Supports S60 5th Edition +[0x1028315F], 0, 0, 0, {"Series60ProductID"} + +;Supports Symbian^3 +[0x20022E6D], 0, 0, 0, {"Series60ProductID"} +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CFC70204-1AD4-5DF0-ADDC-CDE4B39CFF96-GENID-1-8-1-3-1-1-9-1-4-1-6-1.dita --- a/Symbian3/SDK/Source/GUID-CFC70204-1AD4-5DF0-ADDC-CDE4B39CFF96-GENID-1-8-1-3-1-1-9-1-4-1-6-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,106 +0,0 @@ - - - - - -Simulating -and intercepting key events -
                Simulating -key events

                Simulating key events is done by calling CCoeFep ’s -member function SimulateKeyEventsL(); this sends to the application -a key event for each of the items in the array passed to it. There are two -overloads of SimulateKeyEventsL(): in the first and most -commonly used overload, only the character codes of the key events are specified; -in the second overload, modifier keys can also be specified for each key event -to be simulated. The header file epoc32\include\E32KEYS.H defines -the various modifiers possible. The FEP author needs to derive from CCoeFep::MModifiedCharacter in -order to use the second overload of SimulateKeyEventsL(), -implementing all three of its pure virtual functions. The ModifierMask() function -returns the modifiers whose value the FEP wishes to specify; the values for -the modifiers are returned by the ModifierValues() function. ModifierValues() should -not return values for any modifiers that are not also returned by ModifierMask().

                For -example, supposing a FEP wishes to send a key event to an application with -the func modifier on and the shift modifier -off. In this case the ModifierMask() function would return EModifierFunc|EModifierShift and -the ModifierValues() function would return EModifierFunc. -The resulting key event received by the application would then have the EModifierFunc modifier -on and the EModifierShift modifier off (even if the shift -key is being pressed down). All the other modifiers in the key event, since -they were not returned in the ModifierMask() function, will -reflect the current state of the keyboard.

                -
                Intercepting -key events

                In order for a FEP to intercept key events before they -reach the application beneath them, the FEP control must be added to the control -stack at a high priority. This is done by using the following code in the -control’s construction routine:

                STATIC_CAST(CCoeAppUi*, iCoeEnv->AppUi())->AddToStackL(this, ECoeStackPriorityFep, ECoeStackFlagRefusesFocus|ECoeStackFlagSharable);

                and the following code in its destructor:

                STATIC_CAST(CCoeAppUi*, iCoeEnv->AppUi())->RemoveFromStack(this);

                Passing the flag ECoeStackFlagSharable to AddToStackL() ensures -that if an embedded object is edited from an application, for instance an -embedded drawing is edited inside a word processor document, the FEP’s control -will also be put onto the child application’s control stack when the child -application is started. More importantly, the ECoeStackFlagRefusesFocus flag -should be passed to AddToStackL() because FEPs in general -should not “steal” focus from the target underneath them. For the same reason, SetNonFocusing() (a -member function of CCoeControl) should be called in the -control’s construction routine to prevent mouse or pen events from giving -it focus. On some occasions it may be legitimate for the FEP to take the focus, -for instance if the FEP has a floating window and it is temporarily in a mode -where the user can move this window around the screen by using the arrow keys. -In this case, the FEP’s control can take the focus by calling:

                CCoeAppUi& appUi=*STATIC_CAST(CCoeAppUi*, iCoeEnv->AppUi()); -appUi.UpdateStackedControlFlags(this, 0, ECoeStackFlagRefusesFocus); -appUi.HandleStackChanged(); -

                The following code causes the FEP’s control to revert to normal -operation by losing focus:

                CCoeAppUi& appUi=*STATIC_CAST(CCoeAppUi*, iCoeEnv->AppUi()); -appUi.UpdateStackedControlFlags(this, ECoeStackFlagRefusesFocus, ECoeStackFlagRefusesFocus); -appUi.HandleStackChanged(); -

                Adding the FEP’s control to the control stack at priority ECoeStackPriorityFep means -that it gets first refusal of all key events. The UI framework offers key -events to the FEP control by calling its OfferKeyEventL() virtual -function (although key events for a FEP over an OPL application follow a different -route, described below). The signature of this virtual function, which is -first declared in CCoeControl, is:

                TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent, TEventCode aType);

                The first thing that should be done at the start of OfferKeyEventL() is -to call either of the two macros below, both of which are defined in epoc32\include\FEPBASE.H:

                #define FEP_START_KEY_EVENT_HANDLER_L(aFep, aKeyEvent, aEventCode) -#define FEP_START_KEY_EVENT_HANDLER_NO_DOWN_UP_FILTER_L(aFep, aKeyEvent, aEventCode) -

                The aFep parameter must be a CCoeFep object. -Note that it should not be a pointer to a CCoeFep. The aKeyEvent and -the aEventCode parameters should be respectively the TKeyEvent and -the TEventCode parameters of the OfferKeyEventL() function -itself. The OfferKeyEventL() function should only be returned -from by calling either of the following two macros (these are also defined -in epoc32\include\FEPBASE.H):

                #define FEP_END_KEY_EVENT_HANDLER_L(aFep, aKeyEvent, aKeyResponse) -#define FEP_END_KEY_EVENT_HANDLER_NO_DOWN_UP_FILTER_L(aFep, aKeyEvent, aEventCode, aKeyResponse) -

                Both of these two macros contain a return statement, -so the return C++ keyword should not occur in the OfferKeyEventL() function -at all. Note that the macro used at the start of the OfferKeyEventL() function -should match the macro used to return from it; in other words, both should -be of the no-down-up-filter type or neither should be. The no-down-up-filter variants -should be used if the FEP wishes to handle EEventKeyDown or EEventKeyUp events. -This is likely to be rare, however; most FEPs are probably only interested -in EEventKey events, in which case FEP_START_KEY_EVENT_HANDLER_L and FEP_END_KEY_EVENT_HANDLER_L should be used. These variants filter out EEventKeyDown and EEventKeyUp events -so that the FEP only receives EEventKey events.

                The -first three parameters of the FEP_END_KEY_EVENT_HANDLER_ XXX macros -are the same as for the FEP_START_KEY_EVENT_HANDLER_ XXX macros. -The fourth parameter should be a TKeyResponse value (an -enum defined in epoc32\include\COEDEF.H). Specifying EKeyWasNotConsumed as -this fourth parameter allows that key event to 'fall through' to the application, -whereas specifying EKeyWasConsumed prevents the application -from receiving that event. A good rule of thumb for a FEP that takes key events -as its input is to intercept as few key events as possible when not inside -a FEP transaction, but once inside a transaction to block all key events from -getting through to the application. A transaction may be defined as the composition -and abandoning/committing of a piece of text ('committing' means sending it -on to the application). For a Japanese FEP, that piece of text may be an entire -sentence, whereas for a Chinese FEP it may be just one or two characters.

                For -a FEP running over an OPL application, the OfferKeyEventL() virtual -function declared in CCoeFep will get called. This is a -completely independent function from CCoeControl ’s virtual -function of the same name, and it has a different signature which is as follows:

                void OfferKeyEventL(TEventResponse& aEventResponse, const TKeyEvent& aKeyEvent, TEventCode aEventCode);

                This virtual function should be implemented in exactly the same way as CCoeControl ’s OfferKeyEventL(), -the meaning of the aKeyEvent and aEventCode parameters -being the same as for CCoeControl ’s OfferKeyEventL(). -The aEventResponse parameter should be set by the function -overriding CCoeFep::OfferKeyEventL() to either CCoeFep::EEventWasNotConsumed or CCoeFep::EEventWasConsumed, and this must be done before any function that can leave is called.

                -                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CFC70204-1AD4-5DF0-ADDC-CDE4B39CFF96-GENID-1-8-1-6-1-1-4-1-8-1-4-1-6-1.dita --- a/Symbian3/SDK/Source/GUID-CFC70204-1AD4-5DF0-ADDC-CDE4B39CFF96-GENID-1-8-1-6-1-1-4-1-8-1-4-1-6-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,106 +0,0 @@ - - - - - -Simulating -and intercepting key events -
                Simulating -key events

                Simulating key events is done by calling CCoeFep ’s -member function SimulateKeyEventsL(); this sends to the application -a key event for each of the items in the array passed to it. There are two -overloads of SimulateKeyEventsL(): in the first and most -commonly used overload, only the character codes of the key events are specified; -in the second overload, modifier keys can also be specified for each key event -to be simulated. The header file epoc32\include\E32KEYS.H defines -the various modifiers possible. The FEP author needs to derive from CCoeFep::MModifiedCharacter in -order to use the second overload of SimulateKeyEventsL(), -implementing all three of its pure virtual functions. The ModifierMask() function -returns the modifiers whose value the FEP wishes to specify; the values for -the modifiers are returned by the ModifierValues() function. ModifierValues() should -not return values for any modifiers that are not also returned by ModifierMask().

                For -example, supposing a FEP wishes to send a key event to an application with -the func modifier on and the shift modifier -off. In this case the ModifierMask() function would return EModifierFunc|EModifierShift and -the ModifierValues() function would return EModifierFunc. -The resulting key event received by the application would then have the EModifierFunc modifier -on and the EModifierShift modifier off (even if the shift -key is being pressed down). All the other modifiers in the key event, since -they were not returned in the ModifierMask() function, will -reflect the current state of the keyboard.

                -
                Intercepting -key events

                In order for a FEP to intercept key events before they -reach the application beneath them, the FEP control must be added to the control -stack at a high priority. This is done by using the following code in the -control’s construction routine:

                STATIC_CAST(CCoeAppUi*, iCoeEnv->AppUi())->AddToStackL(this, ECoeStackPriorityFep, ECoeStackFlagRefusesFocus|ECoeStackFlagSharable);

                and the following code in its destructor:

                STATIC_CAST(CCoeAppUi*, iCoeEnv->AppUi())->RemoveFromStack(this);

                Passing the flag ECoeStackFlagSharable to AddToStackL() ensures -that if an embedded object is edited from an application, for instance an -embedded drawing is edited inside a word processor document, the FEP’s control -will also be put onto the child application’s control stack when the child -application is started. More importantly, the ECoeStackFlagRefusesFocus flag -should be passed to AddToStackL() because FEPs in general -should not “steal” focus from the target underneath them. For the same reason, SetNonFocusing() (a -member function of CCoeControl) should be called in the -control’s construction routine to prevent mouse or pen events from giving -it focus. On some occasions it may be legitimate for the FEP to take the focus, -for instance if the FEP has a floating window and it is temporarily in a mode -where the user can move this window around the screen by using the arrow keys. -In this case, the FEP’s control can take the focus by calling:

                CCoeAppUi& appUi=*STATIC_CAST(CCoeAppUi*, iCoeEnv->AppUi()); -appUi.UpdateStackedControlFlags(this, 0, ECoeStackFlagRefusesFocus); -appUi.HandleStackChanged(); -

                The following code causes the FEP’s control to revert to normal -operation by losing focus:

                CCoeAppUi& appUi=*STATIC_CAST(CCoeAppUi*, iCoeEnv->AppUi()); -appUi.UpdateStackedControlFlags(this, ECoeStackFlagRefusesFocus, ECoeStackFlagRefusesFocus); -appUi.HandleStackChanged(); -

                Adding the FEP’s control to the control stack at priority ECoeStackPriorityFep means -that it gets first refusal of all key events. The UI framework offers key -events to the FEP control by calling its OfferKeyEventL() virtual -function (although key events for a FEP over an OPL application follow a different -route, described below). The signature of this virtual function, which is -first declared in CCoeControl, is:

                TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent, TEventCode aType);

                The first thing that should be done at the start of OfferKeyEventL() is -to call either of the two macros below, both of which are defined in epoc32\include\FEPBASE.H:

                #define FEP_START_KEY_EVENT_HANDLER_L(aFep, aKeyEvent, aEventCode) -#define FEP_START_KEY_EVENT_HANDLER_NO_DOWN_UP_FILTER_L(aFep, aKeyEvent, aEventCode) -

                The aFep parameter must be a CCoeFep object. -Note that it should not be a pointer to a CCoeFep. The aKeyEvent and -the aEventCode parameters should be respectively the TKeyEvent and -the TEventCode parameters of the OfferKeyEventL() function -itself. The OfferKeyEventL() function should only be returned -from by calling either of the following two macros (these are also defined -in epoc32\include\FEPBASE.H):

                #define FEP_END_KEY_EVENT_HANDLER_L(aFep, aKeyEvent, aKeyResponse) -#define FEP_END_KEY_EVENT_HANDLER_NO_DOWN_UP_FILTER_L(aFep, aKeyEvent, aEventCode, aKeyResponse) -

                Both of these two macros contain a return statement, -so the return C++ keyword should not occur in the OfferKeyEventL() function -at all. Note that the macro used at the start of the OfferKeyEventL() function -should match the macro used to return from it; in other words, both should -be of the no-down-up-filter type or neither should be. The no-down-up-filter variants -should be used if the FEP wishes to handle EEventKeyDown or EEventKeyUp events. -This is likely to be rare, however; most FEPs are probably only interested -in EEventKey events, in which case FEP_START_KEY_EVENT_HANDLER_L and FEP_END_KEY_EVENT_HANDLER_L should be used. These variants filter out EEventKeyDown and EEventKeyUp events -so that the FEP only receives EEventKey events.

                The -first three parameters of the FEP_END_KEY_EVENT_HANDLER_ XXX macros -are the same as for the FEP_START_KEY_EVENT_HANDLER_ XXX macros. -The fourth parameter should be a TKeyResponse value (an -enum defined in epoc32\include\COEDEF.H). Specifying EKeyWasNotConsumed as -this fourth parameter allows that key event to 'fall through' to the application, -whereas specifying EKeyWasConsumed prevents the application -from receiving that event. A good rule of thumb for a FEP that takes key events -as its input is to intercept as few key events as possible when not inside -a FEP transaction, but once inside a transaction to block all key events from -getting through to the application. A transaction may be defined as the composition -and abandoning/committing of a piece of text ('committing' means sending it -on to the application). For a Japanese FEP, that piece of text may be an entire -sentence, whereas for a Chinese FEP it may be just one or two characters.

                For -a FEP running over an OPL application, the OfferKeyEventL() virtual -function declared in CCoeFep will get called. This is a -completely independent function from CCoeControl ’s virtual -function of the same name, and it has a different signature which is as follows:

                void OfferKeyEventL(TEventResponse& aEventResponse, const TKeyEvent& aKeyEvent, TEventCode aEventCode);

                This virtual function should be implemented in exactly the same way as CCoeControl ’s OfferKeyEventL(), -the meaning of the aKeyEvent and aEventCode parameters -being the same as for CCoeControl ’s OfferKeyEventL(). -The aEventResponse parameter should be set by the function -overriding CCoeFep::OfferKeyEventL() to either CCoeFep::EEventWasNotConsumed or CCoeFep::EEventWasConsumed, and this must be done before any function that can leave is called.

                -                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CFC70204-1AD4-5DF0-ADDC-CDE4B39CFF96.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-CFC70204-1AD4-5DF0-ADDC-CDE4B39CFF96.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,106 @@ + + + + + +Simulating +and intercepting key events +
                Simulating +key events

                Simulating key events is done by calling CCoeFep ’s +member function SimulateKeyEventsL(); this sends to the application +a key event for each of the items in the array passed to it. There are two +overloads of SimulateKeyEventsL(): in the first and most +commonly used overload, only the character codes of the key events are specified; +in the second overload, modifier keys can also be specified for each key event +to be simulated. The header file epoc32\include\E32KEYS.H defines +the various modifiers possible. The FEP author needs to derive from CCoeFep::MModifiedCharacter in +order to use the second overload of SimulateKeyEventsL(), +implementing all three of its pure virtual functions. The ModifierMask() function +returns the modifiers whose value the FEP wishes to specify; the values for +the modifiers are returned by the ModifierValues() function. ModifierValues() should +not return values for any modifiers that are not also returned by ModifierMask().

                For +example, supposing a FEP wishes to send a key event to an application with +the func modifier on and the shift modifier +off. In this case the ModifierMask() function would return EModifierFunc|EModifierShift and +the ModifierValues() function would return EModifierFunc. +The resulting key event received by the application would then have the EModifierFunc modifier +on and the EModifierShift modifier off (even if the shift +key is being pressed down). All the other modifiers in the key event, since +they were not returned in the ModifierMask() function, will +reflect the current state of the keyboard.

                +
                Intercepting +key events

                In order for a FEP to intercept key events before they +reach the application beneath them, the FEP control must be added to the control +stack at a high priority. This is done by using the following code in the +control’s construction routine:

                STATIC_CAST(CCoeAppUi*, iCoeEnv->AppUi())->AddToStackL(this, ECoeStackPriorityFep, ECoeStackFlagRefusesFocus|ECoeStackFlagSharable);

                and the following code in its destructor:

                STATIC_CAST(CCoeAppUi*, iCoeEnv->AppUi())->RemoveFromStack(this);

                Passing the flag ECoeStackFlagSharable to AddToStackL() ensures +that if an embedded object is edited from an application, for instance an +embedded drawing is edited inside a word processor document, the FEP’s control +will also be put onto the child application’s control stack when the child +application is started. More importantly, the ECoeStackFlagRefusesFocus flag +should be passed to AddToStackL() because FEPs in general +should not “steal” focus from the target underneath them. For the same reason, SetNonFocusing() (a +member function of CCoeControl) should be called in the +control’s construction routine to prevent mouse or pen events from giving +it focus. On some occasions it may be legitimate for the FEP to take the focus, +for instance if the FEP has a floating window and it is temporarily in a mode +where the user can move this window around the screen by using the arrow keys. +In this case, the FEP’s control can take the focus by calling:

                CCoeAppUi& appUi=*STATIC_CAST(CCoeAppUi*, iCoeEnv->AppUi()); +appUi.UpdateStackedControlFlags(this, 0, ECoeStackFlagRefusesFocus); +appUi.HandleStackChanged(); +

                The following code causes the FEP’s control to revert to normal +operation by losing focus:

                CCoeAppUi& appUi=*STATIC_CAST(CCoeAppUi*, iCoeEnv->AppUi()); +appUi.UpdateStackedControlFlags(this, ECoeStackFlagRefusesFocus, ECoeStackFlagRefusesFocus); +appUi.HandleStackChanged(); +

                Adding the FEP’s control to the control stack at priority ECoeStackPriorityFep means +that it gets first refusal of all key events. The UI framework offers key +events to the FEP control by calling its OfferKeyEventL() virtual +function (although key events for a FEP over an OPL application follow a different +route, described below). The signature of this virtual function, which is +first declared in CCoeControl, is:

                TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent, TEventCode aType);

                The first thing that should be done at the start of OfferKeyEventL() is +to call either of the two macros below, both of which are defined in epoc32\include\FEPBASE.H:

                #define FEP_START_KEY_EVENT_HANDLER_L(aFep, aKeyEvent, aEventCode) +#define FEP_START_KEY_EVENT_HANDLER_NO_DOWN_UP_FILTER_L(aFep, aKeyEvent, aEventCode) +

                The aFep parameter must be a CCoeFep object. +Note that it should not be a pointer to a CCoeFep. The aKeyEvent and +the aEventCode parameters should be respectively the TKeyEvent and +the TEventCode parameters of the OfferKeyEventL() function +itself. The OfferKeyEventL() function should only be returned +from by calling either of the following two macros (these are also defined +in epoc32\include\FEPBASE.H):

                #define FEP_END_KEY_EVENT_HANDLER_L(aFep, aKeyEvent, aKeyResponse) +#define FEP_END_KEY_EVENT_HANDLER_NO_DOWN_UP_FILTER_L(aFep, aKeyEvent, aEventCode, aKeyResponse) +

                Both of these two macros contain a return statement, +so the return C++ keyword should not occur in the OfferKeyEventL() function +at all. Note that the macro used at the start of the OfferKeyEventL() function +should match the macro used to return from it; in other words, both should +be of the no-down-up-filter type or neither should be. The no-down-up-filter variants +should be used if the FEP wishes to handle EEventKeyDown or EEventKeyUp events. +This is likely to be rare, however; most FEPs are probably only interested +in EEventKey events, in which case FEP_START_KEY_EVENT_HANDLER_L and FEP_END_KEY_EVENT_HANDLER_L should be used. These variants filter out EEventKeyDown and EEventKeyUp events +so that the FEP only receives EEventKey events.

                The +first three parameters of the FEP_END_KEY_EVENT_HANDLER_ XXX macros +are the same as for the FEP_START_KEY_EVENT_HANDLER_ XXX macros. +The fourth parameter should be a TKeyResponse value (an +enum defined in epoc32\include\COEDEF.H). Specifying EKeyWasNotConsumed as +this fourth parameter allows that key event to 'fall through' to the application, +whereas specifying EKeyWasConsumed prevents the application +from receiving that event. A good rule of thumb for a FEP that takes key events +as its input is to intercept as few key events as possible when not inside +a FEP transaction, but once inside a transaction to block all key events from +getting through to the application. A transaction may be defined as the composition +and abandoning/committing of a piece of text ('committing' means sending it +on to the application). For a Japanese FEP, that piece of text may be an entire +sentence, whereas for a Chinese FEP it may be just one or two characters.

                For +a FEP running over an OPL application, the OfferKeyEventL() virtual +function declared in CCoeFep will get called. This is a +completely independent function from CCoeControl ’s virtual +function of the same name, and it has a different signature which is as follows:

                void OfferKeyEventL(TEventResponse& aEventResponse, const TKeyEvent& aKeyEvent, TEventCode aEventCode);

                This virtual function should be implemented in exactly the same way as CCoeControl ’s OfferKeyEventL(), +the meaning of the aKeyEvent and aEventCode parameters +being the same as for CCoeControl ’s OfferKeyEventL(). +The aEventResponse parameter should be set by the function +overriding CCoeFep::OfferKeyEventL() to either CCoeFep::EEventWasNotConsumed or CCoeFep::EEventWasConsumed, and this must be done before any function that can leave is called.

                +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CFD3CD78-D99A-57B8-80EB-8C67899E5D27_d0e427383_href.png Binary file Symbian3/SDK/Source/GUID-CFD3CD78-D99A-57B8-80EB-8C67899E5D27_d0e427383_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CFD3CD78-D99A-57B8-80EB-8C67899E5D27_d0e427545_href.png Binary file Symbian3/SDK/Source/GUID-CFD3CD78-D99A-57B8-80EB-8C67899E5D27_d0e427545_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-CFF1BCCA-5D07-5B8A-9363-AD11EEEAB485.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-CFF1BCCA-5D07-5B8A-9363-AD11EEEAB485.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,190 @@ + + + + + +Symmetric +ciphers -- HowTo +
                  +

                • How do I use the symmetric cipher framework?

                  • +

                • Symmetric Modes

                  • +

                • Which symmetric cipher should I use?

                  • +

                • How does buffering work within the symmetric cipher framework?

                  • +
                +
                How do I use +the symmetric cipher framework?
                  +

                • An introduction to the symmetric cipher framework

                  • +

                • CSymmetricCipher interface basics

                  • +

                • Example code for a symmetric factory class

                  • +

                An introduction +to the symmetric cipher framework

                The symmetric cipher framework +collates the behaviour of all symmetric ciphers under one interface: CSymmetricCipher. +This interface is intended to represent one direction of one instance of any +symmetric cipher. One direction means either encryption or decryption, but +not both.

                CSymmetricCipher +interface basics

                  +

                • Block ciphers -- +Here one must create an underlying transformation (CBlockTransformation) +and create a CBufferedTransformation (which is an CSymmetricCipher) +from that.

                  • +

                • Stream ciphers -- +These have no concept of buffering and are treated as specializations of CSymmetricCipher. +They require no intermediate container class.

                  • +

                The following code illustrates the creation of a buffered AES ECB +encryptor and an ARC4 stream cipher.

                +CBlockTransformation* block = 0; +block = CAESEncryptor::NewLC(aKey); +CPadding* padding = CPaddingSSLv3::NewLC(KAESBlockSize); //The blocksize of AES (16 bytes) +CSymmetricCipher* cipher = CBufferedEncryptor::NewL(block, padding); +CleanupStack::Pop(2, block); //padding, block -> both owned by cipher + +CSymmetricCipher* cipher = new(ELeave)CARC4(aKey); +CleanupStack::PushL(cipher): +

                After creation, both examples are usable through the CSymmetricCipher interface. +So, to encrypt with either of the above ciphers one could do:

                +HBufC8* output = HBufC8::NewLC(cipher->MaxOutputLength(input.Size())); +cipher->Process(input, output); +HBufC8* output2 = HBufC8::NewLC(cipher->MaxFinalOutputLength(input2.Size())); +cipher->ProcessFinalL(input2, output2); +

                In this example, input and input2 are +two arbitrary, finite length descriptors. The derived implementations of CSymmetricCipher (CBufferedEncryptor / CBufferedDecryptor and CStreamCipher) +are responsible for handling what to do in each specific case. For example, +in the case of an encrypting block cipher, ProcessFinalL() will +call the underlying padding system, which will in turn ensure that the overall +length of input plaintext is of a suitable length for encryption. For more +information on how the values returned from MaxOutputLength() and MaxFinalOutputLength() are +calculated see How +does buffering work within the symmetric cipher framework?.

                Example code for a symmetric +factory class

                To simplify the process of creating symmetric encryptors +and decryptors, it is strongly recommended that applications create a factory +that automates the process for them. The following code gives a sample factory +that applications might like to use as a reference. It is not supplied as +part of the framework as every application has different ways of identifying +symmetric cipher suites.

                +CSymmetricCipher* CCipherFactory::BuildEncryptorL( + TSymmetricCipherType aType,const TDesC8& aKey,const TDesC8& aIV) + { + CSymmetricCipher* cipher = NULL; + + if (aType==ERc4) + { + cipher = new(ELeave) CARC4(aKey); + } + else + { + CBlockTransformation* bT = NULL; + switch (aType) + { + case EDes_cbc: + bT = CDESEncryptor::NewL(aKey); + break; + case EDes_ede3_cbc: + bT = C3DESEncryptor::NewL(aKey); + break; + case ERc2_cbc: + bT = CRC2Encryptor::NewL(aKey); + break; + default: + User::Leave(KErrNotSupported); + }; + CleanupStack::PushL(bT); + CBlockTransformation* mode = CModeCBCEncryptor::NewL(bT, aIV); + CleanupStack::Pop(bT); // owned by mode + CleanupStack::PushL(mode); + + CPadding* padding = CPaddingSSLv3::NewLC(KBlockSize); //All of these ciphers use 8 byte blocks + cipher = CBufferedEncryptor::NewL(mode, padding); + CleanupStack::Pop(2, mode); //padding, mode now owned by cipher + } + return cipher; + } +

                Applications creating these factories need to supply an equivalent +to the TSymmetricCipherType enum, which contains the list +of identifiers representing the cipher, padding, and mode requirements of +the application.

                Note that a similar BuildDecryptorL() will +also have to be created.

                Good naming conventions dictate that applications +should not pollute the global namespace and either use their own namespace +or prefix their factory classes with identifiers that associated it with that +specific application.

                +
                Symmetric Modes

                When +the amount of plaintext to be encrypted is larger than a single block, some +method must be employed to specify how subsequent blocks are dependent on +previous blocks. The simplest method, known as ECB (Electronic CodeBook), +specifies that subsequent blocks are completely independent. Therefore, two +identical blocks of plaintext will encrypt to two identical blocks of ciphertext. +ECB has significant security drawbacks, thus most applications use more advanced +modes in which subsequent blocks are dependent on the ciphertext of previous +blocks. The symmetric framework handles these modes through the CBlockChainingMode class, +which is a specialization of CBlockTransformation. The +idea is that one gives an implementation of a CBlockChainingMode another CBlockTransformation (CAESEncryptor, for instance) and then performs all operations on the CBlockChainingMode instance. +When CBlockTransformation::Transform() is called on the +mode, it is responsible for calling Transform() on the underlying +transformation that it owns and then applying its own chaining mode transformation.

                The +following example shows how to create a buffered AES CBC encryptor.

                +CBlockTransformation* basicAesBlock = 0; +CBlockTransformation* cbcBlock = 0; +basicAesBlock = CAESEncryptor::NewLC(aKey); +cbcBlock = CModeCBCEncryptor::NewL(basicAesBlock, iv); +CleanupStack::Pop(basicAesBlock); //owned by cbcBlock +CleanupStack::PushL(cbcBlock); +CPadding* padding = CPaddingSSLv3::NewLC(KAESBlockSize); //The blocksize of AES (16 bytes) +CSymmetricCipher* cipher = CBufferedEncryptor::NewL(cbcBlock, padding); +CleanupStack::Pop(2, cbcBlock); //padding, cbcBlock -> both owned by cipher +
                +
                Which symmetric +cipher should I use?

                Generally, when implementing secure comms +protocols, the cipher you use will be dictated by the protocol specification. +However, if you are writing your own application, you should consider the +use of AES (CAESEncryptor); this is the cipher recommended +by NIST.

                +
                How does buffering +work within the symmetric cipher framework?
                  +

                • Stream ciphers consume +all content they are given. That is, the value returned from CSymmetricCipher::MaxOutputLength() is +always the same as the aInputLength parameter passed in.

                  • +

                • Block ciphers controlled +through a CBufferedTransformation operate under the following +rules:

                    +

                  • Process()

                      +

                    • Any previously buffered +data is (logically) prepended to aInput.

                      • +

                    • All whole blocks are +transformed and appended to aOutput.

                      • +

                    • Any remaining partial +blocks, orphaned by the above rule, are buffered.

                      • +
                    • +

                  • ProcessFinalL()

                      +

                    • Encryption

                        +

                      1. Any previously buffered +data is (logically) prepended to aInput.

                        2. +

                      2. All whole block are +transformed and appended to aOutput.

                        3. +

                      3. Any remaining partial +blocks are padded with underlying padding system to be block aligned to +the padding block size. (In the vast majority of cases, the padding block +size is equal to the block cipher block size).

                        4. +

                      4. The resulting block(s) +are transformed and appended to aOutput.

                        5. +
                      • +

                    • Decryption

                        +

                      1. The input must be +a multiple of the block size.

                        2. +

                      2. Data is decrypted and +unpadded using underlying padding system.

                        3. +

                      3. Decrypted, unpadded +data is appended to aOutput.

                        4. +
                      • +
                    • +
                  • +

                In all cases CSymmetricCipher::MaxOutputLength() returns +as tight an upper bound as possible on the number of bytes that will be returned +by a call to CSymmetricCipher::Process() with a specified +number of input bytes. Correspondingly, CSymmetricCipher::MaxFinalOutputLength() returns +a similar bound but for a pending call to CSymmetricCipher::ProcessFinalL().

                +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D038D77F-A6B8-5A18-8978-4981AE8D0F35.dita --- a/Symbian3/SDK/Source/GUID-D038D77F-A6B8-5A18-8978-4981AE8D0F35.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-D038D77F-A6B8-5A18-8978-4981AE8D0F35.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,54 +1,148 @@ - - - - - - Using the Encoded H264 Video Frames to Capture VideoThis topic describes how to use the encoded H264 video frames in the Ecam video capture function to capture the video data.

                You need to be familiar with the Capturing Video tutorial.

                The H264 video encoder provides a new, high quality video data encoding format for Ecam. Ecam allows the device to capture video frames which are encoded in the H264 format. The Ecam video capture function supports the H264 video capture format by default. You can select the H264 video capture format when preparing video capture.

                Call the CCameraVideoCaptureControl::NewL() function to create an object that maps the exported call to an internal object of the MCameraVideoCaptureControl function. Pass a handle to the MCameraVideoCaptureControl function. This implementation creates a handle to the CCameraVideoCaptureControl object by the active CCamera during the construction phase. The CCameraVideoCaptureControl object makes an internal call to the CCamera::CustomInterface() function of the active CCamera implementation. The CustomInterface() function passes a UID KECamMCameraVideoCaptureControlUid value for the CCamera implementation. The CCamera implementation creates the concrete implementation of the MCameraVideoCaptureControl function and passes back a handle to the CCameraVideoCaptureControl object. Call the MCaptureVideoObserver function to notify when the video capture operations are ready. Call CCameraVideoCaptureControl::GetVideoCaptureSupportInfoL() to identify which video capture modes are supported by the CCamera implementation. Call the TPrepareVideoParameters::SetVideoCaptureType() function to set the desired video capture mode as the EClientVideoCapture or EDirectVideoCapture mode. Set the value of CCameraVideoCaptureControl::TPrepareVideoParameter::iFormat() to the EFormatEncodedH264 value for the CCamera implementation. This CCamera implementation supports the H264 video encoding data format. Prepare video capture by using the CCameraVideoCaptureControl::PrepareVideoCapture() asynchronous function. The PrepareVideoCapture() function performs setup and allocation of memory before calling the StartVideoCapture() function, in order to keep minimum latency of the PrepareVideoCapture() function. Notify the Ecam client to complete the video capture preparation using the KUidECamEventVideoCaptureControlPrepareComplete event. Call the CCameraVideoCaptureControl::StartVideoCaptureL() function to start video capture. Call the CCamera::CCameraVideoCaptureControl::PauseVideoCapture() function to pause the on-going video capture. Call the CcameraVideoCaptureControl::GetPrepareVideoParameterl() function to retrieve the current prepare video parameters. The current video capture mode is retrieved by the TPrepareVideoParameters::VideoCaptureMode() function. Call the CCamera::CCameraVideoCaptureControl::ResumeVideoCaptureL() function to resume the on-going video capture. Call the CCamera::CCameraVideoCaptureControl::StopVideoCapture() function to stop video capture. Call the CCameraVideoCaptureControl::ReleaseVideoResource() function to release the video resource, which is allocated while performing the PrepareVideoCapture() function. If an error occurs while performing video capture, call the MCaptureVideoObserver::DirectVideoCaptureFailed() function. Any video capture operation is stopped. Example

                The following example code snippet illustrates video capture using H264 encoding:

                - -CCamera* camera = NULL; -MCameraObserver2* observer2 = NULL; - -CCamera::CCameraVideoCaptureControl* videocapture = NULL; -MCaptureVideoObserver* videoObserver = NULL; - -camera = CCamera::New2L(*observer2, 0, 0); - -videocapture = CCamera::CCameraVideoCaptureControl::NewL(*camera, *videoObserver); - -CCamera::CCameraVideoCaptureControl::TPrepareVideoParameters prepareVideoParameters; - -TInt supportedDVCType = -1; - -// To retrieve the supported video capture mode -videocapture->GetVideoCaptureSupportInfoL(supportedDVCType); - -// To set the video capture mode, if supported by the CCamera implementation -prepareVideoParameters.SetVideoCaptureType(CCamera::CCameraVideoCaptureControl::EDirectVideoCapture); - -// To set encoding for the H264 video data format -prepareVideoParameters.iFormat = CCamera::EFormatEncodedH264; - -// To set aspect ratio for the chosen H264 video format -prepareVideoParameters.iPixelAspectRatio = CCamera::CCameraAdvancedSettings::EEPixelAspect40To33; - -videocapture->PrepareVideoCapture(prepareVideoParameters); - -videocapture->StartVideoCaptureL(); - -videocapture->StopVideoCapture(); - -CCamera::CCameraVideoCaptureControl::TPrepareVideoParameters retrievedVideoParam; -videocapture->GetPrepareVideoParametersL(retrievedVideoParam); - -CCamera::CCameraVideoCaptureControl::TVideoCaptureType retrievedVideoCaptureType; -retrievedVideoCaptureType = retrievedVideoParam.VideoCaptureType(); - - -                 Camera API Accessing and Power Control of - Camera Camera Preset Support Capturing Image                 \ No newline at end of file + + + + + + Using +the Encoded H264 Video Frames to Capture VideoThis topic describes how to use the encoded H264 video frames in +the Ecam video capture function to capture the video data. +

                You need to be familiar +with the Capturing +a Video Clip tutorial.

                +

                The H264 video +encoder provides a new, high quality video data encoding format for Ecam. +Ecam allows the device to capture video frames which are encoded in the H264 +format. The Ecam video capture function supports the H264 video capture format +by default. You can select the H264 video capture format when preparing video +capture.

                + + +Call the CCamera::CCameraVideoCaptureControl::NewL(CCamera +&,MCaptureVideoObserver &) function to create an object +that maps the exported call to an internal object of the MCameraVideoCaptureControl function. + + +Pass a handle to the MCameraVideoCaptureControl function. +This implementation creates a handle to the CCamera::CCameraVideoCaptureControl object +by the active CCamera during the construction phase. +The CCameraVideoCaptureControl object makes an internal +call to the CCamera::CustomInterface(TUid) function of +the active CCamera implementation. The CustomInterface() function +passes a UID KECamMCameraVideoCaptureControlUid value for +the CCamera implementation. +The CCamera implementation creates the concrete implementation +of the MCameraVideoCaptureControl function and passes back +a handle to the CCameraVideoCaptureControl object. + + +Call the MCaptureVideoObserver function to notify +when the video capture operations are ready. + + +Call CCamera::CCameraVideoCaptureControl::GetVideoCaptureSupportInfoL(TInt +&)const to identify which video capture modes are supported +by the CCamera implementation. + + +Call the CCamera::CCameraVideoCaptureControl::TPrepareVideoParameters::SetVideoCaptureType(CCamera::CCameraVideoCaptureControl::TVideoCaptureType) function to set the desired video capture mode as the EClientVideoCapture or EDirectVideoCapture mode. + + +Set the value of CCamera::CCameraVideoCaptureControl::TPrepareVideoParameters::iFormat to +the EFormatEncodedH264 value for the CCamera implementation. +This CCamera implementation supports the H264 video encoding +data format. + + +Prepare video capture by using the CCamera::CCameraVideoCaptureControl::PrepareVideoCapture(const +TPrepareVideoParameters &) asynchronous function. The PrepareVideoCapture() function +performs setup and allocation of memory before calling the StartVideoCapture() function, +in order to keep minimum latency of the PrepareVideoCapture() function. + + +Notify the Ecam client to complete the video capture preparation using +the KUidECamEventVideoCaptureControlPrepareComplete event. + + +Call the CCamera::CCameraVideoCaptureControl::StartVideoCaptureL() function +to start video capture. + + +Call the CCamera::CCameraVideoCaptureControl::PauseVideoCapture() function +to pause the on-going video capture. + + +Call the CCamera::CCameraVideoCaptureControl::GetPrepareVideoParametersL(TPrepareVideoParameters +&)const function to retrieve the current prepare video parameters. +The current video capture type is retrieved by the CCamera::CCameraVideoCaptureControl::TPrepareVideoParameters::VideoCaptureType()const function. + + +Call the CCamera::CCameraVideoCaptureControl::ResumeVideoCaptureL() function +to resume the on-going video capture. + + +Call the CCamera::CCameraVideoCaptureControl::StopVideoCapture() function +to stop video capture. + + +Call the CCamera::CCameraVideoCaptureControl::ReleaseVideoResource()() function +to release the video resource, which is allocated while performing the PrepareVideoCapture() function. + + +If an error occurs while performing video capture, call the MCaptureVideoObserver::DirectVideoCaptureFailed(TInt) function. Any video capture operation is stopped. + + +Example

                The following example code snippet illustrates +video capture using H264 encoding:

                + +CCamera* camera = NULL; +MCameraObserver2* observer2 = NULL; + +CCamera::CCameraVideoCaptureControl* videocapture = NULL; +MCaptureVideoObserver* videoObserver = NULL; + +camera = CCamera::New2L(*observer2, 0, 0); + +videocapture = CCamera::CCameraVideoCaptureControl::NewL(*camera, *videoObserver); + +CCamera::CCameraVideoCaptureControl::TPrepareVideoParameters prepareVideoParameters; + +TInt supportedDVCType = -1; + +// To retrieve the supported video capture mode +videocapture->GetVideoCaptureSupportInfoL(supportedDVCType); + +// To set the video capture mode, if supported by the CCamera implementation +prepareVideoParameters.SetVideoCaptureType(CCamera::CCameraVideoCaptureControl::EDirectVideoCapture); + +// To set encoding for the H264 video data format +prepareVideoParameters.iFormat = CCamera::EFormatEncodedH264; + +// To set aspect ratio for the chosen H264 video format +prepareVideoParameters.iPixelAspectRatio = CCamera::CCameraAdvancedSettings::EEPixelAspect40To33; + +videocapture->PrepareVideoCapture(prepareVideoParameters); + +videocapture->StartVideoCaptureL(); + +videocapture->StopVideoCapture(); + +CCamera::CCameraVideoCaptureControl::TPrepareVideoParameters retrievedVideoParam; +videocapture->GetPrepareVideoParametersL(retrievedVideoParam); + +CCamera::CCameraVideoCaptureControl::TVideoCaptureType retrievedVideoCaptureType; +retrievedVideoCaptureType = retrievedVideoParam.VideoCaptureType(); + + +                 +                 +Camera Preset +Support +Capturing +Still Images +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D04DD8E6-804F-539E-8BD1-146210F4A51C_d0e195099_href.png Binary file Symbian3/SDK/Source/GUID-D04DD8E6-804F-539E-8BD1-146210F4A51C_d0e195099_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D04DD8E6-804F-539E-8BD1-146210F4A51C_d0e200107_href.png Binary file Symbian3/SDK/Source/GUID-D04DD8E6-804F-539E-8BD1-146210F4A51C_d0e200107_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D0BD34C9-7793-5FA0-8864-FD7444D62F90.dita --- a/Symbian3/SDK/Source/GUID-D0BD34C9-7793-5FA0-8864-FD7444D62F90.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-D0BD34C9-7793-5FA0-8864-FD7444D62F90.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,86 +1,86 @@ - - - - - -How to -form linksThis document describes how to use links within a doubly linked -list. -

                To form a doubly linked list of CMyClass objects, include -the link object TDblQueLink as a component of CMyClass:

                -class CMyClass : public CBase - { - ... - TDblQueLink iDlink; - ... - }; - - - -

                Although any kind of object can be an element of a linked list, most lists -consist of elements which are all of the same type.

                -

                An object can participate in more than one list. For example, to allow CMyClass objects -to participate in two doubly linked lists, include two separate TDblQueLink objects -as components of CMyClass:

                -class CMyClass : public CBase - { - ... - TDblQueLink iDlink1; - ... - TDblQueLink iDlink2; - }; - - - -

                Elements can also be objects constructed from a variety of classes, all -ultimately derived from the same base class, where that base class includes -the link object as a component. For example, if CBc is a -base class for CD1 which, in turn, is a base class for CD2, -then the elements of the list can consist of a mix of CBc or CDc1 or CDc2 objects.

                -class CBc : public CBase - { - ... - TDblQueLink iDlink; - ... - }; -class CDc1 : public CBclass - { - ... - } - -class CDc2 : public CDc1 - { - ... - } - - - - -

                New link elements are inserted into an existing list using either TDblQueLink::Enque() or TDblQueLink::AddBefore() function. Note that AddBefore() is not available in v5. -These are prototyped as:

                -void Enque(TDblQueLinkBase* aLink); - -void AddBefore(TDblQueLinkBase* aLink); -

                Calling Enque() on an element means that this element -is added to the list so that its position follows the element aLink, -as the following figure shows.

                - - - -

                Calling AddBefore() on an element means that this element -is added to the list so that its position precedes the element aLink, -as the following figure shows.

                - - - -

                Note that new elements cannot be inserted at the beginning or end of a -list using these functions. The AddFirst() and AddLast() members -of the header class TDblQue<class T> must be used -instead.

                + + + + + +How to +form linksThis document describes how to use links within a doubly linked +list. +

                To form a doubly linked list of CMyClass objects, include +the link object TDblQueLink as a component of CMyClass:

                +class CMyClass : public CBase + { + ... + TDblQueLink iDlink; + ... + }; + + + +

                Although any kind of object can be an element of a linked list, most lists +consist of elements which are all of the same type.

                +

                An object can participate in more than one list. For example, to allow CMyClass objects +to participate in two doubly linked lists, include two separate TDblQueLink objects +as components of CMyClass:

                +class CMyClass : public CBase + { + ... + TDblQueLink iDlink1; + ... + TDblQueLink iDlink2; + }; + + + +

                Elements can also be objects constructed from a variety of classes, all +ultimately derived from the same base class, where that base class includes +the link object as a component. For example, if CBc is a +base class for CD1 which, in turn, is a base class for CD2, +then the elements of the list can consist of a mix of CBc or CDc1 or CDc2 objects.

                +class CBc : public CBase + { + ... + TDblQueLink iDlink; + ... + }; +class CDc1 : public CBclass + { + ... + } + +class CDc2 : public CDc1 + { + ... + } + + + + +

                New link elements are inserted into an existing list using either TDblQueLink::Enque() or TDblQueLink::AddBefore() function. Note that AddBefore() is not available in v5. +These are prototyped as:

                +void Enque(TDblQueLinkBase* aLink); + +void AddBefore(TDblQueLinkBase* aLink); +

                Calling Enque() on an element means that this element +is added to the list so that its position follows the element aLink, +as the following figure shows.

                + + + +

                Calling AddBefore() on an element means that this element +is added to the list so that its position precedes the element aLink, +as the following figure shows.

                + + + +

                Note that new elements cannot be inserted at the beginning or end of a +list using these functions. The AddFirst() and AddLast() members +of the header class TDblQue<class T> must be used +instead.

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D0F6E95B-B35A-4EA1-8CC3-D86D1E0E6DD3.dita --- a/Symbian3/SDK/Source/GUID-D0F6E95B-B35A-4EA1-8CC3-D86D1E0E6DD3.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-D0F6E95B-B35A-4EA1-8CC3-D86D1E0E6DD3.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,72 +1,80 @@ - - - - - -Creating -stylus pop-up menu -

                Construct the menu using the method NewL()in the class CAknStylusPopUpMenu.

                -

                The last parameter in the constructor is a pointer to the preview -pop-up from which the stylus pop-up menu is launched. If you are not constructing -a pop-up menu for a preview pop-up, set the parameter as NULL.

                 -

                To construct the menu from a resource, use the method CAknStylusPopUpMenu::ConstructFromResourceL().

                -

                The following example illustrates a stylus pop-up menu opened in the location -(not a preview pop-up) where the user taps with the stylus as well as the -resource that defines the menu items:

                -

                The menu is constructed only once: when HandlePointerEventL runs -for the first time. Later the already constructed menu is shown again.

                 -void CMyAppView::HandlePointerEventL - ( const TPointerEvent& aPointerEvent ) - { - if ( aPointerEvent.iType == TPointerEvent::EButton1Down ) - { - if ( !iMenu ) - { - iMenu = CAknStylusPopUpMenu::NewL( - iMenuObserver, - aPointerEvent.iParentPosition, - NULL ); - TInt resourceReaderId = 0; - resourceReaderId = R_MYAPP_STYLUS_MENU; - TResourceReader reader; - iCoeEnv->CreateResourceReaderLC( - reader, resourceReaderId ); - iMenu->ConstructFromResourceL( reader ); - CleanupStack::PopAndDestroy(); // reader - } - iMenu->SetPosition( aPointerEvent.iParentPosition ); - iMenu->ShowMenu(); - } - // Forward event to base class too. - CCoeControl::HandlePointerEventL( aPointerEvent ); - } - -RESOURCE STYLUS_POPUP_MENU r_myapp_stylus_menu - { - items = - { - STYLUS_POPUP_MENU_ITEM - { - txt = "Stylus Popup Menu Item 1"; - command = EMyAppMenuItemCmd1; - }, - STYLUS_POPUP_MENU_ITEM - { - txt = "Stylus Popup Menu Item 2"; - command = EMyAppMenuItemCmd2; - }, - STYLUS_POPUP_MENU_ITEM - { - txt = "Stylus Popup Menu Item 3"; - command = EMyAppMenuItemCmd3; - } - }; - } - + + + + + +Creating +stylus pop-up menu +

                Construct the menu using the method NewL()in the class CAknStylusPopUpMenu.

                +

                The last parameter in the constructor is a pointer to the preview +pop-up from which the stylus pop-up menu is launched. If you are not constructing +a pop-up menu for a preview pop-up, set the parameter as NULL.

                 +

                To construct the menu from a resource, use the method CAknStylusPopUpMenu::ConstructFromResourceL().

                +

                The following example illustrates a stylus pop-up menu opened in the location +(not a preview pop-up) where the user taps with the stylus as well as the +resource that defines the menu items:

                +

                The menu is constructed only once: when HandlePointerEventL runs +for the first time. Later the already constructed menu is shown again.

                 +

                The following code snippets explain how to create and display Stylus pop-up +menu:

                  +

                • Creating directly:

                  // member variable point to the stylus Popup menu +CAknStylusPopUpMenu * iPopupMenu ; +_LIT(KItem1, "Item 1"); +_LIT(KItem2, "Item 2"); +_LIT(KItem3, "Item 3"); +_LIT(KItem4, "Item 4"); +enum StylusPopupMenuCommand + { + StylusMenuCommand1 = 0 , + StylusMenuCommand2, + StylusMenuCommand3, + StylusMenuCommand4 + }; +// create object , “this” is a object implement the interface +// MEikMenuObserver +iPopupMenu = CAknStylusPopUpMenu::NewL( this , TPoint( 0 , 0 ) ); +// add menu item +iPopupMenu->AddMenuItemL( KItem1 , StylusMenuCommand1 ); +iPopupMenu->AddMenuItemL( KItem2 , StylusMenuCommand2 ); +iPopupMenu->AddMenuItemL( KItem3 , StylusMenuCommand3 ); +iPopupMenu->AddMenuItemL( KItem4 , StylusMenuCommand4 ); +
                  • +

                • Creating through resource file:

                  RESOURCE STYLUS_POPUP_MENU r_stylus_popup_menu + { + items = + { + STYLUS_POPUP_MENU_ITEM + { + txt = "Menu Item 1"; + command = EStylusPopupCommand1; }, + STYLUS_POPUP_MENU_ITEM + { + txt = "Menu Item 2"; + command = EStylusPopupCommand2; }, + STYLUS_POPUP_MENU_ITEM + { + txt = "Menu Item 3"; + command = EStylusPopupCommand3; + } + }; + } +// create object +iPopupMenu = CAknStylusPopUpMenu::NewL( this , TPoint( 0 , 0 ) ); +{ + TResourceReader reader; + iCoeEnv->CreateResourceReaderLC( + reader , + R_STYLUS_POPUP_MENU ); + iPopupMenu->ConstructFromResourceL( reader ); + // destroy reader + CleanupStack::PopAndDestroy(); +} +
                  • +

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D0FEE812-AD80-40D8-B902-05EC16C44C42.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-D0FEE812-AD80-40D8-B902-05EC16C44C42.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,50 @@ + + + + + +Opening +a Connection to an IAPExtended Connection Preferences API can be used by applications +to set the preferred Internet Access Point (IAP) prior to establishing a connection. +

                Specifying +IAP ID enables the applications to start a connection to a specific IAP. The +application acquires a connection to the requested IAP, regardless of the +existing connections.

                 + +Connect to socket server . + RSocketServ ss; +ss.Connect(); + + Open a RConnection object. + RConnection conn; +conn.Open( ss ); + +Create a connection +preference list and extended connection preferences object. + TConnPrefList prefList; +TExtendedConnPref preferences; + +Define the IAP using TExtendedConnPref::SetIapId(). +preferences.SetIapId( 8 ); + +Append extended +connection preferences into connection preference list. +prefList.AppendL( &preferences ); + +Start a connection +with connection preferences. +conn.Start( prefList ); + + +

                The application +is connected to the specified IAP.

                 +                 +Additional +Connection Preferences +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D15068B5-D12E-5515-A772-EA3B304EE01E_d0e354923_href.png Binary file Symbian3/SDK/Source/GUID-D15068B5-D12E-5515-A772-EA3B304EE01E_d0e354923_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D15068B5-D12E-5515-A772-EA3B304EE01E_d0e361003_href.png Binary file Symbian3/SDK/Source/GUID-D15068B5-D12E-5515-A772-EA3B304EE01E_d0e361003_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D18E56F1-3DB9-472D-B587-30A168E8B8C4_d0e36218_href.png Binary file Symbian3/SDK/Source/GUID-D18E56F1-3DB9-472D-B587-30A168E8B8C4_d0e36218_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D18E56F1-3DB9-472D-B587-30A168E8B8C4_d0e41785_href.png Binary file Symbian3/SDK/Source/GUID-D18E56F1-3DB9-472D-B587-30A168E8B8C4_d0e41785_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D1E80B1B-FBFD-5FBC-981C-E2D04A02EF41_d0e203822_href.png Binary file Symbian3/SDK/Source/GUID-D1E80B1B-FBFD-5FBC-981C-E2D04A02EF41_d0e203822_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D1E80B1B-FBFD-5FBC-981C-E2D04A02EF41_d0e208830_href.png Binary file Symbian3/SDK/Source/GUID-D1E80B1B-FBFD-5FBC-981C-E2D04A02EF41_d0e208830_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D1F29744-EB92-5811-A735-B0BC1B352ED5.dita --- a/Symbian3/SDK/Source/GUID-D1F29744-EB92-5811-A735-B0BC1B352ED5.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-D1F29744-EB92-5811-A735-B0BC1B352ED5.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,115 +1,115 @@ - - - - - -Video -Renderer OverviewThis topic describes the Video Renderer component and is aimed -at video controller and video adaptation developers who want to take advantage -of rendering to graphics surfaces. -
                Purpose

                The Video Renderer renders video to a graphics -surface. The Video Renderer can be used by video decoders, video post-processors -and video controllers. It can also be used to implement the ECam -viewfinder using a graphics surface.

                The Video Renderer has -two modes: timed and non-timed. In timed mode, the Video Renderer renders -a frame at a specific time. In non-timed mode, the Video Renderer renders -a frame immediately.

                On the Symbian platform, ScreenPlay (also -known as the New Graphics Architecture or NGA) enables rendering to a graphics -surface. The Video Renderer can only be used in conjunction with ScreenPlay. -The Video Renderer does not contain any video or graphics processing software. -All operations that are needed to display video content on the screen are -handled by the Graphics -Composition Components.

                The Video Renderer component is classified -as Optional Replaceable. This means that device creators can either substitute -it with their own implementation or remove it if they do not want to use it.

                -
                Required background

                To understand the Video Renderer, -the reader must be familiar with the following:

                  -

                • Graphics -Surfaces

                  • -
                -
                Architecture

                The Video Renderer can be implemented -in two different ways, as shown in the following diagram:

                - The two Video Renderer architectures - -

                Note: For simplicity, only the Multimedia Framework client/controller -thread boundary has been shown; other thread boundaries may exist.

                In -both architectures, the Video -Client API (CVideoPlayerUtility2) is responsible -for retrieving graphics surface handles from the video player controller and -registering them with the Window -Server. The difference in the two approaches is in the implementation -of the video adaptation and the video player controller:

                  -

                • Video adaptation -approach

                  The video adaptation uses the Video Renderer to create -and manage graphics surfaces and handle video rendering. The video player -controller simply passes surface information between DevVideoPlay and -the client. An example of this is the Symbian reference AVI player controller -and XVid decoder. Symbian recommends this approach for -new implementations.

                  • -

                • Video player controller -approach

                  The video player controller uses the Video Renderer -to create and manage graphics surfaces, and handle video rendering and timing. -This approach is suitable for implementations where DevVideoPlay is only used -as a codec interface or where DevVideoPlay is not used.

                  • -

                In both architectures, the Surface -Update component provides a communication channel between the Video -Renderer and the composition engine.

                -
                APIs

                The Video Renderer component contains the -following DLL with its associated APIs:

                - - - -DLL -Description - - - - -

                videorenderer.dll

                -

                The functionality of the Video Renderer is provided by the following -key classes:

                  -

                • CVideoRenderer - -a utility class for rendering video to graphics surfaces on behalf of a client.

                  • -

                • MVideoRendererObserver - -an observer class that provides notifications about the availability and status -of buffers submitted for rendering.

                  • -

                • TVideoFrameBuffer - -represents a buffer for a single decoded video picture.

                  • -

                The Video Renderer also uses a resource file (videorenderer.rss) -to store supported pixel formats and timed mode values. For more information, -see Video Renderer -Resource File.

                -                 - - -
                -
                Typical uses

                The Video Renderer is used for the -following:

                  -

                • Creating a surface for -video rendering

                  • -

                • Supplying buffers to -decode video frames into

                  • -

                • Rendering a buffer on -the display (timed or non-timed)

                  • -

                • Destroying a surface.

                  • -
                -                 -Video Client - -Multimedia -Framework (MMF) -Multimedia -Plug-ins -Video HAI - -Graphics -Surface Composition Collection -Surface Manager -Component + + + + + +Video +Renderer OverviewThis topic describes the Video Renderer component and is aimed +at video controller and video adaptation developers who want to take advantage +of rendering to graphics surfaces. +
                Purpose

                The Video Renderer renders video to a graphics +surface. The Video Renderer can be used by video decoders, video post-processors +and video controllers. It can also be used to implement the ECam +viewfinder using a graphics surface.

                The Video Renderer has +two modes: timed and non-timed. In timed mode, the Video Renderer renders +a frame at a specific time. In non-timed mode, the Video Renderer renders +a frame immediately.

                On the Symbian platform, ScreenPlay (also +known as the New Graphics Architecture or NGA) enables rendering to a graphics +surface. The Video Renderer can only be used in conjunction with ScreenPlay. +The Video Renderer does not contain any video or graphics processing software. +All operations that are needed to display video content on the screen are +handled by the Graphics +Composition Components.

                The Video Renderer component is classified +as Optional Replaceable. This means that device creators can either substitute +it with their own implementation or remove it if they do not want to use it.

                +
                Required background

                To understand the Video Renderer, +the reader must be familiar with the following:

                  +

                • Graphics +Surfaces

                  • +
                +
                Architecture

                The Video Renderer can be implemented +in two different ways, as shown in the following diagram:

                + The two Video Renderer architectures + +

                Note: For simplicity, only the Multimedia Framework client/controller +thread boundary has been shown; other thread boundaries may exist.

                In +both architectures, the Video +Client API (CVideoPlayerUtility2) is responsible +for retrieving graphics surface handles from the video player controller and +registering them with the Window +Server. The difference in the two approaches is in the implementation +of the video adaptation and the video player controller:

                  +

                • Video adaptation +approach

                  The video adaptation uses the Video Renderer to create +and manage graphics surfaces and handle video rendering. The video player +controller simply passes surface information between DevVideoPlay and +the client. An example of this is the Symbian reference AVI player controller +and XVid decoder. Symbian recommends this approach for +new implementations.

                  • +

                • Video player controller +approach

                  The video player controller uses the Video Renderer +to create and manage graphics surfaces, and handle video rendering and timing. +This approach is suitable for implementations where DevVideoPlay is only used +as a codec interface or where DevVideoPlay is not used.

                  • +

                In both architectures, the Surface +Update component provides a communication channel between the Video +Renderer and the composition engine.

                +
                APIs

                The Video Renderer component contains the +following DLL with its associated APIs:

                + + + +DLL +Description + + + + +

                videorenderer.dll

                +

                The functionality of the Video Renderer is provided by the following +key classes:

                  +

                • CVideoRenderer - +a utility class for rendering video to graphics surfaces on behalf of a client.

                  • +

                • MVideoRendererObserver - +an observer class that provides notifications about the availability and status +of buffers submitted for rendering.

                  • +

                • TVideoFrameBuffer - +represents a buffer for a single decoded video picture.

                  • +

                The Video Renderer also uses a resource file (videorenderer.rss) +to store supported pixel formats and timed mode values. For more information, +see Video Renderer +Resource File.

                +                 + + +
                +
                Typical uses

                The Video Renderer is used for the +following:

                  +

                • Creating a surface for +video rendering

                  • +

                • Supplying buffers to +decode video frames into

                  • +

                • Rendering a buffer on +the display (timed or non-timed)

                  • +

                • Destroying a surface.

                  • +
                +                 +Video Client + +Multimedia +Framework (MMF) +Multimedia +Plug-ins +Video HAI + +Graphics +Surface Composition Collection +Surface Manager +Component                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D1F4B2DC-5B18-4454-BFD7-8BB61D80E7CA.dita --- a/Symbian3/SDK/Source/GUID-D1F4B2DC-5B18-4454-BFD7-8BB61D80E7CA.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-D1F4B2DC-5B18-4454-BFD7-8BB61D80E7CA.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,105 +1,104 @@ - - - - - -Special -character table -

                Special character table consists of symbols other than alphanumeric letters -such as punctuation marks, currency symbols.

                -

                The special character table works with touch down and release. Special -character table can be found by:

                  -

                • short pressing * §key_star_key§ key in virtual ITU-T.

                  • -

                • pressing the dedicated special character table button in handwriting -recognition.

                  • -

                • pressing the dedicated special character table button in smiley picker.

                  • -
                Special character table does not have title or traditional -softkeys.

                -

                Orientation of special character table follows the orientation of the input -method. For example, if the special character table is opened from the full -screen QWERTY, the orientation is landscape. If the table is opened from smaller -QWERTY which is in portrait, the orientation of the table should also be portrait. -There is no focus in the grid but if evoked with hardware key event, focus -is brought to the first item of the most recently used character row.

                -

                The first row in the special character table consists of the Close button -and can consist of the Smiley picker button. Smiley picker button can be hidden -if needed by the application. The second row in the special character table -displays most recently used characters. In portrait mode, the row consists -of five items and in landscape, seven items. If characters cannot fit to one -page, a page navigator is opened. Through this page navigator, user can change -the page by tapping on the navigation arrows. Navigating arrows are looping -so that user can access from the last page to the first page and vice versa.

                -

                Special character table can be closed only by pressing the Close button. -When the special character table is in landscape, the page navigator is moved -to the top row next to the Close button. The amount of most recently used -characters is increased by two items so that the table fills the entire display.

                - -Special character table portrait and landscape mode - - -

                -Default touch -events to special character table. - - - - - - -

                User action

                 -

                State change

                 -

                Feedback

                 -                 - - - -

                Touch down

                 -

                Inactive

                 -

                Highlight is shown.

                Tactile: Basic list effect and audio -feedback are provided with touch down event.

                 -                 - -

                Touch release on grid item

                 -

                Activates the selected item and closes the table.

                 -

                Highlight disappears.

                Tactile: Basic list effect is provided -with touch release event. No audio feedback is provided.

                 -                 - -

                Touch down on navigation arrow or smiley picker button

                 -

                Button pressed effect.

                 -

                Tactile: Basic button effect and audio feedback are provided with -touch down event.

                 -                 - -

                Touch release on navigation arrow

                 -

                Next or previous page of the table is opened.

                 -

                Tactile: Basic button effect is provided with touch release event. -No audio feedback is provided.

                 -                 - -

                Touch release on SCT button or smiley picker button

                 -

                Special character table is opened and smiley picker is closed or -other way around.

                 -

                Tactile: Basic button effect is provided with touch release event. -No audio feedback is provided.

                 -                 - -

                Touch down and release on close button

                 -

                Table is closed, no characters are selected.

                 -

                Tactile: Basic button effect is provided with touch release event. -No audio feedback is provided.

                 -                 - -

                Touch down and move

                 -

                Inactive

                 -

                Tactile: No effect

                 -                 - - + + + + + +Special +character table +

                Special character table consists of symbols other than alphanumeric letters +such as punctuation marks, currency symbols.

                +

                The special character table works with touch down and release. Special +character table is opened by:

                  +

                • short pressing * §key_star_key§ key in virtual ITU-T.

                  • +

                • pressing the dedicated special character table button in handwriting +recognition.

                  • +

                • pressing the dedicated special character table button in smiley picker.

                  • +
                Special character table does not have title or traditional softkeys.

                +

                Orientation of special character table follows the orientation of the input +method. For example, if the special character table is opened from the full +screen QWERTY, the orientation is landscape. If the table is opened from smaller +QWERTY which is in portrait, the orientation of the table should also be portrait. +There is no focus in the grid but if evoked with hardware key event, focus +is brought to the first item of the most recently used character row.

                +

                The first row in the special character table consists of the Close button +and can consist of the Smiley picker button. Smiley picker button can be hidden +if needed by the application. The second row in the special character table +displays most recently used characters. In portrait mode, the row consists +of five items and in landscape, seven items. If characters cannot fit to one +page, a page navigator is opened. Through this page navigator, user can change +the page by tapping on the navigation arrows. Navigating arrows are looping +so that user can access from the last page to the first page and vice versa.

                +

                Special character table can be closed only by pressing the Close button. +When the special character table is in landscape, the page navigator is moved +to the top row next to the Close button. The amount of most recently used +characters is increased by two items so that the table fills the entire display.

                + +Special character table portrait and landscape mode + + +

                +

                Default touch +events to special character table. + + + + + + +

                User action

                 +

                State change

                 +

                Feedback

                 +                 + + + +

                Touch down

                 +

                Inactive

                 +

                Highlight is shown.

                Tactile: Basic list effect and audio +feedback are provided with touch down event.

                 +                 + +

                Touch release on grid item

                 +

                Activates the selected item and closes the table.

                 +

                Highlight disappears.

                Tactile: Basic list effect is provided +with touch release event. No audio feedback is provided.

                 +                 + +

                Touch down on navigation arrow or smiley picker button

                 +

                Button pressed effect.

                 +

                Tactile: Basic button effect and audio feedback are provided with +touch down event.

                 +                 + +

                Touch release on navigation arrow

                 +

                Next or previous page of the table is opened.

                 +

                Tactile: Basic button effect is provided with touch release event. +No audio feedback is provided.

                 +                 + +

                Touch release on SCT button or smiley picker button

                 +

                Special character table is opened and smiley picker is closed or +other way around.

                 +

                Tactile: Basic button effect is provided with touch release event. +No audio feedback is provided.

                 +                 + +

                Touch down and release on close button

                 +

                Table is closed, no characters are selected.

                 +

                Tactile: Basic button effect is provided with touch release event. +No audio feedback is provided.

                 +                 + +

                Touch down and move

                 +

                Inactive

                 +

                Tactile: No effect

                 +                 + +
                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D205622E-FB0F-59C4-A039-B418B551CBFA_d0e10560_href.png Binary file Symbian3/SDK/Source/GUID-D205622E-FB0F-59C4-A039-B418B551CBFA_d0e10560_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D205622E-FB0F-59C4-A039-B418B551CBFA_d0e9285_href.png Binary file Symbian3/SDK/Source/GUID-D205622E-FB0F-59C4-A039-B418B551CBFA_d0e9285_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D222EAAA-ACF4-5837-8CDD-5EDB02EAE259_d0e407085_href.png Binary file Symbian3/SDK/Source/GUID-D222EAAA-ACF4-5837-8CDD-5EDB02EAE259_d0e407085_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D222EAAA-ACF4-5837-8CDD-5EDB02EAE259_d0e407247_href.png Binary file Symbian3/SDK/Source/GUID-D222EAAA-ACF4-5837-8CDD-5EDB02EAE259_d0e407247_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D2263F64-2582-473A-B939-ACEBF8E974BF-master.png Binary file Symbian3/SDK/Source/GUID-D2263F64-2582-473A-B939-ACEBF8E974BF-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D2263F64-2582-473A-B939-ACEBF8E974BF_d0e53323_href.png Binary file Symbian3/SDK/Source/GUID-D2263F64-2582-473A-B939-ACEBF8E974BF_d0e53323_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D2263F64-2582-473A-B939-ACEBF8E974BF_d0e59088_href.png Binary file Symbian3/SDK/Source/GUID-D2263F64-2582-473A-B939-ACEBF8E974BF_d0e59088_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D2263F64-2582-473A-B939-ACEBF8E974BF_d0e82219_href.png Binary file Symbian3/SDK/Source/GUID-D2263F64-2582-473A-B939-ACEBF8E974BF_d0e82219_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D280276A-6E4C-41B7-B6EA-700B33B04981.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-D280276A-6E4C-41B7-B6EA-700B33B04981.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,17 @@ + + + + + +IP Connection +ManagementThe IP Connection Management package provides services to accommodate + automatic IP connection selection, application-assisted roaming logic, contention +management for IP connections, IP connection monitoring and logging, settings +management for IP connections, UI dialogs related to IP connections and managing +PDP contexts. \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D28FA4E1-6A94-4508-95B3-ACE21BCE6EA7.dita --- a/Symbian3/SDK/Source/GUID-D28FA4E1-6A94-4508-95B3-ACE21BCE6EA7.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-D28FA4E1-6A94-4508-95B3-ACE21BCE6EA7.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,55 +1,55 @@ - - - - - -Open -C String Utilities ExampleString Utilities Library Example -

                String manipulation on Symbian platform is bit tricky. Even though Symbian -platform has rich set of APIs for formatting/manipulating strings with both -UNICODE (16 bit variants) and narrow character sets (8-bits), using those -APIs will be bit complex for those who have familiarized Standard C string -manipulations. When one writes hybrid applications on Symbian platform using -native Symbian APIs as well as Open C APIs, user may need to convert the descriptors -of Symbian platform to standard C character strings and vice versa. Especially, -in case of writing hybrid applications on open C, user will be facing this -conversion problem more frequently. It is really difficult to do these conversions -without the thorough knowledge of Symbian platform descriptors. OpenCStringUtilitiesEx -is a library, which makes Open C’s developers life easy. OpenCStringUtilitiesEx -is a library, which exports several string- utility APIs for descriptor to -character string conversions and vice versa. With the help of this library, -user will be able to write a hybrid application on Open C, with out knowing -much about the descriptors of Symbian platform.

                -
                Download

                Click -on the following link to download the example: OpenCStringUtilitiesEx.zip

                Click: browse to view the example code.

                -
                Design and -Implementation

                The following sections provide information about -the implementation of the example.

                Capabilities

                The program -capabilities are defined in: stringutils.mmp(DLL - library): CAPABILITY -NONE stringutils_example.mmp (EXE - application): CAPABILITY -NONE.

                Module Hierarchy

                This application has 2 modules -as below: String-utils library (OpenCStringUtilitiesLibEx.dll) that exports -set of APIs for the user (OpenCStringUtilitiesLibEx). An application (EXE) -that demonstrates the usage of Open C APIs and also those APIs exported by -String Utils library. (OpenCStringUtilitiesLibEx) This example creates a -DLL which exports set of generic APIs that can be used to convert descriptor -of Symbian platform to character string and vice versa. To give an rough -idea on how to use these APIs, an EXE is provided that calls the APIs of OpenCStringUtilitiesLibEx -and illustrates their uses.

                Implementation details of EXE

                OpenCStringUtilitiesExeEx -is a simple console based C application that uses String-utils library. This -application uses main() as the entry point for the application.It demonstrates -how to use String-utils library (OpenCStringUtilitiesLibEx.dll) APIs. It -has its own icon and can be launched from the UI both in the emulator and -in the device.

                APIs demonstrated

                tbuf16towchar

                tbuf16tochar

                tbuf8towchar

                tbufC16towchar

                tbufC8tochar

                tbufC16tochar

                tbufC8towchar

                wchartotbuf16

                chartotbuf16

                wchartotbuf8

                chartotbuf8

                wchartohbufc16

                chartohbufc16

                wchartohbufc8

                chartohbufc8

                hbufC16towchar

                hbufC16tochar

                hbufC8towchar

                hbufC8tochar

                -
                Building and -Using To build the example application, go to the OpenCStringUtilitiesEx\group -directory and build the application. The definition for the whole application -can be found in the bld.inf file in the group subdirectory of the applications -main directory.
                + + + + + +Open +C String Utilities ExampleString Utilities Library Example +

                String manipulation on Symbian platform is bit tricky. Even though Symbian +platform has rich set of APIs for formatting/manipulating strings with both +UNICODE (16 bit variants) and narrow character sets (8-bits), using those +APIs will be bit complex for those who have familiarized Standard C string +manipulations. When one writes hybrid applications on Symbian platform using +native Symbian APIs as well as Open C APIs, user may need to convert the descriptors +of Symbian platform to standard C character strings and vice versa. Especially, +in case of writing hybrid applications on open C, user will be facing this +conversion problem more frequently. It is really difficult to do these conversions +without the thorough knowledge of Symbian platform descriptors. OpenCStringUtilitiesEx +is a library, which makes Open C’s developers life easy. OpenCStringUtilitiesEx +is a library, which exports several string- utility APIs for descriptor to +character string conversions and vice versa. With the help of this library, +user will be able to write a hybrid application on Open C, with out knowing +much about the descriptors of Symbian platform.

                +
                Download

                Click +on the following link to download the example: OpenCStringUtilitiesEx.zip

                Click: browse to view the example code.

                +
                Design and +Implementation

                The following sections provide information about +the implementation of the example.

                Capabilities

                The program +capabilities are defined in: stringutils.mmp(DLL - library): CAPABILITY +NONE stringutils_example.mmp (EXE - application): CAPABILITY +NONE.

                Module Hierarchy

                This application has 2 modules +as below: String-utils library (OpenCStringUtilitiesLibEx.dll) that exports +set of APIs for the user (OpenCStringUtilitiesLibEx). An application (EXE) +that demonstrates the usage of Open C APIs and also those APIs exported by +String Utils library. (OpenCStringUtilitiesLibEx) This example creates a +DLL which exports set of generic APIs that can be used to convert descriptor +of Symbian platform to character string and vice versa. To give an rough +idea on how to use these APIs, an EXE is provided that calls the APIs of OpenCStringUtilitiesLibEx +and illustrates their uses.

                Implementation details of EXE

                OpenCStringUtilitiesExeEx +is a simple console based C application that uses String-utils library. This +application uses main() as the entry point for the application.It demonstrates +how to use String-utils library (OpenCStringUtilitiesLibEx.dll) APIs. It +has its own icon and can be launched from the UI both in the emulator and +in the device.

                APIs demonstrated

                tbuf16towchar

                tbuf16tochar

                tbuf8towchar

                tbufC16towchar

                tbufC8tochar

                tbufC16tochar

                tbufC8towchar

                wchartotbuf16

                chartotbuf16

                wchartotbuf8

                chartotbuf8

                wchartohbufc16

                chartohbufc16

                wchartohbufc8

                chartohbufc8

                hbufC16towchar

                hbufC16tochar

                hbufC8towchar

                hbufC8tochar

                +
                Building and +Using To build the example application, go to the OpenCStringUtilitiesEx\group +directory and build the application. The definition for the whole application +can be found in the bld.inf file in the group subdirectory of the applications +main directory.
                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D2AE7E31-CAE7-5F03-8754-24172580BBAF.dita --- a/Symbian3/SDK/Source/GUID-D2AE7E31-CAE7-5F03-8754-24172580BBAF.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-D2AE7E31-CAE7-5F03-8754-24172580BBAF.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,12 +1,12 @@ - - - - - -Bluetooth Management Collection OverviewThe Bluetooth Management collection contains the Bluetooth Manager and Bluetooth Client components.
                Purpose

                The Bluetooth Management collection contains the Bluetooth Manager and Bluetooth Client components.

                Architecture
                Components

                The Bluetooth Management collection contains the following components:

                • Bluetooth Manager

                  The Bluetooth Manager component stores non-volatile details of Bluetooth devices in the BT Registry using DBMS. Stored information can be retrieved, modified and deleted.

                • Bluetooth Client

                  The Bluetooth Client component provides support for configuring and managing Bluetooth sockets, accessing the HCI, and configuring Bluetooth AV sessions.

                Using Bluetooth Management

                The Bluetooth Management collection has the following uses:

                • storing, retrieving, modifying and deleting details from the Bluetooth Registry using Bluetooth Manager

                • configuring and managing Bluetooth sockets, accessing the HCI and configuring Bluetooth AV sessions using the Bluetooth Client.

                \ No newline at end of file + + + + + +Bluetooth Management Collection OverviewThe Bluetooth Management collection contains the Bluetooth Manager and Bluetooth Client components.
                Purpose

                The Bluetooth Management collection contains the Bluetooth Manager and Bluetooth Client components.

                Architecture
                Components

                The Bluetooth Management collection contains the following components:

                • Bluetooth Manager

                  The Bluetooth Manager component stores non-volatile details of Bluetooth devices in the BT Registry using DBMS. Stored information can be retrieved, modified and deleted.

                • Bluetooth Client

                  The Bluetooth Client component provides support for configuring and managing Bluetooth sockets, accessing the HCI, and configuring Bluetooth AV sessions.

                Using Bluetooth Management

                The Bluetooth Management collection has the following uses:

                • storing, retrieving, modifying and deleting details from the Bluetooth Registry using Bluetooth Manager

                • configuring and managing Bluetooth sockets, accessing the HCI and configuring Bluetooth AV sessions using the Bluetooth Client.

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D2CF64ED-0D85-5535-9A51-C127B10B07B2_d0e351327_href.png Binary file Symbian3/SDK/Source/GUID-D2CF64ED-0D85-5535-9A51-C127B10B07B2_d0e351327_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D2CF64ED-0D85-5535-9A51-C127B10B07B2_d0e357407_href.png Binary file Symbian3/SDK/Source/GUID-D2CF64ED-0D85-5535-9A51-C127B10B07B2_d0e357407_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D2D17EF9-FFC6-5FBD-A992-55746A12B625.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-D2D17EF9-FFC6-5FBD-A992-55746A12B625.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,103 @@ + + + + + +Basic +encryption and decryption using a symmetric cipher +

                This example demonstrates how to encrypt and decrypt a small string of +data using a symmetric cipher. Firstly, an encryption operation is performed +on the data. Following this a decryption operation is performed on the encrypted +data. Finally a check is made on the decrypted data for equality with the +original data which tests that the encrypt and decrypt operations have maintained +data integrity.

                +#include <legacyselector.h> +#include <cryptosymmetriccipherapi.h> +#include <keys.h> + +using namespace CryptoSpi; + +//Create a new CCryptoParams object to encapsulate the secret key string and key type +CCryptoParams* params = CCryptoParams::NewLC(); + +//Add the secret key to the CCryptoParams object by calling the CCryptoParams::AddL() method, +//passing in the key string and appropriate key parameter UID +params->AddL( _L8("12345678"), KSymmetricKeyParameterUid); + +//Create a key object (CKey) by passing in an instance of TKeyProperty and the previously +//created CCryptoParams object containing the secret key. +TKeyProperty keyProperty = {KDesUid, KNullUid, KSymmetricKey, KNonEmbeddedKeyUid}; +CKey* key=CKey::NewL(keyProperty, *params); +CleanupStack::PushL(key); +//Create and initialize a pointer for the Symmetric cipher implementation object +CSymmetricCipher* impl = NULL; + +//Create a symmetric cipher passing in the appropriate CKey object +TRAPD(err, CSymmetricCipherFactory::CreateSymmetricCipherL + (impl, + KDesUid, + *key, + KCryptoModeEncryptUid, // This can be either encrypt or decrypt + KOperationModeECBUid, // Use "electronic code book" mode + KPaddingModeNoneUid, // This is the type of padding to be used + NULL)); + +//Check the return value and for non NULL +if (impl && (err == KErrNone)) + { + //Create a buffer holding the data to be encrypted + TBuf8<8> srcData(_L8("12345678")); + + //Create a buffer to hold the encrypted data. + //MaxFinalOutputLength() returns the number of bytes the buffer passed to ProcessFinalL() + //needs to be capable of holding + TInt maxOutputLength = impl->MaxFinalOutputLength(srcData.Length()); + HBufC8* encrypted = HBufC8::NewLC(maxOutputLength); + TPtr8 encryptedPtr = encrypted->Des(); + + //Perform the encryption operation + //ProcessFinalL() pads the input buffer if required + TRAP(err, impl->ProcessFinalL(srcData, encryptedPtr)); + + if (err == KErrNone) + { + //Switch to decrypt mode + impl->SetCryptoModeL(KCryptoModeDecryptUid); + + //Create a buffer for the decrypted data + maxOutputLength = encryptedPtr.Length(); + HBufC8* output = HBufC8::NewLC(impl->MaxFinalOutputLength(maxOutputLength)); + TPtr8 outputPtr = output->Des(); + + //Perform the decryption operation + TRAP(err, impl->ProcessFinalL(encryptedPtr, outputPtr)); + + if (err == KErrNone) + { + //Check that the original source data matches the data that + //has been encrypted then decrypted + if (!outputPtr.Compare(srcData)) + { + // Descriptors are the same - successful encrypt/decrypt check + } + } + + CleanupStack::PopAndDestroy(output); + } + + CleanupStack::PopAndDestroy(encrypted); + } + +//Destroy the symmetric implementation object +delete impl; +impl = NULL; + +CleanupStack::PopAndDestroy(key); +CleanupStack::PopAndDestroy(params); +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D2DCBC1F-91B8-5F81-AAE8-546AE3EB1E29_d0e324862_href.png Binary file Symbian3/SDK/Source/GUID-D2DCBC1F-91B8-5F81-AAE8-546AE3EB1E29_d0e324862_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D2DCBC1F-91B8-5F81-AAE8-546AE3EB1E29_d0e331019_href.png Binary file Symbian3/SDK/Source/GUID-D2DCBC1F-91B8-5F81-AAE8-546AE3EB1E29_d0e331019_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D37E0579-0F3B-5EE4-8264-1358E493672B.dita --- a/Symbian3/SDK/Source/GUID-D37E0579-0F3B-5EE4-8264-1358E493672B.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-D37E0579-0F3B-5EE4-8264-1358E493672B.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,39 +1,39 @@ - - - - - -Array -of variable length elements, flat bufferDescribes how elements of varying length are organised in the array -buffer. -

                This is a CArrayVarFlat<class T> object whose -elements can have different lengths. Although each element is a class T object, -the length of that object can vary.

                -

                In this type of array, each element occupies its own individual cell allocated -from the heap. The array buffer contains fixed length data structures, one -for each element, which are physically contiguous within the flat array buffer. -Each fixed length data structure contains the length of an element (a TInt value) -and a pointer to it. The structure itself is part of the implementation but -occupies no more than eight bytes on 32-bit machines.

                -

                A flat buffer always occupies a single cell allocated from the heap and -is always extended by the process of reallocation. A flat array buffer is -implemented using a CBufFlat object.

                -

                The following diagram illustrates how elements are organised within the -array buffer:

                - - - -

                This kind of array is suitable for a small number of elements or for a -moderately large but fixed maximum number of elements. It is not suitable -for large arrays with a high turnover of elements.

                -

                This class is immediately derived from the abstract templated base class CArrayVar<class T> which -is itself derived from the abstract non-templated base class CArrayVarBase.

                -
                See also

                Using -Dynamic Buffers.

                + + + + + +Array +of variable length elements, flat bufferDescribes how elements of varying length are organised in the array +buffer. +

                This is a CArrayVarFlat<class T> object whose +elements can have different lengths. Although each element is a class T object, +the length of that object can vary.

                +

                In this type of array, each element occupies its own individual cell allocated +from the heap. The array buffer contains fixed length data structures, one +for each element, which are physically contiguous within the flat array buffer. +Each fixed length data structure contains the length of an element (a TInt value) +and a pointer to it. The structure itself is part of the implementation but +occupies no more than eight bytes on 32-bit machines.

                +

                A flat buffer always occupies a single cell allocated from the heap and +is always extended by the process of reallocation. A flat array buffer is +implemented using a CBufFlat object.

                +

                The following diagram illustrates how elements are organised within the +array buffer:

                + + + +

                This kind of array is suitable for a small number of elements or for a +moderately large but fixed maximum number of elements. It is not suitable +for large arrays with a high turnover of elements.

                +

                This class is immediately derived from the abstract templated base class CArrayVar<class T> which +is itself derived from the abstract non-templated base class CArrayVarBase.

                +
                See also

                Using +Dynamic Buffers.

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D3881E09-4519-5E3F-9978-C9FEFD123B85_d0e366524_href.png Binary file Symbian3/SDK/Source/GUID-D3881E09-4519-5E3F-9978-C9FEFD123B85_d0e366524_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D3881E09-4519-5E3F-9978-C9FEFD123B85_d0e372605_href.png Binary file Symbian3/SDK/Source/GUID-D3881E09-4519-5E3F-9978-C9FEFD123B85_d0e372605_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D3F52BB9-7230-499C-9BB7-CFAEDBA8F48B.dita --- a/Symbian3/SDK/Source/GUID-D3F52BB9-7230-499C-9BB7-CFAEDBA8F48B.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-D3F52BB9-7230-499C-9BB7-CFAEDBA8F48B.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,43 +1,43 @@ - - - - - -Managing -feedback areas -

                Usually control areas (and hence feedback areas) should not overlap. However, -in some cases you may have to define a priority for the feedback areas.

                -

                Consider, for example, situations where a compound control has a simple -control inside its own area as illustrated in the figure below.

                - -Tactile feedback area priorities - - -

                In both situations, the compound control wants to give one type of feedback, -but there should be a different type of feedback (or no feedback at all) for -the simple control. Both controls can register themselves to area registry, -but the problem is making sure that simple control has a higher priority than -the compound control (in the API implementation hit tests are only run as -long as one control with matching area and pointer event type is found).

                -

                You can solve this in two ways:

                  -
                1. By adding the simple control -to area registry after compound control (the last added area always has the -highest priority inside its window).
                  2. -
                2. By using the MoveFeedbackAreaToFirstPriority function for moving -the simple control to first priority.
                  3. -

                -

                In many cases the first option is most natural choice, but you can also -use the second option in case the situation changes after the areas have been -already added to the area registry.

                -

                The priority order will only remain as long as the next area is added -to the registry, that is, moving some area to first priority will only keep -it as the top priority area as long as the next area is added to the registry. -(Registry entries of one window are kept in a stack, and new areas are always -added on top.)

                 + + + + + +Managing +feedback areas +

                Usually control areas (and hence feedback areas) should not overlap. However, +in some cases you may have to define a priority for the feedback areas.

                +

                Consider, for example, situations where a compound control has a simple +control inside its own area as illustrated in the figure below.

                + +Tactile feedback area priorities + + +

                In both situations, the compound control wants to give one type of feedback, +but there should be a different type of feedback (or no feedback at all) for +the simple control. Both controls can register themselves to area registry, +but the problem is making sure that simple control has a higher priority than +the compound control (in the API implementation hit tests are only run as +long as one control with matching area and pointer event type is found).

                +

                You can solve this in two ways:

                  +
                1. By adding the simple control +to area registry after compound control (the last added area always has the +highest priority inside its window).
                  2. +
                2. By using the MoveFeedbackAreaToFirstPriority function for moving +the simple control to first priority.
                  3. +

                +

                In many cases the first option is most natural choice, but you can also +use the second option in case the situation changes after the areas have been +already added to the area registry.

                +

                The priority order will only remain as long as the next area is added +to the registry, that is, moving some area to first priority will only keep +it as the top priority area as long as the next area is added to the registry. +(Registry entries of one window are kept in a stack, and new areas are always +added on top.)

                                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D4001895-09B9-5A47-BEE7-648FAB55F85B.dita --- a/Symbian3/SDK/Source/GUID-D4001895-09B9-5A47-BEE7-648FAB55F85B.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-D4001895-09B9-5A47-BEE7-648FAB55F85B.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,52 +1,52 @@ - - - - - -Introduction -to TransactionsA transaction is a series of operations on a store, normally completed -by committing them using the store's CommitL() function. -

                Transactions are supported by the commit and revert protocol. The series -of operations forming a transaction must all succeed for the transaction to -be successful.

                -

                If a leave occurs during an operation on the store during a transaction, -or if the store's RevertL() function is called explicitly, -the transaction is reverted. This facility parallels the commit and rollback -functions which are conventional in databases. However, reverting is not quite -the same as rolling back; integrity of data is guaranteed, but some indexes -may be corrupted.

                -

                The commit and revert protocol is useful for ensuring that persistent data -moves from one consistent state to another and for guaranteeing the integrity -of persistent store data in the event of failures.

                -

                Typically, changes to a store are not made permanent until they are committed, -establishing what is called a commit point. Until such changes are committed, -they can be rolled back or reverted, effectively causing the store to revert -back to its state before the changes were made. If a process termination or -a media failure occurs, the store reverts automatically to its state at the -last successful commit point.

                -

                In permanent file stores the protocol applies to:

                -
                  -

                • generating new streams

                  • -

                • deleting streams

                  • -

                • creating new streams

                  • -

                • replacing streams

                  • -

                • setting the root stream

                  • -
                -

                The protocol also applies to creating new streams or replacing existing -streams in dictionary stores.

                -

                The protocol does not apply to overwriting existing streams.

                -

                The following diagram shows the idea:

                - -Transaction Commit and Revert - - -                 -Dictionary -stores + + + + + +Introduction +to TransactionsA transaction is a series of operations on a store, normally completed +by committing them using the store's CommitL() function. +

                Transactions are supported by the commit and revert protocol. The series +of operations forming a transaction must all succeed for the transaction to +be successful.

                +

                If a leave occurs during an operation on the store during a transaction, +or if the store's RevertL() function is called explicitly, +the transaction is reverted. This facility parallels the commit and rollback +functions which are conventional in databases. However, reverting is not quite +the same as rolling back; integrity of data is guaranteed, but some indexes +may be corrupted.

                +

                The commit and revert protocol is useful for ensuring that persistent data +moves from one consistent state to another and for guaranteeing the integrity +of persistent store data in the event of failures.

                +

                Typically, changes to a store are not made permanent until they are committed, +establishing what is called a commit point. Until such changes are committed, +they can be rolled back or reverted, effectively causing the store to revert +back to its state before the changes were made. If a process termination or +a media failure occurs, the store reverts automatically to its state at the +last successful commit point.

                +

                In permanent file stores the protocol applies to:

                +
                  +

                • generating new streams

                  • +

                • deleting streams

                  • +

                • creating new streams

                  • +

                • replacing streams

                  • +

                • setting the root stream

                  • +
                +

                The protocol also applies to creating new streams or replacing existing +streams in dictionary stores.

                +

                The protocol does not apply to overwriting existing streams.

                +

                The following diagram shows the idea:

                + +Transaction Commit and Revert + + +                 +Dictionary +stores                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D458A54E-0D19-479C-B628-001C704E1CB3.dita --- a/Symbian3/SDK/Source/GUID-D458A54E-0D19-479C-B628-001C704E1CB3.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,19 +0,0 @@ - - - - - -Navigation -using links -

                Links leading from one application (or the Idle state) to another application -may exist. Links are one-way shortcuts: there is no direct path back to the -state where the link was started; instead, the navigation inside the linked -application functions as if the user had manually activated the other application -and navigated to the target state.

                -                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D45A4AE9-4169-4466-B02B-629B15C3E9AA.dita --- a/Symbian3/SDK/Source/GUID-D45A4AE9-4169-4466-B02B-629B15C3E9AA.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-D45A4AE9-4169-4466-B02B-629B15C3E9AA.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,52 +1,52 @@ - - - - - -MakeKeys -TutorialThe MakeKeys tool is a PC-side stand-alone tool that helps you -to create a private key-public key pair and generate certificate requests. -

                The following diagram illustrates the procedure for creating -a private key, self-signed certificate and a certificate request file.

                - -                 - -Creating -a private key and self signed certificate - -Generating -a certificate request - -Viewing -certificate details - - -
                  -

                • The private key can be specified as an argument while signing an installation -file using the SignSIS tool. For details, see SignSIS.

                  • -

                • Symbian developer must send the certificate request to a trusted third -party, that is, a Certificate Authority (CA) for signing.

                  The CA verifies -the identity of the originator of the certificate request. After verification, -the CA signs the public key (contained in the certificate request) using the -CA's private key and creates a signed certificate. This signed certificate -is then sent back to the applicant.

                  The CA can return a single certificate -or a file containing a chain of certificates. This includes intermediate certificates -in addition to the CA's root certificate and the Symbian developer certificate. -

                  Certificates returned by CA must be in the base64 -encoded ASCII format.
                  • -

                • The digital certificate returned by the CA must be bundled with the -installation file to allow the digital signature to be verified. The self-signed -certificate can then be discarded.

                  • -
                 -                 -MakeKeys -Overview -MakeKeys -Reference + + + + + +MakeKeys +TutorialThe MakeKeys tool is a PC-side stand-alone tool that helps you +to create a private key-public key pair and generate certificate requests. +

                The following diagram illustrates the procedure for creating +a private key, self-signed certificate and a certificate request file.

                + +                 + +Creating +a private key and self signed certificate + +Generating +a certificate request + +Viewing +certificate details + + +
                  +

                • The private key can be specified as an argument while signing an installation +file using the SignSIS tool. For details, see SignSIS.

                  • +

                • Symbian developer must send the certificate request to a trusted third +party, that is, a Certificate Authority (CA) for signing.

                  The CA verifies +the identity of the originator of the certificate request. After verification, +the CA signs the public key (contained in the certificate request) using the +CA's private key and creates a signed certificate. This signed certificate +is then sent back to the applicant.

                  The CA can return a single certificate +or a file containing a chain of certificates. This includes intermediate certificates +in addition to the CA's root certificate and the Symbian developer certificate. +

                  Certificates returned by CA must be in the base64 +encoded ASCII format.
                  • +

                • The digital certificate returned by the CA must be bundled with the +installation file to allow the digital signature to be verified. The self-signed +certificate can then be discarded.

                  • +
                 +                 +MakeKeys +Overview +MakeKeys +Reference                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D492CF6C-F889-4299-AC75-951EF343AC9F_d0e4703_href.png Binary file Symbian3/SDK/Source/GUID-D492CF6C-F889-4299-AC75-951EF343AC9F_d0e4703_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D492CF6C-F889-4299-AC75-951EF343AC9F_d0e5978_href.png Binary file Symbian3/SDK/Source/GUID-D492CF6C-F889-4299-AC75-951EF343AC9F_d0e5978_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D4AA635F-DF24-541A-A452-192DDBEE4142.dita --- a/Symbian3/SDK/Source/GUID-D4AA635F-DF24-541A-A452-192DDBEE4142.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-D4AA635F-DF24-541A-A452-192DDBEE4142.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,14 +1,14 @@ - - - - - -Processes and Data Flow

                The following figure shows the processes and data flow in the Messaging subsystem on a secured Symbian platform.

                - Processes and dataflow in the Messaging subsystem -                 \ No newline at end of file + + + + + +Processes and Data Flow

                The following figure shows the processes and data flow in the Messaging subsystem on a secured Symbian platform.

                + Processes and dataflow in the Messaging subsystem +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D52E98C3-F5EE-4CE1-A4F5-2EF41A066B8A.dita --- a/Symbian3/SDK/Source/GUID-D52E98C3-F5EE-4CE1-A4F5-2EF41A066B8A.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-D52E98C3-F5EE-4CE1-A4F5-2EF41A066B8A.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,76 +1,76 @@ - - - - - -Creating -resource header files -

                Typically when you create an application, there are cases where you -need to create an enumerated set of command IDs (which are symbols with integer -values). These defined symbols can then be used in both your code and resource -files. Common examples of these cases, include:

                -
                  -

                • Custom command IDs used for mapping mobile device user input -based upon Options menu selections to command handling. -These custom command IDs are mapped to the text displayed for the command -in the Options menu in resource files, and then are passed -back to the application by the application framework.

                  • -

                • Control IDs in dialogs to allow references to the dialog -controls from C++ code.

                  - -

                  For more information on control IDs for dialogs, see Using -Dialogs API.

                  -                   -
                  • -

                • Application view IDs. Note that these could also be enumerated -in the header files for the views.

                  • -

                • IDs for other resource structures, such as for TABS in -the status pane.

                  • -
                -

                These enumerated values need to be defined in a resource file, which -by convention has the extension hrh, The syntax is as -follows:

                -enum TCommandIds - { - ECmdAppTest1 = 1, - ECmdView1Cmd1, - ECmdView1Cmd2, - ECmdView1Cmd3, - ECmdView2Cmd1, - ECmdView2Cmd2, - ECmdView2Cmd3, - ECmdView2Cmd4 - }; -

                where

                -
                  -

                • enum is the keyword declaration the -set of integer values.

                  - -

                  Use this keyword for each set of enumerated values you defined.

                  -                   -
                  • -

                • TCommandIds is a label for the list -of enumerated values. This label is not used in the code or resource files.

                  -
                  • -

                • ECmdAppTest1 is a symbol that can be -used in your code or resource files.

                  • -

                • = is the operator used for setting the -value to the symbol.

                  • -

                • 1 is the specific value assigned to -the enumerator symbol.

                  • -
                -

                Each enumerator is followed by a comma (,) except for -the last value. It is recommended to have a final semi colon (;) -after the enumerated list. If a specific value is not assigned to a symbol -in the enumerated list, then the value is that of the previous enumerator -plus one. Thus, the value for ECmdView1Cmd1 above is -2.

                -

                For more information about the use of the enum statement, -see ENUM statement.

                + + + + + +Creating +resource header files +

                Typically when you create an application, there are cases where you +need to create an enumerated set of command IDs (which are symbols with integer +values). These defined symbols can then be used in both your code and resource +files. Common examples of these cases, include:

                +
                  +

                • Custom command IDs used for mapping mobile device user input +based upon Options menu selections to command handling. +These custom command IDs are mapped to the text displayed for the command +in the Options menu in resource files, and then are passed +back to the application by the application framework.

                  • +

                • Control IDs in dialogs to allow references to the dialog +controls from C++ code.

                  + +

                  For more information on control IDs for dialogs, see Using +Dialogs API.

                  +                   +
                  • +

                • Application view IDs. Note that these could also be enumerated +in the header files for the views.

                  • +

                • IDs for other resource structures, such as for TABS in +the status pane.

                  • +
                +

                These enumerated values need to be defined in a resource file, which +by convention has the extension hrh, The syntax is as +follows:

                +enum TCommandIds + { + ECmdAppTest1 = 1, + ECmdView1Cmd1, + ECmdView1Cmd2, + ECmdView1Cmd3, + ECmdView2Cmd1, + ECmdView2Cmd2, + ECmdView2Cmd3, + ECmdView2Cmd4 + }; +

                where

                +
                  +

                • enum is the keyword declaration the +set of integer values.

                  + +

                  Use this keyword for each set of enumerated values you defined.

                  +                   +
                  • +

                • TCommandIds is a label for the list +of enumerated values. This label is not used in the code or resource files.

                  +
                  • +

                • ECmdAppTest1 is a symbol that can be +used in your code or resource files.

                  • +

                • = is the operator used for setting the +value to the symbol.

                  • +

                • 1 is the specific value assigned to +the enumerator symbol.

                  • +
                +

                Each enumerator is followed by a comma (,) except for +the last value. It is recommended to have a final semi colon (;) +after the enumerated list. If a specific value is not assigned to a symbol +in the enumerated list, then the value is that of the previous enumerator +plus one. Thus, the value for ECmdView1Cmd1 above is +2.

                +

                For more information about the use of the enum statement, +see ENUM statement.

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D53A00E4-CF37-5F11-8D15-C5ECCCE64597.dita --- a/Symbian3/SDK/Source/GUID-D53A00E4-CF37-5F11-8D15-C5ECCCE64597.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-D53A00E4-CF37-5F11-8D15-C5ECCCE64597.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,92 +1,92 @@ - - - - - -Vibra -APIVibra API provides the functionality to control the device -vibra, which is accessed using the CHWRMVibra instance. It -also provides methods to retrieve the current settings of the vibration feature -in the user profile and the current status of the vibra. It uses synchronous -method calls which block the client application until a response is received -from the plug-in.

                Vibra API also allows the client to request -for tactile vibration feedback.

                -

                The API consists of CHWRMVibra,MHWRMVibraObserver and MHWRMVibraFeedbackObserver classes.

                -

                It provides the following fields:

                - - - - -

                Fields

                -

                Values

                -

                Descriptions

                -                 - - - - -

                KHWRMVibraMinIntensity

                -

                -100

                -

                Minimum allowed intensity setting for vibra.

                -                 - -

                KHWRMVibraMinPulseIntensity

                -

                1

                 -

                Minimum allowed intensity setting for vibra pulse.

                -                 - -

                KHWRMVibraMaxIntensity

                -

                100

                 -

                Maximum allowed intensity setting for vibra.

                -                 - -

                KHWRMVibraMaxDuration

                -

                (KMaxTInt/1000)-1

                -

                Maximum allowed duration value in milliseconds.

                -                 - -

                KHWRMVibraInfiniteDuration

                -

                0

                 -

                Specifies that vibrating must continue for maximum vibrating time -supported by device if vibrating is not explicitly stopped.

                -                 - - -
                -
                Observer

                A separate callback interface MHWRMVibraObserver for status reporting is also -used. The client creates an instance of CHWRMVibra using NewL(). If the client requires the status information, -it must provide a callback pointer of the MHWRMVibraObserver implementing -class for the NewL() method.

                - Vibra API Interfaces - -
                -
                Tactile vibration feedback

                Tactile vibration is -used in many touch screen devices to provide vibration feedback to the user -through display surface.

                The clients can specify the intensity and -duration of the feedback pulse, and receive notifications when the tactile -feedback settings changes in the user profile through MHWRMVibraFeedbackObserver class.

                Note: The tactile feedback functionality is only available to the clients configured -at the firmware build time (Symbian platform licensees).

                -Definitions - - - -

                Vibra frozen state

                -

                Whenever vibra is released, its current state is stored as frozen -state. On next reserve, the user can specify that the frozen state be restored.

                -                 - -

                Vibra virtual state

                -

                Reserves the specified resource. If reservation is not suspended, -then actual vibra is also set to the same state. If reservation is suspended, -actual vibra is not affected by any control methods.

                 -                 - - -
                + + + + + +Vibra +APIVibra API provides the functionality to control the device +vibra, which is accessed using the CHWRMVibra instance. It +also provides methods to retrieve the current settings of the vibration feature +in the user profile and the current status of the vibra. It uses synchronous +method calls which block the client application until a response is received +from the plug-in.

                Vibra API also allows the client to request +for tactile vibration feedback.

                +

                The API consists of CHWRMVibra,MHWRMVibraObserver and MHWRMVibraFeedbackObserver classes.

                +

                It provides the following fields:

                + + + + +

                Fields

                +

                Values

                +

                Descriptions

                +                 + + + + +

                KHWRMVibraMinIntensity

                +

                -100

                +

                Minimum allowed intensity setting for vibra.

                +                 + +

                KHWRMVibraMinPulseIntensity

                +

                1

                 +

                Minimum allowed intensity setting for vibra pulse.

                +                 + +

                KHWRMVibraMaxIntensity

                +

                100

                 +

                Maximum allowed intensity setting for vibra.

                +                 + +

                KHWRMVibraMaxDuration

                +

                (KMaxTInt/1000)-1

                +

                Maximum allowed duration value in milliseconds.

                +                 + +

                KHWRMVibraInfiniteDuration

                +

                0

                 +

                Specifies that vibrating must continue for maximum vibrating time +supported by device if vibrating is not explicitly stopped.

                +                 + + +
                +
                Observer

                A separate callback interface MHWRMVibraObserver for status reporting is also +used. The client creates an instance of CHWRMVibra using NewL(). If the client requires the status information, +it must provide a callback pointer of the MHWRMVibraObserver implementing +class for the NewL() method.

                + Vibra API Interfaces + +
                +
                Tactile vibration feedback

                Tactile vibration is +used in many touch screen devices to provide vibration feedback to the user +through display surface.

                The clients can specify the intensity and +duration of the feedback pulse, and receive notifications when the tactile +feedback settings changes in the user profile through MHWRMVibraFeedbackObserver class.

                Note: The tactile feedback functionality is only available to the clients configured +at the firmware build time (Symbian platform licensees).

                +Definitions + + + +

                Vibra frozen state

                +

                Whenever vibra is released, its current state is stored as frozen +state. On next reserve, the user can specify that the frozen state be restored.

                +                 + +

                Vibra virtual state

                +

                Reserves the specified resource. If reservation is not suspended, +then actual vibra is also set to the same state. If reservation is suspended, +actual vibra is not affected by any control methods.

                 +                 + + +
                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D5A05EE7-5559-55CC-A839-478B4F513CE4_d0e204270_href.png Binary file Symbian3/SDK/Source/GUID-D5A05EE7-5559-55CC-A839-478B4F513CE4_d0e204270_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D5A05EE7-5559-55CC-A839-478B4F513CE4_d0e209278_href.png Binary file Symbian3/SDK/Source/GUID-D5A05EE7-5559-55CC-A839-478B4F513CE4_d0e209278_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D5A6A5C9-A959-5CE7-AF45-43DA7D8B2EFF.dita --- a/Symbian3/SDK/Source/GUID-D5A6A5C9-A959-5CE7-AF45-43DA7D8B2EFF.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-D5A6A5C9-A959-5CE7-AF45-43DA7D8B2EFF.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,16 +1,16 @@ - - - - - -Introduction to Pictures

                A picture is an object which can be drawn to a graphics context and can be stored and restored. A picture is stored, together with its picture header, in any type of store using a storemap.

                - Relationship between picture headers and pictures in a store -

                A picture can thus be any object which draws an image — be it a bitmap or a set of graphic commands.

                Additionally, two common desirable facilities for a picture to have are:

                • the ability to be cropped

                • the ability to be scaled

                Scaling can be done in one of three ways:

                • by specifying percentage scale factors for the width and height

                • by specifying the picture size in pixels

                • by specifying the picture size in twips

                Cropping can be done in two ways:

                • by specifying a set of margins in twips

                • by specifying a further set of margins in pixels, for additional cropping

                The drawing operation positions and draws the scaled and cropped picture on the graphics device.

                - The relationships between the picture classes -                 Picture Concepts Picture Tutorials                 \ No newline at end of file + + + + + +Introduction to Pictures

                A picture is an object which can be drawn to a graphics context and can be stored and restored. A picture is stored, together with its picture header, in any type of store using a storemap.

                + Relationship between picture headers and pictures in a store +

                A picture can thus be any object which draws an image — be it a bitmap or a set of graphic commands.

                Additionally, two common desirable facilities for a picture to have are:

                • the ability to be cropped

                • the ability to be scaled

                Scaling can be done in one of three ways:

                • by specifying percentage scale factors for the width and height

                • by specifying the picture size in pixels

                • by specifying the picture size in twips

                Cropping can be done in two ways:

                • by specifying a set of margins in twips

                • by specifying a further set of margins in pixels, for additional cropping

                The drawing operation positions and draws the scaled and cropped picture on the graphics device.

                + The relationships between the picture classes +                 Picture Concepts Picture Tutorials                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D62A0234-348C-5553-B8C0-7B483AF9D50C.dita --- a/Symbian3/SDK/Source/GUID-D62A0234-348C-5553-B8C0-7B483AF9D50C.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-D62A0234-348C-5553-B8C0-7B483AF9D50C.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,55 +1,55 @@ - - - - - -Thread-relative -and Process-relative handlesThis document describes the difference between thread-relative -and process-relative handles. -

                This is the issue of handle ownership.

                -

                Threads and processes each maintain a list of objects to which they refer. -This list is an object index and is the way in which handle-numbers representing -these objects are generated.

                -

                When user code causes a Kernel object (e.g. a mutex) to be created, ownership -of the handle which is opened on that object may be vested either in the thread -or the process. If ownership is vested in the thread, the handle associated -with that object is said to be thread-relative, conversely, if ownership -is vested in the process, the handle associated with that object is said to -beprocess-relative.

                -

                The following diagram shows the case where code belonging to thread A creates -a mutex and vests ownership of the handle in the thread.

                - -Thread-relative handle - - -

                Compare with the following case where ownership of the mutex handle is -vested in the process.

                - -Process-relative handle - - -

                In both cases, the mutex object is added to the appropriate Kernel container -which can be considered as the owner of the object.

                -

                The significance of a process-relative handle is that any thread in the -process can use that handle to access the Kernel side object that the handle -represents. In contrast, a thread-relative handle can only be used by the -thread creating it; other threads in that process can only access the Kernel -side object by duplicating that -handle.

                -

                For a thread-relative handle, the associated Kernel side object is closed -if the thread dies. For a process-relative handle, the Kernel side object -is closed if the process dies. Such an object is not closed if any thread -belonging to that process dies; the object remains in existence for the lifetime -of the process, or until all references to it have been explicitly closed.

                -

                See also:

                -
                  -

                • The -object index

                  • -
                + + + + + +Thread-relative +and Process-relative handlesThis document describes the difference between thread-relative +and process-relative handles. +

                This is the issue of handle ownership.

                +

                Threads and processes each maintain a list of objects to which they refer. +This list is an object index and is the way in which handle-numbers representing +these objects are generated.

                +

                When user code causes a Kernel object (e.g. a mutex) to be created, ownership +of the handle which is opened on that object may be vested either in the thread +or the process. If ownership is vested in the thread, the handle associated +with that object is said to be thread-relative, conversely, if ownership +is vested in the process, the handle associated with that object is said to +beprocess-relative.

                +

                The following diagram shows the case where code belonging to thread A creates +a mutex and vests ownership of the handle in the thread.

                + +Thread-relative handle + + +

                Compare with the following case where ownership of the mutex handle is +vested in the process.

                + +Process-relative handle + + +

                In both cases, the mutex object is added to the appropriate Kernel container +which can be considered as the owner of the object.

                +

                The significance of a process-relative handle is that any thread in the +process can use that handle to access the Kernel side object that the handle +represents. In contrast, a thread-relative handle can only be used by the +thread creating it; other threads in that process can only access the Kernel +side object by duplicating that +handle.

                +

                For a thread-relative handle, the associated Kernel side object is closed +if the thread dies. For a process-relative handle, the Kernel side object +is closed if the process dies. Such an object is not closed if any thread +belonging to that process dies; the object remains in existence for the lifetime +of the process, or until all references to it have been explicitly closed.

                +

                See also:

                +
                  +

                • The +object index

                  • +
                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D62A282E-9DEA-5EF3-A606-20647BC5049D.dita --- a/Symbian3/SDK/Source/GUID-D62A282E-9DEA-5EF3-A606-20647BC5049D.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-D62A282E-9DEA-5EF3-A606-20647BC5049D.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,14 +1,14 @@ - - - - - -Audio Client Overview

                This document provides an overview of the Audio Client.

                Purpose

                The Audio Client provides an interface to:

                • Play back, record, and convert sound clips.

                • Play tone sequences and DTMF (Dual-Tone Multi-Frequency) strings.

                Audio Client Library Details

                The DLL that provides the functionality and the library to which your code must link is identified below.

                DLL LIB Short Description

                mediaclientaudio.dll

                mediaclientaudio.lib

                These files are used for implementing the Audio Client.

                Architectural Relationship

                The methods for recording, converting, and playing audio clips or tones interact with the lower levels of MMF (known as the controller framework). The controller framework is in turn responsible for managing the interface to audio hardware. On some phones, this is implemented as a device driver; on others it may be implemented as a connection to a lower level hardware controller.

                Clients using any of the CMdaAudioRecorderUtility, CMdaAudioConvertUtility, CMdaAudioPlayerUtility or CMdaAudioToneUtility classes must have an active scheduler running in their thread because the implementations use active objects and callbacks.

                How the tone player class interacts with other components of MMF is shown below.

                - Audio tone player overview -
                Description

                Audio Playing, Recording, and Conversion

                All three of the audio classes are plugin based, leaving the list of supported audio formats for input and output open ended. The audio file formats supported as standard by MMF are: AU, WAV and raw audio data. Each file format may support one or more compression algorithms (codecs). The standard file formats and corresponding codecs are shown below:

                Audio file format Codecs supported

                AU

                A-Law, mu-law, signed 16 bit PCM big-endian, signed 8 bit PCM

                WAV

                IMA-ADPCM, A-Law, mu-law, unsigned 8 bit PCM, gsm 6.10, signed 16 bit PCM

                raw data

                Signed big-endian 16 bit PCM, signed 16 bit PCM, unsigned 16 bit PCM

                Input and output audio data can be of any format supported by the installed plugins. When possible MMF uses a plugin resolver to determine the format and codecs to use. It determines this by checking the filename extension and reading any header data that may be present in the audio clip. The plugin resolver cannot determine the format and codecs to use for raw audio, so in such cases you must specify this information yourself. A full list of supported plugins can be retrieved by using CMdaAudioConvertUtility::GetSupportedDestinationDataTypesL().

                Note: All audio clips can be uniquely identified for purposes of plugin assignment by their format (gsm z6.10, AU, WAV and so on) and their codec (for example for AU, valid codecs include A-Law, mu-law, signed 16 bit PCM big-endian, signed 8 bit PCM). Each format and codec has an arbitrary ID assigned to it by MMF and its associated plugin, for use with the "Open" functions of both CMdaAudioConvertUtility and CMdaAudioRecorderUtility.

                Tone Playing

                The Audio Client provide a simple interface for tone generation (synthesized sounds) that enables the playing of tone sequences and DTMF (Dual-Tone Multi-Frequency) strings. The tone player functionality is provided by the CMdaAudioToneUtility class and using this class you can play:

                • Single tones of a specified duration and frequency.

                • DTMF strings.

                • Sequences of tones held in files or descriptors.

                • Predefined (fixed) sequences of tones held in the mobile equipment.

                Key Audio Client Classes

                The functionality provided by the Audio Client is contained within the following classes:

                • CMdaAudioRecorderUtility

                • CMdaAudioConvertUtility

                • CMdaAudioPlayerUtility

                • CMdaAudioToneUtility

                Using the Audio Client

                Clients can use the Audio Client to:

                • Manipulate audio sources and sinks, add, retrieve and modify meta data and record audio data to files or descriptors.

                • Convert audio clips contained in files or descriptors to other formats using the default codecs provided by MMF.

                • Play audio clips contained in files, descriptors or URLs.

                • Play single tones, DTMF strings and tone sequences.

                See Also

                How to use the audio convert utility

                How to use the audio player utility

                How to use audio recorder utility

                How to use the audio tone player utility

                DevSound Overview

                \ No newline at end of file + + + + + +Audio Client Overview

                This document provides an overview of the Audio Client.

                Purpose

                The Audio Client provides an interface to:

                • Play back, record, and convert sound clips.

                • Play tone sequences and DTMF (Dual-Tone Multi-Frequency) strings.

                Audio Client Library Details

                The DLL that provides the functionality and the library to which your code must link is identified below.

                DLL LIB Short Description

                mediaclientaudio.dll

                mediaclientaudio.lib

                These files are used for implementing the Audio Client.

                Architectural Relationship

                The methods for recording, converting, and playing audio clips or tones interact with the lower levels of MMF (known as the controller framework). The controller framework is in turn responsible for managing the interface to audio hardware. On some phones, this is implemented as a device driver; on others it may be implemented as a connection to a lower level hardware controller.

                Clients using any of the CMdaAudioRecorderUtility, CMdaAudioConvertUtility, CMdaAudioPlayerUtility or CMdaAudioToneUtility classes must have an active scheduler running in their thread because the implementations use active objects and callbacks.

                How the tone player class interacts with other components of MMF is shown below.

                + Audio tone player overview +
                Description

                Audio Playing, Recording, and Conversion

                All three of the audio classes are plugin based, leaving the list of supported audio formats for input and output open ended. The audio file formats supported as standard by MMF are: AU, WAV and raw audio data. Each file format may support one or more compression algorithms (codecs). The standard file formats and corresponding codecs are shown below:

                Audio file format Codecs supported

                AU

                A-Law, mu-law, signed 16 bit PCM big-endian, signed 8 bit PCM

                WAV

                IMA-ADPCM, A-Law, mu-law, unsigned 8 bit PCM, gsm 6.10, signed 16 bit PCM

                raw data

                Signed big-endian 16 bit PCM, signed 16 bit PCM, unsigned 16 bit PCM

                Input and output audio data can be of any format supported by the installed plugins. When possible MMF uses a plugin resolver to determine the format and codecs to use. It determines this by checking the filename extension and reading any header data that may be present in the audio clip. The plugin resolver cannot determine the format and codecs to use for raw audio, so in such cases you must specify this information yourself. A full list of supported plugins can be retrieved by using CMdaAudioConvertUtility::GetSupportedDestinationDataTypesL().

                Note: All audio clips can be uniquely identified for purposes of plugin assignment by their format (gsm z6.10, AU, WAV and so on) and their codec (for example for AU, valid codecs include A-Law, mu-law, signed 16 bit PCM big-endian, signed 8 bit PCM). Each format and codec has an arbitrary ID assigned to it by MMF and its associated plugin, for use with the "Open" functions of both CMdaAudioConvertUtility and CMdaAudioRecorderUtility.

                Tone Playing

                The Audio Client provide a simple interface for tone generation (synthesized sounds) that enables the playing of tone sequences and DTMF (Dual-Tone Multi-Frequency) strings. The tone player functionality is provided by the CMdaAudioToneUtility class and using this class you can play:

                • Single tones of a specified duration and frequency.

                • DTMF strings.

                • Sequences of tones held in files or descriptors.

                • Predefined (fixed) sequences of tones held in the mobile equipment.

                Key Audio Client Classes

                The functionality provided by the Audio Client is contained within the following classes:

                • CMdaAudioRecorderUtility

                • CMdaAudioConvertUtility

                • CMdaAudioPlayerUtility

                • CMdaAudioToneUtility

                Using the Audio Client

                Clients can use the Audio Client to:

                • Manipulate audio sources and sinks, add, retrieve and modify meta data and record audio data to files or descriptors.

                • Convert audio clips contained in files or descriptors to other formats using the default codecs provided by MMF.

                • Play audio clips contained in files, descriptors or URLs.

                • Play single tones, DTMF strings and tone sequences.

                See Also

                How to use the audio convert utility

                How to use the audio player utility

                How to use audio recorder utility

                How to use the audio tone player utility

                DevSound Overview

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D65D1EDC-5CB4-58C1-99B5-4495B6DA511F-GENID-1-8-1-3-1-1-8-1-5-1.dita --- a/Symbian3/SDK/Source/GUID-D65D1EDC-5CB4-58C1-99B5-4495B6DA511F-GENID-1-8-1-3-1-1-8-1-5-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,192 +0,0 @@ - - - - - -Text resource -utility overview -
                Purpose

                Text -Resource Utility is part of the Symbian Text Utilities. It is an API class, -which provides static methods for loading and formatting resource strings. -The purpose of Text Resource Utility is to make localization of the software -easier by allowing variable order in indexing of the key strings in the resource -string.

                Text Resource Utility provides resource string loading and -formatting methods for other subsystems. Through simple Load() and Format() operation -calls, the user can access resource strings which may contain formatting parameters -(%U for text or %N for numerical). Strings -can contain multiple instances of the same parameter. The 0x0001 character -has special meaning in strings; it is used to delimit different options for -displayable string. The client of TulTextResourceUtils is -responsible for choosing the proper string to display from given options.

                -
                Architectural -Relationships

                The implementation requires a CCoeEnv instance -(given as reference by the user or CCoeEnv::Static) -to access the resource files.

                All interface methods are static, so -there is no need to explicitly allocate memory for the interface class. All -functionality is accessed through exported methods of the TulTextResourceUtils class.

                The -interface is accessed through the tultextresourceutils.h header -file. Binaries are linked to the etul.dll library.

                -
                Description

                Usage

                Applications -load and format resource strings from normal resources with static methods -of the TulTextResourceUtils class. -The loading is done with the LoadL() and LoadLC() methods -and with the Load() method in situations where memory allocation -from the heap is not possible. Formatting is done automatically after loading -in the LoadL() and LoadLC() methods, but -it can also be done separately with the Format() method -in situations where memory allocation from the heap is not possible.

                For -reading the resource strings with the Load(), LoadL() and LoadLC() methods, -the user should provide a pointer to CCoeEnv for -efficiency reasons. If the pointer is not provided, the implementation uses -the CCoeEnv::Static method -internally to get it. The user can get a pointer to CCoeEnv, -for example, via the iEikonEnv macro (for which see <eikdef.h>).

                Scalable -UI Support

                Different size displays can handle different length -strings. To take full advantage of this fact, TulTextResourceUtils supports -resource strings with multiple options for string separated by 0x0001 character. -Each such string can contain same or different sub string keys (%U and %N). TulTextResourceUtils returns all strings, -it is the responsibility of the caller to parse the result and choose the -proper string to display.

                Setting the Maximum Substring Length

                This -may be done in the text resources. Sub string maximum lengths can be localized -separately for every language.

                The maximum sub string length is of -the format:

                %U[NN]

                where NN is -a number [01..99]. Please note that NN must -always consist of two characters, in other words, if the sub string maximum -length is eight characters, the value to be used is 08, not -plain 8.

                If the number of characters exceeds the -maximum length, the sub string is cut to fit and the last character is replaced -with an ellipsis character.

                Error Handling

                The leave -mechanism is used to handle memory exhaustion. Errors in application programming -are handled with the panic mechanism. The error codes used are as follows:

                - - - -

                ETooFewArguments

                -

                = 0: Unsolved parameters in the resource string.

                -                 - -

                ETooManyArguments

                -

                = 1: Already solved all parameters in the resource string.

                -                 - -

                EKeyStringNotFound

                -

                = 2: The key string was not found in formatting.

                -                 - -

                EInvalidIndex

                -

                = 3: Invalid index in the Format method.

                -                 - -

                EDescriptorTooSmall

                -

                = 4: Too small destination descriptor.

                -                 - -

                ECCoeEnvNotInitialized

                -

                = 5: CCoeEnv not initialized.

                -                 - -

                EInvalidSubstitute

                -

                = 6: Substituted string contains substring separator (i.e. 0x0001).

                -                 - - -

                Example

                The following example describes the usage -of the Text Resource Utility component:

                /* Using examples: */ - -#include <tultextresourceutils.h> - -// Get CCoeEnv instance -CEikonEnv* iEikonEnv = CEikonEnv::Static(); - -/* -* One TInt to add: -*/ - -//(In .loc -file) -#define TEXT_EXAMPLE "You have %N undone tasks." - -//(In .rss -file) -RESOURCE TBUF R_TEXT_EXAMPLE { buf = TEXT_EXAMPLE; } - -//(In the .cpp -file) -TInt number( 324 ); - -// -//iEikonEnv is needed for loading the resource string. -// -HBufC* stringholder = TulTextResourceUtils::LoadL( R_TEXT_EXAMPLE, number, iEikonEnv ); - -// -//The TInt in number is added to the resource string. The result is -//that stringholder points to a heap descriptor containing string: -//"You have 324 undone tasks." -// - -/* -* Several strings to add: -*/ - -//(In a .loc -file) -#define TEXT_EXAMPLE "I'm %2U%1U %3U%0U fine." - -//(In an .rss -file) -RESOURCE TBUF R_TEXT_EXAMPLE { buf = TEXT_EXAMPLE; } - -//(In the .cpp -file) -CDesCArrayFlat* strings = new CDesCArrayFlat( 4 ); -CleanupStack::PushL( strings ); - -strings->AppendL( _L("orking") ); //First string - -strings->AppendL( _L("ll") ); //Second string - -strings->AppendL( _L("sti") ); //Third string - -strings->AppendL( _L("w") ); //Fourth string - -// -//iEikonEnv is needed for loading the resource string. -// -HBufC* stringholder = TulTextResourceUtils::LoadL( R_TEXT_EXAMPLE, *strings, iEikonEnv ); - -// -//The strings in strings are added to the resource string. The result is -//that stringholder points to a heap descriptor containing string: -//"I'm still working fine." -// - -/* -* Scalable UI support -*/ -//(In .loc -file) -#define TEXT_EXAMPLE "You have missed %N messages from %U."<0x0001>"Missed %N msgs from %U."<0x0001>"Missed %N msgs." - -//(In .rss -file) -RESOURCE TBUF R_TEXT_EXAMPLE { buf = TEXT_EXAMPLE; } - -//(In the .cpp -file) -TInt number( 12 ); -_LIT(name, “John Doe”); - -// -//iEikonEnv is needed for loading the resource string. -// -HBufC* stringholder = TulTextResourceUtils::LoadL(R_TEXT_EXAMPLE,name,number,iEikonEnv); - -// -//The number and name are added to the resource string. The result is -//that stringholder points to a heap descriptor containing string: -//"You have missed 12 messages from John Doe.\001Missed 12 msgs from John -// Doe.\001Missed 12 msgs." -// - -CleanupStack::PopAndDestroy(); //strings -

                For more information on individual methods, please see the -reference API for TulTextResourceUtils.

                -                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D65D1EDC-5CB4-58C1-99B5-4495B6DA511F-GENID-1-8-1-6-1-1-4-1-7-1-5-1.dita --- a/Symbian3/SDK/Source/GUID-D65D1EDC-5CB4-58C1-99B5-4495B6DA511F-GENID-1-8-1-6-1-1-4-1-7-1-5-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,192 +0,0 @@ - - - - - -Text resource -utility overview -
                Purpose

                Text -Resource Utility is part of the Symbian Text Utilities. It is an API class, -which provides static methods for loading and formatting resource strings. -The purpose of Text Resource Utility is to make localization of the software -easier by allowing variable order in indexing of the key strings in the resource -string.

                Text Resource Utility provides resource string loading and -formatting methods for other subsystems. Through simple Load() and Format() operation -calls, the user can access resource strings which may contain formatting parameters -(%U for text or %N for numerical). Strings -can contain multiple instances of the same parameter. The 0x0001 character -has special meaning in strings; it is used to delimit different options for -displayable string. The client of TulTextResourceUtils is -responsible for choosing the proper string to display from given options.

                -
                Architectural -Relationships

                The implementation requires a CCoeEnv instance -(given as reference by the user or CCoeEnv::Static) -to access the resource files.

                All interface methods are static, so -there is no need to explicitly allocate memory for the interface class. All -functionality is accessed through exported methods of the TulTextResourceUtils class.

                The -interface is accessed through the tultextresourceutils.h header -file. Binaries are linked to the etul.dll library.

                -
                Description

                Usage

                Applications -load and format resource strings from normal resources with static methods -of the TulTextResourceUtils class. -The loading is done with the LoadL() and LoadLC() methods -and with the Load() method in situations where memory allocation -from the heap is not possible. Formatting is done automatically after loading -in the LoadL() and LoadLC() methods, but -it can also be done separately with the Format() method -in situations where memory allocation from the heap is not possible.

                For -reading the resource strings with the Load(), LoadL() and LoadLC() methods, -the user should provide a pointer to CCoeEnv for -efficiency reasons. If the pointer is not provided, the implementation uses -the CCoeEnv::Static method -internally to get it. The user can get a pointer to CCoeEnv, -for example, via the iEikonEnv macro (for which see <eikdef.h>).

                Scalable -UI Support

                Different size displays can handle different length -strings. To take full advantage of this fact, TulTextResourceUtils supports -resource strings with multiple options for string separated by 0x0001 character. -Each such string can contain same or different sub string keys (%U and %N). TulTextResourceUtils returns all strings, -it is the responsibility of the caller to parse the result and choose the -proper string to display.

                Setting the Maximum Substring Length

                This -may be done in the text resources. Sub string maximum lengths can be localized -separately for every language.

                The maximum sub string length is of -the format:

                %U[NN]

                where NN is -a number [01..99]. Please note that NN must -always consist of two characters, in other words, if the sub string maximum -length is eight characters, the value to be used is 08, not -plain 8.

                If the number of characters exceeds the -maximum length, the sub string is cut to fit and the last character is replaced -with an ellipsis character.

                Error Handling

                The leave -mechanism is used to handle memory exhaustion. Errors in application programming -are handled with the panic mechanism. The error codes used are as follows:

                - - - -

                ETooFewArguments

                -

                = 0: Unsolved parameters in the resource string.

                -                 - -

                ETooManyArguments

                -

                = 1: Already solved all parameters in the resource string.

                -                 - -

                EKeyStringNotFound

                -

                = 2: The key string was not found in formatting.

                -                 - -

                EInvalidIndex

                -

                = 3: Invalid index in the Format method.

                -                 - -

                EDescriptorTooSmall

                -

                = 4: Too small destination descriptor.

                -                 - -

                ECCoeEnvNotInitialized

                -

                = 5: CCoeEnv not initialized.

                -                 - -

                EInvalidSubstitute

                -

                = 6: Substituted string contains substring separator (i.e. 0x0001).

                -                 - - -

                Example

                The following example describes the usage -of the Text Resource Utility component:

                /* Using examples: */ - -#include <tultextresourceutils.h> - -// Get CCoeEnv instance -CEikonEnv* iEikonEnv = CEikonEnv::Static(); - -/* -* One TInt to add: -*/ - -//(In .loc -file) -#define TEXT_EXAMPLE "You have %N undone tasks." - -//(In .rss -file) -RESOURCE TBUF R_TEXT_EXAMPLE { buf = TEXT_EXAMPLE; } - -//(In the .cpp -file) -TInt number( 324 ); - -// -//iEikonEnv is needed for loading the resource string. -// -HBufC* stringholder = TulTextResourceUtils::LoadL( R_TEXT_EXAMPLE, number, iEikonEnv ); - -// -//The TInt in number is added to the resource string. The result is -//that stringholder points to a heap descriptor containing string: -//"You have 324 undone tasks." -// - -/* -* Several strings to add: -*/ - -//(In a .loc -file) -#define TEXT_EXAMPLE "I'm %2U%1U %3U%0U fine." - -//(In an .rss -file) -RESOURCE TBUF R_TEXT_EXAMPLE { buf = TEXT_EXAMPLE; } - -//(In the .cpp -file) -CDesCArrayFlat* strings = new CDesCArrayFlat( 4 ); -CleanupStack::PushL( strings ); - -strings->AppendL( _L("orking") ); //First string - -strings->AppendL( _L("ll") ); //Second string - -strings->AppendL( _L("sti") ); //Third string - -strings->AppendL( _L("w") ); //Fourth string - -// -//iEikonEnv is needed for loading the resource string. -// -HBufC* stringholder = TulTextResourceUtils::LoadL( R_TEXT_EXAMPLE, *strings, iEikonEnv ); - -// -//The strings in strings are added to the resource string. The result is -//that stringholder points to a heap descriptor containing string: -//"I'm still working fine." -// - -/* -* Scalable UI support -*/ -//(In .loc -file) -#define TEXT_EXAMPLE "You have missed %N messages from %U."<0x0001>"Missed %N msgs from %U."<0x0001>"Missed %N msgs." - -//(In .rss -file) -RESOURCE TBUF R_TEXT_EXAMPLE { buf = TEXT_EXAMPLE; } - -//(In the .cpp -file) -TInt number( 12 ); -_LIT(name, “John Doe”); - -// -//iEikonEnv is needed for loading the resource string. -// -HBufC* stringholder = TulTextResourceUtils::LoadL(R_TEXT_EXAMPLE,name,number,iEikonEnv); - -// -//The number and name are added to the resource string. The result is -//that stringholder points to a heap descriptor containing string: -//"You have missed 12 messages from John Doe.\001Missed 12 msgs from John -// Doe.\001Missed 12 msgs." -// - -CleanupStack::PopAndDestroy(); //strings -

                For more information on individual methods, please see the -reference API for TulTextResourceUtils.

                -                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D65D1EDC-5CB4-58C1-99B5-4495B6DA511F.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-D65D1EDC-5CB4-58C1-99B5-4495B6DA511F.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,192 @@ + + + + + +Text resource +utility overview +
                Purpose

                Text +Resource Utility is part of the Symbian Text Utilities. It is an API class, +which provides static methods for loading and formatting resource strings. +The purpose of Text Resource Utility is to make localization of the software +easier by allowing variable order in indexing of the key strings in the resource +string.

                Text Resource Utility provides resource string loading and +formatting methods for other subsystems. Through simple Load() and Format() operation +calls, the user can access resource strings which may contain formatting parameters +(%U for text or %N for numerical). Strings +can contain multiple instances of the same parameter. The 0x0001 character +has special meaning in strings; it is used to delimit different options for +displayable string. The client of TulTextResourceUtils is +responsible for choosing the proper string to display from given options.

                +
                Architectural +Relationships

                The implementation requires a CCoeEnv instance +(given as reference by the user or CCoeEnv::Static) +to access the resource files.

                All interface methods are static, so +there is no need to explicitly allocate memory for the interface class. All +functionality is accessed through exported methods of the TulTextResourceUtils class.

                The +interface is accessed through the tultextresourceutils.h header +file. Binaries are linked to the etul.dll library.

                +
                Description

                Usage

                Applications +load and format resource strings from normal resources with static methods +of the TulTextResourceUtils class. +The loading is done with the LoadL() and LoadLC() methods +and with the Load() method in situations where memory allocation +from the heap is not possible. Formatting is done automatically after loading +in the LoadL() and LoadLC() methods, but +it can also be done separately with the Format() method +in situations where memory allocation from the heap is not possible.

                For +reading the resource strings with the Load(), LoadL() and LoadLC() methods, +the user should provide a pointer to CCoeEnv for +efficiency reasons. If the pointer is not provided, the implementation uses +the CCoeEnv::Static method +internally to get it. The user can get a pointer to CCoeEnv, +for example, via the iEikonEnv macro (for which see <eikdef.h>).

                Scalable +UI Support

                Different size displays can handle different length +strings. To take full advantage of this fact, TulTextResourceUtils supports +resource strings with multiple options for string separated by 0x0001 character. +Each such string can contain same or different sub string keys (%U and %N). TulTextResourceUtils returns all strings, +it is the responsibility of the caller to parse the result and choose the +proper string to display.

                Setting the Maximum Substring Length

                This +may be done in the text resources. Sub string maximum lengths can be localized +separately for every language.

                The maximum sub string length is of +the format:

                %U[NN]

                where NN is +a number [01..99]. Please note that NN must +always consist of two characters, in other words, if the sub string maximum +length is eight characters, the value to be used is 08, not +plain 8.

                If the number of characters exceeds the +maximum length, the sub string is cut to fit and the last character is replaced +with an ellipsis character.

                Error Handling

                The leave +mechanism is used to handle memory exhaustion. Errors in application programming +are handled with the panic mechanism. The error codes used are as follows:

                + + + +

                ETooFewArguments

                +

                = 0: Unsolved parameters in the resource string.

                +                 + +

                ETooManyArguments

                +

                = 1: Already solved all parameters in the resource string.

                +                 + +

                EKeyStringNotFound

                +

                = 2: The key string was not found in formatting.

                +                 + +

                EInvalidIndex

                +

                = 3: Invalid index in the Format method.

                +                 + +

                EDescriptorTooSmall

                +

                = 4: Too small destination descriptor.

                +                 + +

                ECCoeEnvNotInitialized

                +

                = 5: CCoeEnv not initialized.

                +                 + +

                EInvalidSubstitute

                +

                = 6: Substituted string contains substring separator (i.e. 0x0001).

                +                 + + +

                Example

                The following example describes the usage +of the Text Resource Utility component:

                /* Using examples: */ + +#include <tultextresourceutils.h> + +// Get CCoeEnv instance +CEikonEnv* iEikonEnv = CEikonEnv::Static(); + +/* +* One TInt to add: +*/ + +//(In .loc -file) +#define TEXT_EXAMPLE "You have %N undone tasks." + +//(In .rss -file) +RESOURCE TBUF R_TEXT_EXAMPLE { buf = TEXT_EXAMPLE; } + +//(In the .cpp -file) +TInt number( 324 ); + +// +//iEikonEnv is needed for loading the resource string. +// +HBufC* stringholder = TulTextResourceUtils::LoadL( R_TEXT_EXAMPLE, number, iEikonEnv ); + +// +//The TInt in number is added to the resource string. The result is +//that stringholder points to a heap descriptor containing string: +//"You have 324 undone tasks." +// + +/* +* Several strings to add: +*/ + +//(In a .loc -file) +#define TEXT_EXAMPLE "I'm %2U%1U %3U%0U fine." + +//(In an .rss -file) +RESOURCE TBUF R_TEXT_EXAMPLE { buf = TEXT_EXAMPLE; } + +//(In the .cpp -file) +CDesCArrayFlat* strings = new CDesCArrayFlat( 4 ); +CleanupStack::PushL( strings ); + +strings->AppendL( _L("orking") ); //First string + +strings->AppendL( _L("ll") ); //Second string + +strings->AppendL( _L("sti") ); //Third string + +strings->AppendL( _L("w") ); //Fourth string + +// +//iEikonEnv is needed for loading the resource string. +// +HBufC* stringholder = TulTextResourceUtils::LoadL( R_TEXT_EXAMPLE, *strings, iEikonEnv ); + +// +//The strings in strings are added to the resource string. The result is +//that stringholder points to a heap descriptor containing string: +//"I'm still working fine." +// + +/* +* Scalable UI support +*/ +//(In .loc -file) +#define TEXT_EXAMPLE "You have missed %N messages from %U."<0x0001>"Missed %N msgs from %U."<0x0001>"Missed %N msgs." + +//(In .rss -file) +RESOURCE TBUF R_TEXT_EXAMPLE { buf = TEXT_EXAMPLE; } + +//(In the .cpp -file) +TInt number( 12 ); +_LIT(name, “John Doe”); + +// +//iEikonEnv is needed for loading the resource string. +// +HBufC* stringholder = TulTextResourceUtils::LoadL(R_TEXT_EXAMPLE,name,number,iEikonEnv); + +// +//The number and name are added to the resource string. The result is +//that stringholder points to a heap descriptor containing string: +//"You have missed 12 messages from John Doe.\001Missed 12 msgs from John +// Doe.\001Missed 12 msgs." +// + +CleanupStack::PopAndDestroy(); //strings +

                For more information on individual methods, please see the +reference API for TulTextResourceUtils.

                +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D69DD425-5F93-4238-A7E9-915F24A9C9CA.dita --- a/Symbian3/SDK/Source/GUID-D69DD425-5F93-4238-A7E9-915F24A9C9CA.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-D69DD425-5F93-4238-A7E9-915F24A9C9CA.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,56 +1,56 @@ - - - - - -Open -C MessageQueue Library Example -

                The Message Queue Library example demonstrates how to use Open C APIs for -developing applications that use Open C standard libraries on Symbian platform. -This example uses the APIs of the message queue library to create/close message -queues and send/receive messages and also get information on created message -queues.

                -
                Download

                Click -on the following link to download the example: opencmessagequeuelibraryex.zip

                Click: browse to view the example code.

                -
                Design and -Implementation

                The following sections provide information about -the implementation of the example.

                Description

                OpenCMessageQueueClientEx -is a C Application that uses the Message Queue library. This application -uses main() as the entry point for the application. This is a simple console -based application. The application uses Message Queue library (OpenCMessageQueueLibrary.dll) -APIs. The Main thread of the application creates two message queues, and -two threads. Thread one will send message to message queue 1 and waits for -messages from message queue 2. Then thread one will send message to message -queue 2 and waits for messages from message queue 1. If a user tries to create -a message queue using OpenCMessageQueueLibrary.dll with the already -existing name, it will just return the existing message queue Id. The application -has its own icon and can be launched from the UI both in the emulator and -in the device.

                Capabilities

                The program capabilities are -defined in: MessageQueueLibrary.mmp (DLL - library): CAPABILITY -ALL -TCB MessageQueueClient.mmp(EXE - application): CAPABILITY -NONE.

                Module hierarchy

                This application has 2 modules -as below:

                Message Queue Library (DLL) that exports set of apis for the -user.

                OpenCMessageQueueLibraryEx\engine : The application (EXE) that -demonstrates the usage of Open C APIs and also those APIs exported by Message -Queue Library.

                (OpenCMessageQueueLibraryEx\exe) : This example will -create a DLL which exports set of generic APIs with which the user can do -message queue related operations. To give a rough idea on how to use these -apis, an EXE is provided that creates threads and does send/receive on message -queues using those exported apis.

                APIs used

                msgget

                msgctl -

                msgrcv

                msgsnd

                semget

                semctl

                semop

                -
                Building and -Using To build the Message Queue Library example application, go to -the OpenCMessageQueueLibraryEx\group directory and build -the application. The Message Queue Library application consists of two modules, -which should be built in the following order: engine - which builds the -generic message queue library exe - which builds an EXE that demonstrates -the usage of this library The definition for the whole application can be -found in thebld.infin the group subdirectory of the applications -main directory.
                + + + + + +Open +C MessageQueue Library Example +

                The Message Queue Library example demonstrates how to use Open C APIs for +developing applications that use Open C standard libraries on Symbian platform. +This example uses the APIs of the message queue library to create/close message +queues and send/receive messages and also get information on created message +queues.

                +
                Download

                Click +on the following link to download the example: opencmessagequeuelibraryex.zip

                Click: browse to view the example code.

                +
                Design and +Implementation

                The following sections provide information about +the implementation of the example.

                Description

                OpenCMessageQueueClientEx +is a C Application that uses the Message Queue library. This application +uses main() as the entry point for the application. This is a simple console +based application. The application uses Message Queue library (OpenCMessageQueueLibrary.dll) +APIs. The Main thread of the application creates two message queues, and +two threads. Thread one will send message to message queue 1 and waits for +messages from message queue 2. Then thread one will send message to message +queue 2 and waits for messages from message queue 1. If a user tries to create +a message queue using OpenCMessageQueueLibrary.dll with the already +existing name, it will just return the existing message queue Id. The application +has its own icon and can be launched from the UI both in the emulator and +in the device.

                Capabilities

                The program capabilities are +defined in: MessageQueueLibrary.mmp (DLL - library): CAPABILITY +ALL -TCB MessageQueueClient.mmp(EXE - application): CAPABILITY +NONE.

                Module hierarchy

                This application has 2 modules +as below:

                Message Queue Library (DLL) that exports set of apis for the +user.

                OpenCMessageQueueLibraryEx\engine : The application (EXE) that +demonstrates the usage of Open C APIs and also those APIs exported by Message +Queue Library.

                (OpenCMessageQueueLibraryEx\exe) : This example will +create a DLL which exports set of generic APIs with which the user can do +message queue related operations. To give a rough idea on how to use these +apis, an EXE is provided that creates threads and does send/receive on message +queues using those exported apis.

                APIs used

                msgget

                msgctl +

                msgrcv

                msgsnd

                semget

                semctl

                semop

                +
                Building and +Using To build the Message Queue Library example application, go to +the OpenCMessageQueueLibraryEx\group directory and build +the application. The Message Queue Library application consists of two modules, +which should be built in the following order: engine - which builds the +generic message queue library exe - which builds an EXE that demonstrates +the usage of this library The definition for the whole application can be +found in thebld.infin the group subdirectory of the applications +main directory.
                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D6A2B169-F6DB-5BCE-83C9-7CD4A10C5BE9.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-D6A2B169-F6DB-5BCE-83C9-7CD4A10C5BE9.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,12 @@ + + + + + +Changing the cryptographic strength

                To change the cryptographic strength simply replace the cryptography.dll file, located in <your-SDK-path>\epoc32\release\<target>\<variant>, with a version of the DLL that has the required strength. There are two crypto DLLs available for selection, see Weak and strong cryptography.

                So, for example, if you wanted to increase the strength of cryptography.dll in say <your-SDK-path>\epoc32\release\wins\urel to strong_cryptography.dll, then you would do this as follows:

                • Get a copy of strong_cryptography.dll from <your-SDK-path>\src\generic\security\crypto\import\bin\wins\urel

                • Paste this into <your-SDK-path>\epoc32\release\wins\urel

                • Rename the copied strong_cryptography.dll to cryptography.dll

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D6B1B658-0582-511A-8583-758F9338E5CB.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-D6B1B658-0582-511A-8583-758F9338E5CB.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,99 @@ + + + + + +Secure +stream encryption -- guide/HowTo +

                This document describes secure stream encryption and its use (with the Cryptography API).

                +
                  +

                • What is secure stream encryption?

                  • +

                • What is secure stream encryption used for?

                  • +

                • How do I use the secure stream encryption API?

                    +

                  • Encrypting a stream

                    • +

                  • Decrypting a stream

                    • +

                  • Handling multiple elements

                    • +

                  • Storing encryption data

                    • +
                  • +

                • Example +code

                  • +
                +
                What is secure +stream encryption?

                Secure stream encryption provides subclasses +of RReadStream, RWriteStream and CStreamStore that +allow transparent access to encrypted streams and stores. It is implemented +in terms of PBE (Password +Based Encryption) -- that is, PBE does most of the work, the stream +encryption classes are just wrappers that call PBE. The word "secure" refers +to the fact that it uses well-known cryptographic algorithms.

                +
                What is secure +stream encryption used for?

                Secure stream encryption is used for +example:

                  +

                • to password protect +a database file

                  • +

                • to store contacts encrypted +on a mobile phone.

                  • +
                +
                How do I use +the secure stream encryption API?

                Encrypting +a stream

                  +

                • An encryption object +(i.e., a CPBEncryptElement or CPBEncryptSet object) +is necessary to allow the password +based encryption of elements or multiple elements. Objects of this +type contain the encryption key with its encryption data (i.e. password, cipher, +salt, IV, iterations). Note that encryption objects can be recreated at a +later stage from existing encryption data (see Storing +encryption data)

                  • +

                • An RWriteStream object +(such as an RFileWriteStream, or RStoreWriteStream object) +representing a target stream needs to be created in order to write the stream +to a file or store

                  • +

                • To support the encryption, +an REncryptStream object is required, which forms an encryption +filter or layer over the RWriteStream object.

                  • +

                • Data can now be encrypted +as it is externalized through the REncryptStream to the stream +represented by the RWriteStream object.

                  • +

                Decrypting a stream

                Reading +from an encrypted stream is a similar process to that of writing to one.

                  +

                • An encryption object +(i.e., a CPBEncryptElement or a CPBEncryptSet object) +is needed to allow the password +based decryption of elements or multiple elements.

                  • +

                • An RReadStream object +(such as an RFileReadStream, or RStoreReadStream object) +needs to be created to read the stream from a file or store.

                  • +

                • An RDecryptStream object +is needed to form an encryption wrapper around the existing RReadStream object.

                  • +

                • The encrypted data is +internalized from the stream represented by the RReadStream object +by way of the RDecryptStream object.

                  • +

                Handling multiple +elements

                CPBEncryptElement is good +for handling individual elements, but for encrypting/decrypting information +with multiple, independent elements it is advisable to use CPBEncryptSet; +for instance, if you wished to store contacts encrypted on a mobile phone.

                When +you create a CPBEncryptSet object a master key is generated +for you. This master key, which is encrypted with the password provided by +the user of the class, enables the encryption/decryption of individual elements. +The password may be changed by using the CPBEncryptSet::ChangePasswordL() function, +which re-encrypts the master key with the new password.

                Storing +encryption data

                In order to decrypt any information previously +encrypted with a CPBEncryptElement or CPBEncryptSet object, +you must store its encryption data along with it. Externalizing the CPBEncryptionData object +will achieve this; for example:

                writeStream << encryption->EncryptionData();

                where writeStream is a RFileWriteStream object, +and encryption is a CPBEncryptElement object. Failure to +do this will result in the permanent loss of the encrypted information. See Secure stream example code.

                +
                Note

                The +Secure Store APIs REncryptStream and RDecryptStream currently +support both the old CSecurityBase methods and the new PBE-based +methods. In the near future, the old methods will be marked as officially +deprecated.

                +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D6B332EB-D9D7-5598-98C7-E73164A2057D_d0e252535_href.jpg Binary file Symbian3/SDK/Source/GUID-D6B332EB-D9D7-5598-98C7-E73164A2057D_d0e252535_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D6B332EB-D9D7-5598-98C7-E73164A2057D_d0e256243_href.jpg Binary file Symbian3/SDK/Source/GUID-D6B332EB-D9D7-5598-98C7-E73164A2057D_d0e256243_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D6BB18FE-289D-546F-97DC-389B57B5B2E3.dita --- a/Symbian3/SDK/Source/GUID-D6BB18FE-289D-546F-97DC-389B57B5B2E3.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-D6BB18FE-289D-546F-97DC-389B57B5B2E3.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,78 +1,78 @@ - - - - - -Multimedia -APIs and Frameworks Overview -

                This section provides an overview of all the components that form the Multimedia -APIs and Frameworks collection.

                -
                Purpose

                The Multimedia APIs and Frameworks collection -provides a client API consisting of several interfaces that encapsulate a -lightweight plug-in framework. The client API enables you to manipulate the -audio and video features of the Symbian platform.

                -
                Architectural Relationship

                The following figure -shows the architectural of the components that form the Multimedia APIs and -Frameworks collection.

                - Multimedia APIs and Frameworks Architectural Overview - - -
                -
                Description

                The Multimedia Framework overview details -the architecture of the components that constitutes the Multimedia APIs and -Frameworks collection.

                The Multimedia Subsystem provides the Multimedia -capabilities of the Symbian platform. It includes audio recording/playback, -video recording/playback, still image conversion and camera control. It includes -framework to support these, even if all these functionality are not included. -The function inclusion depends on the discretion of the device creator.

                -
                Components

                The Multimedia APIs and Frameworks constitutes -the following components:

                  - - -

                • Camera API

                  • -

                • Image Conversion Library -(ICL)

                  • -

                • Multimedia Framework -(MMF)

                  • -

                • Multimedia Utility Library

                  • - -

                Camera

                The -Onboard Camera API can be used to achieve video input streaming, and direct -screen access can be used to achieve video output streaming. For more information -about the Onboard Camera API, see Onboard -Camera API Overview.

                Image Conversion Library

                The -Image Conversion Library is a light-weight, client-side plug-in framework -for still image codecs. A number of software codecs are shipped with the Symbian -platform, most of which are un-optimised, but device creators may replace -them with optimised or hardware accelerated versions. The JPEG decoder / encoder -has been optimised.

                Multimedia Framework

                The Multimedia -Framework is a light-weight, multi-threaded plug-in framework for handling -multimedia data, running as one or more threads in the application process. -The only controller plug-in supplied by default is a simple linear audio controller. -In turn this supports a number of formats and audio data types. In addition -two example controllers are supplied; one for audio (Ogg/Vorbis) and one for -video (Avi/XviD).

                Multimedia Utility Library

                The Multimedia -Utility Library provides shared utilities for the MMF.

                -
                Using Multimedia APIs and Frameworks

                The Multimedia -APIs and Frameworks collection provides cross-platform compatibility for client -applications and hardware acceleration plug-in writers, and reduces the cost -of porting the applications and codecs between platforms.

                -                 - - -Camera - Overview -Imaging Frameworks -Overview -Multimedia -Framework Overview -Multimedia -Utility Library Overview - + + + + + +Multimedia +APIs and Frameworks Overview +

                This section provides an overview of all the components that form the Multimedia +APIs and Frameworks collection.

                +
                Purpose

                The Multimedia APIs and Frameworks collection +provides a client API consisting of several interfaces that encapsulate a +lightweight plug-in framework. The client API enables you to manipulate the +audio and video features of the Symbian platform.

                +
                Architectural Relationship

                The following figure +shows the architectural of the components that form the Multimedia APIs and +Frameworks collection.

                + Multimedia APIs and Frameworks Architectural Overview + + +
                +
                Description

                The Multimedia Framework overview details +the architecture of the components that constitutes the Multimedia APIs and +Frameworks collection.

                The Multimedia Subsystem provides the Multimedia +capabilities of the Symbian platform. It includes audio recording/playback, +video recording/playback, still image conversion and camera control. It includes +framework to support these, even if all these functionality are not included. +The function inclusion depends on the discretion of the device creator.

                +
                Components

                The Multimedia APIs and Frameworks constitutes +the following components:

                  + + +

                • Camera API

                  • +

                • Image Conversion Library +(ICL)

                  • +

                • Multimedia Framework +(MMF)

                  • +

                • Multimedia Utility Library

                  • + +

                Camera

                The +Onboard Camera API can be used to achieve video input streaming, and direct +screen access can be used to achieve video output streaming. For more information +about the Onboard Camera API, see Onboard +Camera API Overview.

                Image Conversion Library

                The +Image Conversion Library is a light-weight, client-side plug-in framework +for still image codecs. A number of software codecs are shipped with the Symbian +platform, most of which are un-optimised, but device creators may replace +them with optimised or hardware accelerated versions. The JPEG decoder / encoder +has been optimised.

                Multimedia Framework

                The Multimedia +Framework is a light-weight, multi-threaded plug-in framework for handling +multimedia data, running as one or more threads in the application process. +The only controller plug-in supplied by default is a simple linear audio controller. +In turn this supports a number of formats and audio data types. In addition +two example controllers are supplied; one for audio (Ogg/Vorbis) and one for +video (Avi/XviD).

                Multimedia Utility Library

                The Multimedia +Utility Library provides shared utilities for the MMF.

                +
                Using Multimedia APIs and Frameworks

                The Multimedia +APIs and Frameworks collection provides cross-platform compatibility for client +applications and hardware acceleration plug-in writers, and reduces the cost +of porting the applications and codecs between platforms.

                +                 + + +Camera + Overview +Imaging Frameworks +Overview +Multimedia +Framework Overview +Multimedia +Utility Library Overview +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D6BE4647-25A8-5F88-9137-F4882AF22BCF.dita --- a/Symbian3/SDK/Source/GUID-D6BE4647-25A8-5F88-9137-F4882AF22BCF.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-D6BE4647-25A8-5F88-9137-F4882AF22BCF.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,14 +1,14 @@ - - - - - -Setting the Text Cursor

                A text cursor (TTextCursor) is a rectangular area which can optionally be set to flash. It has a height, width, ascent and origin, illustrated below.

                - Text cursor -

                The text cursor is positioned on screen by specifying an offset between its origin and the origin of a window. It can be added to a window group using RWindowGroup::SetTextCursor().

                Two predefined types of text cursors are provided: solid and hollow rectangles. In addition bitmaps can be used as text cursors. Custom text cursors are added to the Window Server using RWsSession::SetCustomTextCursor(). They have a unique identifier, which is used by RWindowGroup::SetTextCursor(). They are clipped if too large and their vertical alignment can be adjusted.

                Sprites and Cursors                 \ No newline at end of file + + + + + +Setting the Text Cursor

                A text cursor (TTextCursor) is a rectangular area which can optionally be set to flash. It has a height, width, ascent and origin, illustrated below.

                + Text cursor +

                The text cursor is positioned on screen by specifying an offset between its origin and the origin of a window. It can be added to a window group using RWindowGroup::SetTextCursor().

                Two predefined types of text cursors are provided: solid and hollow rectangles. In addition bitmaps can be used as text cursors. Custom text cursors are added to the Window Server using RWsSession::SetCustomTextCursor(). They have a unique identifier, which is used by RWindowGroup::SetTextCursor(). They are clipped if too large and their vertical alignment can be adjusted.

                Sprites and Cursors                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D729593E-C131-5F67-BF0C-6C9AD847C9F9_d0e322196_href.png Binary file Symbian3/SDK/Source/GUID-D729593E-C131-5F67-BF0C-6C9AD847C9F9_d0e322196_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D729593E-C131-5F67-BF0C-6C9AD847C9F9_d0e328353_href.png Binary file Symbian3/SDK/Source/GUID-D729593E-C131-5F67-BF0C-6C9AD847C9F9_d0e328353_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D73AD200-BE4D-50BF-BCF9-14627DE530B7.dita --- a/Symbian3/SDK/Source/GUID-D73AD200-BE4D-50BF-BCF9-14627DE530B7.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-D73AD200-BE4D-50BF-BCF9-14627DE530B7.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,24 +1,21 @@ - - - - - -S60 -Platform: POP/IMAP Example -
                Description This -C++ application shows how to retrieve e-mail from a remote mailbox to an S60 -device using IMAP and POP protocols. The usual e-mail features such as sending, -editing, and deleting e-mail messages are demonstrated. The updated example -has been modified to support S60 5th Edition and touch UI. Important classes: -CMsvSession, CClientMtmRegistry, CMtmUiRegistry, CMsvOperation, CMsvEntrySelection, -CMsvEntry, CBaseMtm. For more details, click on this link : InternetEmail.zip
                -
                Download

                Click -on the following link to download the example: Imap4Example.zip

                Click: browse to view the example code.

                -
                See also

                IMAP4 MTM Overview

                SMTP MTM Overview

                + + + + + +POP/IMAP +Example +
                Description This +C++ application shows how to retrieve e-mail from a remote mailbox to a device +using IMAP and POP protocols. The usual e-mail features such as sending, editing, +and deleting e-mail messages are demonstrated.
                +
                Download

                Click +on the following link to download the example: InternetEmail.zip

                Click: browse to view the example code.

                +
                See also

                IMAP4 MTM Overview

                SMTP MTM Overview

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D74C4403-1516-4C8F-B457-98BA0F97718A-master.png Binary file Symbian3/SDK/Source/GUID-D74C4403-1516-4C8F-B457-98BA0F97718A-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D74C4403-1516-4C8F-B457-98BA0F97718A_d0e58942_href.png Binary file Symbian3/SDK/Source/GUID-D74C4403-1516-4C8F-B457-98BA0F97718A_d0e58942_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D74C4403-1516-4C8F-B457-98BA0F97718A_d0e59705_href.png Binary file Symbian3/SDK/Source/GUID-D74C4403-1516-4C8F-B457-98BA0F97718A_d0e59705_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D754C477-DB73-56F7-A135-13E1179CBB2D_d0e398384_href.png Binary file Symbian3/SDK/Source/GUID-D754C477-DB73-56F7-A135-13E1179CBB2D_d0e398384_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D754C477-DB73-56F7-A135-13E1179CBB2D_d0e398546_href.png Binary file Symbian3/SDK/Source/GUID-D754C477-DB73-56F7-A135-13E1179CBB2D_d0e398546_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D76B1999-E118-585B-A6B4-8AE8CCCB6F8B.dita --- a/Symbian3/SDK/Source/GUID-D76B1999-E118-585B-A6B4-8AE8CCCB6F8B.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-D76B1999-E118-585B-A6B4-8AE8CCCB6F8B.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,20 +1,19 @@ - - - - - -paged -

                paged

                -

                Use the paged statement to specify that the executable -is both code paged and data paged. This is the same as specifying both pagedcode and pageddata keywords -for an executable.

                -

                You can also mark an executable as paged using the OBY file keyword file[[HWVD]]. -For more information about the file[[HWVD]] keyword, refer to the ROM Tools -Guide in the Application Development Toolkit available for download at http://developer.symbian.org.

                + + + + + +paged +

                paged

                +

                Use the paged statement to specify that the executable +is code-paged. This is the same as specifying the pagedcode keyword +for an executable.

                +

                You can also mark an executable as paged using the OBY file keyword file[[HWVD]]. For more information about the file[[HWVD]] keyword, refer to the ROM Tools Guide in the Application Development +Toolkit available for download at http://developer.symbian.org.

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D7E5FECF-0B29-5908-A163-37036DF165E1_d0e78813_href.png Binary file Symbian3/SDK/Source/GUID-D7E5FECF-0B29-5908-A163-37036DF165E1_d0e78813_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D7E5FECF-0B29-5908-A163-37036DF165E1_d0e85525_href.png Binary file Symbian3/SDK/Source/GUID-D7E5FECF-0B29-5908-A163-37036DF165E1_d0e85525_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D7F000F0-019A-486E-BB0C-C0065D08C5F6_d0e4575_href.png Binary file Symbian3/SDK/Source/GUID-D7F000F0-019A-486E-BB0C-C0065D08C5F6_d0e4575_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D7F000F0-019A-486E-BB0C-C0065D08C5F6_d0e5850_href.png Binary file Symbian3/SDK/Source/GUID-D7F000F0-019A-486E-BB0C-C0065D08C5F6_d0e5850_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D81EAF75-EF8C-4B62-8866-439E29325E8A_d0e11345_href.png Binary file Symbian3/SDK/Source/GUID-D81EAF75-EF8C-4B62-8866-439E29325E8A_d0e11345_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D81EAF75-EF8C-4B62-8866-439E29325E8A_d0e12620_href.png Binary file Symbian3/SDK/Source/GUID-D81EAF75-EF8C-4B62-8866-439E29325E8A_d0e12620_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D8302B04-D850-5FA7-A1AD-F5C40CF6A1EF.dita --- a/Symbian3/SDK/Source/GUID-D8302B04-D850-5FA7-A1AD-F5C40CF6A1EF.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-D8302B04-D850-5FA7-A1AD-F5C40CF6A1EF.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,240 +1,240 @@ - - - - - -Porting -Data-caged ApplicationsThis document describes the changes required to migrate exe-apps -to a data caged directory structure. -
                Introduction

                In Symbian OS v8.0 and earlier, application -specific information (for instance captions and icons) was provided by a combination -of the AIF (Application Information File) and the caption file. Both of these -files were optional.

                Migrated applications must provide a registration -file, and may optionally provide localizable application information resource -files and icon files. Localizable application information resource files provide -localizable application information (for instance captions and icons), whereas -an application's localizable UI resource file provides UI resources such as -menus and dialogs.

                The localizable information that was previously -provided by a combination of AIF and caption files, has been split into two -categories:

                The diagram below shows the new file structure used to -provide application information.

                - -
                  -

                • A registration file -which 'points' to one of three localizable resource files provided. If the -current language is 01 or 02, the -system will load the corresponding version of AppName_loc, -otherwise AppName_loc.rsc will be loaded.

                  • -

                • AppName_loc.r01 and AppName_loc.r02 share -the same icon file.

                  • -

                Migrated applications may be used with or without data caging enforced.

                -
                Procedure

                The following sections detail the mandatory -and optional steps required to migrate an application.

                Mandatory -steps

                  -

                1. Provide a registration -file.

                  A registration file is a standard Symbian platform compiled -resource file (.rsc). The .rss file -used to build the registration file should be named AppName_reg.rss and -contain at least the following lines:

                  #include <appinfo.rh> -UID2 KUidAppRegistrationResourceFile -UID3 0x01000000 // application UID -RESOURCE APP_REGISTRATION_INFO - { - app_file="AppName"; // filename of application binary (minus extension) - }

                  To build the registration file, add the following lines -to the application's MMP file:

                  START RESOURCE AppName_reg.rss -TARGETPATH \private\10003a3f\apps -END

                  The _reg filename suffix is used as -a naming convention only and is not mandatory.

                  Note that any lines -in the MMP file that are used to build an AIF file should be removed.

                  2. -

                2. Build the application -binary to a new location.

                  The following line should replace the TARGETPATH line -associated with the TARGET, TARGETTYPE and UID lines:

                  TARGETPATH \sys\bin
                  3. -

                Optional steps

                  -

                • A UI resource file whose -location is provided by CEikApplication::ResourceFileName()

                  • -

                • An MBM file whose location -is provided by CEikApplication::BitmapStoreName()

                  • -

                • Application information -through an AIF and/or caption file.

                  • -

                The following steps are only required if the application provides -one or more of the following:

                  -

                1. Specify the default -UI resource file location.

                  When building the application UI resource -file, the TARGETPATH must be specified as follows:

                  TARGETPATH \resource\apps
                  2. -

                2. Specify the default -MBM file location.

                  When building the application's MBM file, the TARGETPATH must -be specified as follows:

                  TARGETPATH \resource\apps
                  3. -

                3. Specify the application -information by providing the following files:

                    -

                  • Non-localizable information -(provided by the registration file)

                    The registration file provides -non-localizable application information. For an example registration file -see AppName_reg.rss in the Example -files section.

                    • -

                  • Localizable information -(localizable resource file and icon file)

                    Localizable application -information can either be provided in a separate resource file (see AppName_loc.rss), -or as a resource within the application UI resource file (see AppName.rss and AppName2_reg.rss in -the Example -files section).

                    When providing the information as a resource -within the application UI resource file, the registration file's APP_REGISTRATION_INFO struct -must contain the following lines:

                    localisable_resource_file="\\resource\\apps\\AppName"; -localisable_resource_id = R_LAI;

                    where R_LAI is -a named LOCALISABLE_APP_INFO resource struct within the UI -resource file.

                    The localisable_resource_file field -should not include a drive in the path, or a file-extension, but it should -provide a full directory path and a file name (without extension).

                    To -build a resource file for language 01, add the following -to the MMP file:

                    start resource AppName_loc.rss -targetpath \resource\apps -lang 01 -end

                    The _loc filename suffix is used as -a naming convention only and is not mandatory.

                    Icon files referenced -in the localizable resource should also be built to \resource\apps\.

                    • -
                  4. -
                -
                Software install -package file requirements

                When creating a PKG file (software install -package file) for an application, the registration file must be installed -to the \private\10003a3f\import\apps\ directory.

                The -application binary must be installed to \sys\bin\ on -the same drive as the registration file.

                The localizable resource -files must be installed to \resource\apps\ on the same -drive as the registration file.

                -
                Data caged -file locations

                To comply with the directory structure imposed by -data caging, many of the files associated with an application need to be relocated.

                Care -should be taken to ensure application code which overrides the following APIs -uses appropriate file locations:

                CEikApplication::ResourceFileName() -CEikApplication::BitmapStoreName() -CEikApplication::OpenIniFileLC( RFs& aFs )

                When specifying -the location of files on a target device, application IBY files should explicitly -specify \sys\bin as the destination location for application -binary files instead of using SYSTEM_BINDIR.

                -
                Example files

                AppName_reg.rss

                #include <appinfo.rh> - -UID2 KUidAppRegistrationResourceFile -UID3 0x01000000 // application UID - -RESOURCE APP_REGISTRATION_INFO - { - app_file = "AppName"; - // - localisable_resource_file = "\\resource\\apps\\AppName_loc"; - // - hidden = KAppNotHidden; - embeddability = KAppNotEmbeddable; - newfile = KAppDoesNotSupportNewFile; - launch = KAppLaunchInForeground; - group_name = "AppNameGroup"; - // - default_screen_number = 2; - // - datatype_list = - { - DATATYPE { priority=EDataTypePriorityNormal; type="image/jpeg"; }, - DATATYPE { priority=EDataTypePriorityNormal; type="image/gif"; } - }; - // - file_ownership_list = - { - FILE_OWNERSHIP_INFO {file_name="z:\\temp\\AppNameTempFile.txt"; }, - FILE_OWNERSHIP_INFO {file_name="z:\\temp\\AppName.txt"; } - }; - }

                AppName_loc.rss

                #include <appinfo.rh> -#ifdef LANGUAGE_01 -#include "AppName01.rls" -#else -#include "AppNamesc.rls" -#endif -RESOURCE LOCALISABLE_APP_INFO - { - short_caption = STRING_r_short_caption; - caption_and_icon = - { - CAPTION_AND_ICON_INFO - { - caption = STRING_r_caption; - number_of_icons = 2; // each icon must be a bitmap/mask pair - icon_file = STRING_r_icon_file; - } - }; - // - view_list = - { - VIEW_DATA - { - uid = 268123123; - screen_mode = 0x00; - caption_and_icon = - { - CAPTION_AND_ICON_INFO - { - caption = STRING_r_view_268123123_caption; - number_of_icons = 1; // each icon must be a bitmap/mask pair - } - }; - }, - VIEW_DATA - { - uid = 268123124; - screen_mode = 0x01; - caption_and_icon = - { - CAPTION_AND_ICON_INFO - { - caption = STRING_r_view_268123124_caption; - number_of_icons = 1; // each icon must be a bitmap/mask pair - icon_file = "z:\\resource\\apps\\icon.svg"; - } - }; - } - }; - }

                Note: In the above example, RLS files have been -used to demonstrate how resource files for different languages (AppName_loc.r01 and AppName_loc.rsc) -can be built from a single RSS file.

                AppName01.rls

                rls_string STRING_r_short_caption "English AppName" -rls_string STRING_r_caption "English AppName Long Caption" -rls_string STRING_r_icon_file "z:\\resource\\apps\\EnglishAppNameIcons.mbm" -rls_string STRING_r_view_268123123_caption "caption for view 268123123" -rls_string STRING_r_view_268123124_caption "English view 268123124"

                AppNamesc.rls

                rls_string STRING_r_short_caption "AppName" -rls_string STRING_r_caption "Default AppName Caption" -rls_string STRING_r_icon_file "z:\\resource\\apps\\DefaultAppNameIcons.mbm" -rls_string STRING_r_view_268123123_caption "caption for view 268123123" -rls_string STRING_r_view_268123124_caption "caption for view 268123124"

                AppName2_reg.rss

                #include <appinfo.rh> -#include <appname.rsg> - -UID2 KUidAppRegistrationResourceFile -UID3 0x01000000 // application UID - -RESOURCE APP_REGISTRATION_INFO - { - app_file = "AppName"; - // - localisable_resource_file = "\\resource\\apps\\appname"; - localisable_resource_id = R_LAI; - }

                AppName.rss

                NAME APPN -#include <eikon.rh> -#include <eikon.rsg> -#include <appinfo.rh> - -RESOURCE RSS_SIGNATURE { } -RESOURCE TBUF r_appname_default_file { buf="default file name"; } -RESOURCE EIK_APP_INFO { hotkeys=r_appname_hotkeys; menubar=r_appname_menubar; toolbar=r_appname_toolbar; } -RESOURCE LOCALISABLE_APP_INFO r_lai - { - short_caption = "AppName"; - } -RESOURCE TOOLBAR r_appname_toolbar { } -RESOURCE HOTKEYS r_appname_hotkeys { } -RESOURCE MENU_BAR r_appname_menubar { }
                -                 -Porting Applications -to EXEs + + + + + +Porting +Data-caged ApplicationsThis document describes the changes required to migrate exe-apps +to a data caged directory structure. +
                Introduction

                In Symbian OS v8.0 and earlier, application +specific information (for instance captions and icons) was provided by a combination +of the AIF (Application Information File) and the caption file. Both of these +files were optional.

                Migrated applications must provide a registration +file, and may optionally provide localizable application information resource +files and icon files. Localizable application information resource files provide +localizable application information (for instance captions and icons), whereas +an application's localizable UI resource file provides UI resources such as +menus and dialogs.

                The localizable information that was previously +provided by a combination of AIF and caption files, has been split into two +categories:

                The diagram below shows the new file structure used to +provide application information.

                + +
                  +

                • A registration file +which 'points' to one of three localizable resource files provided. If the +current language is 01 or 02, the +system will load the corresponding version of AppName_loc, +otherwise AppName_loc.rsc will be loaded.

                  • +

                • AppName_loc.r01 and AppName_loc.r02 share +the same icon file.

                  • +

                Migrated applications may be used with or without data caging enforced.

                +
                Procedure

                The following sections detail the mandatory +and optional steps required to migrate an application.

                Mandatory +steps

                  +

                1. Provide a registration +file.

                  A registration file is a standard Symbian platform compiled +resource file (.rsc). The .rss file +used to build the registration file should be named AppName_reg.rss and +contain at least the following lines:

                  #include <appinfo.rh> +UID2 KUidAppRegistrationResourceFile +UID3 0x01000000 // application UID +RESOURCE APP_REGISTRATION_INFO + { + app_file="AppName"; // filename of application binary (minus extension) + }

                  To build the registration file, add the following lines +to the application's MMP file:

                  START RESOURCE AppName_reg.rss +TARGETPATH \private\10003a3f\apps +END

                  The _reg filename suffix is used as +a naming convention only and is not mandatory.

                  Note that any lines +in the MMP file that are used to build an AIF file should be removed.

                  2. +

                2. Build the application +binary to a new location.

                  The following line should replace the TARGETPATH line +associated with the TARGET, TARGETTYPE and UID lines:

                  TARGETPATH \sys\bin
                  3. +

                Optional steps

                  +

                • A UI resource file whose +location is provided by CEikApplication::ResourceFileName()

                  • +

                • An MBM file whose location +is provided by CEikApplication::BitmapStoreName()

                  • +

                • Application information +through an AIF and/or caption file.

                  • +

                The following steps are only required if the application provides +one or more of the following:

                  +

                1. Specify the default +UI resource file location.

                  When building the application UI resource +file, the TARGETPATH must be specified as follows:

                  TARGETPATH \resource\apps
                  2. +

                2. Specify the default +MBM file location.

                  When building the application's MBM file, the TARGETPATH must +be specified as follows:

                  TARGETPATH \resource\apps
                  3. +

                3. Specify the application +information by providing the following files:

                    +

                  • Non-localizable information +(provided by the registration file)

                    The registration file provides +non-localizable application information. For an example registration file +see AppName_reg.rss in the Example +files section.

                    • +

                  • Localizable information +(localizable resource file and icon file)

                    Localizable application +information can either be provided in a separate resource file (see AppName_loc.rss), +or as a resource within the application UI resource file (see AppName.rss and AppName2_reg.rss in +the Example +files section).

                    When providing the information as a resource +within the application UI resource file, the registration file's APP_REGISTRATION_INFO struct +must contain the following lines:

                    localisable_resource_file="\\resource\\apps\\AppName"; +localisable_resource_id = R_LAI;

                    where R_LAI is +a named LOCALISABLE_APP_INFO resource struct within the UI +resource file.

                    The localisable_resource_file field +should not include a drive in the path, or a file-extension, but it should +provide a full directory path and a file name (without extension).

                    To +build a resource file for language 01, add the following +to the MMP file:

                    start resource AppName_loc.rss +targetpath \resource\apps +lang 01 +end

                    The _loc filename suffix is used as +a naming convention only and is not mandatory.

                    Icon files referenced +in the localizable resource should also be built to \resource\apps\.

                    • +
                  4. +
                +
                Software install +package file requirements

                When creating a PKG file (software install +package file) for an application, the registration file must be installed +to the \private\10003a3f\import\apps\ directory.

                The +application binary must be installed to \sys\bin\ on +the same drive as the registration file.

                The localizable resource +files must be installed to \resource\apps\ on the same +drive as the registration file.

                +
                Data caged +file locations

                To comply with the directory structure imposed by +data caging, many of the files associated with an application need to be relocated.

                Care +should be taken to ensure application code which overrides the following APIs +uses appropriate file locations:

                CEikApplication::ResourceFileName() +CEikApplication::BitmapStoreName() +CEikApplication::OpenIniFileLC( RFs& aFs )

                When specifying +the location of files on a target device, application IBY files should explicitly +specify \sys\bin as the destination location for application +binary files instead of using SYSTEM_BINDIR.

                +
                Example files

                AppName_reg.rss

                #include <appinfo.rh> + +UID2 KUidAppRegistrationResourceFile +UID3 0x01000000 // application UID + +RESOURCE APP_REGISTRATION_INFO + { + app_file = "AppName"; + // + localisable_resource_file = "\\resource\\apps\\AppName_loc"; + // + hidden = KAppNotHidden; + embeddability = KAppNotEmbeddable; + newfile = KAppDoesNotSupportNewFile; + launch = KAppLaunchInForeground; + group_name = "AppNameGroup"; + // + default_screen_number = 2; + // + datatype_list = + { + DATATYPE { priority=EDataTypePriorityNormal; type="image/jpeg"; }, + DATATYPE { priority=EDataTypePriorityNormal; type="image/gif"; } + }; + // + file_ownership_list = + { + FILE_OWNERSHIP_INFO {file_name="z:\\temp\\AppNameTempFile.txt"; }, + FILE_OWNERSHIP_INFO {file_name="z:\\temp\\AppName.txt"; } + }; + }

                AppName_loc.rss

                #include <appinfo.rh> +#ifdef LANGUAGE_01 +#include "AppName01.rls" +#else +#include "AppNamesc.rls" +#endif +RESOURCE LOCALISABLE_APP_INFO + { + short_caption = STRING_r_short_caption; + caption_and_icon = + { + CAPTION_AND_ICON_INFO + { + caption = STRING_r_caption; + number_of_icons = 2; // each icon must be a bitmap/mask pair + icon_file = STRING_r_icon_file; + } + }; + // + view_list = + { + VIEW_DATA + { + uid = 268123123; + screen_mode = 0x00; + caption_and_icon = + { + CAPTION_AND_ICON_INFO + { + caption = STRING_r_view_268123123_caption; + number_of_icons = 1; // each icon must be a bitmap/mask pair + } + }; + }, + VIEW_DATA + { + uid = 268123124; + screen_mode = 0x01; + caption_and_icon = + { + CAPTION_AND_ICON_INFO + { + caption = STRING_r_view_268123124_caption; + number_of_icons = 1; // each icon must be a bitmap/mask pair + icon_file = "z:\\resource\\apps\\icon.svg"; + } + }; + } + }; + }

                Note: In the above example, RLS files have been +used to demonstrate how resource files for different languages (AppName_loc.r01 and AppName_loc.rsc) +can be built from a single RSS file.

                AppName01.rls

                rls_string STRING_r_short_caption "English AppName" +rls_string STRING_r_caption "English AppName Long Caption" +rls_string STRING_r_icon_file "z:\\resource\\apps\\EnglishAppNameIcons.mbm" +rls_string STRING_r_view_268123123_caption "caption for view 268123123" +rls_string STRING_r_view_268123124_caption "English view 268123124"

                AppNamesc.rls

                rls_string STRING_r_short_caption "AppName" +rls_string STRING_r_caption "Default AppName Caption" +rls_string STRING_r_icon_file "z:\\resource\\apps\\DefaultAppNameIcons.mbm" +rls_string STRING_r_view_268123123_caption "caption for view 268123123" +rls_string STRING_r_view_268123124_caption "caption for view 268123124"

                AppName2_reg.rss

                #include <appinfo.rh> +#include <appname.rsg> + +UID2 KUidAppRegistrationResourceFile +UID3 0x01000000 // application UID + +RESOURCE APP_REGISTRATION_INFO + { + app_file = "AppName"; + // + localisable_resource_file = "\\resource\\apps\\appname"; + localisable_resource_id = R_LAI; + }

                AppName.rss

                NAME APPN +#include <eikon.rh> +#include <eikon.rsg> +#include <appinfo.rh> + +RESOURCE RSS_SIGNATURE { } +RESOURCE TBUF r_appname_default_file { buf="default file name"; } +RESOURCE EIK_APP_INFO { hotkeys=r_appname_hotkeys; menubar=r_appname_menubar; toolbar=r_appname_toolbar; } +RESOURCE LOCALISABLE_APP_INFO r_lai + { + short_caption = "AppName"; + } +RESOURCE TOOLBAR r_appname_toolbar { } +RESOURCE HOTKEYS r_appname_hotkeys { } +RESOURCE MENU_BAR r_appname_menubar { }
                +                 +Porting Applications +to EXEs                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D84847BB-523D-5057-8F14-F6BCEECA2327-master.jpg Binary file Symbian3/SDK/Source/GUID-D84847BB-523D-5057-8F14-F6BCEECA2327-master.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D84847BB-523D-5057-8F14-F6BCEECA2327_d0e185542_href.jpg Binary file Symbian3/SDK/Source/GUID-D84847BB-523D-5057-8F14-F6BCEECA2327_d0e185542_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF.dita --- a/Symbian3/SDK/Source/GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,209 +1,209 @@ - - - - - -Loader -Search RulesThis topic provides a summary of the rules that the loader follows -to search for EXEs and DLLs. -
                  -

                • Search rules for an EXE

                  • -

                • Search rules for a DLL in the import table of an EXE or another DLL

                  • -

                • Search rules for a DLL loaded from a program

                  • -
                -
                Search rules -for an EXE

                To start a new process, call RProcess::Create().

                RProcess::Create() loads -the EXE specified in the input parameters. The function then looks through -the import table of the EXE to get a list of DLLs that the EXE references. -The loader uses the list of DLLs in the import table to load the DLLs. If -DLLs reference other DLLS, the loader uses the same method to load those DLLs. -See Search -rules for a DLL listed in the import table of an EXE.

                The result -of a search for an EXE depends on:

                  -

                • the name of the EXE. -You provide this information.

                  • -

                • the UID type : you provide. -This is optional

                  • -

                • the version of the EXEs -on the device

                  • -

                You pass the name of the EXE in the first parameter of RProcess::Create(). -You have a number of choices:

                  -

                • you can specify the -file name only. The loader will assume a .exe file extension. -For example:

                  efile

                  • -

                • you can specify a filename -and an extension. For example:

                  efile.exe

                  • -

                • you can put a path in -front of the file name. A path has limited use, because the loader can load -EXEs only from the directory \sys\bin, or from subdirectories -of \sys\bin.

                  • -

                The -search procedure

                The loader searches for EXEs with the given name -and extension. More than one EXE with the given name and extension can exist -on a device.

                  -

                1. If you do not provide -a path, the loader searches the \sys\bin directory on -all drives. The loader searches drives in the order Y:, X: ... B:, A:. The Z: drive is searched last. Subdirectories of \sys\bin are -not searched.

                  If you provide a path, there are only three useful cases:

                    -

                  • to limit the search -to a specific drive. For example:

                    X:\sys\bin

                    where X: can -be one of the drives A: to Z:.

                    • -

                  • to limit the search -to a subdirectory of \sys\bin on a specific drive. For -example:

                    X:\sys\bin\aaa\bbb

                    The use -of subdirectories in \sys\bin is not common.

                    where X: -can be one of the drives A: to Z:.

                    • -

                  • to limit the search -to a subdirectory of \sys\bin on all drives. For example:

                    \sys\bin\aaa\bbb

                    The -loader searches all drives in the order Y:, X: ... B:, A:. -The Z: drive is searched last.

                    The use of subdirectories -in \sys\bin is not common.

                    • -

                  The loader cannot load EXEs from other directories, because system -security prevents it.

                  2. -

                2. The loader compares -the UID type (TUidType) of each EXE in the list with the -UID type you specify in RProcess::Create(). The UID type -is a set of three UIDs. Each UID in the UID type that you specify must match -the same UID in the UID type of the EXE. If you specify KNullUid for -any of the three UIDs in your UID type, a match is automatic.

                  3. -

                3. If the search has found -no EXEs, the load fails.

                  4. -

                4. If the search has found -one EXE only, the loader loads that EXE.

                  5. -

                5. If more than one EXE -has been found, the loader loads the EXE with the highest version. A version N.n is -higher than version M.m if (N>M or (N==M and n>m)).

                  6. -

                6. If all EXEs have the -same version, the loader loads the version found first.

                  7. -
                -
                Search rules -for a DLL in the import table of an EXE or another DLL

                After the -loader has selected the EXE, the loader loads all DLLs in the import table. -This is also called static linkage.

                The import table contains the -name and extension of each DLL. The import table also contains the version -of each DLL and the 3rd UID that identifies each DLL. The version information -is stored in the import table when the executable file is built. All DLLs -have an ordered set of three UIDs. The third UID gives a unique identity to -the DLL. See UID protection.

                The search procedure

                The search uses the following procedure -for each DLL:

                  -

                1. The loader searches -the \sys\bin directory on all drives for all DLLs that -have the filename and extension. The loader searches drives in the order Y:, X: ... B:, A:. The Z: drive is searched -last. Subdirectories of \sys\bin are not searched. The -loader searches for all versions of the DLL. If the loader finds the same -version of a DLL on more than one drive, the loader only adds the first one -to the set of possible DLLs. For example, if version 2.1 of a DLL is on drive D: and -on drive Z:, only the version on drive D: is -added to the set of possible DLLs.

                  The loader cannot load DLLs from -other directories, because system security prevents it.

                  [Before December -2007, the loader had different behaviour. The loader searched the drive from -which the EXE was loaded before the loader checked the other drives. For example, -if the EXE was loaded from drive Z:, and version 2.1 -of a DLL was on drive D: and drive Z:, -the loader selected the version of the DLL that was on drive Z:.]

                  2. -

                2. The loader then selects -those DLLs that have the same 3rd UID from the set of possible DLLs. This -operation can decrease the set of possible DLLs. If there are no DLLs in the -set, the load fails.

                  3. -

                3. The loader then selects -those DLLs that have platform security capabilities that match or exceed those -of the EXE. This selection operation can decrease the set of possible DLLs. -If there are no DLLs in the set the load fails.

                  See also : Platform -security.

                  4. -

                4. Each DLL in the import -table of the EXE has a version number. This number is the version of the DLL -to which the EXE is linked. The loader uses the version number in the import -table to select the correct version of the DLL. The following flowchart shows -how the loader selects the DLL from the set of possible DLLs.

                  - -
                  5. -

                5. If there are no DLLs -that meet the requirements, the load fails.

                  6. -
                -
                Search rules -for a DLL loaded from a program

                To load a DLL from a program, call RLibrary::Load(). -This is known as dynamic linking.

                RLibrary::Load() loads -the DLL specified in the input parameters. The function then uses the import -table to get a list of referred DLLs. The loader loads the DLLs in the list -and uses the same search method that the loader uses for EXEs. See Search rules for a DLL in the import table of an EXE.

                The -result of a search for an DLL depends on:

                  -

                • the name of the DLL. -You provide this information.

                  • -

                • the UID type : you provide. -This is optional.

                  • -

                • the required version -: you provide. This is optional.

                  • -

                • the version of the DLLs -on the device.

                  • -

                You pass the name of the DLL in the first parameter of RLibrary::Load(). -You have a number of choices:

                  -

                • you can specify the -file name only. The loader will assume a .dll file extension. -For example:

                  efsrv

                  • -

                • you can specify a filename -and an extension. For example:

                  efsrv.dll

                  • -

                • you can put a path in -front of the file name. A path has limited use, because the loader can load -DLLs only from the directory \sys\bin, or from subdirectories -of \sys\bin.

                  • -

                See Dynamically -loading link libraries and Using -ECom.

                The -search procedure

                The loader searches for DLLs with the given name -and extension. More than one DLL with the given name and extension can exist -on a device.

                  -

                1. If you do not provide -a path, the loader searches the \sys\bin directory on -all drives. The loader searches drives in the order Y:, X: ... B:, A:. The Z: drive is searched last. Subdirectories of \sys\bin are -not searched.

                  If you provide a path, there are only three useful cases:

                    -

                  • to limit the search -to a specific drive. For example:

                    X:\sys\bin

                    where X: can -be one of the drives A: to Z:.

                    • -

                  • to limit the search -to a subdirectory of \sys\bin on a specific drive. For -example:

                    X:\sys\bin\aaa\bb

                    The use -of subdirectories in \sys\bin is not common.

                    where X: can -be one of the drives A: to Z:.

                    • -

                  • to limit the search -to a subdirectory of \sys\bin on all drives. For example:

                    \sys\bin\aaa\bbb

                    The -loader searches all drives in the order Y:, X: ... B:, A:. -The Z: drive is searched last.

                    The use of subdirectories -in \sys\bin is not common.

                    • -

                  System security prevents the loader from loading DLLs from any other -directories.

                  2. -

                2. The loader compares -the UID type (TUidType) of each DLL in the list with the -UID type you specify in RLibrary::Load(). The UID type -is a set of three UIDs. Each UID in the UID type that you specify must match -the same UID in the UID type of the DLL. If you specify KNullUid for -any of the three UIDs in your UID type, there is a match.

                  3. -

                3. If the search has found -no DLLs, the load fails.

                  4. -

                4. The loader then selects -those DLLs that have platform security capabilities that match or exceed those -of the process . This selection operation can decrease the set of possible -DLLs. If there are no DLLs in the set the load fails.

                  5. -

                5. If the search has found -no DLLs, the load fails.

                  6. -

                6. If you specify a version -number in RLibrary::Load(), the loader selects a version -of the DLL from the set. The following flowchart shows how the loader selects -the DLL from the set of possible DLLs.

                  - -
                  7. -

                7. If there are no DLLs -that meet the requirements, the load fails.

                  8. -

                8. If you do not specify -a version number in RLibrary::Load(), the loader loads -the DLL with the highest version. A version N.n is higher -than version M.m, if (N>M or (N==M and n>m)).

                  9. -

                9. If all DLLs have the -same version, the loader loads the DLL found first.

                  10. -
                + + + + + +Loader +Search RulesThis topic provides a summary of the rules that the loader follows +to search for EXEs and DLLs. +
                  +

                • Search rules for an EXE

                  • +

                • Search rules for a DLL in the import table of an EXE or another DLL

                  • +

                • Search rules for a DLL loaded from a program

                  • +
                +
                Search rules +for an EXE

                To start a new process, call RProcess::Create().

                RProcess::Create() loads +the EXE specified in the input parameters. The function then looks through +the import table of the EXE to get a list of DLLs that the EXE references. +The loader uses the list of DLLs in the import table to load the DLLs. If +DLLs reference other DLLS, the loader uses the same method to load those DLLs. +See Search +rules for a DLL listed in the import table of an EXE.

                The result +of a search for an EXE depends on:

                  +

                • the name of the EXE. +You provide this information.

                  • +

                • the UID type : you provide. +This is optional

                  • +

                • the version of the EXEs +on the device

                  • +

                You pass the name of the EXE in the first parameter of RProcess::Create(). +You have a number of choices:

                  +

                • you can specify the +file name only. The loader will assume a .exe file extension. +For example:

                  efile

                  • +

                • you can specify a filename +and an extension. For example:

                  efile.exe

                  • +

                • you can put a path in +front of the file name. A path has limited use, because the loader can load +EXEs only from the directory \sys\bin, or from subdirectories +of \sys\bin.

                  • +

                The +search procedure

                The loader searches for EXEs with the given name +and extension. More than one EXE with the given name and extension can exist +on a device.

                  +

                1. If you do not provide +a path, the loader searches the \sys\bin directory on +all drives. The loader searches drives in the order Y:, X: ... B:, A:. The Z: drive is searched last. Subdirectories of \sys\bin are +not searched.

                  If you provide a path, there are only three useful cases:

                    +

                  • to limit the search +to a specific drive. For example:

                    X:\sys\bin

                    where X: can +be one of the drives A: to Z:.

                    • +

                  • to limit the search +to a subdirectory of \sys\bin on a specific drive. For +example:

                    X:\sys\bin\aaa\bbb

                    The use +of subdirectories in \sys\bin is not common.

                    where X: +can be one of the drives A: to Z:.

                    • +

                  • to limit the search +to a subdirectory of \sys\bin on all drives. For example:

                    \sys\bin\aaa\bbb

                    The +loader searches all drives in the order Y:, X: ... B:, A:. +The Z: drive is searched last.

                    The use of subdirectories +in \sys\bin is not common.

                    • +

                  The loader cannot load EXEs from other directories, because system +security prevents it.

                  2. +

                2. The loader compares +the UID type (TUidType) of each EXE in the list with the +UID type you specify in RProcess::Create(). The UID type +is a set of three UIDs. Each UID in the UID type that you specify must match +the same UID in the UID type of the EXE. If you specify KNullUid for +any of the three UIDs in your UID type, a match is automatic.

                  3. +

                3. If the search has found +no EXEs, the load fails.

                  4. +

                4. If the search has found +one EXE only, the loader loads that EXE.

                  5. +

                5. If more than one EXE +has been found, the loader loads the EXE with the highest version. A version N.n is +higher than version M.m if (N>M or (N==M and n>m)).

                  6. +

                6. If all EXEs have the +same version, the loader loads the version found first.

                  7. +
                +
                Search rules +for a DLL in the import table of an EXE or another DLL

                After the +loader has selected the EXE, the loader loads all DLLs in the import table. +This is also called static linkage.

                The import table contains the +name and extension of each DLL. The import table also contains the version +of each DLL and the 3rd UID that identifies each DLL. The version information +is stored in the import table when the executable file is built. All DLLs +have an ordered set of three UIDs. The third UID gives a unique identity to +the DLL. See UID protection.

                The search procedure

                The search uses the following procedure +for each DLL:

                  +

                1. The loader searches +the \sys\bin directory on all drives for all DLLs that +have the filename and extension. The loader searches drives in the order Y:, X: ... B:, A:. The Z: drive is searched +last. Subdirectories of \sys\bin are not searched. The +loader searches for all versions of the DLL. If the loader finds the same +version of a DLL on more than one drive, the loader only adds the first one +to the set of possible DLLs. For example, if version 2.1 of a DLL is on drive D: and +on drive Z:, only the version on drive D: is +added to the set of possible DLLs.

                  The loader cannot load DLLs from +other directories, because system security prevents it.

                  [Before December +2007, the loader had different behaviour. The loader searched the drive from +which the EXE was loaded before the loader checked the other drives. For example, +if the EXE was loaded from drive Z:, and version 2.1 +of a DLL was on drive D: and drive Z:, +the loader selected the version of the DLL that was on drive Z:.]

                  2. +

                2. The loader then selects +those DLLs that have the same 3rd UID from the set of possible DLLs. This +operation can decrease the set of possible DLLs. If there are no DLLs in the +set, the load fails.

                  3. +

                3. The loader then selects +those DLLs that have platform security capabilities that match or exceed those +of the EXE. This selection operation can decrease the set of possible DLLs. +If there are no DLLs in the set the load fails.

                  See also : Platform +security.

                  4. +

                4. Each DLL in the import +table of the EXE has a version number. This number is the version of the DLL +to which the EXE is linked. The loader uses the version number in the import +table to select the correct version of the DLL. The following flowchart shows +how the loader selects the DLL from the set of possible DLLs.

                  + +
                  5. +

                5. If there are no DLLs +that meet the requirements, the load fails.

                  6. +
                +
                Search rules +for a DLL loaded from a program

                To load a DLL from a program, call RLibrary::Load(). +This is known as dynamic linking.

                RLibrary::Load() loads +the DLL specified in the input parameters. The function then uses the import +table to get a list of referred DLLs. The loader loads the DLLs in the list +and uses the same search method that the loader uses for EXEs. See Search rules for a DLL in the import table of an EXE.

                The +result of a search for an DLL depends on:

                  +

                • the name of the DLL. +You provide this information.

                  • +

                • the UID type : you provide. +This is optional.

                  • +

                • the required version +: you provide. This is optional.

                  • +

                • the version of the DLLs +on the device.

                  • +

                You pass the name of the DLL in the first parameter of RLibrary::Load(). +You have a number of choices:

                  +

                • you can specify the +file name only. The loader will assume a .dll file extension. +For example:

                  efsrv

                  • +

                • you can specify a filename +and an extension. For example:

                  efsrv.dll

                  • +

                • you can put a path in +front of the file name. A path has limited use, because the loader can load +DLLs only from the directory \sys\bin, or from subdirectories +of \sys\bin.

                  • +

                See Dynamically +loading link libraries and Using +ECom.

                The +search procedure

                The loader searches for DLLs with the given name +and extension. More than one DLL with the given name and extension can exist +on a device.

                  +

                1. If you do not provide +a path, the loader searches the \sys\bin directory on +all drives. The loader searches drives in the order Y:, X: ... B:, A:. The Z: drive is searched last. Subdirectories of \sys\bin are +not searched.

                  If you provide a path, there are only three useful cases:

                    +

                  • to limit the search +to a specific drive. For example:

                    X:\sys\bin

                    where X: can +be one of the drives A: to Z:.

                    • +

                  • to limit the search +to a subdirectory of \sys\bin on a specific drive. For +example:

                    X:\sys\bin\aaa\bb

                    The use +of subdirectories in \sys\bin is not common.

                    where X: can +be one of the drives A: to Z:.

                    • +

                  • to limit the search +to a subdirectory of \sys\bin on all drives. For example:

                    \sys\bin\aaa\bbb

                    The +loader searches all drives in the order Y:, X: ... B:, A:. +The Z: drive is searched last.

                    The use of subdirectories +in \sys\bin is not common.

                    • +

                  System security prevents the loader from loading DLLs from any other +directories.

                  2. +

                2. The loader compares +the UID type (TUidType) of each DLL in the list with the +UID type you specify in RLibrary::Load(). The UID type +is a set of three UIDs. Each UID in the UID type that you specify must match +the same UID in the UID type of the DLL. If you specify KNullUid for +any of the three UIDs in your UID type, there is a match.

                  3. +

                3. If the search has found +no DLLs, the load fails.

                  4. +

                4. The loader then selects +those DLLs that have platform security capabilities that match or exceed those +of the process . This selection operation can decrease the set of possible +DLLs. If there are no DLLs in the set the load fails.

                  5. +

                5. If the search has found +no DLLs, the load fails.

                  6. +

                6. If you specify a version +number in RLibrary::Load(), the loader selects a version +of the DLL from the set. The following flowchart shows how the loader selects +the DLL from the set of possible DLLs.

                  + +
                  7. +

                7. If there are no DLLs +that meet the requirements, the load fails.

                  8. +

                8. If you do not specify +a version number in RLibrary::Load(), the loader loads +the DLL with the highest version. A version N.n is higher +than version M.m, if (N>M or (N==M and n>m)).

                  9. +

                9. If all DLLs have the +same version, the loader loads the DLL found first.

                  10. +
                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D8D65830-CC9D-4E9F-A206-34BB077E89E6-master.png Binary file Symbian3/SDK/Source/GUID-D8D65830-CC9D-4E9F-A206-34BB077E89E6-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D8D65830-CC9D-4E9F-A206-34BB077E89E6_d0e51851_href.png Binary file Symbian3/SDK/Source/GUID-D8D65830-CC9D-4E9F-A206-34BB077E89E6_d0e51851_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D8D65830-CC9D-4E9F-A206-34BB077E89E6_d0e57458_href.png Binary file Symbian3/SDK/Source/GUID-D8D65830-CC9D-4E9F-A206-34BB077E89E6_d0e57458_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D8D65830-CC9D-4E9F-A206-34BB077E89E6_d0e58489_href.png Binary file Symbian3/SDK/Source/GUID-D8D65830-CC9D-4E9F-A206-34BB077E89E6_d0e58489_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D8D65830-CC9D-4E9F-A206-34BB077E89E6_d0e62511_href.png Binary file Symbian3/SDK/Source/GUID-D8D65830-CC9D-4E9F-A206-34BB077E89E6_d0e62511_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D8D65830-CC9D-4E9F-A206-34BB077E89E6_d0e69091_href.png Binary file Symbian3/SDK/Source/GUID-D8D65830-CC9D-4E9F-A206-34BB077E89E6_d0e69091_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D8D65830-CC9D-4E9F-A206-34BB077E89E6_d0e74234_href.png Binary file Symbian3/SDK/Source/GUID-D8D65830-CC9D-4E9F-A206-34BB077E89E6_d0e74234_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.dita --- a/Symbian3/SDK/Source/GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-D93978BE-11A3-5CE3-B110-1DEAA5AD566C.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,166 +1,166 @@ - - - - - -The -ScreenPlay Graphics ArchitectureThis topic provides an introduction to ScreenPlay and its architecture. -ScreenPlay is a new graphics architecture, introduced in Symbian^3 (S^3). -ScreenPlay enables device creators to take advantage of improved software -performance, hardware acceleration and third party graphics engines. ScreenPlay -is sometimes known as the New Graphics Architecture (NGA). -

                ScreenPlay is a response to new requirements and developments in device -hardware models. For example, ScreenPlay can support graphics accelerators -and graphics processing units (GPUs) and non-uniform memory models as well -as uniform memory models. A non-uniform memory model is an architecture in -which a GPU has a completely different processing area from the CPU such that -the GPU memory is not available to the CPU and vice versa. ScreenPlay can -handle non-uniform memory models without the need to copy buffers between -the different processing areas.

                -
                Key features
                  -

                • Asynchronous hardware-accelerated -rendering and composition on devices on which dedicated graphics acceleration -hardware is available. This is achieved through a Hardware Adaptation Layer -(HAL).

                  • -

                • The ability to composit -a semi-transparent UI buffer over highly dynamic content, such as OpenGL ES -games, video and the camera viewfinder.

                  • -

                • The separation of control -and data flow. This has advantages when running on non-uniform memory architectures -and means that video decoding, UI rendering, and so on can take place and -remain in the GPU memory domain.

                  • -

                • A foundation for secure -screen content and Digital Rights Management (DRM). Applications no longer -have direct access to the screen. Read and write access to the screen is controlled -by the Window Server.

                  • -

                • Direct Screen Access -(DSA) is supported in order to provide backwards compatibility. However, because -in ScreenPlay the screen is no longer controlled by the Screen Driver, the -DSA frame buffer is just another buffer that can be allocated dynamically -on demand. ScreenPlay provides alternatives to DSA.

                  • -
                -
                Architecture

                The -following diagram shows the key components in the Symbian Foundation Graphics -package and some closely related components in other packages.

                - Symbian^3 component architecture - -

                The key ScreenPlay components are introduced below under separate -subheadings.

                -
                Graphics Composition

                The -composition engine composes content, possibly from several different sources, -before it is displayed on the screen. Composition involves the important concepts -of scene elements (or layers) and surfaces. Scene elements describe the geometric -position, size and orientation of items to be displayed on the screen; whereas -surfaces are pixel buffers for holding an image or part of a scene.

                The -composition engine maintains the stack of scene elements and computes what -is visible. For example, it culls invisible areas and maintains a list of -dirty rectangles. It blends the pixels if necessary and can perform limited -transformations, such as scaling and rotation (in 90° increments). The composition -engine is an adaptation component, which means that device creators -can adapt or replace it to suit the exact hardware on the device. The composition -engine can utilize GPU hardware composition and LCD hardware rotation if they -are available.

                The composition components are specific to ScreenPlay. -For more information, see Graphics -Composition.

                -
                Surface Manager -and Surface Update Server

                The Surface Manager component creates -and manages graphics composition surfaces. The Surface Manager reference implementation -implements surfaces as shared chunks because they must be accessible by user-side -processes and the kernel and composition hardware. Surfaces can be multi-buffered -and are identified by a 128 bit identifier (called the surface ID). This gets -resolved to an actual memory address by calling the Surface Manager Map Surface -API. Surfaces can be used by other Symbian components such as the Multimedia -Framework (MMF) and ECam -viewfinder and by applications such as OpenGL ES games. The Surface -Manager is an adaptation component and so can be adapted or replaced to suit -the hardware.

                The Surface Update component provides a communication -mechanism between the composition engine and clients. This is particularly -useful for clients (such as video) that produce fast updates and use multi-buffered -surfaces.

                -
                Window Server

                The -Window Server has been extended with a render stage framework, which enables -the last stage of the Window Server rendering to be customizable through render -stage plug-ins. This process, known as "deferred rendering" is achieved by -intercepting the output of the Window Server and then deciding how that output -should be rendered. For example, the output can be hardware accelerated or -it can be sent to a third party graphics engine. The render stage framework -enables device creators to integrate different UIs and runtime environments -(such as Flash or Silverlight) and to achieve transition effects such as slide, -zoom and fade.

                Symbian provides more than one render stage solution. -The following diagram provides a simplified representation of one possible -solution (called solution A in this topic). This solution is full featured. -The diagram focuses on the more relevant components and does not attempt to -show all components in the complete solution. This solution has a dependency -on the S60 middleware layer, in particular on the Hitchcock component (which -is in the UI Accelerator package).

                - Render stage solution A - -

                Another possible solution (called solution B) is based on -the DirectGDI and Graphics Resource components (which are described next), -both of which have interface and adaptation layers. This solution is not full -featured. Like the previous diagram, this diagram focuses on the more relevant -components and does not attempt to show everything.

                -Render stage solution B - -

                Both of these render stage solutions mean that existing Window Server -applications can take advantage of hardware acceleration if it is available -(and therefore run faster) without recompiling the code.

                ScreenPlay -provides extensions to the Window Server client-side API, which enable mobile -devices to respond to events from a number of pointers, including their proximity -and pressure. This feature is known as advanced -pointers.

                A new API, RWsSession::Finish(), -has been added to allow Window Server client applications to synchronize with -the completion of Window Server rendering. The existing API, RWsSession::Flush(), -is redefined to simply flush the client-side command buffer, whereas previously -it also provided a guarantee that Window Server had completed the command -buffer’s operations. This behavioral change allows legacy clients to benefit -from the asynchronous hardware rendering when supported by the render stage -plug-in(s) that are in use.

                For more information, see Windowing -Collection.

                -
                DirectGDI

                DirectGDI -provides a graphics context that can be hardware accelerated and allows an -asynchronous interface. DirectGDI has two parts: a generic layer, which provides -a client API and an adaptation layer. Device creators can replace the adaptation -layer with an implementation that takes advantage of graphics accelerated -hardware, if it is available, or a software implementation, if it is not available.

                DirectGDI -was introduced as a prototype in the development of ScreenPlay. It is deprecated -in Symbian^3.

                -
                Graphics Resource

                The -Graphics Resource component provides an abstraction layer for the memory management -of pixel and non-pixel data (such as OpenVG command lists). Like DirectGDI, -it has a generic part, which provides a client API and an adaptation part, -which device creators can adapt to take advantage of graphics hardware when -it is available.

                The Graphics Resource component was introduced as -a prototype in the development of ScreenPlay. It is deprecated in Symbian^3 -and will be removed in Symbian^4. However, a new Graphics Resource Interface -component is planned for S^4. This new component will provide a similar but -reduced API that is optimized for sharing images across processes.

                -
                OpenVG, OpenGL -ES and EGL

                Symbian provides support for OpenVG, OpenGL ES and EGL. -The main advantage of ScreenPlay with regard to EGL is that EGL can render -into composition surfaces. For application developers this offers the ability -to have semi-transparent GDI content on top of EGL content. The EGL client -can query whether these new features are supported on the particular device.

                For -more information, see Khronos -API Support.

                -
                Screen Driver

                In -ScreenPlay, the implementation of the Screen Driver has been changed so that -DSA content can be passed into the composition engine.

                -                 -Graphics -Composition -Graphics -Hardware Acceleration -Graphics -Concepts - - - - + + + + + +The +ScreenPlay Graphics ArchitectureThis topic provides an introduction to ScreenPlay and its architecture. +ScreenPlay is a new graphics architecture, introduced in Symbian^3 (S^3). +ScreenPlay enables device creators to take advantage of improved software +performance, hardware acceleration and third party graphics engines. ScreenPlay +is sometimes known as the New Graphics Architecture (NGA). +

                ScreenPlay is a response to new requirements and developments in device +hardware models. For example, ScreenPlay can support graphics accelerators +and graphics processing units (GPUs) and non-uniform memory models as well +as uniform memory models. A non-uniform memory model is an architecture in +which a GPU has a completely different processing area from the CPU such that +the GPU memory is not available to the CPU and vice versa. ScreenPlay can +handle non-uniform memory models without the need to copy buffers between +the different processing areas.

                +
                Key features
                  +

                • Asynchronous hardware-accelerated +rendering and composition on devices on which dedicated graphics acceleration +hardware is available. This is achieved through a Hardware Adaptation Layer +(HAL).

                  • +

                • The ability to composit +a semi-transparent UI buffer over highly dynamic content, such as OpenGL ES +games, video and the camera viewfinder.

                  • +

                • The separation of control +and data flow. This has advantages when running on non-uniform memory architectures +and means that video decoding, UI rendering, and so on can take place and +remain in the GPU memory domain.

                  • +

                • A foundation for secure +screen content and Digital Rights Management (DRM). Applications no longer +have direct access to the screen. Read and write access to the screen is controlled +by the Window Server.

                  • +

                • Direct Screen Access +(DSA) is supported in order to provide backwards compatibility. However, because +in ScreenPlay the screen is no longer controlled by the Screen Driver, the +DSA frame buffer is just another buffer that can be allocated dynamically +on demand. ScreenPlay provides alternatives to DSA.

                  • +
                +
                Architecture

                The +following diagram shows the key components in the Symbian Foundation Graphics +package and some closely related components in other packages.

                + Symbian^3 component architecture + +

                The key ScreenPlay components are introduced below under separate +subheadings.

                +
                Graphics Composition

                The +composition engine composes content, possibly from several different sources, +before it is displayed on the screen. Composition involves the important concepts +of scene elements (or layers) and surfaces. Scene elements describe the geometric +position, size and orientation of items to be displayed on the screen; whereas +surfaces are pixel buffers for holding an image or part of a scene.

                The +composition engine maintains the stack of scene elements and computes what +is visible. For example, it culls invisible areas and maintains a list of +dirty rectangles. It blends the pixels if necessary and can perform limited +transformations, such as scaling and rotation (in 90° increments). The composition +engine is an adaptation component, which means that device creators +can adapt or replace it to suit the exact hardware on the device. The composition +engine can utilize GPU hardware composition and LCD hardware rotation if they +are available.

                The composition components are specific to ScreenPlay. +For more information, see Graphics +Composition.

                +
                Surface Manager +and Surface Update Server

                The Surface Manager component creates +and manages graphics composition surfaces. The Surface Manager reference implementation +implements surfaces as shared chunks because they must be accessible by user-side +processes and the kernel and composition hardware. Surfaces can be multi-buffered +and are identified by a 128 bit identifier (called the surface ID). This gets +resolved to an actual memory address by calling the Surface Manager Map Surface +API. Surfaces can be used by other Symbian components such as the Multimedia +Framework (MMF) and ECam +viewfinder and by applications such as OpenGL ES games. The Surface +Manager is an adaptation component and so can be adapted or replaced to suit +the hardware.

                The Surface Update component provides a communication +mechanism between the composition engine and clients. This is particularly +useful for clients (such as video) that produce fast updates and use multi-buffered +surfaces.

                +
                Window Server

                The +Window Server has been extended with a render stage framework, which enables +the last stage of the Window Server rendering to be customizable through render +stage plug-ins. This process, known as "deferred rendering" is achieved by +intercepting the output of the Window Server and then deciding how that output +should be rendered. For example, the output can be hardware accelerated or +it can be sent to a third party graphics engine. The render stage framework +enables device creators to integrate different UIs and runtime environments +(such as Flash or Silverlight) and to achieve transition effects such as slide, +zoom and fade.

                Symbian provides more than one render stage solution. +The following diagram provides a simplified representation of one possible +solution (called solution A in this topic). This solution is full featured. +The diagram focuses on the more relevant components and does not attempt to +show all components in the complete solution. This solution has a dependency +on the S60 middleware layer, in particular on the Hitchcock component (which +is in the UI Accelerator package).

                + Render stage solution A + +

                Another possible solution (called solution B) is based on +the DirectGDI and Graphics Resource components (which are described next), +both of which have interface and adaptation layers. This solution is not full +featured. Like the previous diagram, this diagram focuses on the more relevant +components and does not attempt to show everything.

                +Render stage solution B + +

                Both of these render stage solutions mean that existing Window Server +applications can take advantage of hardware acceleration if it is available +(and therefore run faster) without recompiling the code.

                ScreenPlay +provides extensions to the Window Server client-side API, which enable mobile +devices to respond to events from a number of pointers, including their proximity +and pressure. This feature is known as advanced +pointers.

                A new API, RWsSession::Finish(), +has been added to allow Window Server client applications to synchronize with +the completion of Window Server rendering. The existing API, RWsSession::Flush(), +is redefined to simply flush the client-side command buffer, whereas previously +it also provided a guarantee that Window Server had completed the command +buffer’s operations. This behavioral change allows legacy clients to benefit +from the asynchronous hardware rendering when supported by the render stage +plug-in(s) that are in use.

                For more information, see Windowing +Collection.

                +
                DirectGDI

                DirectGDI +provides a graphics context that can be hardware accelerated and allows an +asynchronous interface. DirectGDI has two parts: a generic layer, which provides +a client API and an adaptation layer. Device creators can replace the adaptation +layer with an implementation that takes advantage of graphics accelerated +hardware, if it is available, or a software implementation, if it is not available.

                DirectGDI +was introduced as a prototype in the development of ScreenPlay. It is deprecated +in Symbian^3.

                +
                Graphics Resource

                The +Graphics Resource component provides an abstraction layer for the memory management +of pixel and non-pixel data (such as OpenVG command lists). Like DirectGDI, +it has a generic part, which provides a client API and an adaptation part, +which device creators can adapt to take advantage of graphics hardware when +it is available.

                The Graphics Resource component was introduced as +a prototype in the development of ScreenPlay. It is deprecated in Symbian^3 +and will be removed in Symbian^4. However, a new Graphics Resource Interface +component is planned for S^4. This new component will provide a similar but +reduced API that is optimized for sharing images across processes.

                +
                OpenVG, OpenGL +ES and EGL

                Symbian provides support for OpenVG, OpenGL ES and EGL. +The main advantage of ScreenPlay with regard to EGL is that EGL can render +into composition surfaces. For application developers this offers the ability +to have semi-transparent GDI content on top of EGL content. The EGL client +can query whether these new features are supported on the particular device.

                For +more information, see Khronos +API Support.

                +
                Screen Driver

                In +ScreenPlay, the implementation of the Screen Driver has been changed so that +DSA content can be passed into the composition engine.

                +                 +Graphics +Composition +Graphics +Hardware Acceleration +Graphics +Concepts + + + +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D96EE819-DEA9-5B1A-AA94-4AC065C73697.dita --- a/Symbian3/SDK/Source/GUID-D96EE819-DEA9-5B1A-AA94-4AC065C73697.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-D96EE819-DEA9-5B1A-AA94-4AC065C73697.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,37 +1,37 @@ - - - - - -Array -of same length elements, segmented bufferDescribes how elements of the same length are organised in the -array buffer. -

                This is a CArrayFixSeg<class T> object whose elements:

                -
                  -

                • all have the same length

                  • -

                • are contained within -a segmented array buffer; the elements are logically contiguous but are physically -contiguous only within a segment.

                  • -
                -

                A segmented buffer is implemented as a doubly linked list of equally sized -cells allocated from the heap and is always extended by allocating a new segment -and inserting it into the appropriate place in the list. A segmented array -buffer is implemented using a CBufSeg object.

                -

                The following diagram illustrates how elements are organised within the -array buffer:

                - - - -

                This kind of array is suitable for large arrays with a high -turnover of elements.

                -

                This class is immediately derived from the abstract template base class CArrayFix<class T> which -is itself derived from the abstract non-templated base class CArrayFixBase.

                -
                See also

                Using -Dynamic Buffers.

                + + + + + +Array +of same length elements, segmented bufferDescribes how elements of the same length are organised in the +array buffer. +

                This is a CArrayFixSeg<class T> object whose elements:

                +
                  +

                • all have the same length

                  • +

                • are contained within +a segmented array buffer; the elements are logically contiguous but are physically +contiguous only within a segment.

                  • +
                +

                A segmented buffer is implemented as a doubly linked list of equally sized +cells allocated from the heap and is always extended by allocating a new segment +and inserting it into the appropriate place in the list. A segmented array +buffer is implemented using a CBufSeg object.

                +

                The following diagram illustrates how elements are organised within the +array buffer:

                + + + +

                This kind of array is suitable for large arrays with a high +turnover of elements.

                +

                This class is immediately derived from the abstract template base class CArrayFix<class T> which +is itself derived from the abstract non-templated base class CArrayFixBase.

                +
                See also

                Using +Dynamic Buffers.

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D99BA4CA-9823-4968-953D-36AA7F266B39_d0e10779_href.png Binary file Symbian3/SDK/Source/GUID-D99BA4CA-9823-4968-953D-36AA7F266B39_d0e10779_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D99BA4CA-9823-4968-953D-36AA7F266B39_d0e12054_href.png Binary file Symbian3/SDK/Source/GUID-D99BA4CA-9823-4968-953D-36AA7F266B39_d0e12054_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D9C4D520-821D-5097-A63C-0BF4C7F59827_d0e267518_href.png Binary file Symbian3/SDK/Source/GUID-D9C4D520-821D-5097-A63C-0BF4C7F59827_d0e267518_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D9C4D520-821D-5097-A63C-0BF4C7F59827_d0e271226_href.png Binary file Symbian3/SDK/Source/GUID-D9C4D520-821D-5097-A63C-0BF4C7F59827_d0e271226_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D9F3D83E-50C7-4D15-839C-F225D95865B0-master.png Binary file Symbian3/SDK/Source/GUID-D9F3D83E-50C7-4D15-839C-F225D95865B0-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D9F3D83E-50C7-4D15-839C-F225D95865B0_d0e51973_href.png Binary file Symbian3/SDK/Source/GUID-D9F3D83E-50C7-4D15-839C-F225D95865B0_d0e51973_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D9F3D83E-50C7-4D15-839C-F225D95865B0_d0e57605_href.png Binary file Symbian3/SDK/Source/GUID-D9F3D83E-50C7-4D15-839C-F225D95865B0_d0e57605_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D9F3D83E-50C7-4D15-839C-F225D95865B0_d0e69180_href.png Binary file Symbian3/SDK/Source/GUID-D9F3D83E-50C7-4D15-839C-F225D95865B0_d0e69180_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D9F3D83E-50C7-4D15-839C-F225D95865B0_d0e74346_href.png Binary file Symbian3/SDK/Source/GUID-D9F3D83E-50C7-4D15-839C-F225D95865B0_d0e74346_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-D9F8B338-5CFA-472F-8A16-B5251B1B5A81.dita --- a/Symbian3/SDK/Source/GUID-D9F8B338-5CFA-472F-8A16-B5251B1B5A81.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,15 +0,0 @@ - - - - - -Changes -and release information -

                The Toolbar API is an SDK API and first released in S60 5th Edition.

                -                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DA070DA3-CE2E-5B4E-834F-32BED736E01D_d0e79469_href.png Binary file Symbian3/SDK/Source/GUID-DA070DA3-CE2E-5B4E-834F-32BED736E01D_d0e79469_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DA070DA3-CE2E-5B4E-834F-32BED736E01D_d0e86181_href.png Binary file Symbian3/SDK/Source/GUID-DA070DA3-CE2E-5B4E-834F-32BED736E01D_d0e86181_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DA1D89FF-52BD-5876-B7A1-300F5EBB9884.dita --- a/Symbian3/SDK/Source/GUID-DA1D89FF-52BD-5876-B7A1-300F5EBB9884.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-DA1D89FF-52BD-5876-B7A1-300F5EBB9884.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,13 +1,41 @@ - - - - - -Converting Manual Aperture to Automatic ApertureThis topic explains how to prepare the camera for the automatic aperture setting. By default, the automatic aperture setting is used if no manual aperture value has been given.

                Before you start you should understand the Onboard Camera Overview topic.

                The automatic aperture setting is implementation specific as to whether the default aperture is auto-aperture or any other value. If the camera cannot determine the aperture value being used, the KErrNotFound error is returned.

                Pass KUidECamEvent2CameraSettingAutoAperture as a value to TECAMEvent2 to notify the camera that the auto aperture setting is to be used. TECAMEvent2::iParam() represents the actual numerical value of aperture being used for the the auto aperture setting. Use the KUidECamEvent2CameraSettingAutoAperture value when you do not specify an aperture value in the CCameraAdvancedSettings::SetAperture(TInt) function or when you select exposure to the EExposureAuto or EExposureShutterPriority value. Note: By default CCamera has an automatic aperture setting .                 Advanced Settings for Focus, Drive Modes, and - Bracket Modes                 \ No newline at end of file + + + + + +Converting +Manual Aperture to Automatic ApertureThis topic explains how to prepare the camera for the automatic +aperture setting. By default, the automatic aperture setting is used if no +manual aperture value has been given. +

                Before you start +you should understand the Onboard +Camera Overview topic.

                +

                The automatic aperture +setting is implementation specific as to whether the default aperture is auto-aperture +or any other value. If the camera cannot determine the aperture value being +used, the KErrNotFound error is returned.

                + + +Pass KUidECamEvent2CameraSettingAutoAperture as a +value to TECAMEvent2 to notify the camera that the auto +aperture setting is to be used. TECAMEvent2::iParam represents +the actual numerical value of aperture being used for the auto aperture setting. + + +Use the KUidECamEvent2CameraSettingAutoAperture value +when you do not specify an aperture value in the CCameraAdvancedSettings::SetAperture(TInt) function +or when you select exposure to the EExposureAuto or EExposureShutterPriority value. +Note: By default CCamera has an automatic aperture +setting . + + +                 +Advanced +Settings for Focus, Drive Modes, and Bracket Modes +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DA26D246-D74A-529F-9F81-11B45669103F.dita --- a/Symbian3/SDK/Source/GUID-DA26D246-D74A-529F-9F81-11B45669103F.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,12 +0,0 @@ - - - - - - Capturing Image

                This document introduces to the image capture feature of the Ecam component.

                Purpose

                This document takes you through a series of documents that provides a detailed explanation on various tasks that can be performed using still image.

                Setup and Configuration Requirement

                Make sure that you use continuous drive mode before capturing the images.

                Get the options supported for a specific reference orientation of the camera using CCamera::CCameraImageProcessing::GetSupportedRelativeOrientationOptionsL method.

                Get the options that is currently used for the orientation reference using CCameraImageProcessing::GetCurrentRelativeOrientationOptionsL method.

                Set the specific option to be used with the orientation reference using CCameraImageProcessing::SetRelativeOrientationOptionsL method. Notify the client about relative custom orientation setting operation using event KUidECamEventImageProcessingTransformRelativeOrientation.

                Basic camera image settings

                CCamera provides functions that allow you to alter the brightness, contrast, and zoom level of the camera image. Before using such functions though, you should test that the camera supports what you want. To do this, get a TCameraInfo object using the CameraInfo() method. The object's iOptionsSupported member is a bitfield of flags that describe which options are supported by the camera.

                Brightness

                To change the camera image brightness:

                1. Check if brightness control is supported, by testing if the TCameraInfo::EBrightnessSupported flag is set in the options.

                2. Set the brightness using CCamera::SetBrightnessL().

                  The brightness should be in the range -100 to +100, or to set the brightness automatically, use the flag CCamera::EBrightnessAuto.

                Contrast

                To change the camera image contrast:

                1. Check if contrast control is supported, by testing if the TCameraInfo::EContrastSupported flag is set in the options.

                2. Set the contrast using CCamera::SetContrastL().

                  The contrast should be in the range -100 to +100, or to set the contrast automatically, use the flag CCamera::EContrastAuto.

                Zoom

                To alter the camera zoom:

                1. Test if zoom is supported, and for what range of values, by reading the minimum and maximum zoom values from the data members in TCameraInfo. A value of zero means zoom is not supported. A step of one in the zoom value corresponds to the smallest zoom change available. The camera zoom increases linearly with the zoom value until the maximum zoom value.

                  A separate set of values is available for zoom and for digital zoom. TCameraInfo also has members that say what is the actual zoom factor when at minimum (non-digital only) and maximum zoom.

                2. Set the zoom using CCamera::SetDigitalZoomFactorL() or CCamera::SetZoomFactorL().

                Image format

                Before a client application captures still, or video, it can first specify the required image format. There may be complicated dependencies between frame sizes and formats, so the required format must be specified as follows:

                1. Select the format from those available from either the TCameraInfo::iImageFormatsSupported or the TCameraInfo::iVideoFrameFormatsSupported bitfield, for still or video images respectively.

                2. Select the required size using either CCamera::EnumerateCaptureSizes() or CCamera::EnumerateVideoFrameSizes() for still or video images respectively. Note that not all possible sizes are guaranteed to be supported for any given format. Unsupported sizes will be returned as (0,0).

                3. For video capture, select the frame rate using CCamera::EnumerateVideoFrameRates(). Again, not all rates are guaranteed to be supported, as dependencies may exist in the camera between the format, size, exposure mode and rate.

                Image Capture

                The Image Capture API allows you to do the following tasks:

                • Pre-image capture control

                • Capturing image

                • Post-image capture control

                • Control of burst image capture

                See also

                Accessing and Power Control of Camera

                Camera Preset Support

                Controlling Pre-Image Capture

                Controlling Still-image Capture

                Controlling Captured Image

                Using Time-Nudge-Capture Drive Mode

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DA2C605B-6CCF-4039-BD02-DD4BDA003C97_d0e41499_href.png Binary file Symbian3/SDK/Source/GUID-DA2C605B-6CCF-4039-BD02-DD4BDA003C97_d0e41499_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DA2C605B-6CCF-4039-BD02-DD4BDA003C97_d0e47056_href.png Binary file Symbian3/SDK/Source/GUID-DA2C605B-6CCF-4039-BD02-DD4BDA003C97_d0e47056_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DA37516F-874F-49B0-A176-73277BB86FD3.dita --- a/Symbian3/SDK/Source/GUID-DA37516F-874F-49B0-A176-73277BB86FD3.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,16 +0,0 @@ - - - - - -Changes -and release information -

                The Title pane touch observer API is an SDK API and first released in S60 -5th Edition.

                -                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DAB4EE70-5F84-5AFA-B95B-A433695251F8.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-DAB4EE70-5F84-5AFA-B95B-A433695251F8.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,39 @@ + + + + + +Simple: +simple window system +
                Description

                Simple creates +two windows: a main window which has nothing drawn to it, and a smaller window +with a border and two diagonal lines. The main window is the parent of the +smaller window.

                +
                Download

                Click +on the following link to download the example: simple.zip

                Click: browse to view the example code.

                +
                Classes defined
                  +

                • CMainWindow: +An empty window. Just draws itself.

                  • +

                • CSmallWindow: +A small window which draws itself with a square border around the edges of +the window, and two diagonal lines between the corners.

                  • +

                • CExampleWsClient: +Derived from CWsClient. Owns the CMainWindow and +the CSmallWindow. Processes key and pointer events.

                  • +
                +
                Class Summary

                RWsSession

                RWindowGroup

                CWindowGc

                CWsScreenDevice

                TRect

                RWindowHandle

                TWsEvent

                +
                Types used
                  +

                • CWindowGc: +Window graphics context. Required when drawing to a window.

                  • +

                • struct TPointerEvent: +Pointer event details

                  • +

                • struct TKeyEvent: +Key event details

                  • +
                +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DAB7AB0C-8B32-4472-8EDC-AA8A5A01205C-master.png Binary file Symbian3/SDK/Source/GUID-DAB7AB0C-8B32-4472-8EDC-AA8A5A01205C-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DAB7AB0C-8B32-4472-8EDC-AA8A5A01205C_d0e58905_href.png Binary file Symbian3/SDK/Source/GUID-DAB7AB0C-8B32-4472-8EDC-AA8A5A01205C_d0e58905_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DAB7AB0C-8B32-4472-8EDC-AA8A5A01205C_d0e59307_href.png Binary file Symbian3/SDK/Source/GUID-DAB7AB0C-8B32-4472-8EDC-AA8A5A01205C_d0e59307_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DAC32BB9-C0EB-42FF-A596-C2F1A90A4BD7.dita --- a/Symbian3/SDK/Source/GUID-DAC32BB9-C0EB-42FF-A596-C2F1A90A4BD7.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-DAC32BB9-C0EB-42FF-A596-C2F1A90A4BD7.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,85 +1,85 @@ - - - - - -Views -

                The term view refers to the MVC -design (Model-View-Controller) component that has the following attributes:

                -
                  -

                • displays the application state known by the application

                  -
                  • -

                • receives user input

                  • -

                • is owned by the UI -controller

                  • -

                • observes application state changes either directly or through -the UI controller and updates the screen accordingly

                  • -
                -

                In practice, views are collections of interface elements, such as controls, -menus, command button areas (CBAs), key events, that make up one top-level -window in an application. Applications may have one or more views. If an application -has more than one view and if the status pane behavior is organized in this -manner, then each view in an application can have its own tab. Applications -can have only a single view active at any one time. The current view is the -view that interacts with the user, receiving events and menu choices as if -it were the only set of UI elements.

                -

                Multiple view architectures are widely used in application development -on the Symbian platform. Multiple view architectures:

                -
                  -

                • provide developers with an efficient way to build multiple -views within an application and switch between them easily and simply.

                  -
                  • -

                • allow applications to bundle their user interface requirements -into a single element (a view). The view architecture then provides the capability -to switch quickly between the views.

                  • -

                • allow applications to take advantage of object orientation -to encapsulate code, keeping it simple and clear.

                  • -

                • provide the ability for one application to activate the view -of another. This is particularly useful when you want to use an existing display -or editing capability without going to the expense of integrating a component -into your application.

                  • -

                • allow applications to register views, with one view being -active in each running application at any one time. It does not dictate what -a view is; however, it does provide support for a view being a display page -on the screen

                  • -
                -Controller-view hierarchy in traditional and Symbian architectures -

                In practice, the view concept varies depending upon your chosen architecture -approach:

                -
                Traditional architecture -views -

                In a traditional architecture, the view is derived from CCoeControl, -which typically constructs a top-level window-owning control that draws itself -and contains other controls.

                -

                For more information on views in tradition architecture approaches, -see Traditional -Symbian UI application architecture.

                -
                -
                Symbian architecture -views -

                In Symbian view architecture, a view controller is added between the UI controller and -the view that draws itself and contains other controls. For example, view -controllers can be used to specify CBAs that are specific to specific views.

                -

                In a Symbian architecture, the view controller is derived from CAknView, -which is derived directly from CBase and not from CCoeControl. -This means the CAknView-derived views are not controls. CAknView-derived -views need to contain CCoeControl-derived classes to provide -visual representation on the display.

                -

                For more information on views in Symbian architecture approaches, see View -architecture.

                -
                -
                Dialog architecture -views -

                In dialog architectures, views are implemented in modeless dialog boxes. -Multiple views can be constructed using nested dialogs or a tabbed dialog -pane.

                -

                For more information on views in dialog architecture approaches, see Dialog -architecture.

                -
                + + + + + +Views +

                The term view refers to the MVC +design (Model-View-Controller) component that has the following attributes:

                +
                  +

                • displays the application state known by the application

                  +
                  • +

                • receives user input

                  • +

                • is owned by the UI +controller

                  • +

                • observes application state changes either directly or through +the UI controller and updates the screen accordingly

                  • +
                +

                In practice, views are collections of interface elements, such as controls, +menus, command button areas (CBAs), key events, that make up one top-level +window in an application. Applications may have one or more views. If an application +has more than one view and if the status pane behavior is organized in this +manner, then each view in an application can have its own tab. Applications +can have only a single view active at any one time. The current view is the +view that interacts with the user, receiving events and menu choices as if +it were the only set of UI elements.

                +

                Multiple view architectures are widely used in application development +on the Symbian platform. Multiple view architectures:

                +
                  +

                • provide developers with an efficient way to build multiple +views within an application and switch between them easily and simply.

                  +
                  • +

                • allow applications to bundle their user interface requirements +into a single element (a view). The view architecture then provides the capability +to switch quickly between the views.

                  • +

                • allow applications to take advantage of object orientation +to encapsulate code, keeping it simple and clear.

                  • +

                • provide the ability for one application to activate the view +of another. This is particularly useful when you want to use an existing display +or editing capability without going to the expense of integrating a component +into your application.

                  • +

                • allow applications to register views, with one view being +active in each running application at any one time. It does not dictate what +a view is; however, it does provide support for a view being a display page +on the screen

                  • +
                +Controller-view hierarchy in traditional and Symbian architectures +

                In practice, the view concept varies depending upon your chosen architecture +approach:

                +
                Traditional architecture +views +

                In a traditional architecture, the view is derived from CCoeControl, +which typically constructs a top-level window-owning control that draws itself +and contains other controls.

                +

                For more information on views in tradition architecture approaches, +see Traditional +Symbian UI application architecture.

                +
                +
                Symbian architecture +views +

                In Symbian view architecture, a view controller is added between the UI controller and +the view that draws itself and contains other controls. For example, view +controllers can be used to specify CBAs that are specific to specific views.

                +

                In a Symbian architecture, the view controller is derived from CAknView, +which is derived directly from CBase and not from CCoeControl. +This means the CAknView-derived views are not controls. CAknView-derived +views need to contain CCoeControl-derived classes to provide +visual representation on the display.

                +

                For more information on views in Symbian architecture approaches, see View +architecture.

                +
                +
                Dialog architecture +views +

                In dialog architectures, views are implemented in modeless dialog boxes. +Multiple views can be constructed using nested dialogs or a tabbed dialog +pane.

                +

                For more information on views in dialog architecture approaches, see Dialog +architecture.

                +
                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DAD40CCE-EA59-4DCA-8922-824B18F0387A.dita --- a/Symbian3/SDK/Source/GUID-DAD40CCE-EA59-4DCA-8922-824B18F0387A.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-DAD40CCE-EA59-4DCA-8922-824B18F0387A.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,27 +1,27 @@ - - - - - -Multi-selection -list query -

                A multi-selection list query is used when the user needs to be able to -select several items from a list at the same time (using Selection key to -mark/unmark the checkbox). See Multi-selection -list for a description of a multi-selection list.

                -

                The left softkey (OK) is used for accepting the query, and the right -softkey is Cancel.

                - -Multi-selection list query - - -
                Using multi-selection -list queries in C++ applications

                For implementation information, -see Queries.

                + + + + + +Multi-selection +list query +

                A multi-selection list query is used when the user needs to be able to +select several items from a list at the same time (using Selection key to +mark/unmark the checkbox). See Multi-selection +list for a description of a multi-selection list.

                +

                The left softkey (OK) is used for accepting the query, and the right +softkey is Cancel.

                + +Multi-selection list query + + +
                Using +multi-selection list queries in applications

                For implementation +information, see Queries.

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DAF35D49-9630-4186-A350-E8483693D50D.dita --- a/Symbian3/SDK/Source/GUID-DAF35D49-9630-4186-A350-E8483693D50D.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-DAF35D49-9630-4186-A350-E8483693D50D.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,135 +1,135 @@ - - - - - -Hierarchical -column list -

                Hierarchical column list is used for browsing in one view files and folders -that are in different levels in the file system. This enables for example -showing subtitles among the list items, and collapsing and expanding data -items under it.

                - -Hierarchical column list component, where the subtitle "Last week" -is expanded - - -

                The hierarchical column list can have three different row types:

                -
                  -

                • Subtitle row

                  • -

                • Core data row

                  • -

                • Simple data row

                  • -
                -

                Subtitle can have only one type of sub-items, thus both core data and simple -data items cannot exist under same subtitle. It is recommended, that only -one type of sub-items would be used in the same view.

                -

                To enable more information in a single row, the core data row can be divided -into two core data columns. The more important information should be shown -in the first column due to more space, for example e-mail sender information -in the first column, and subject in the second column. In landscape there -can be also third column in use.

                -

                General navigation:

                -

                Expanding and collapsing can be done in subtitle rows:

                -
                  -

                • Arrow key: Tabs can be used together with a hierarchical column list, -and thus arrow keys are used for moving between tabs. If there are no tabs, -the arrow keys expand subtitle item (Arrow right, the focus is not moved) -and collapse expanded subtitle item (Arrow left, focus is not moved).

                  • -

                • The Selection key expands collapsed (or vice versa) subtitle item in -focus.

                  • -

                • Commands for expanding, collapsing and opening folders or files are -also available in the Options menu.

                  • -
                -Default touch -events for hierarchical column list items - - - - - - -

                User action

                 -

                State change

                 -

                Feedback

                 -                 - - - -

                Touch down on collapsed subtitle item

                 -

                No change

                 -

                Highlight is shown.

                Tactile: Basic list effect and audio -feedback is provided with touch down event.

                 -                 - -

                Touch release on collapsed subtitle item

                 -

                Item is expanded.

                If the folder is empty, the only action -performed is that the icon is changed to expanded folder indication.

                 -

                Highlight disappears.

                Tactile: Basic list effect is provided -with touch release event

                 -                 - -

                Touch down on expanded subtitle item

                 -

                No change

                 -

                Highlight is shown.

                Tactile: Basic list effect and audio -feedback is provided with touch down event.

                 -                 - -

                Touch release on expanded subtitle item

                 -

                Item is collapsed.

                If the folder is empty, the only action -performed is that the icon is changed to collapsed folder indication.

                 -

                Highlight disappears.

                Tactile: Basic list effect is provided -with touch release event

                 -                 - -

                Touch down and hold on subtitle item

                 -

                Stylus pop-up menu is opened.

                 -

                Highlight is shown. Animation is shown to indicate the opening pop-up.

                Tactile: -If activates a long touch, then increasing long touch effect is provided with -hold event and pop-up effect is provided when the pop-up is opened.

                 -                 - -

                Touch down on data item

                 -

                No change

                 -

                Highlight is shown.

                Tactile: Sensitive list effect and audio -feedback is provided with touch down event.

                 -                 - -

                Touch release on data item

                 -

                Item is activated.

                Application specific

                 -

                Highlight shown. Tactile: Sensitive list effect is provided with -touch release event.

                 -                 - -

                Touch down and hold on data item

                 -

                Stylus pop-up menu is opened.

                 -

                Highlight is shown. Animation is shown to indicate the opening pop-up.

                Tactile: -If activates a long touch, then increasing long touch effect is provided with -hold event and pop-up effect is provided when the pop-up is opened.

                 -                 - -

                Touch down on data/subtitle item and move

                 -

                Refer to Dragging -and flicking events

                Expand and collapse functions are not done -while dragging.

                 -

                Tactile: Refer to Dragging -and flicking events.

                 -                 - -

                Touch down on data/subtitle item and move horizontally

                 -

                Inactive

                 -

                Tactile: No effect

                 -                 - - -
                -
                Using -hierarchical column lists in C++ applications

                The API to use for -hierarchical column lists is the specs/guides/Hierarchical_Lists_API_Specification/Hierarchical_Lists_API_Specification.html. -For implementation information, see Using the Hierarchical lists API.

                + + + + + +Hierarchical +column list +

                Hierarchical column list is used for browsing in one view files and folders +that are in different levels in the file system. This enables for example +showing subtitles among the list items, and collapsing and expanding data +items under it.

                + +Hierarchical column list component, where the subtitle "Today" and +"Yesterday" are expanded + + +

                The hierarchical column list can have three different row types:

                +
                  +

                • Subtitle row

                  • +

                • Core data row

                  • +

                • Simple data row

                  • +
                +

                Subtitle can have only one type of sub-items, thus both core data and simple +data items cannot exist under same subtitle. It is recommended, that only +one type of sub-items would be used in the same view.

                +

                To enable more information in a single row, the core data row can be divided +into two core data columns. The more important information should be shown +in the first column due to more space, for example e-mail sender information +in the first column, and subject in the second column. In landscape there +can be also third column in use.

                +

                General navigation:

                +

                Expanding and collapsing can be done in subtitle rows:

                +
                  +

                • Arrow key: Tabs can be used together with a hierarchical column list, +and thus arrow keys are used for moving between tabs. If there are no tabs, +the arrow keys expand subtitle item (Arrow right, the focus is not moved) +and collapse expanded subtitle item (Arrow left, focus is not moved).

                  • +

                • The Selection key expands collapsed (or vice versa) subtitle item in +focus.

                  • +

                • Commands for expanding, collapsing and opening folders or files are +also available in the Options menu.

                  • +
                +Default touch +events for hierarchical column list items + + + + + + +

                User action

                 +

                State change

                 +

                Feedback

                 +                 + + + +

                Touch down on collapsed subtitle item

                 +

                No change

                 +

                Highlight is shown.

                Tactile: Basic list effect and audio +feedback is provided with touch down event.

                 +                 + +

                Touch release on collapsed subtitle item

                 +

                Item is expanded.

                If the folder is empty, the only action +performed is that the icon is changed to expanded folder indication.

                 +

                Highlight disappears.

                Tactile: Basic list effect is provided +with touch release event

                 +                 + +

                Touch down on expanded subtitle item

                 +

                No change

                 +

                Highlight is shown.

                Tactile: Basic list effect and audio +feedback is provided with touch down event.

                 +                 + +

                Touch release on expanded subtitle item

                 +

                Item is collapsed.

                If the folder is empty, the only action +performed is that the icon is changed to collapsed folder indication.

                 +

                Highlight disappears.

                Tactile: Basic list effect is provided +with touch release event

                 +                 + +

                Touch down and hold on subtitle item

                 +

                Stylus pop-up menu is opened.

                 +

                Highlight is shown. Animation is shown to indicate the opening pop-up.

                Tactile: +If activates a long touch, then increasing long touch effect is provided with +hold event and pop-up effect is provided when the pop-up is opened.

                 +                 + +

                Touch down on data item

                 +

                No change

                 +

                Highlight is shown.

                Tactile: Sensitive list effect and audio +feedback is provided with touch down event.

                 +                 + +

                Touch release on data item

                 +

                Item is activated.

                Application specific

                 +

                Highlight shown. Tactile: Sensitive list effect is provided with +touch release event.

                 +                 + +

                Touch down and hold on data item

                 +

                Stylus pop-up menu is opened.

                 +

                Highlight is shown. Animation is shown to indicate the opening pop-up.

                Tactile: +If activates a long touch, then increasing long touch effect is provided with +hold event and pop-up effect is provided when the pop-up is opened.

                 +                 + +

                Touch down on data/subtitle item and move

                 +

                Refer to Dragging +and flicking events

                Expand and collapse functions are not done +while dragging.

                 +

                Tactile: Refer to Dragging +and flicking events.

                 +                 + +

                Touch down on data/subtitle item and move horizontally

                 +

                Inactive

                 +

                Tactile: No effect

                 +                 + + +
                +
                Using +hierarchical column lists in applications

                The API to use for hierarchical +column lists is the Hierarchical lists API. For implementation information, +see Using the Hierarchical lists API.

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DAF86036-CC40-5F26-9F15-2F2093F59C03.dita --- a/Symbian3/SDK/Source/GUID-DAF86036-CC40-5F26-9F15-2F2093F59C03.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-DAF86036-CC40-5F26-9F15-2F2093F59C03.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,88 +1,88 @@ - - - - - -Security -issuesThis topic explains the security issues while performing a publish -and subscribe. -
                  -

                • Who can define a property?

                  • -

                • Read and write access rights

                  • -

                • Deletion rights

                  • -
                -
                Who can define -a property?

                One of the most important attributes of a property -is the category to which it belongs. A category is represented by a UID value.

                The -general rule is that the (category) UID must be the same as the Security ID -(the SID) of the process in which the code that is performing the define operation -is running. In effect, this forms a data cage, preventing a process from defining, -or "occupying", another process's property.

                You define a property -using the overload of RProperty::Define() with the signature:

                static TInt Define(TUint aKey, TInt aAttr, const TSecurityPolicy& aReadPolicy, const TSecurityPolicy& aWritePolicy, TInt aPreallocate);

                This function was introduced in V9.1 of Symbian platform, and it does not allow -you to explicitly specify the category. Indeed, Symbian platform takes the -category to be the value of the process SID.

                  -

                • The situation before Version 9.1

                  • -

                • Migration issues

                  • -

                • Notes

                  • -

                The situation before Version -9.1

                Before version 9.1 of Symbian platform, you had to explicitly -define a category using the overload of RProperty::Define() with -the signature:

                static TInt RProperty::Define(TUid aCategory, TUint aKey, TInt aAttr, const TSecurityPolicy& aReadPolicy, const TSecurityPolicy& aWritePolicy, TInt aPreallocate)

                This function was introduced in V9.0 of Symbian platform.

                It -was also possible to specify a category, known as the system category, which -was reserved for system services. This category was identified by the KUidSystemCategoryValue UID; -a process required the WriteDeviceData capability, (ECapabilityWriteDeviceData), -to use it.

                This overload is still available, but from V9.1 there are -restrictions that govern its use, and it is recommended that, if possible, -users of Property & Subscribe services should migrate to using the version -of RProperty::Define() that does not require the category -to be specified.

                Migration issues

                Processes -that use the 9.0 version of RProperty::Define() must now -have the WriteDeviceData capability to define a property with an explicitly -specified category (including the system category), provided that the SID -of the process is less than the value KUidSecurityThresholdCategoryValue.

                A -process that has a SID value greater than KUidSecurityThresholdCategoryValue cannot -explicitly specify a category. This is an absolute rule that cannot be -overridden regardless of the capabilities assigned to that process.

                The -logic here is that all new .exe s require a SID to be -assigned, and that this value will be greater than KUidSecurityThresholdCategoryValue. -This means that an associated process is forced to define properties with -category values that are the same as the process SID. Older .exe s -are expected to have SID values that are less than KUidSecurityThresholdCategoryValue, -and means that an associated process can continue to explicitly specify a -category, using the 9.0 version of Define(), but must have -the WriteDeviceData capability.

                Ideally, all older .exe s -should be migrated to use the 9.1 version of Define().

                The -following diagram shows the "category space".

                - -

                The KUidSecurityThresholdCategoryValue value -effectively forms a threshold value. Processes with a SID value below -this threshold can define a category that is different from their SID, provided -they have the WriteDeviceData capability. Processes with a SID value -above this threshold value can only define a category that is the same as -the SID - regardless of capability.

                Notes

                When we -refer to the SID of the process, we also mean the SID value assigned to the -associated .exe installed on the device. By older or -younger processes, we are referring to the age of the associated executables.

                -
                Read and write -access rights

                Access rights to a property are set when the property -is defined.

                The process defining the property can specify the rights -of access to that property. In particular, it can specify a security policy -to control read access (i.e. retrieval of the property) and a separate security -policy to control write access (i.e. publication of the property).

                Access -to a property is governed by a pair of security policies, instances of TSecurityPolicy objects. -These define the combination of capabilities and/or vendor Id and/or Secure -Id that a process must possess before being allowed to write to, or read from, -a property. Any attempt to access a property by a thread whose owning process -does not have sufficient capability, will fail with KErrPermissionDenied.

                The -security policies are passed to the RProperty::Define() function -when the property is defined.

                -
                Deletion rights

                Only -the owning process, i.e. the process that defined the property, is allowed -to delete that property.

                + + + + + +Security +issuesThis topic explains the security issues while performing a publish +and subscribe. +
                  +

                • Who can define a property?

                  • +

                • Read and write access rights

                  • +

                • Deletion rights

                  • +
                +
                Who can define +a property?

                One of the most important attributes of a property +is the category to which it belongs. A category is represented by a UID value.

                The +general rule is that the (category) UID must be the same as the Security ID +(the SID) of the process in which the code that is performing the define operation +is running. In effect, this forms a data cage, preventing a process from defining, +or "occupying", another process's property.

                You define a property +using the overload of RProperty::Define() with the signature:

                static TInt Define(TUint aKey, TInt aAttr, const TSecurityPolicy& aReadPolicy, const TSecurityPolicy& aWritePolicy, TInt aPreallocate);

                This function was introduced in V9.1 of Symbian platform, and it does not allow +you to explicitly specify the category. Indeed, Symbian platform takes the +category to be the value of the process SID.

                  +

                • The situation before Version 9.1

                  • +

                • Migration issues

                  • +

                • Notes

                  • +

                The situation before Version +9.1

                Before version 9.1 of Symbian platform, you had to explicitly +define a category using the overload of RProperty::Define() with +the signature:

                static TInt RProperty::Define(TUid aCategory, TUint aKey, TInt aAttr, const TSecurityPolicy& aReadPolicy, const TSecurityPolicy& aWritePolicy, TInt aPreallocate)

                This function was introduced in V9.0 of Symbian platform.

                It +was also possible to specify a category, known as the system category, which +was reserved for system services. This category was identified by the KUidSystemCategoryValue UID; +a process required the WriteDeviceData capability, (ECapabilityWriteDeviceData), +to use it.

                This overload is still available, but from V9.1 there are +restrictions that govern its use, and it is recommended that, if possible, +users of Property & Subscribe services should migrate to using the version +of RProperty::Define() that does not require the category +to be specified.

                Migration issues

                Processes +that use the 9.0 version of RProperty::Define() must now +have the WriteDeviceData capability to define a property with an explicitly +specified category (including the system category), provided that the SID +of the process is less than the value KUidSecurityThresholdCategoryValue.

                A +process that has a SID value greater than KUidSecurityThresholdCategoryValue cannot +explicitly specify a category. This is an absolute rule that cannot be +overridden regardless of the capabilities assigned to that process.

                The +logic here is that all new .exe s require a SID to be +assigned, and that this value will be greater than KUidSecurityThresholdCategoryValue. +This means that an associated process is forced to define properties with +category values that are the same as the process SID. Older .exe s +are expected to have SID values that are less than KUidSecurityThresholdCategoryValue, +and means that an associated process can continue to explicitly specify a +category, using the 9.0 version of Define(), but must have +the WriteDeviceData capability.

                Ideally, all older .exe s +should be migrated to use the 9.1 version of Define().

                The +following diagram shows the "category space".

                + +

                The KUidSecurityThresholdCategoryValue value +effectively forms a threshold value. Processes with a SID value below +this threshold can define a category that is different from their SID, provided +they have the WriteDeviceData capability. Processes with a SID value +above this threshold value can only define a category that is the same as +the SID - regardless of capability.

                Notes

                When we +refer to the SID of the process, we also mean the SID value assigned to the +associated .exe installed on the device. By older or +younger processes, we are referring to the age of the associated executables.

                +
                Read and write +access rights

                Access rights to a property are set when the property +is defined.

                The process defining the property can specify the rights +of access to that property. In particular, it can specify a security policy +to control read access (i.e. retrieval of the property) and a separate security +policy to control write access (i.e. publication of the property).

                Access +to a property is governed by a pair of security policies, instances of TSecurityPolicy objects. +These define the combination of capabilities and/or vendor Id and/or Secure +Id that a process must possess before being allowed to write to, or read from, +a property. Any attempt to access a property by a thread whose owning process +does not have sufficient capability, will fail with KErrPermissionDenied.

                The +security policies are passed to the RProperty::Define() function +when the property is defined.

                +
                Deletion rights

                Only +the owning process, i.e. the process that defined the property, is allowed +to delete that property.

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DB1D3045-2DC5-5C50-B430-526674369DC6.dita --- a/Symbian3/SDK/Source/GUID-DB1D3045-2DC5-5C50-B430-526674369DC6.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-DB1D3045-2DC5-5C50-B430-526674369DC6.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,54 +1,56 @@ - - - - - -Server-side -MTM implementation -
                Example Code

                Click on the following link to download -the example: TextMTM.zip

                Click: browse to view the example code.

                The -files reproduced here are the main files contained in the examples directory. -Some extra files may be needed to run the examples, and these will be found -in the appropriate examples directory.

                The Server-side Text MTM simulates -with the local file system the actions normally undertaken by a message transport -protocol. A Text service entry maps a local file directory, from which message -header information can be obtained (in a similar fashion to POP3), and from -which messages can be get and put.

                A file or folder in the mapped directory -is regarded as a remote entry, and recorded by an entry in the message index. -The name of the file to which a message corresponds is stored in the index -Description field, and the full folder path in the index Details field. No -message store is associated with these remote entries.

                Under a local -folder, for example, the Inbox, each message has a message store that contains -a rich text stream representing the body text.

                Messages can be deleted, -moved, or copied. When a local message to transferred to a Text service, -the Server-side MTM constructs a new file, obtaining its name and location -from the index fields. When the transfer is from the service to a local folder, -the Server-side MTM creates a rich text stream and reads the file text into -it.

                The Text server DLL currently supports one MTM-specific operation, KTXTMTMRefresh, -which refreshes the folder tree below a service entry.

                -
                Class summary

                CMsvServerEntry TMsvId CMsvEntrySelection -TParse

                -
                Move, copy, and delete implementation

                Move, copy, -and delete operations all operate on a collection of message entries, often -involving creating new index entries, and deleting existing ones. This common -functionality is provided by the class CTxtCopyMoveBase.

                A CTxtCopyMoveBase instance -is provided with an object to perform the specific operation required. The -classes CTxtCopyToLocalOp, CTxtCopyFromLocalOp, CTxtCopyWithinServiceOp, CTxtMoveToLocalOp, CTxtMoveFromLocalOp, CTxtMoveWithinServiceOp and CTxtDeleteOp each -define the functionality for a specific operation.

                Each of these classes -is derived from CTxtActiveOper. The move operation classes -are derived from their copy counterparts, and add the extra deletion after -copying.

                -
                Service refresh implementation

                The contents of -folders under the file system can be changed at any time outside of the application, -by the user or some other application. In order for these changes to be visible -in the messaging application, the Server-side MTM provides a refresh capability.

                The -refresh capability is provided by the refresher class CTxtRefreshMBox. -It ensures that the current entries accurately reflect the state of the corresponding -file folder, adding or removing entries under the service as required.

                + + + + + +Server-side MTM implementation +
                Example Code

                Click on the following link +to download the example: TextMTM.zip

                Click: browse to view the example code.

                The files +reproduced here are the main files contained in the examples directory. +Some extra files may be needed to run the examples, and these will +be found in the appropriate examples directory.

                The Server-side +Text MTM simulates with the local file system the actions normally +undertaken by a message transport protocol. A Text service entry +maps a local file directory, from which message header information +can be obtained (in a similar fashion to POP3), and from which messages +can be get and put.

                A file or folder in the mapped directory +is regarded as a remote entry, and recorded by an entry in the message +index. The name of the file to which a message corresponds is stored +in the index Description field, and the full folder path in the index +Details field. No message store is associated with these remote entries.

                Under a local folder, for example, the Inbox, each message has +a message store that contains a rich text stream representing the +body text.

                Messages can be deleted, moved, or copied. When a +local message to transferred to a Text service, the Server-side MTM +constructs a new file, obtaining its name and location from the index +fields. When the transfer is from the service to a local folder, the +Server-side MTM creates a rich text stream and reads the file text +into it.

                The Text server DLL currently supports one MTM-specific +operation, KTXTMTMRefresh, which refreshes the folder +tree below a service entry.

                +
                Class summary
                  +

                • CMsvServerEntry

                  • +

                • TMsvId

                  • +

                • CMsvEntrySelection

                  • +

                • TParse

                  • +
                +
                Move, copy, and delete implementation

                Move, +copy, and delete operations all operate on a collection of message +entries, often involving creating new index entries, and deleting +existing ones. This common functionality is provided by the class CTxtCopyMoveBase.

                A CTxtCopyMoveBase instance is provided with an object to perform the specific operation +required. The classes CTxtCopyToLocalOp, CTxtCopyFromLocalOp, CTxtCopyWithinServiceOp, CTxtMoveToLocalOp, CTxtMoveFromLocalOp, CTxtMoveWithinServiceOp and CTxtDeleteOp each define the functionality for a specific operation.

                Each of these classes is derived from CTxtActiveOper. The move operation classes are derived from their copy counterparts, +and add the extra deletion after copying.

                +
                Service refresh implementation

                The contents +of folders under the file system can be changed at any time outside +of the application, by the user or some other application. In order +for these changes to be visible in the messaging application, the +Server-side MTM provides a refresh capability.

                The refresh +capability is provided by the refresher class CTxtRefreshMBox. It ensures that the current entries accurately reflect the state +of the corresponding file folder, adding or removing entries under +the service as required.

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DB571D42-03F4-50F9-974D-B905707FC5F4_d0e79867_href.png Binary file Symbian3/SDK/Source/GUID-DB571D42-03F4-50F9-974D-B905707FC5F4_d0e79867_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DB571D42-03F4-50F9-974D-B905707FC5F4_d0e86579_href.png Binary file Symbian3/SDK/Source/GUID-DB571D42-03F4-50F9-974D-B905707FC5F4_d0e86579_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DB6EC285-F5DB-5A7A-AFF3-E423AD4B9F81_d0e461294_href.png Binary file Symbian3/SDK/Source/GUID-DB6EC285-F5DB-5A7A-AFF3-E423AD4B9F81_d0e461294_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DB6EC285-F5DB-5A7A-AFF3-E423AD4B9F81_d0e461458_href.png Binary file Symbian3/SDK/Source/GUID-DB6EC285-F5DB-5A7A-AFF3-E423AD4B9F81_d0e461458_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DB9F413A-35E2-577E-91C3-1D519835FAB4_d0e79595_href.png Binary file Symbian3/SDK/Source/GUID-DB9F413A-35E2-577E-91C3-1D519835FAB4_d0e79595_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DB9F413A-35E2-577E-91C3-1D519835FAB4_d0e86307_href.png Binary file Symbian3/SDK/Source/GUID-DB9F413A-35E2-577E-91C3-1D519835FAB4_d0e86307_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DBF6760F-D209-4B8F-89D5-A7EFFF7959E2.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-DBF6760F-D209-4B8F-89D5-A7EFFF7959E2.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,43 @@ + + + + + +Starting +the connection through the destination networkAfter you have selected the destination network to be used, you +can open the data connection. +

                To open +the data connection with the selected destination network:

                 + +Start the connection +through the Internet destination network using the Connection Manager API. + +Select the best available access point within the Internet destination +network using the Connection Manager API. +

                RConnection handle is returned to the network. The connection can +now be used.

                 +                 +                 +RSocketServ ss; + +// Connect to ESOCK +ss.Connect(); + +// Open an RConnection object. Note that you must provide an RSocketServ object +RConnection conn; +conn.Open( ss ); + +// Create overrides +TConnSnapPref prefs +prefs.SetSnap( 4 ); + +// Start an Outgoing Connection with overrides +conn.Start( prefs ); + +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DC37C3A9-B03F-5699-9E05-8ADD62C2FF04_d0e7089_href.png Binary file Symbian3/SDK/Source/GUID-DC37C3A9-B03F-5699-9E05-8ADD62C2FF04_d0e7089_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DC37C3A9-B03F-5699-9E05-8ADD62C2FF04_d0e8364_href.png Binary file Symbian3/SDK/Source/GUID-DC37C3A9-B03F-5699-9E05-8ADD62C2FF04_d0e8364_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DC44DCFC-8549-5CDE-B6DA-F5FD73E2D9FC_d0e125271_href.jpg Binary file Symbian3/SDK/Source/GUID-DC44DCFC-8549-5CDE-B6DA-F5FD73E2D9FC_d0e125271_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DC44DCFC-8549-5CDE-B6DA-F5FD73E2D9FC_d0e131809_href.jpg Binary file Symbian3/SDK/Source/GUID-DC44DCFC-8549-5CDE-B6DA-F5FD73E2D9FC_d0e131809_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DC4E42CA-2A65-44D7-8DBE-386F60F998A0_d0e51623_href.png Binary file Symbian3/SDK/Source/GUID-DC4E42CA-2A65-44D7-8DBE-386F60F998A0_d0e51623_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DC4E42CA-2A65-44D7-8DBE-386F60F998A0_d0e56400_href.png Binary file Symbian3/SDK/Source/GUID-DC4E42CA-2A65-44D7-8DBE-386F60F998A0_d0e56400_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DC4E42CA-2A65-44D7-8DBE-386F60F998A0_d0e57178_href.png Binary file Symbian3/SDK/Source/GUID-DC4E42CA-2A65-44D7-8DBE-386F60F998A0_d0e57178_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DC4E42CA-2A65-44D7-8DBE-386F60F998A0_d0e64122_href.png Binary file Symbian3/SDK/Source/GUID-DC4E42CA-2A65-44D7-8DBE-386F60F998A0_d0e64122_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DC4E42CA-2A65-44D7-8DBE-386F60F998A0_d0e68872_href.png Binary file Symbian3/SDK/Source/GUID-DC4E42CA-2A65-44D7-8DBE-386F60F998A0_d0e68872_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DC4E42CA-2A65-44D7-8DBE-386F60F998A0_d0e74016_href.png Binary file Symbian3/SDK/Source/GUID-DC4E42CA-2A65-44D7-8DBE-386F60F998A0_d0e74016_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DC59BEAD-0047-4D7A-96D1-C5E3EC4F982B.dita --- a/Symbian3/SDK/Source/GUID-DC59BEAD-0047-4D7A-96D1-C5E3EC4F982B.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-DC59BEAD-0047-4D7A-96D1-C5E3EC4F982B.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,94 +1,94 @@ - - - - - -Drawing -in traditional architecture -

                The application framework callsCCoeControl::Draw() when -a control area needs to be updated on the display. Controls may implement CCoeControl::Draw() or -leave the drawing to their child controls. For more information on control -hierarchies, see The -run-time control hierarchy. The platform calls CCoeControl::Draw() for -the parent control first, and then recursively for each control.

                -

                Controls should override CCoeControl::Draw() to draw -their content. The override should do nothing else and should be as fast as -possible. For example, it is bad design to create fonts dynamically, and read -any bitmaps or resources while drawing. A good rule of thumb is that there -should not be trap handlers in the method override; any time-consuming functionality -that can be done beforehand should be cached.

                -

                In most cases controls are drawn on the display using the screen device -graphics context, accessed with CCoeControl::SystemGc(). -The graphics context provides a wide set of GDI (Graphics -Device Interface - common Symbian platform graphics API) drawing primitives -that can be used for drawing virtually anything on screen.

                -

                An example of a basic override of CCoeControl::Draw() for -a control that is a top-level window in an application is as follows:

                -void CMyAppView::Draw( const TRect& /*aRect*/ ) const - { - // Get the standard graphics context - CWindowGc& gc = SystemGc(); - gc.SetPenStyle( CGraphicsContext::ENullPen ); - gc.SetBrushColor( KRgbWhite); - gc.SetBrushStyle( CGraphicsContext::ESolidBrush ); - - // Gets the control's extent - TRect rect( Rect()); - - { - gc.Clear( rect ); - } - } - -

                , where

                -
                  -

                • CWindowGc& gc = SystemGc(); gets -the graphics context that is used when drawing the control.

                  • -

                • CWindowGc::SetPenStyle(), CWindowGc::SetBrushColor(), -and CWindowGc::SetBrushStyle() are used to set the drawing -primatives for the context

                  • -

                • TRect gets the size of the control rectangle

                  -
                  • -

                • CWindowGc:Clear(rect) clears the control -rectangle

                  • -
                -
                Double buffering -

                For controls that perform intensive drawing operations, the drawing -should be cached: a process also known as double-buffering. Here the drawing -is done to a memory context first and then in the CCoeControl::Draw() method -only the context's bitmap is passed to screen. In the Symbian platform, the -easiest way to implement a double buffer is to create a CFbsBitmap and -then bind a graphics context to that - this makes it possible to use the -same GDI interface for drawing as the display context. The drawing is done -to a memory bitmap buffer. Double-buffering is a common paradigm used in games, -but can also be utilized in any application when performance of drawing controls -is important.

                -

                The following is a short example of how a double buffer is created and -used:

                -iGcBmp = new (ELeave) CWsBitmap(iEikonEnv->WsSession()); -User::LeaveIfError(iGcBmp->Create(aClientRect.Size(), iEikonEnv->ScreenDevice()->DisplayMode())); -iGcDevice = CFbsBitmapDevice::NewL(iGcBmp); -User::LeaveIfError(iGcDevice->CreateBitmapContext(iGc)); - -

                iGcBmp is a pointer to CWsBitmap, -the bitmap memory buffer, that is created with the same width and height as -the top-level window and with the same color bit depth as the display. iGcDevice is -a pointer to the CBitmapDevice device class and the context iGc holds -the CBitmapContext instance. iGc is -then used instead of CScreenGc, obtained from the CCoeControl::SystemGc() method, -when the control draws itself. The double-buffer drawing should be done outside -of the CCoeControl::Draw() method and can be called directly -when needed. Only at the end of the off-screen drawing is the memory buffer -flushed to the screen by calling CCoeControl::DrawDeferred()

                -void CMyDrawingExample::Draw(const TRect& /*aRect*/) const - { - SystemGc().BitBlt(TPoint(0, 0), iGcBmp); - } -
                + + + + + +Drawing +in traditional architecture +

                The application framework callsCCoeControl::Draw() when +a control area needs to be updated on the display. Controls may implement CCoeControl::Draw() or +leave the drawing to their child controls. For more information on control +hierarchies, see The +run-time control hierarchy. The platform calls CCoeControl::Draw() for +the parent control first, and then recursively for each control.

                +

                Controls should override CCoeControl::Draw() to draw +their content. The override should do nothing else and should be as fast as +possible. For example, it is bad design to create fonts dynamically, and read +any bitmaps or resources while drawing. A good rule of thumb is that there +should not be trap handlers in the method override; any time-consuming functionality +that can be done beforehand should be cached.

                +

                In most cases controls are drawn on the display using the screen device +graphics context, accessed with CCoeControl::SystemGc(). +The graphics context provides a wide set of GDI (Graphics +Device Interface - common Symbian platform graphics API) drawing primitives +that can be used for drawing virtually anything on screen.

                +

                An example of a basic override of CCoeControl::Draw() for +a control that is a top-level window in an application is as follows:

                +void CMyAppView::Draw( const TRect& /*aRect*/ ) const + { + // Get the standard graphics context + CWindowGc& gc = SystemGc(); + gc.SetPenStyle( CGraphicsContext::ENullPen ); + gc.SetBrushColor( KRgbWhite); + gc.SetBrushStyle( CGraphicsContext::ESolidBrush ); + + // Gets the control's extent + TRect rect( Rect()); + + { + gc.Clear( rect ); + } + } + +

                , where

                +
                  +

                • CWindowGc& gc = SystemGc(); gets +the graphics context that is used when drawing the control.

                  • +

                • CWindowGc::SetPenStyle(), CWindowGc::SetBrushColor(), +and CWindowGc::SetBrushStyle() are used to set the drawing +primatives for the context

                  • +

                • TRect gets the size of the control rectangle

                  +
                  • +

                • CWindowGc:Clear(rect) clears the control +rectangle

                  • +
                +
                Double buffering +

                For controls that perform intensive drawing operations, the drawing +should be cached: a process also known as double-buffering. Here the drawing +is done to a memory context first and then in the CCoeControl::Draw() method +only the context's bitmap is passed to screen. In the Symbian platform, the +easiest way to implement a double buffer is to create a CFbsBitmap and +then bind a graphics context to that - this makes it possible to use the +same GDI interface for drawing as the display context. The drawing is done +to a memory bitmap buffer. Double-buffering is a common paradigm used in games, +but can also be utilized in any application when performance of drawing controls +is important.

                +

                The following is a short example of how a double buffer is created and +used:

                +iGcBmp = new (ELeave) CWsBitmap(iEikonEnv->WsSession()); +User::LeaveIfError(iGcBmp->Create(aClientRect.Size(), iEikonEnv->ScreenDevice()->DisplayMode())); +iGcDevice = CFbsBitmapDevice::NewL(iGcBmp); +User::LeaveIfError(iGcDevice->CreateBitmapContext(iGc)); + +

                iGcBmp is a pointer to CWsBitmap, +the bitmap memory buffer, that is created with the same width and height as +the top-level window and with the same color bit depth as the display. iGcDevice is +a pointer to the CBitmapDevice device class and the context iGc holds +the CBitmapContext instance. iGc is +then used instead of CScreenGc, obtained from the CCoeControl::SystemGc() method, +when the control draws itself. The double-buffer drawing should be done outside +of the CCoeControl::Draw() method and can be called directly +when needed. Only at the end of the off-screen drawing is the memory buffer +flushed to the screen by calling CCoeControl::DrawDeferred()

                +void CMyDrawingExample::Draw(const TRect& /*aRect*/) const + { + SystemGc().BitBlt(TPoint(0, 0), iGcBmp); + } +
                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DC8BFEF5-DA50-52DA-8CE2-5729A4A005F6.dita --- a/Symbian3/SDK/Source/GUID-DC8BFEF5-DA50-52DA-8CE2-5729A4A005F6.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-DC8BFEF5-DA50-52DA-8CE2-5729A4A005F6.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,98 +1,118 @@ - - - - - -EGL -Collection OverviewEGL is an interface between EGL client APIs (such as OpenGL ES -and OpenVG) and an underlying native platform window system. EGL is independent -of definitions and concepts specific to any native window system or rendering -API. -

                EGL is an open standard developed by the Khronos Group, which is a member-funded -industry consortium. Khronos creates open standard, royalty-free APIs to help -write and execute dynamic media on a wide variety of platforms and devices. -For more information about EGL operations, functions, errors, versions and -header files, see http://www.khronos.org/egl/.

                -

                In this documentation the term EGL client API is used to mean a -rendering API, such as OpenGL ES or OpenVG, that is a client of EGL.

                -
                Introduction to EGL on the Symbian platform

                EGL -provides:

                  -

                • Mechanisms that create -rendering surfaces onto which EGL client APIs can draw and which they can -share.

                  • -

                • Methods that create -and manage graphics contexts for EGL client APIs.

                  • -

                • Methods that synchronize -drawing by EGL client APIs and Symbian APIs (such as CWindowGc).

                  • -

                One of the purposes of EGL is to provide a means to create EGL client -API rendering contexts, and associate them with drawing surfaces. EGL defines -three types of drawing surfaces collectively referred to as EGLSurfaces. -These are:

                  -

                • Window surfaces, -which are used for on-screen rendering into windows that are provided by the -Symbian platform (rather than EGL) .

                  • -

                • Pbuffer surfaces, -which are used for off screen rendering and are entirely provided by EGL.

                  • -

                • Pixmap surfaces, -which are used for off screen rendering into pixmap buffers that are provided -by the Symbian platform (rather than EGL).

                  • -

                Some key points to note include:

                  -

                • EGL objects and their -related context state cannot be used outside of the address space in which -they are created.

                  • -

                • EGL enables sharing -of certain types of context state among contexts existing in a single address -space.

                  • -

                Thread-safety

                Currently EGL and its client APIs are -only guaranteed to work correctly on the Symbian platform when they are within -a single thread. EGL guarantees sequential ordering within a command stream -for each of the EGL client APIs. However, there is no guarantee of sequential -ordering between EGL client APIs and Symbian APIs which render into the same -surface.

                EGL client API commands may be asynchronous, in order to -prevent impairing the interactive use of the windowing system by the user. -For example, otherwise rendering a large texture mapped polygon on a system -with no graphics hardware, or drawing a large OpenGL ES vertex array, could -prevent a user from invoking a menu soon enough to be usable.

                Synchronization -depends on the client—it can be maintained at moderate cost with the careful -use of commands such as glFinish, vgFinish, eglWaitClient, -and eglWaitNative, as well as synchronization commands present -in the Symbian APIs. The EGL client API and Symbian API rendering can be done -in parallel if the client does not prevent it with explicit synchronization -calls. Some performance degradation may be experienced when there is unnecessary -switching between EGL client APIs and Symbian API rendering.

                -
                Architectural relationships

                The following diagram -shows the key EGL relationships and dependencies within the Symbian platform. -On the Symbian platform, OpenGL ES, OpenVG and EGL all have a component (shown -in blue) that declares the interface, and all require an implementation that -implements that interface (shown in green).

                - Key EGL relationships and dependencies - -

                The EGL Interface -component provides a consistent interface to EGL on the Symbian platform, -enabling cross-device compatibility. The component includes the Khronos-released -header files (which incorporate some minor changes, such as to the comments). -It also provides some Symbian-specific header files and some other files (such -as LIB, DEF and MMP files) and UIDs. It does not provide any implementations -of the APIs.

                The EGL Interface component includes the header files -for EGL 1.2, 1.3 and 1.4 (which is used by default). The main advantage of -EGL 1.4 over previous versions is the introduction of a preserve buffer flag. -When supported by the implementation, an EGL window surface can have its color -buffer preserved from one frame to the next. This means that the client does -not need to send the entire drawing instructions for each frame. Instead the -client can simply send the drawing operations for what changes in each frame -compared to the previous one. This can reduce the memory footprint and the -CPU overhead when an EGL client API renders successive frames.

                -                 -EGL - Collection -OpenVG Collection - -OpenGLES -Collection + + + + + +EGL Collection +OverviewEGL is an interface between EGL client APIs (such as OpenGL ES +and OpenVG) and an underlying native platform window system. EGL is independent +of definitions and concepts specific to any native window system or rendering +API. +

                EGL is an open standard developed by the Khronos Group, which is a member-funded +industry consortium. Khronos creates open standard, royalty-free APIs to help +write and execute dynamic media on a wide variety of platforms and devices. +For more information about EGL operations, functions, errors, versions and +header files, see http://www.khronos.org/egl/.

                +

                In this documentation the term EGL client API is used to mean a +rendering API, such as OpenGL ES or OpenVG, that is a client of EGL.

                +
                Introduction +to EGL on the Symbian platform

                EGL provides:

                  +

                • Mechanisms that create +rendering surfaces onto which EGL client APIs can draw and which they can +share.

                  • +

                • Methods that create +and manage graphics contexts for EGL client APIs.

                  • +

                • Methods that synchronize +drawing by EGL client APIs and Symbian APIs (such as CWindowGc).

                  • +

                One of the purposes of EGL is to provide a means to create EGL client +API rendering contexts, and associate them with drawing surfaces. EGL defines +three types of drawing surfaces collectively referred to as EGLSurfaces. +These are:

                  +

                • Window surfaces, +which are used for on-screen rendering into windows that are provided by the +Symbian platform (rather than EGL) .

                  • +

                • Pbuffer surfaces, +which are used for off screen rendering and are entirely provided by EGL.

                  • +

                • Pixmap surfaces, +which are used for off screen rendering into pixmap buffers that are provided +by the Symbian platform (rather than EGL).

                  • +

                Some key points to note include:

                  +

                • EGL objects and their +related context state cannot be used outside of the address space in which +they are created.

                  • +

                • EGL enables sharing +of certain types of context state among contexts existing in a single address +space.

                  • +

                Thread-safety

                Currently EGL and its client APIs are +only guaranteed to work correctly on the Symbian platform when they are within +a single thread. EGL guarantees sequential ordering within a command stream +for each of the EGL client APIs. However, there is no guarantee of sequential +ordering between EGL client APIs and Symbian APIs which render into the same +surface.

                EGL client API commands may be asynchronous, in order to +prevent impairing the interactive use of the windowing system by the user. +For example, otherwise rendering a large texture mapped polygon on a system +with no graphics hardware, or drawing a large OpenGL ES vertex array, could +prevent a user from invoking a menu soon enough to be usable.

                Synchronization +depends on the client—it can be maintained at moderate cost with the careful +use of commands such as glFinish, vgFinish, eglWaitClient, +and eglWaitNative, as well as synchronization commands present +in the Symbian APIs. The EGL client API and Symbian API rendering can be done +in parallel if the client does not prevent it with explicit synchronization +calls. Some performance degradation may be experienced when there is unnecessary +switching between EGL client APIs and Symbian API rendering.

                +
                Architectural +relationships

                The following diagram shows the key EGL relationships +and dependencies within the Symbian platform. On the Symbian platform, OpenGL +ES, OpenVG and EGL all have a component (shown in blue) that declares the +interface, and all require an implementation that implements that interface +(shown in green).

                + Key EGL relationships and dependencies + +

                The EGL Interface +component provides a consistent interface to EGL on the Symbian platform, +enabling cross-device compatibility. The component includes the Khronos-released +header files (which incorporate some minor changes, such as to the comments). +It also provides some Symbian-specific header files and some other files (such +as LIB, DEF and MMP files) and UIDs. It does not provide any implementations +of the APIs.

                Symbian^3 introduces ScreenPlay, +the new graphics architecture. This has a composition engine, which enables +composition surfaces to be arranged in layers and to be composed together +to produce the final output on the display. All native Symbian drawing (such +as the application UI) is rendered to a special composition surface called +the UI surface, which is the topmost layer and can be semi-transparent.

                In +a ScreenPlay environment, EGL window surfaces are implemented as composition +surfaces. This means that it is possible to use the native Symbian drawing +APIs (CWindowGc) to create semi-transparent UI content over +the EGL window surface onto which the OpenVG and OpenGL ES content is rendered. + See the Coverflow; +using ScreenPlay application for an example of this.

                In the +non-ScreenPlay environment, it is not possible to use the native Symbian APIs +to create semi-transparent UI content over the EGL window surface. A different +solution must therefore be used; for example, using Khronos rendering APIs +to create the UI content and direct it onto the EGL window surface or using +the Symbian APIs to create opaque child windows.

                The EGL Interface +component includes the header files for EGL 1.2, 1.3 and 1.4 (which is used +by default). The main advantage of EGL 1.4 over previous versions is the introduction +of a preserve buffer flag. When supported by the implementation, an +EGL window surface can have its color buffer preserved from one frame to the +next. This means that the client does not need to send the entire drawing +instructions for each frame. Instead the client can simply send the drawing +operations for what changes in each frame compared to the previous one. This +can reduce the memory footprint and the CPU overhead when an EGL client API +renders successive frames.

                +                 +EGL + Collection +OpenVG Collection + +OpenGLES +Collection +Graphics +Composition                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DCCA3BD3-582A-5C71-A104-D922FFE3C680_d0e287427_href.png Binary file Symbian3/SDK/Source/GUID-DCCA3BD3-582A-5C71-A104-D922FFE3C680_d0e287427_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DCCA3BD3-582A-5C71-A104-D922FFE3C680_d0e291060_href.png Binary file Symbian3/SDK/Source/GUID-DCCA3BD3-582A-5C71-A104-D922FFE3C680_d0e291060_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DCFF3240-F1CD-41FF-B832-990ADF101674_d0e3450_href.png Binary file Symbian3/SDK/Source/GUID-DCFF3240-F1CD-41FF-B832-990ADF101674_d0e3450_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DCFF3240-F1CD-41FF-B832-990ADF101674_d0e4725_href.png Binary file Symbian3/SDK/Source/GUID-DCFF3240-F1CD-41FF-B832-990ADF101674_d0e4725_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DD04585F-3D60-5CB2-8975-AE602B75740B_d0e398653_href.png Binary file Symbian3/SDK/Source/GUID-DD04585F-3D60-5CB2-8975-AE602B75740B_d0e398653_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DD04585F-3D60-5CB2-8975-AE602B75740B_d0e398815_href.png Binary file Symbian3/SDK/Source/GUID-DD04585F-3D60-5CB2-8975-AE602B75740B_d0e398815_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DD0F8AFB-F96C-4EAC-96DE-7D5C0597B574-master.png Binary file Symbian3/SDK/Source/GUID-DD0F8AFB-F96C-4EAC-96DE-7D5C0597B574-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DD0F8AFB-F96C-4EAC-96DE-7D5C0597B574_d0e315975_href.png Binary file Symbian3/SDK/Source/GUID-DD0F8AFB-F96C-4EAC-96DE-7D5C0597B574_d0e315975_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DD22D66C-C303-5432-9C24-71F26190FCA0_d0e184514_href.png Binary file Symbian3/SDK/Source/GUID-DD22D66C-C303-5432-9C24-71F26190FCA0_d0e184514_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DD22D66C-C303-5432-9C24-71F26190FCA0_d0e191110_href.png Binary file Symbian3/SDK/Source/GUID-DD22D66C-C303-5432-9C24-71F26190FCA0_d0e191110_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DD263BCA-B660-49A5-BB65-8C45035002BD-master.png Binary file Symbian3/SDK/Source/GUID-DD263BCA-B660-49A5-BB65-8C45035002BD-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DD263BCA-B660-49A5-BB65-8C45035002BD_d0e81773_href.png Binary file Symbian3/SDK/Source/GUID-DD263BCA-B660-49A5-BB65-8C45035002BD_d0e81773_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DD3783B2-B8ED-4CD4-AAF6-75EC8B53B8EF.dita --- a/Symbian3/SDK/Source/GUID-DD3783B2-B8ED-4CD4-AAF6-75EC8B53B8EF.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,18 +0,0 @@ - - - - - -Symbian -device user experience for non-touch devices -

                This section presents an overview of the user experience in Symbian devices -without touch. For information on interaction in devices supporting touch, -see Touch -UI user experience.

                -                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DD39680E-C0CB-4D97-A921-25FACC30FBE3_d0e306771_href.jpg Binary file Symbian3/SDK/Source/GUID-DD39680E-C0CB-4D97-A921-25FACC30FBE3_d0e306771_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DD39680E-C0CB-4D97-A921-25FACC30FBE3_d0e313165_href.jpg Binary file Symbian3/SDK/Source/GUID-DD39680E-C0CB-4D97-A921-25FACC30FBE3_d0e313165_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DD3A519B-26D5-5920-BEF3-16273A661448_d0e19147_href.png Binary file Symbian3/SDK/Source/GUID-DD3A519B-26D5-5920-BEF3-16273A661448_d0e19147_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DD3A519B-26D5-5920-BEF3-16273A661448_d0e49491_href.png Binary file Symbian3/SDK/Source/GUID-DD3A519B-26D5-5920-BEF3-16273A661448_d0e49491_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DD3A519B-26D5-5920-BEF3-16273A661448_d0e55049_href.png Binary file Symbian3/SDK/Source/GUID-DD3A519B-26D5-5920-BEF3-16273A661448_d0e55049_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DD764F2C-365A-5A5C-9412-4AF2EDB16924_d0e357582_href.png Binary file Symbian3/SDK/Source/GUID-DD764F2C-365A-5A5C-9412-4AF2EDB16924_d0e357582_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DD764F2C-365A-5A5C-9412-4AF2EDB16924_d0e363662_href.png Binary file Symbian3/SDK/Source/GUID-DD764F2C-365A-5A5C-9412-4AF2EDB16924_d0e363662_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DD77AA04-D0AB-4BEB-900F-B3BE50AC0B7F.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-DD77AA04-D0AB-4BEB-900F-B3BE50AC0B7F.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,51 @@ + + + + + +Opening +a Connection based on User SelectionExtended Connection Preferences API can be used by applications +to open a connection based on user selection. +

                When an +application chooses to establish a connection based on user selection, +Connection selection dialog needs to be enabled. Only the SNAPs and IAPs matching +with bearer set are displayed for selection.

                + +Connect to socket server . + RSocketServ ss; +ss.Connect(); + + Open a RConnection object. + RConnection conn; +conn.Open( ss ); + +Create a connection +preference list and extended connection preferences object. + TConnPrefList prefList; +TExtendedConnPref preferences; + +Enable the Connection +selection dialog to accept user queries using TExtendedConnPref::SetConnSelectionDialog(). +preferences.SetConnSelectionDialog( ETrue ); + +Append extended +connection preferences into connection preference list. +prefList.AppendL( &preferences ); + +Start a connection +with connection preferences. +conn.Start( prefList ); + + +

                The application +is connected to the SNAP or IAP selected by the user.

                 +                 +Additional +Connection Preferences +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DDA0ECF7-BC92-4AFB-998F-5FDD300655FB.dita --- a/Symbian3/SDK/Source/GUID-DDA0ECF7-BC92-4AFB-998F-5FDD300655FB.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-DDA0ECF7-BC92-4AFB-998F-5FDD300655FB.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,57 +1,57 @@ - - - - - -Getting -a Nearest Equivalent Language

                In this example, the system language is ELangCanadianEnglish and -there is no exact match of the resource file on the system. The application -calls BaflUtils::NearestLanguageFileV2() to get the closest -match. There are three available resource files:

                  -

                • c:\FileMenu.rsc is -the language-neutral resource file.

                  • -

                • c:\FileMenu.r01 is -for ELangEnglish.

                  • -

                • c:\FileMenu.r10 is -for ELangAmerican.

                  • -
                 - - -

                In the application, define a string with the neutral-language resource -file name.

                _LIT(KRscFilename, "C:\\FileMenu.rsc");                 -                 - -

                Create a session with the File Server to search the file system for -available resource files. RFs fileServerSession; -CleanupClosePushL(fileServerSession); -User::LeaveIfError(fileServerSession.Connect());

                 -                 - -

                Construct a buffer to save a resource file name. The buffer takes -the neutral-language resource file name as a input parameter to BaflUtils::NearestLanguageFileV2(). -It will be updated with a new value after the call. TBuf<256> filename; -filename.Copy(KRscFilename);

                 -                 - -

                Define a TLanguage as a return parameter for the -nearest equivalent language. TLanguage lang=ELangNone;

                 -                 - -

                Get the nearest language. BaflUtils::NearestLanguageFileV2(fileServerSession, filename, lang); -...

                 -                 - -

                Close the session with the File Server. CleanupStack::PopAndDestroy (&fileServerSession);

                 -                 -                 -

                The filename parameter is updated as "c:\\FileMenu.r10" which -is the closest resource file for ELangCanadianEnglish. The lang parameter -is returned as ELangAmerican (value 10) which is the nearest -equivalent language.

                + + + + + +Getting +a Nearest Equivalent Language

                In this example, the system language is ELangCanadianEnglish and +there is no exact match of the resource file on the system. The application +calls BaflUtils::NearestLanguageFileV2() to get the closest +match. There are three available resource files:

                  +

                • c:\FileMenu.rsc is +the language-neutral resource file.

                  • +

                • c:\FileMenu.r01 is +for ELangEnglish.

                  • +

                • c:\FileMenu.r10 is +for ELangAmerican.

                  • +
                 + + +

                In the application, define a string with the neutral-language resource +file name.

                _LIT(KRscFilename, "C:\\FileMenu.rsc");                 +                 + +

                Create a session with the File Server to search the file system for +available resource files. RFs fileServerSession; +CleanupClosePushL(fileServerSession); +User::LeaveIfError(fileServerSession.Connect());

                 +                 + +

                Construct a buffer to save a resource file name. The buffer takes +the neutral-language resource file name as a input parameter to BaflUtils::NearestLanguageFileV2(). +It will be updated with a new value after the call. TBuf<256> filename; +filename.Copy(KRscFilename);

                 +                 + +

                Define a TLanguage as a return parameter for the +nearest equivalent language. TLanguage lang=ELangNone;

                 +                 + +

                Get the nearest language. BaflUtils::NearestLanguageFileV2(fileServerSession, filename, lang); +...

                 +                 + +

                Close the session with the File Server. CleanupStack::PopAndDestroy (&fileServerSession);

                 +                 +                 +

                The filename parameter is updated as "c:\\FileMenu.r10" which +is the closest resource file for ELangCanadianEnglish. The lang parameter +is returned as ELangAmerican (value 10) which is the nearest +equivalent language.

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DE0E5230-A422-5859-A8DF-5E51AAA9B23A_d0e203628_href.png Binary file Symbian3/SDK/Source/GUID-DE0E5230-A422-5859-A8DF-5E51AAA9B23A_d0e203628_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DE0E5230-A422-5859-A8DF-5E51AAA9B23A_d0e208636_href.png Binary file Symbian3/SDK/Source/GUID-DE0E5230-A422-5859-A8DF-5E51AAA9B23A_d0e208636_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DE417474-906D-5EB8-A80D-2CBF099EC81C_d0e322882_href.jpg Binary file Symbian3/SDK/Source/GUID-DE417474-906D-5EB8-A80D-2CBF099EC81C_d0e322882_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DE417474-906D-5EB8-A80D-2CBF099EC81C_d0e329039_href.jpg Binary file Symbian3/SDK/Source/GUID-DE417474-906D-5EB8-A80D-2CBF099EC81C_d0e329039_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DE5FC074-75C1-5833-83B2-D25396F52732_d0e354645_href.png Binary file Symbian3/SDK/Source/GUID-DE5FC074-75C1-5833-83B2-D25396F52732_d0e354645_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DE5FC074-75C1-5833-83B2-D25396F52732_d0e360725_href.png Binary file Symbian3/SDK/Source/GUID-DE5FC074-75C1-5833-83B2-D25396F52732_d0e360725_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DEB6E162-B2AA-5DF6-B750-E833C7DE4902.dita --- a/Symbian3/SDK/Source/GUID-DEB6E162-B2AA-5DF6-B750-E833C7DE4902.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-DEB6E162-B2AA-5DF6-B750-E833C7DE4902.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,118 +1,118 @@ - - - - - -PAN -Profile OverviewThe Bluetooth PAN Profile API supports standard IP-based network -services deployed over the Bluetooth transport layer. -
                Purpose

                The -Personal Area Network (PAN) profile is designed to make a Bluetooth network -simulate an ethernet, from an application's perspective. Symbian platform -supports only one active PAN at a time. Each remote device that connects to -the PAN device for networking purposes will be merged into the same active -PAN.

                Symbian platform provides support for a PAN agent to assume the -role of PANU (User), PAN-GN (Group ad hoc Network) or PAN-NAP (Network Access -Point).

                The Symbian PAN implementation is integrated into the Symbian -networking framework enabling IP applications to run on a Bluetooth network.

                -
                Required background

                You need to be familiar with -the PAN Profile specification.

                -
                Key concepts -and terms
                - -
                Personal Area Network (PAN)
                -

                A PAN is an ad-hoc network of devices communicating on a standard network -configuration, over a Bluetooth radio connection. A PAN may have anywhere -from 2 to 8 participating member devices.

                A PAN is not the same as -a piconet. Where a piconet is any ad-hoc networking of devices over a Bluetooth -connection for the purposes of sharing data or services, like when you pair -your phone to your Bluetooth hands-free kit, a PAN deals specifically with -networking resources.

                -                 - -
                PAN Profile
                -

                The Bluetooth specification identifies several profiles including the -Bluetooth Personal Area Networking (PAN) profile. The PAN profile simplifies -the now deprecated Bluetooth LAN Access and Dial-up Networking profiles by -reducing the number of layers in a network Bluetooth connection.

                The -PAN profile identifies certain configuration and setup details of a participant -of the network, including the PAN host. If a device wants to join a PAN it -must support and be able to be configured according to the requirements of -the profile in use. For more general information about Bluetooth profiles -see Introduction -to Bluetooth Profiles.

                -                 - -
                PAN profile roles
                -

                Typical PAN profile roles include the following:

                  -

                • PANU

                  • -

                • PAN-GN

                  • -

                • PAN-NAP

                  • -

                PANU (User) acts as a client member of a PAN-GN (Group ad hoc Network) -or a PAN-NAP (Network Access Point). Any device in either the PAN-GN or the -PAN-NAP role acts as a server.

                -                 -
                -
                PAN Roles

                The -PAN Profile roles are described below:

                PANU

                A -Bluetooth enabled device seeking entry into a network or participating in -a peer-to-peer (one on one) connection assumes the PANU role, thus becoming -a client member of the piconet.

                - PANU to PANU connection - -

                PAN-GN

                A -PAN-GN device assumes the role of a forwarding node or host and the attached -PANU devices act as clients, networking up to a maximum of seven PANUs. The -wireless network is formed without the need of additional hardware like a -hub or router as in the case of a conventional cabled network.

                Group -Ad-hoc Network (GN) is a temporary, ad hoc network of devices in proximity -for sharing information and services. It is called ad hoc because of its on-the-fly -or transient nature and can include up to eight (including the host) available -Bluetooth-enabled devices in the immediate vicinity, that are willing to participate.

                The -device that initiates the network - in this case the PAN-GN - becomes the -host or controller. Correspondence in a PAN between the clients is routed -through the PAN-GN device (host) in both one-to-one and one-to-many cases.

                PAN-NAP

                A PAN-NAP device plays the role of a proxy, bridge, -or a router between an existing network say a LAN or the Internet and Bluetooth-enabled -devices. The PAN-NAP device takes up to seven active wireless clients. The -NAP device acts as a bridge between PANU devices or bluetooth networks and -other networks for routing ethernet packets. The Symbian platform PAN-NAP -role allows only a single PANU client access to the uplink for the external -network.

                - PAN-NAP, bridging networks - -

                The following image shows a Bluetooth-enabled laptop accessing the -Internet through a mobile handset that is acting as a PAN-NAP device. The -Bluetooth handset may provide the uplink via GPRS, WIFI, dial-up, or in some -other way.

                For more information about please see the PAN -NAP Role Guide.

                -
                Architecture

                The -PAN Profile specification fits in between the application and the hardware -abstraction layers. It is connected to and accessed through the Comms-Infras -socket by the application.

                Initially, the connection preferences are -set in CommDB through the code. The Bluetooth stack is then initialized. An RConnection and RSocketServ instance -are created as part of initiating an ESock session and the RConnection object -opens the connection through the RSocketServ instance. RConnection::Control() allows -configuration of certain aspects of the PAN, for instance adding and deleting -devices to/from the PAN.

                Intact ethernet payloads are transported -with the BNEP (Bluetooth Network Encapsulation Protocol) underneath. The PAN -profile interacts with the Bluetooth BB (baseband) and conveys the various -roles that PAN network nodes would play.

                -
                Typical uses

                The following tutorials have been -provided to help give licensee developers guidance when writing applications -that make use of the PAN profile.

                  -

                • Creating -a Personal Area Network

                  • -

                • Adding -a device to the PAN

                  • -

                • Removing -a device from the PAN

                  • -

                • Closing -the PAN

                  • -
                + + + + + +PAN +Profile OverviewThe Bluetooth PAN Profile API supports standard IP-based network +services deployed over the Bluetooth transport layer. +
                Purpose

                The +Personal Area Network (PAN) profile is designed to make a Bluetooth network +simulate an ethernet, from an application's perspective. Symbian platform +supports only one active PAN at a time. Each remote device that connects to +the PAN device for networking purposes will be merged into the same active +PAN.

                Symbian platform provides support for a PAN agent to assume the +role of PANU (User), PAN-GN (Group ad hoc Network) or PAN-NAP (Network Access +Point).

                The Symbian PAN implementation is integrated into the Symbian +networking framework enabling IP applications to run on a Bluetooth network.

                +
                Required background

                You need to be familiar with +the PAN Profile specification.

                +
                Key concepts +and terms
                + +
                Personal Area Network (PAN)
                +

                A PAN is an ad-hoc network of devices communicating on a standard network +configuration, over a Bluetooth radio connection. A PAN may have anywhere +from 2 to 8 participating member devices.

                A PAN is not the same as +a piconet. Where a piconet is any ad-hoc networking of devices over a Bluetooth +connection for the purposes of sharing data or services, like when you pair +your phone to your Bluetooth hands-free kit, a PAN deals specifically with +networking resources.

                +                 + +
                PAN Profile
                +

                The Bluetooth specification identifies several profiles including the +Bluetooth Personal Area Networking (PAN) profile. The PAN profile simplifies +the now deprecated Bluetooth LAN Access and Dial-up Networking profiles by +reducing the number of layers in a network Bluetooth connection.

                The +PAN profile identifies certain configuration and setup details of a participant +of the network, including the PAN host. If a device wants to join a PAN it +must support and be able to be configured according to the requirements of +the profile in use. For more general information about Bluetooth profiles +see Introduction +to Bluetooth Profiles.

                +                 + +
                PAN profile roles
                +

                Typical PAN profile roles include the following:

                  +

                • PANU

                  • +

                • PAN-GN

                  • +

                • PAN-NAP

                  • +

                PANU (User) acts as a client member of a PAN-GN (Group ad hoc Network) +or a PAN-NAP (Network Access Point). Any device in either the PAN-GN or the +PAN-NAP role acts as a server.

                +                 +
                +
                PAN Roles

                The +PAN Profile roles are described below:

                PANU

                A +Bluetooth enabled device seeking entry into a network or participating in +a peer-to-peer (one on one) connection assumes the PANU role, thus becoming +a client member of the piconet.

                + PANU to PANU connection + +

                PAN-GN

                A +PAN-GN device assumes the role of a forwarding node or host and the attached +PANU devices act as clients, networking up to a maximum of seven PANUs. The +wireless network is formed without the need of additional hardware like a +hub or router as in the case of a conventional cabled network.

                Group +Ad-hoc Network (GN) is a temporary, ad hoc network of devices in proximity +for sharing information and services. It is called ad hoc because of its on-the-fly +or transient nature and can include up to eight (including the host) available +Bluetooth-enabled devices in the immediate vicinity, that are willing to participate.

                The +device that initiates the network - in this case the PAN-GN - becomes the +host or controller. Correspondence in a PAN between the clients is routed +through the PAN-GN device (host) in both one-to-one and one-to-many cases.

                PAN-NAP

                A PAN-NAP device plays the role of a proxy, bridge, +or a router between an existing network say a LAN or the Internet and Bluetooth-enabled +devices. The PAN-NAP device takes up to seven active wireless clients. The +NAP device acts as a bridge between PANU devices or bluetooth networks and +other networks for routing ethernet packets. The Symbian platform PAN-NAP +role allows only a single PANU client access to the uplink for the external +network.

                + PAN-NAP, bridging networks + +

                The following image shows a Bluetooth-enabled laptop accessing the +Internet through a mobile handset that is acting as a PAN-NAP device. The +Bluetooth handset may provide the uplink via GPRS, WIFI, dial-up, or in some +other way.

                For more information about please see the PAN +NAP Role Guide.

                +
                Architecture

                The +PAN Profile specification fits in between the application and the hardware +abstraction layers. It is connected to and accessed through the Comms-Infras +socket by the application.

                Initially, the connection preferences are +set in CommDB through the code. The Bluetooth stack is then initialized. An RConnection and RSocketServ instance +are created as part of initiating an ESock session and the RConnection object +opens the connection through the RSocketServ instance. RConnection::Control() allows +configuration of certain aspects of the PAN, for instance adding and deleting +devices to/from the PAN.

                Intact ethernet payloads are transported +with the BNEP (Bluetooth Network Encapsulation Protocol) underneath. The PAN +profile interacts with the Bluetooth BB (baseband) and conveys the various +roles that PAN network nodes would play.

                +
                Typical uses

                The following tutorials have been +provided to help give licensee developers guidance when writing applications +that make use of the PAN profile.

                  +

                • Creating +a Personal Area Network

                  • +

                • Adding +a device to the PAN

                  • +

                • Removing +a device from the PAN

                  • +

                • Closing +the PAN

                  • +
                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DEF3B8B3-5BD7-505B-93F9-A20CE00FFAE6.dita --- a/Symbian3/SDK/Source/GUID-DEF3B8B3-5BD7-505B-93F9-A20CE00FFAE6.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-DEF3B8B3-5BD7-505B-93F9-A20CE00FFAE6.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,297 +1,297 @@ - - - - - -File Server -Plugin ConceptsThis topic describes the file server plug-in concepts. -

                File server plugins can issue direct file server requests, interpret and -modify inbound messages and change file and metadata. A compression plugin -may need to intercept file read or file write requests which are sent from -the client to provide a seamless user experience. This operation requires -the modification of the data, position and length arguments that are sent -from the client to the file server.

                -

                There are some limitations to the file server plugin framework:

                -
                  -

                • The file server plugin -framework only operates on one client file at any time. However, a plugin -itself can operate on any number of files during a single request from the -client.

                  • -

                • The file server plugin -framework does not enable the compression or encryption of whole volumes. -If access to the whole media volume is needed use a file -server extension rather than a plugin.

                  • -

                • File modification plugins -cannot operate on demand paged executables. Demand paging does not use the -file server, so the plugin framework cannot be used to encrypt/process the -executable.

                  • -
                - The improved framework will not prevent deadlock with existing plugins. -Plugins that currently issue RFs requests must be migrated -to the new APIs to prevent deadlock. Follow the guidelines within the plugin implementation tutorial -
                  -

                • Plugin type,

                  • -

                • Architecture,

                  • -

                • Plugin order,

                  • -

                • Drive selection,

                  • -

                • Interception of file server requests,

                  • -

                • Security.

                  • -
                -
                Plugin type

                There -are two different types of file server plugins:

                  -

                • Observer plugins - intercept -requests but do not modify file data or associated meta data.

                  Examples -of observer plugins are those for virus scanning or logging.

                  • -

                • Modifier plugins - intercept -requests and modify the data or associated meta data of the target files or -directories..

                  Examples of file modifier plugins are compression and -encryption plugins.

                  • -
                -
                Architecture

                This -section describes the structure of the plugin framework and the changes that -have been made to the framework in v9.5:

                  -

                • Threads and execution context,

                  • -

                • Exclusive access,

                  • -

                • Intercepting requests to the ROM drive,

                  • -

                • Preventing deadlock.

                  • -

                The diagram below shows how plugins fit into the File Server software -stack.

                - -

                Note: more than one plugin can be loaded into the file server -at the same time. A plugin is not aware of other plugins.

                Threads and execution context

                The -Symbian platform File Server has multiple threads. There is a thread for each -drive in use and a main thread that receives the requests from clients and -sends them to the drive threads. Synchronous drives, however, do not have -their own drive thread; requests for these are processed by the main thread. -There is also a separate thread for processing session disconnect requests.

                Each -plugin also has its own thread for processing requests. Requests are dispatched -to the plugin thread associated with the request's drive before they are dispatched -to the drive thread. This is discussed in more detail in interception of file server requests.

                Exclusive access

                Previously, -when a client application opens a file for exclusive write access, no other -clients could access the file until the client closed its associated subsession. -This also applied to plugins that needed to modify file data (as they are -also clients of the file server).

                Symbian platform provides plugins -that are able to perform operations on files and directories irrespective -of the mode in which the file has been opened.

                Operations are now -able to use the same file handle as the originating request (run in the same -context as the original request) so files opened for exclusive access can -still be written to by a plugin wishing to modify the file.

                Intercepting ROM drive requests

                Previously, -plugins could not intercept any requests to the ROM drive (Z) however, there -is a requirement to be able to intercept requests on this drive to enable -secure-load and logging plugins. Requests to drive Z can now be intercepted -by plugins. See the tutorial for CFsPluginFactory for more details.

                Preventing deadlock

                The -new framework allows a plugin to have direct access to file data without the -need to issue new file server requests through the RFile, RDir and RFs client -APIs. In the pre-9.5 approach it was possible to reach deadlock if more than -one plugin was present.

                The diagram below shows two plugins in the -pre v9.5 framework. If both plugins issue new file server requests and if -the plugins are not re-entrant safe this can lead to deadlock in the file -server.

                - File server deadlock - -

                The framework introduced in v9.5 prevents deadlock by allowing plugins -to issue internal file server requests after intercepting a request by using -the newly introduced RFilePlugin, RDirPlugin and RFsPlugin APIs -and not by using the RFs, RFile and RDir APIs. -Internally issued requests are only dispatched to plugins mounted below the -issuing plugin and the appropriate drive thread.

                The sequence of events -for a typical plugin intercepting a file read request is illustrated below:

                - Read request intercepted by a plugin - - -

                The classes RFilePlugin, RDirPlugin and RFsPlugin have -been introduced to facilitate plugins with direct access behaviour on file -and directory requests. These classes are analogous to the client-side RFile, RDir and RFs classes and have functions with similar or identical signitures.

                In -order to perform requests on a file it is necessary to open a sub-session -by calling either AdoptFromClient() or Open(). AdoptFromClient() is -used in order to open a sub-session with the file associated with the client’s -request. Alternatively the Open() method can be used to open -either a different file, or the file associated with the client’s request -possibly with a different access mode.

                More than one file can be opened -at any time by creating multiple instances of RFilePlugin.

                The -following example shows how to open many files from a plugin during a single -request:

                // Define the object -RFilePlugin clientsFile(aRequest); - -// Opens the file associated with the intercepted request -Tint r = clientsFile.AdoptFromClient(); -User::LeaveIfError(r); -TBuf<20> data; -TInt64 pos = (Tint64)0; -Tint length = 0; - -// Read the file -r = clientsFile.Read(pos, data, length); -User::LeaveIfError(r); - -// Open a second file -RFilePlugin secondFile(aRequest); -_LIT(KSecondName, ”D:\\myfile.txt”); -r = secondFile.Open(KSecondName(), EFileRead); -User::LeaveIfError(r); - -// Read from second file -TBuf<20> data2; -TInt64 pos2 = (Tint64)0; -Tint length2 = 0; - -// Read the file -r = secondFile.Read(pos2, data2, length2); -User::LeaveIfError(r); - -// Close the files -clientsFile.Close(); -secondFile.Close();

                Issuing -an internal file system request

                An internal request can be marked -as ‘Direct to Drive’. This allows requests that are generated by a plugin -to be dispatched straight to the drive thread bypassing all other plugins -which may be mounted below the plugin that issued the request. After being -processed by the drive thread the request also bypasses the plugins between -the drive thread and the plugin that the Direct to Drive request originated -from. Once returned to the plugin that generated the request, the Direct to -Drive request is complete and any other requests issued from the plugin are -processed by plugins further down the plugin-stack in the normal manner.

                The -last argument of the RFilePlugin constructor of the classes RFilePlugin, RFsPlugin and RDirPlugin is named aDirectToDrive. aDirectToDrive is -a boolean value (TBool) to indicate that the request is Direct -to Drive. The default value is EFalse indicating that the -request is interceptable by plugins further down the plugin-stack.

                -
                Plugin order

                The -Plugin framework provides support for multiple plugins to be present and active. -Plugins are arranged in a stack. Plugins intercept requests in the order they -are arranged in the stack with the plugin at the top of the stack (at the -smallest numerical absolute position) getting the first intercept. The order -of plugins in the stack is therefore crucial to the correct operation of the -file server when more than one plugin is active, especially when the plugins -are modifier plugins (i.e when both modify the data or parameters of the requests).

                If -two plugins are active and one of those is a virus scanner, for the virus -scanner to operate correctly it must be the first plugin to intercept requests. -This is so that the virus scanner can have first refusal to block any requests -for files which it believes may not be safe for opening. If there is another -plugin higher in the stack then this plugin could send Direct To Drive requests, -for example, and would significantly reduce the virus scanning ability of -the virus scanning plugin.

                Two mechanisms are provided that allow -plugin authors to control the position of their plugins in the plugin stack -these are Absolute position and Unique position.

                Absolute position

                Plugins -can be inserted into the stack by specifying an absolute position at mount -time. This absolute position is the index in the internal array of plugins -in which the plugin should be mounted. The plugin at position 0 being the -first plugin to be able to intercept requests.

                - Plugin stack showing absolute positions - - -

                The absolute position method is more appropriate for mounting plugins -that operate regardless of their position in the plugin stack or when all -of the plugins for a device are known and installed when manufactured. This -method does not suit plugins that are added after manufacture where the dependencies -of other available plugins is not known. If this is the case use the unique -position method described below.

                Unique position

                Plugins -can be ordered according to a unique position stored within the plugin. Unique -position identifiers are defined by the manufacturer during the software validation/signing -process. Unique positions are defined in the derived CFsPluginFactory class. -See the description in CFsPluginFactory.

                The position value specifies the category and position of the plugin:

                - - - -

                plugin Type

                -

                Unique Position Range

                -                 - -

                File Observers

                -

                0x20000000 - 0x2FFFFFFF

                -                 - -

                File Modifiers

                -

                0x40000000 - 0x4FFFFFFF

                -                 - - -

                File Observers do not modify data so they are allocated a lower -range of numbers placing them at the top of the plugin stack. File Modifiers -modify the data stream so they are allocated a higher range placing them lower -down the plugin stack.

                Note: a plugin has a unique position -then do not specify an absolute -position when mounting it, otherwise the error KErrNotSupported is -returned.

                -
                Drive selection

                A -File Server Plugin can intercept requests for a specific drive or for all -drives. A plugin that intercepts requests for all drives must filter requests -that are not appropriate for some drives. Requests can be filtered within -an overridden CFsPlugin::Deliver() function.

                There are two ways to specify a drive:

                  -

                • When the plugin is mounted. -See mounting -a plugin.

                  • -

                • At run-time through -the use of CFsPluginFactory::iSupportedDrives. See the -tutorial for CFsPluginFactory.

                  • -

                If the drive is not specified then RFs::MountPlugin() attempts -to mount the plugin for all drives. If this behaviour is not supported by -the plugin KErrNotSupported is returned.

                -
                Interception -of file server requests

                After a file server request has been initialised -by the main file server thread it can be intercepted by a plugin. There are -two types of intercept:

                  -

                • pre-operation intercepts,

                  • -

                • post-operation intercepts.

                  • -

                Plugins can register for pre-intercepts, for post-intercepts or for -both pre and post-intercepts.

                Pre-operation

                Pre-operation -intercepts occur before the drive associated with a request processes it. -In a file write request for example, the pre-intercept operations occur before -data has been written to the file. Requests are passed down the plugin-stack -from the file server towards the drive thread.

                When the main file -server thread has initialised a request, the request is dispatched to the -highest plugin in the stack. This plugin must have been mounted on the requested -drive and registered to pre-intercept this type of request. See mounting a plugin. The request is dispatched by calling the plugin's CFsPlugin::Deliver() function.

                The Deliver() function runs in the context of the previous calling thread, -this can be the main file server thread or a plugin thread. Override CFsPlugin::Deliver() to -filter the request. If the Deliver() function has not been -overridden then the request is dispatched for asynchronous processing by calling -the base class Deliver(). See the CFsPlugin::Deliver() tutorial section.

                Post operation

                Post-operation -intercepts occur after the drive associated with a request has processed it. -In a file write request for example, the post-intercept occurs after data -has been written to the file. Requests are passed from the drive thread back -up the stack towards the client.

                When the drive thread has finished -processing a request it dispatches it to the plugin lowest in the stack by -calling the plugin's Deliver() function.

                Filtering requests internally

                The CFSPlugin::Deliver() function -filters the request and decides what kind of action is neccessary in terms -of the flow of the request through the plugin stack:

                  -

                • KPluginMessageForward is -returned if the intercept is pre-operation. The request is passed to the next -plugin down the stack or to the drive thread if there are no more plugins.

                  • -

                • KPluginMessageComplete is -returned if the intercept is post-operation. The request is passed to the -next plugin up the stack or if there are no more plugins to process the request -it is passed to the main file server thread.

                  • -

                If the request requires processing by the plugin then the plugin's Deliver() function -calls the base class Deliver() function and the request is -dispatched to the plugin's thread for asynchronous processing.

                Asynchronous -processing is carried out in the plugin's DoRequestL() function. -A plugin can only have a single DoRequestL() function which -must handle both pre and post-intercepts. Plugin authors can use the IsPostOperation() function -of the utility class, TFsPluginRequest to indicate whether -the DoRequestL() is processing a request as a pre-intercept -or post-intercept. See the description of TFsPluginRequest.

                Once the asynchronous processing is complete the DoRequestL() function -returns KErrNone and the request is passed to the next plugin -down the stack by calling its Deliver() function. If there -are no lower plugins then the request is passed to the appropriate drive thread -for processing.

                If the plugin intercepts a request in pre-operation -and wants to complete the request on behalf of the client then the plugin -can return KErrCompletion to indicate that the request -has been completed and that the request is now in post operation mode. The -flow will then proceed to any previous plugins if mounted or directly back -to the client otherwise. KErrCompletion prevents any further -plugins further down the stack from intercepting the request.

                When -a plugin intercepts file read or file write and does an early completion (i.e. -returns KErrCompletion in pre-intercept) then the plugin -author should call TFsPluginRequest::SetSharePos() to allow -share position to be updated after early read/write completion.

                -
                Security

                File -server plugins are implemented as libraries that are loaded into the file -server process at runtime. Therefore, plugins must have the same platform -security capabilities as the file server process, these are TCB, ProtServ, DiskAdmin, AllFiles, PowerMgmt and CommDD.

                Any -user side process that wishes to load and mount plugins must have the DiskAdmin capability.

                + + + + + +File Server +Plugin ConceptsThis topic describes the file server plug-in concepts. +

                File server plugins can issue direct file server requests, interpret and +modify inbound messages and change file and metadata. A compression plugin +may need to intercept file read or file write requests which are sent from +the client to provide a seamless user experience. This operation requires +the modification of the data, position and length arguments that are sent +from the client to the file server.

                +

                There are some limitations to the file server plugin framework:

                +
                  +

                • The file server plugin +framework only operates on one client file at any time. However, a plugin +itself can operate on any number of files during a single request from the +client.

                  • +

                • The file server plugin +framework does not enable the compression or encryption of whole volumes. +If access to the whole media volume is needed use a file +server extension rather than a plugin.

                  • +

                • File modification plugins +cannot operate on demand paged executables. Demand paging does not use the +file server, so the plugin framework cannot be used to encrypt/process the +executable.

                  • +
                + The improved framework will not prevent deadlock with existing plugins. +Plugins that currently issue RFs requests must be migrated +to the new APIs to prevent deadlock. Follow the guidelines within the plugin implementation tutorial +
                  +

                • Plugin type,

                  • +

                • Architecture,

                  • +

                • Plugin order,

                  • +

                • Drive selection,

                  • +

                • Interception of file server requests,

                  • +

                • Security.

                  • +
                +
                Plugin type

                There +are two different types of file server plugins:

                  +

                • Observer plugins - intercept +requests but do not modify file data or associated meta data.

                  Examples +of observer plugins are those for virus scanning or logging.

                  • +

                • Modifier plugins - intercept +requests and modify the data or associated meta data of the target files or +directories..

                  Examples of file modifier plugins are compression and +encryption plugins.

                  • +
                +
                Architecture

                This +section describes the structure of the plugin framework and the changes that +have been made to the framework in v9.5:

                  +

                • Threads and execution context,

                  • +

                • Exclusive access,

                  • +

                • Intercepting requests to the ROM drive,

                  • +

                • Preventing deadlock.

                  • +

                The diagram below shows how plugins fit into the File Server software +stack.

                + +

                Note: more than one plugin can be loaded into the file server +at the same time. A plugin is not aware of other plugins.

                Threads and execution context

                The +Symbian platform File Server has multiple threads. There is a thread for each +drive in use and a main thread that receives the requests from clients and +sends them to the drive threads. Synchronous drives, however, do not have +their own drive thread; requests for these are processed by the main thread. +There is also a separate thread for processing session disconnect requests.

                Each +plugin also has its own thread for processing requests. Requests are dispatched +to the plugin thread associated with the request's drive before they are dispatched +to the drive thread. This is discussed in more detail in interception of file server requests.

                Exclusive access

                Previously, +when a client application opens a file for exclusive write access, no other +clients could access the file until the client closed its associated subsession. +This also applied to plugins that needed to modify file data (as they are +also clients of the file server).

                Symbian platform provides plugins +that are able to perform operations on files and directories irrespective +of the mode in which the file has been opened.

                Operations are now +able to use the same file handle as the originating request (run in the same +context as the original request) so files opened for exclusive access can +still be written to by a plugin wishing to modify the file.

                Intercepting ROM drive requests

                Previously, +plugins could not intercept any requests to the ROM drive (Z) however, there +is a requirement to be able to intercept requests on this drive to enable +secure-load and logging plugins. Requests to drive Z can now be intercepted +by plugins. See the tutorial for CFsPluginFactory for more details.

                Preventing deadlock

                The +new framework allows a plugin to have direct access to file data without the +need to issue new file server requests through the RFile, RDir and RFs client +APIs. In the pre-9.5 approach it was possible to reach deadlock if more than +one plugin was present.

                The diagram below shows two plugins in the +pre v9.5 framework. If both plugins issue new file server requests and if +the plugins are not re-entrant safe this can lead to deadlock in the file +server.

                + File server deadlock + +

                The framework introduced in v9.5 prevents deadlock by allowing plugins +to issue internal file server requests after intercepting a request by using +the newly introduced RFilePlugin, RDirPlugin and RFsPlugin APIs +and not by using the RFs, RFile and RDir APIs. +Internally issued requests are only dispatched to plugins mounted below the +issuing plugin and the appropriate drive thread.

                The sequence of events +for a typical plugin intercepting a file read request is illustrated below:

                + Read request intercepted by a plugin + + +

                The classes RFilePlugin, RDirPlugin and RFsPlugin have +been introduced to facilitate plugins with direct access behaviour on file +and directory requests. These classes are analogous to the client-side RFile, RDir and RFs classes and have functions with similar or identical signitures.

                In +order to perform requests on a file it is necessary to open a sub-session +by calling either AdoptFromClient() or Open(). AdoptFromClient() is +used in order to open a sub-session with the file associated with the client’s +request. Alternatively the Open() method can be used to open +either a different file, or the file associated with the client’s request +possibly with a different access mode.

                More than one file can be opened +at any time by creating multiple instances of RFilePlugin.

                The +following example shows how to open many files from a plugin during a single +request:

                // Define the object +RFilePlugin clientsFile(aRequest); + +// Opens the file associated with the intercepted request +Tint r = clientsFile.AdoptFromClient(); +User::LeaveIfError(r); +TBuf<20> data; +TInt64 pos = (Tint64)0; +Tint length = 0; + +// Read the file +r = clientsFile.Read(pos, data, length); +User::LeaveIfError(r); + +// Open a second file +RFilePlugin secondFile(aRequest); +_LIT(KSecondName, ”D:\\myfile.txt”); +r = secondFile.Open(KSecondName(), EFileRead); +User::LeaveIfError(r); + +// Read from second file +TBuf<20> data2; +TInt64 pos2 = (Tint64)0; +Tint length2 = 0; + +// Read the file +r = secondFile.Read(pos2, data2, length2); +User::LeaveIfError(r); + +// Close the files +clientsFile.Close(); +secondFile.Close();

                Issuing +an internal file system request

                An internal request can be marked +as ‘Direct to Drive’. This allows requests that are generated by a plugin +to be dispatched straight to the drive thread bypassing all other plugins +which may be mounted below the plugin that issued the request. After being +processed by the drive thread the request also bypasses the plugins between +the drive thread and the plugin that the Direct to Drive request originated +from. Once returned to the plugin that generated the request, the Direct to +Drive request is complete and any other requests issued from the plugin are +processed by plugins further down the plugin-stack in the normal manner.

                The +last argument of the RFilePlugin constructor of the classes RFilePlugin, RFsPlugin and RDirPlugin is named aDirectToDrive. aDirectToDrive is +a boolean value (TBool) to indicate that the request is Direct +to Drive. The default value is EFalse indicating that the +request is interceptable by plugins further down the plugin-stack.

                +
                Plugin order

                The +Plugin framework provides support for multiple plugins to be present and active. +Plugins are arranged in a stack. Plugins intercept requests in the order they +are arranged in the stack with the plugin at the top of the stack (at the +smallest numerical absolute position) getting the first intercept. The order +of plugins in the stack is therefore crucial to the correct operation of the +file server when more than one plugin is active, especially when the plugins +are modifier plugins (i.e when both modify the data or parameters of the requests).

                If +two plugins are active and one of those is a virus scanner, for the virus +scanner to operate correctly it must be the first plugin to intercept requests. +This is so that the virus scanner can have first refusal to block any requests +for files which it believes may not be safe for opening. If there is another +plugin higher in the stack then this plugin could send Direct To Drive requests, +for example, and would significantly reduce the virus scanning ability of +the virus scanning plugin.

                Two mechanisms are provided that allow +plugin authors to control the position of their plugins in the plugin stack +these are Absolute position and Unique position.

                Absolute position

                Plugins +can be inserted into the stack by specifying an absolute position at mount +time. This absolute position is the index in the internal array of plugins +in which the plugin should be mounted. The plugin at position 0 being the +first plugin to be able to intercept requests.

                + Plugin stack showing absolute positions + + +

                The absolute position method is more appropriate for mounting plugins +that operate regardless of their position in the plugin stack or when all +of the plugins for a device are known and installed when manufactured. This +method does not suit plugins that are added after manufacture where the dependencies +of other available plugins is not known. If this is the case use the unique +position method described below.

                Unique position

                Plugins +can be ordered according to a unique position stored within the plugin. Unique +position identifiers are defined by the manufacturer during the software validation/signing +process. Unique positions are defined in the derived CFsPluginFactory class. +See the description in CFsPluginFactory.

                The position value specifies the category and position of the plugin:

                + + + +

                plugin Type

                +

                Unique Position Range

                +                 + +

                File Observers

                +

                0x20000000 - 0x2FFFFFFF

                +                 + +

                File Modifiers

                +

                0x40000000 - 0x4FFFFFFF

                +                 + + +

                File Observers do not modify data so they are allocated a lower +range of numbers placing them at the top of the plugin stack. File Modifiers +modify the data stream so they are allocated a higher range placing them lower +down the plugin stack.

                Note: a plugin has a unique position +then do not specify an absolute +position when mounting it, otherwise the error KErrNotSupported is +returned.

                +
                Drive selection

                A +File Server Plugin can intercept requests for a specific drive or for all +drives. A plugin that intercepts requests for all drives must filter requests +that are not appropriate for some drives. Requests can be filtered within +an overridden CFsPlugin::Deliver() function.

                There are two ways to specify a drive:

                  +

                • When the plugin is mounted. +See mounting +a plugin.

                  • +

                • At run-time through +the use of CFsPluginFactory::iSupportedDrives. See the +tutorial for CFsPluginFactory.

                  • +

                If the drive is not specified then RFs::MountPlugin() attempts +to mount the plugin for all drives. If this behaviour is not supported by +the plugin KErrNotSupported is returned.

                +
                Interception +of file server requests

                After a file server request has been initialised +by the main file server thread it can be intercepted by a plugin. There are +two types of intercept:

                  +

                • pre-operation intercepts,

                  • +

                • post-operation intercepts.

                  • +

                Plugins can register for pre-intercepts, for post-intercepts or for +both pre and post-intercepts.

                Pre-operation

                Pre-operation +intercepts occur before the drive associated with a request processes it. +In a file write request for example, the pre-intercept operations occur before +data has been written to the file. Requests are passed down the plugin-stack +from the file server towards the drive thread.

                When the main file +server thread has initialised a request, the request is dispatched to the +highest plugin in the stack. This plugin must have been mounted on the requested +drive and registered to pre-intercept this type of request. See mounting a plugin. The request is dispatched by calling the plugin's CFsPlugin::Deliver() function.

                The Deliver() function runs in the context of the previous calling thread, +this can be the main file server thread or a plugin thread. Override CFsPlugin::Deliver() to +filter the request. If the Deliver() function has not been +overridden then the request is dispatched for asynchronous processing by calling +the base class Deliver(). See the CFsPlugin::Deliver() tutorial section.

                Post operation

                Post-operation +intercepts occur after the drive associated with a request has processed it. +In a file write request for example, the post-intercept occurs after data +has been written to the file. Requests are passed from the drive thread back +up the stack towards the client.

                When the drive thread has finished +processing a request it dispatches it to the plugin lowest in the stack by +calling the plugin's Deliver() function.

                Filtering requests internally

                The CFSPlugin::Deliver() function +filters the request and decides what kind of action is neccessary in terms +of the flow of the request through the plugin stack:

                  +

                • KPluginMessageForward is +returned if the intercept is pre-operation. The request is passed to the next +plugin down the stack or to the drive thread if there are no more plugins.

                  • +

                • KPluginMessageComplete is +returned if the intercept is post-operation. The request is passed to the +next plugin up the stack or if there are no more plugins to process the request +it is passed to the main file server thread.

                  • +

                If the request requires processing by the plugin then the plugin's Deliver() function +calls the base class Deliver() function and the request is +dispatched to the plugin's thread for asynchronous processing.

                Asynchronous +processing is carried out in the plugin's DoRequestL() function. +A plugin can only have a single DoRequestL() function which +must handle both pre and post-intercepts. Plugin authors can use the IsPostOperation() function +of the utility class, TFsPluginRequest to indicate whether +the DoRequestL() is processing a request as a pre-intercept +or post-intercept. See the description of TFsPluginRequest.

                Once the asynchronous processing is complete the DoRequestL() function +returns KErrNone and the request is passed to the next plugin +down the stack by calling its Deliver() function. If there +are no lower plugins then the request is passed to the appropriate drive thread +for processing.

                If the plugin intercepts a request in pre-operation +and wants to complete the request on behalf of the client then the plugin +can return KErrCompletion to indicate that the request +has been completed and that the request is now in post operation mode. The +flow will then proceed to any previous plugins if mounted or directly back +to the client otherwise. KErrCompletion prevents any further +plugins further down the stack from intercepting the request.

                When +a plugin intercepts file read or file write and does an early completion (i.e. +returns KErrCompletion in pre-intercept) then the plugin +author should call TFsPluginRequest::SetSharePos() to allow +share position to be updated after early read/write completion.

                +
                Security

                File +server plugins are implemented as libraries that are loaded into the file +server process at runtime. Therefore, plugins must have the same platform +security capabilities as the file server process, these are TCB, ProtServ, DiskAdmin, AllFiles, PowerMgmt and CommDD.

                Any +user side process that wishes to load and mount plugins must have the DiskAdmin capability.

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DF1B3C55-2CFC-49C8-88A2-D10925ECAC3E.dita --- a/Symbian3/SDK/Source/GUID-DF1B3C55-2CFC-49C8-88A2-D10925ECAC3E.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-DF1B3C55-2CFC-49C8-88A2-D10925ECAC3E.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,143 +1,143 @@ - - - - - -Known -Issues -
                ARM RVCT compiler -issues with STLport

                Due to a defect in the ARM RVCT compiler versions -2.2, 3.1 and 4.0, building STLport v4 or STLport-based applications, creates -some invalid export entries in DEF files. To workaround this issue, perform -the following steps:

                  -

                1. Use the GCCE compiler -to generate the DEF file, if it is not available.

                  2. -

                2. Ignore the warnings -generated by the ARM RVCT compiler.

                  When you ignore the warnings, -do not freeze the invalid export entries in the DEF file using the ARM RVCT -compiler.
                  3. -
                -
                Use -of Global Destructor

                Symbian does not invoke destructors -of global objects upon program termination. For example, in the code below, -the destructor ~foo() is not called upon program termination. -At the moment, it is advised not to perform any important operations using -destructors.

                #include -using namespace std; -class foo -{ -public: -foo() -{ -cout <<"Entering foo\n"; -} -~foo() -{ -cout <<"Leaving foo\n"; -} -}; -foo foo_bar; -int main(void) -{ -return 0; -} - -
                -
                Issues -with <codeph>new</codeph> operator

                Throwing bad_alloc or -any object from new on ARMV5 platfrom crashes. RVCT reports an exception when new throws bad_alloc. -The problem occurs even if the user throws any object from within an overloaded -operator new. The following new signatures are affected:

                void *operator new(unsigned int aSize); -void *operator new[](unsigned int aSize); -

                The following code snippet is an example that depicts the problem:

                class Dummy -{ -}; -void *operator new(unsigned int aSize) -{ -void* __y = malloc(aSize); -// try to simulate bad alloc -if (__y == 0) -{ -throw Dummy(); //this will result in a crash -} -return __y; -} -

                To implement user owned overloaded version of new, the user -must implement them as class specific. The other way this could be achieved -is by defining new similar to:

                void* operator new(size_t s,newarg) throw (std::bad_alloc)

                and -invoking it as:

                Myclass* my = new(S60) Myclass() -
                -
                The <codeph>id</codeph> Member -Issue

                The id member variable of facet classes -cannot be accessed directly, it has to be accessed via the GetFacetLocaleId() interface.

                Following -code snippet is an example that illustrates how to uselocale::id while -writing an application on top of the Standard Template Library (STL). Declare -a static method GetFacetLocaleId() instead of the member -variable id when, defining a class base_facet inherited from locale::facet in -a header file.

                //b_facet.h -class base_facet : public locale::facet -{ -public: -static locale::id; -GetFacetLocaleId(); // in place of static locale::id -id; -}; -

                In the source file define the method GetFacetLocaleId().

                //b_facet.cpp -locale::id base_facet_id; -locale::id& base_facet::GetFacetLocaleId() -{ -return base_facet_id; -} -
                -
                Interleaving -Symbian and Standard C++ Code

                The user must exercise caution while -using try or catch, and trap while -interleaving Symbian C++ and Standard C++ code. Adapter code is required to -handover or suppress exception coming from the Standard C++ to Symbian C++ -code.

                Following code snippet illustrates how to use the adaptor code. -Adaptor code can be a part of DLLA.

                DLL A - Symbian C++ code

                void CDoIt::Doit() -{ - class foo *p = new __foo__(); - p->bar(); - delete p; -}; -

                DLLB - Standard C++ code

                class foo { -public: - foo(); //constructor - bar(); // throw exception -}; -

                DLLC - Adaptor code

                class __foo__ { - foo *p; -public: - __foo__(); - bar(); -}; - -void __foo__::__foo__() -{ - int err = 0; - try { - p = new foo(); - } catch { - err = some error - } - User::LeaveIfError(err); -}; -void __foo__::bar() -{ - int err = 0; - try { - p->bar(); - } catch { - err = some error - } - User::LeaveIfError(err); -}; -
                + + + + + +Known +Issues +
                ARM RVCT compiler +issues with STLport

                Due to a defect in the ARM RVCT compiler versions +2.2, 3.1 and 4.0, building STLport v4 or STLport-based applications, creates +some invalid export entries in DEF files. To workaround this issue, perform +the following steps:

                  +

                1. Use the GCCE compiler +to generate the DEF file, if it is not available.

                  2. +

                2. Ignore the warnings +generated by the ARM RVCT compiler.

                  When you ignore the warnings, +do not freeze the invalid export entries in the DEF file using the ARM RVCT +compiler.
                  3. +
                +
                Use +of Global Destructor

                Symbian does not invoke destructors +of global objects upon program termination. For example, in the code below, +the destructor ~foo() is not called upon program termination. +At the moment, it is advised not to perform any important operations using +destructors.

                #include +using namespace std; +class foo +{ +public: +foo() +{ +cout <<"Entering foo\n"; +} +~foo() +{ +cout <<"Leaving foo\n"; +} +}; +foo foo_bar; +int main(void) +{ +return 0; +} + +
                +
                Issues +with <codeph>new</codeph> operator

                Throwing bad_alloc or +any object from new on ARMV5 platfrom crashes. RVCT reports an exception when new throws bad_alloc. +The problem occurs even if the user throws any object from within an overloaded +operator new. The following new signatures are affected:

                void *operator new(unsigned int aSize); +void *operator new[](unsigned int aSize); +

                The following code snippet is an example that depicts the problem:

                class Dummy +{ +}; +void *operator new(unsigned int aSize) +{ +void* __y = malloc(aSize); +// try to simulate bad alloc +if (__y == 0) +{ +throw Dummy(); //this will result in a crash +} +return __y; +} +

                To implement user owned overloaded version of new, the user +must implement them as class specific. The other way this could be achieved +is by defining new similar to:

                void* operator new(size_t s,newarg) throw (std::bad_alloc)

                and +invoking it as:

                Myclass* my = new(S60) Myclass() +
                +
                The <codeph>id</codeph> Member +Issue

                The id member variable of facet classes +cannot be accessed directly, it has to be accessed via the GetFacetLocaleId() interface.

                Following +code snippet is an example that illustrates how to uselocale::id while +writing an application on top of the Standard Template Library (STL). Declare +a static method GetFacetLocaleId() instead of the member +variable id when, defining a class base_facet inherited from locale::facet in +a header file.

                //b_facet.h +class base_facet : public locale::facet +{ +public: +static locale::id; +GetFacetLocaleId(); // in place of static locale::id +id; +}; +

                In the source file define the method GetFacetLocaleId().

                //b_facet.cpp +locale::id base_facet_id; +locale::id& base_facet::GetFacetLocaleId() +{ +return base_facet_id; +} +
                +
                Interleaving +Symbian and Standard C++ Code

                The user must exercise caution while +using try or catch, and trap while +interleaving Symbian C++ and Standard C++ code. Adapter code is required to +handover or suppress exception coming from the Standard C++ to Symbian C++ +code.

                Following code snippet illustrates how to use the adaptor code. +Adaptor code can be a part of DLLA.

                DLL A - Symbian C++ code

                void CDoIt::Doit() +{ + class foo *p = new __foo__(); + p->bar(); + delete p; +}; +

                DLLB - Standard C++ code

                class foo { +public: + foo(); //constructor + bar(); // throw exception +}; +

                DLLC - Adaptor code

                class __foo__ { + foo *p; +public: + __foo__(); + bar(); +}; + +void __foo__::__foo__() +{ + int err = 0; + try { + p = new foo(); + } catch { + err = some error + } + User::LeaveIfError(err); +}; +void __foo__::bar() +{ + int err = 0; + try { + p->bar(); + } catch { + err = some error + } + User::LeaveIfError(err); +}; +
                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DF37DAC3-8B86-5674-B025-931F743ED888_d0e124732_href.png Binary file Symbian3/SDK/Source/GUID-DF37DAC3-8B86-5674-B025-931F743ED888_d0e124732_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DF37DAC3-8B86-5674-B025-931F743ED888_d0e131270_href.png Binary file Symbian3/SDK/Source/GUID-DF37DAC3-8B86-5674-B025-931F743ED888_d0e131270_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DF3ECD47-4A5B-5836-B5CA-ACCEE98412D4_d0e16477_href.png Binary file Symbian3/SDK/Source/GUID-DF3ECD47-4A5B-5836-B5CA-ACCEE98412D4_d0e16477_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DF3ECD47-4A5B-5836-B5CA-ACCEE98412D4_d0e46823_href.png Binary file Symbian3/SDK/Source/GUID-DF3ECD47-4A5B-5836-B5CA-ACCEE98412D4_d0e46823_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DF3ECD47-4A5B-5836-B5CA-ACCEE98412D4_d0e52379_href.png Binary file Symbian3/SDK/Source/GUID-DF3ECD47-4A5B-5836-B5CA-ACCEE98412D4_d0e52379_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DF3F2FD0-FF68-4CEF-843F-CBC9E84F3A7F.dita --- a/Symbian3/SDK/Source/GUID-DF3F2FD0-FF68-4CEF-843F-CBC9E84F3A7F.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-DF3F2FD0-FF68-4CEF-843F-CBC9E84F3A7F.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,23 +1,23 @@ - - - - - -Signal -pane -

                The Signal pane displays the cellular signal strength indicator.

                - -Signal pane (left) - - -

                The indicator may also contain information about a packet data connection -(such as GPRS) status.

                -

                The Signal pane is not accessible -to applications.

                + + + + + +Signal +pane +

                The Signal pane displays the cellular signal strength indicator.

                + +Signal pane (left) + + +

                The indicator may also contain information about a packet data connection +(such as GPRS) status.

                +

                The Signal pane is not accessible +to applications.

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DF7959E7-15A4-5504-8D22-B8189DB2688E.dita --- a/Symbian3/SDK/Source/GUID-DF7959E7-15A4-5504-8D22-B8189DB2688E.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-DF7959E7-15A4-5504-8D22-B8189DB2688E.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,12 +1,12 @@ - - - - - -Introduction to Swizzles and deferred loading

                In complex applications involving a large network of objects, it may be desirable, and even necessary, to defer the loading of objects into memory from the store.

                It should, therefore, be possible to represent such an object in one of two ways:

                • by the stream ID of the stream containing the external representation of that object, if it is not in memory.

                • by a pointer, if it is in memory (or has already been loaded into memory); the pointer points to the in-memory object.

                A Swizzle is a device for handling this dual representation.

                A typical container type object, therefore, does not have a pointer directly to a contained object, but has a Swizzle which can represent that contained object either as a pointer or as a stream ID, as illustrated in the following diagram.

                A Swizzle can be considered as a lean, but efficient, container in its own right.

                The concrete Swizzle classes are templated; the template parameter defines the type of object which the Swizzle represents.

                There are two general concrete Swizzle classes:

                • TSwizzle<class T>

                • TSwizzleC<class T>

                A TSwizzle<class T> represents a <class T> type object. Full access is available to the <class T> type object through the Swizzle.

                A TSwizzleC<class T> represents a <class T> type object. Access to the object is limited; in particular the object cannot be changed.

                 \ No newline at end of file + + + + + +Introduction to Swizzles and deferred loading

                In complex applications involving a large network of objects, it may be desirable, and even necessary, to defer the loading of objects into memory from the store.

                It should, therefore, be possible to represent such an object in one of two ways:

                • by the stream ID of the stream containing the external representation of that object, if it is not in memory.

                • by a pointer, if it is in memory (or has already been loaded into memory); the pointer points to the in-memory object.

                A Swizzle is a device for handling this dual representation.

                A typical container type object, therefore, does not have a pointer directly to a contained object, but has a Swizzle which can represent that contained object either as a pointer or as a stream ID, as illustrated in the following diagram.

                A Swizzle can be considered as a lean, but efficient, container in its own right.

                The concrete Swizzle classes are templated; the template parameter defines the type of object which the Swizzle represents.

                There are two general concrete Swizzle classes:

                • TSwizzle<class T>

                • TSwizzleC<class T>

                A TSwizzle<class T> represents a <class T> type object. Full access is available to the <class T> type object through the Swizzle.

                A TSwizzleC<class T> represents a <class T> type object. Access to the object is limited; in particular the object cannot be changed.

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DF83E798-408C-5E69-9520-A733DAEAB788_d0e79092_href.png Binary file Symbian3/SDK/Source/GUID-DF83E798-408C-5E69-9520-A733DAEAB788_d0e79092_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DF83E798-408C-5E69-9520-A733DAEAB788_d0e85804_href.png Binary file Symbian3/SDK/Source/GUID-DF83E798-408C-5E69-9520-A733DAEAB788_d0e85804_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DFBBA71F-0042-4303-B66F-0D291106B655-master.png Binary file Symbian3/SDK/Source/GUID-DFBBA71F-0042-4303-B66F-0D291106B655-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DFBBA71F-0042-4303-B66F-0D291106B655_d0e51793_href.png Binary file Symbian3/SDK/Source/GUID-DFBBA71F-0042-4303-B66F-0D291106B655_d0e51793_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DFBBA71F-0042-4303-B66F-0D291106B655_d0e57398_href.png Binary file Symbian3/SDK/Source/GUID-DFBBA71F-0042-4303-B66F-0D291106B655_d0e57398_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DFBBA71F-0042-4303-B66F-0D291106B655_d0e58465_href.png Binary file Symbian3/SDK/Source/GUID-DFBBA71F-0042-4303-B66F-0D291106B655_d0e58465_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DFBBA71F-0042-4303-B66F-0D291106B655_d0e62487_href.png Binary file Symbian3/SDK/Source/GUID-DFBBA71F-0042-4303-B66F-0D291106B655_d0e62487_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DFBBA71F-0042-4303-B66F-0D291106B655_d0e69038_href.png Binary file Symbian3/SDK/Source/GUID-DFBBA71F-0042-4303-B66F-0D291106B655_d0e69038_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-DFBBA71F-0042-4303-B66F-0D291106B655_d0e74183_href.png Binary file Symbian3/SDK/Source/GUID-DFBBA71F-0042-4303-B66F-0D291106B655_d0e74183_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E049772D-A96F-592F-AF59-C9B69E8D24C1-GENID-1-10-1-3-1-1-4-1-4-1.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-E049772D-A96F-592F-AF59-C9B69E8D24C1-GENID-1-10-1-3-1-1-4-1-4-1.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,84 @@ + + + + + +Using +the extended notifier framework +
                The framework

                Notifiers +allow components with no direct UI linkage to interact with the user via an +interface such as a dialog box. For example, a low level component might want +to warn the user about a low battery level. Typically, such a component would +not have direct access, or knowledge of, a UI. The solution to this problem +is provided by what are known as notifiers and the extended notifier framework. +The UI element (the dialog box) is provided by the device's UI +through what are known as notifier plug-ins.

                The extended notifier +framework is a system that loads these plug-in DLLs from Z\sys\bin\notifiers.

                These +DLLs are expected to export a single factory function at ordinal #1 that returns +an array of notifiers. A special notifier target type is supported by makmake. +The second Uid for notifiers should be 0x10005522.

                The behaviour of +notifiers is supplied by providing an implementation of the MEikSrvNotifierBase2 interface +. A notifier is associated with a channel and a priority. Priority is used +to determine the order of activation if more than one notifier is activated +at any time. Priority only affects notifiers on the same channel (for example, +a screen or LED). This means that two notifiers can be active at the same +time provided that they are on different channels.

                The channel and +priority used by all the notifiers in the system needs to be considered carefully +to avoid them interfering with each other in unexpected ways. The MEikSrvNotifierBase2 derived +class also needs to be implemented correctly. Notifiers run in the UIKON server +thread and are accessed on the client side via RNotifier. +Note that if a notifier panics it will lead to a device reset.

                +
                The factory +function

                The factory function at ordinal #1 is expected to return +an array of notifiers. The following is a typical implementation:

                EXPORT_C CArrayPtr<MEikSrvNotifierBase2>* NotifierArray() + { + CArrayPtrFlat<MEikSrvNotifierBase2>* notifiers=new CArrayPtrFlat<MEikSrvNotifierBase2>(5); + if (notifiers) + { + TRAPD(err, CreateNotifiersL(notifiers)); + if(err) + { + TInt count = notifiers->Count(); + while(count--) + { + (*notifiers)[count]->Release(); + } + delete notifiers; + notifiers = NULL; + } + } + return(notifiers); + } +

                Ownership of the notifier array or its contents is not +transferred to the framework until this function returns. To avoid memory +leaks, all acquired resources must be freed if anything goes wrong part of +the way through its processing.

                Calling Release() on +a notifier should cause that notifier to free all of its resources, and as +a minimum should call delete this;. See MEikSrvNotifierBase2::Release().

                Returning +a Null value from this function causes the framework to leave +with KErrNoMemory.

                The CreateNotifiersL() function +should be implemented as follows:

                LOCAL_C void CreateNotifiersL(CArrayPtrFlat<MEikSrvNotifierBase2>* aNotifiers) + { + MEikSrvNotifierBase2* notifier; + notifier = CMyNotifierA::NewL(); + CleanupStack::PushL(notifier); + aNotifiers->AppendL(notifier); + CleanupStack::Pop(notifier); + ... + ... + // typically, repeat this procedure for as + // many notifiers as are implemented + // in the plug-in DLL. + }

                Use of the standard Symbian platform technique +of using the cleanup stack to hold pointers to allocated objects for as long +as these objects have no owner; this prevents memory leaks. For this reason, +avoid using a technique such as aNotifiers->AppendL(CMyNotifierA::NewL());, +which, although shorter, will result in a memory leak if the AppendL() operation +fails.

                +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E049772D-A96F-592F-AF59-C9B69E8D24C1-GENID-1-10-1-6-1-1-3-1-10-1.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-E049772D-A96F-592F-AF59-C9B69E8D24C1-GENID-1-10-1-6-1-1-3-1-10-1.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,84 @@ + + + + + +Using +the extended notifier framework +
                The framework

                Notifiers +allow components with no direct UI linkage to interact with the user via an +interface such as a dialog box. For example, a low level component might want +to warn the user about a low battery level. Typically, such a component would +not have direct access, or knowledge of, a UI. The solution to this problem +is provided by what are known as notifiers and the extended notifier framework. +The UI element (the dialog box) is provided by the device's UI +through what are known as notifier plug-ins.

                The extended notifier +framework is a system that loads these plug-in DLLs from Z\sys\bin\notifiers.

                These +DLLs are expected to export a single factory function at ordinal #1 that returns +an array of notifiers. A special notifier target type is supported by makmake. +The second Uid for notifiers should be 0x10005522.

                The behaviour of +notifiers is supplied by providing an implementation of the MEikSrvNotifierBase2 interface +. A notifier is associated with a channel and a priority. Priority is used +to determine the order of activation if more than one notifier is activated +at any time. Priority only affects notifiers on the same channel (for example, +a screen or LED). This means that two notifiers can be active at the same +time provided that they are on different channels.

                The channel and +priority used by all the notifiers in the system needs to be considered carefully +to avoid them interfering with each other in unexpected ways. The MEikSrvNotifierBase2 derived +class also needs to be implemented correctly. Notifiers run in the UIKON server +thread and are accessed on the client side via RNotifier. +Note that if a notifier panics it will lead to a device reset.

                +
                The factory +function

                The factory function at ordinal #1 is expected to return +an array of notifiers. The following is a typical implementation:

                EXPORT_C CArrayPtr<MEikSrvNotifierBase2>* NotifierArray() + { + CArrayPtrFlat<MEikSrvNotifierBase2>* notifiers=new CArrayPtrFlat<MEikSrvNotifierBase2>(5); + if (notifiers) + { + TRAPD(err, CreateNotifiersL(notifiers)); + if(err) + { + TInt count = notifiers->Count(); + while(count--) + { + (*notifiers)[count]->Release(); + } + delete notifiers; + notifiers = NULL; + } + } + return(notifiers); + } +

                Ownership of the notifier array or its contents is not +transferred to the framework until this function returns. To avoid memory +leaks, all acquired resources must be freed if anything goes wrong part of +the way through its processing.

                Calling Release() on +a notifier should cause that notifier to free all of its resources, and as +a minimum should call delete this;. See MEikSrvNotifierBase2::Release().

                Returning +a Null value from this function causes the framework to leave +with KErrNoMemory.

                The CreateNotifiersL() function +should be implemented as follows:

                LOCAL_C void CreateNotifiersL(CArrayPtrFlat<MEikSrvNotifierBase2>* aNotifiers) + { + MEikSrvNotifierBase2* notifier; + notifier = CMyNotifierA::NewL(); + CleanupStack::PushL(notifier); + aNotifiers->AppendL(notifier); + CleanupStack::Pop(notifier); + ... + ... + // typically, repeat this procedure for as + // many notifiers as are implemented + // in the plug-in DLL. + }

                Use of the standard Symbian platform technique +of using the cleanup stack to hold pointers to allocated objects for as long +as these objects have no owner; this prevents memory leaks. For this reason, +avoid using a technique such as aNotifiers->AppendL(CMyNotifierA::NewL());, +which, although shorter, will result in a memory leak if the AppendL() operation +fails.

                +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E049772D-A96F-592F-AF59-C9B69E8D24C1-GENID-1-8-1-3-1-1-11-1-4-1.dita --- a/Symbian3/SDK/Source/GUID-E049772D-A96F-592F-AF59-C9B69E8D24C1-GENID-1-8-1-3-1-1-11-1-4-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,84 +0,0 @@ - - - - - -Using -the extended notifier framework -
                The framework

                Notifiers -allow components with no direct UI linkage to interact with the user via an -interface such as a dialog box. For example, a low level component might want -to warn the user about a low battery level. Typically, such a component would -not have direct access, or knowledge of, a UI. The solution to this problem -is provided by what are known as notifiers and the extended notifier framework. -The UI element (the dialog box) is provided by the device's UI -through what are known as notifier plug-ins.

                The extended notifier -framework is a system that loads these plug-in DLLs from Z\sys\bin\notifiers.

                These -DLLs are expected to export a single factory function at ordinal #1 that returns -an array of notifiers. A special notifier target type is supported by makmake. -The second Uid for notifiers should be 0x10005522.

                The behaviour of -notifiers is supplied by providing an implementation of the MEikSrvNotifierBase2 interface -. A notifier is associated with a channel and a priority. Priority is used -to determine the order of activation if more than one notifier is activated -at any time. Priority only affects notifiers on the same channel (for example, -a screen or LED). This means that two notifiers can be active at the same -time provided that they are on different channels.

                The channel and -priority used by all the notifiers in the system needs to be considered carefully -to avoid them interfering with each other in unexpected ways. The MEikSrvNotifierBase2 derived -class also needs to be implemented correctly. Notifiers run in the UIKON server -thread and are accessed on the client side via RNotifier. -Note that if a notifier panics it will lead to a device reset.

                -
                The factory -function

                The factory function at ordinal #1 is expected to return -an array of notifiers. The following is a typical implementation:

                EXPORT_C CArrayPtr<MEikSrvNotifierBase2>* NotifierArray() - { - CArrayPtrFlat<MEikSrvNotifierBase2>* notifiers=new CArrayPtrFlat<MEikSrvNotifierBase2>(5); - if (notifiers) - { - TRAPD(err, CreateNotifiersL(notifiers)); - if(err) - { - TInt count = notifiers->Count(); - while(count--) - { - (*notifiers)[count]->Release(); - } - delete notifiers; - notifiers = NULL; - } - } - return(notifiers); - } -

                Ownership of the notifier array or its contents is not -transferred to the framework until this function returns. To avoid memory -leaks, all acquired resources must be freed if anything goes wrong part of -the way through its processing.

                Calling Release() on -a notifier should cause that notifier to free all of its resources, and as -a minimum should call delete this;. See MEikSrvNotifierBase2::Release().

                Returning -a Null value from this function causes the framework to leave -with KErrNoMemory.

                The CreateNotifiersL() function -should be implemented as follows:

                LOCAL_C void CreateNotifiersL(CArrayPtrFlat<MEikSrvNotifierBase2>* aNotifiers) - { - MEikSrvNotifierBase2* notifier; - notifier = CMyNotifierA::NewL(); - CleanupStack::PushL(notifier); - aNotifiers->AppendL(notifier); - CleanupStack::Pop(notifier); - ... - ... - // typically, repeat this procedure for as - // many notifiers as are implemented - // in the plug-in DLL. - }

                Use of the standard Symbian platform technique -of using the cleanup stack to hold pointers to allocated objects for as long -as these objects have no owner; this prevents memory leaks. For this reason, -avoid using a technique such as aNotifiers->AppendL(CMyNotifierA::NewL());, -which, although shorter, will result in a memory leak if the AppendL() operation -fails.

                -                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E049772D-A96F-592F-AF59-C9B69E8D24C1-GENID-1-8-1-6-1-1-3-1-10-1.dita --- a/Symbian3/SDK/Source/GUID-E049772D-A96F-592F-AF59-C9B69E8D24C1-GENID-1-8-1-6-1-1-3-1-10-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,84 +0,0 @@ - - - - - -Using -the extended notifier framework -
                The framework

                Notifiers -allow components with no direct UI linkage to interact with the user via an -interface such as a dialog box. For example, a low level component might want -to warn the user about a low battery level. Typically, such a component would -not have direct access, or knowledge of, a UI. The solution to this problem -is provided by what are known as notifiers and the extended notifier framework. -The UI element (the dialog box) is provided by the device's UI -through what are known as notifier plug-ins.

                The extended notifier -framework is a system that loads these plug-in DLLs from Z\sys\bin\notifiers.

                These -DLLs are expected to export a single factory function at ordinal #1 that returns -an array of notifiers. A special notifier target type is supported by makmake. -The second Uid for notifiers should be 0x10005522.

                The behaviour of -notifiers is supplied by providing an implementation of the MEikSrvNotifierBase2 interface -. A notifier is associated with a channel and a priority. Priority is used -to determine the order of activation if more than one notifier is activated -at any time. Priority only affects notifiers on the same channel (for example, -a screen or LED). This means that two notifiers can be active at the same -time provided that they are on different channels.

                The channel and -priority used by all the notifiers in the system needs to be considered carefully -to avoid them interfering with each other in unexpected ways. The MEikSrvNotifierBase2 derived -class also needs to be implemented correctly. Notifiers run in the UIKON server -thread and are accessed on the client side via RNotifier. -Note that if a notifier panics it will lead to a device reset.

                -
                The factory -function

                The factory function at ordinal #1 is expected to return -an array of notifiers. The following is a typical implementation:

                EXPORT_C CArrayPtr<MEikSrvNotifierBase2>* NotifierArray() - { - CArrayPtrFlat<MEikSrvNotifierBase2>* notifiers=new CArrayPtrFlat<MEikSrvNotifierBase2>(5); - if (notifiers) - { - TRAPD(err, CreateNotifiersL(notifiers)); - if(err) - { - TInt count = notifiers->Count(); - while(count--) - { - (*notifiers)[count]->Release(); - } - delete notifiers; - notifiers = NULL; - } - } - return(notifiers); - } -

                Ownership of the notifier array or its contents is not -transferred to the framework until this function returns. To avoid memory -leaks, all acquired resources must be freed if anything goes wrong part of -the way through its processing.

                Calling Release() on -a notifier should cause that notifier to free all of its resources, and as -a minimum should call delete this;. See MEikSrvNotifierBase2::Release().

                Returning -a Null value from this function causes the framework to leave -with KErrNoMemory.

                The CreateNotifiersL() function -should be implemented as follows:

                LOCAL_C void CreateNotifiersL(CArrayPtrFlat<MEikSrvNotifierBase2>* aNotifiers) - { - MEikSrvNotifierBase2* notifier; - notifier = CMyNotifierA::NewL(); - CleanupStack::PushL(notifier); - aNotifiers->AppendL(notifier); - CleanupStack::Pop(notifier); - ... - ... - // typically, repeat this procedure for as - // many notifiers as are implemented - // in the plug-in DLL. - }

                Use of the standard Symbian platform technique -of using the cleanup stack to hold pointers to allocated objects for as long -as these objects have no owner; this prevents memory leaks. For this reason, -avoid using a technique such as aNotifiers->AppendL(CMyNotifierA::NewL());, -which, although shorter, will result in a memory leak if the AppendL() operation -fails.

                -                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E04B4397-2926-4F4D-A7FE-F79F3BF37BF8-master.png Binary file Symbian3/SDK/Source/GUID-E04B4397-2926-4F4D-A7FE-F79F3BF37BF8-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E04B4397-2926-4F4D-A7FE-F79F3BF37BF8_d0e67575_href.png Binary file Symbian3/SDK/Source/GUID-E04B4397-2926-4F4D-A7FE-F79F3BF37BF8_d0e67575_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E04B4397-2926-4F4D-A7FE-F79F3BF37BF8_d0e72373_href.png Binary file Symbian3/SDK/Source/GUID-E04B4397-2926-4F4D-A7FE-F79F3BF37BF8_d0e72373_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E079315A-E5B6-4D33-B7E3-88697A3F11A4.dita --- a/Symbian3/SDK/Source/GUID-E079315A-E5B6-4D33-B7E3-88697A3F11A4.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-E079315A-E5B6-4D33-B7E3-88697A3F11A4.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,23 +1,23 @@ - - - - - -Control -and animation framework -

                Complex GUI applications usually need to define and use their own controls, -in addition to using the standard controls. This is done using the UI -Control Framework.

                -

                Application user interfaces can also be made more attractive by adding animations and the -simple to use bitmap -animations.

                -

                Classic UI also provides UI -Graphics Utilities for miscellaneous user interface utility -functions, related to fonts, colors, and drawing.

                + + + + + +Control +and animation framework +

                Complex GUI applications usually need to define and use their own controls, +in addition to using the standard controls. This is done using the UI +Control Framework.

                +

                Application user interfaces can also be made more attractive by adding animations and the +simple to use bitmap +animations.

                +

                Classic UI also provides UI +Graphics Utilities for miscellaneous user interface utility +functions, related to fonts, colors, and drawing.

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E09CA978-2599-50F9-AF6D-077AD7D5CA6F_d0e303526_href.jpg Binary file Symbian3/SDK/Source/GUID-E09CA978-2599-50F9-AF6D-077AD7D5CA6F_d0e303526_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E09CA978-2599-50F9-AF6D-077AD7D5CA6F_d0e309541_href.jpg Binary file Symbian3/SDK/Source/GUID-E09CA978-2599-50F9-AF6D-077AD7D5CA6F_d0e309541_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E0A02CCA-486B-592E-9B3B-BA4A378EC5AD.dita --- a/Symbian3/SDK/Source/GUID-E0A02CCA-486B-592E-9B3B-BA4A378EC5AD.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-E0A02CCA-486B-592E-9B3B-BA4A378EC5AD.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,12 +1,12 @@ - - - - - -Socket connection example

                This example shows the relationship that sockets, connections and subconnections have to each other.

                \ No newline at end of file + + + + + +Socket connection example

                This example shows the relationship that sockets, connections and subconnections have to each other.

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E0C21636-657A-413F-A905-A08608B60768.dita --- a/Symbian3/SDK/Source/GUID-E0C21636-657A-413F-A905-A08608B60768.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-E0C21636-657A-413F-A905-A08608B60768.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,27 +1,27 @@ - - - - - -Touch -UI utilities API class structure -

                The class structure consists of the class CaknLongTapDetector. -The MaknLongTapDetectorCallBack interface is used for notifying -clients about long tap events.

                - -Touch UI utilities API class structure - - -

                To receive long tap events in your application, implement the MaknLongTapDetectorCallBack interface. -When the user makes long tap on the device screen, the framework sends events -through this interface. Use the method HandleLongTapEventL to -handle the events sent by the framework.

                -

                You need to have a separate instance of this class for each client component -using it to observe long taps in the component’s control area.

                + + + + + +Touch +UI utilities API class structure +

                The class structure consists of the class CaknLongTapDetector. +The MaknLongTapDetectorCallBack interface is used for notifying +clients about long tap events.

                + +Touch UI utilities API class structure + + +

                To receive long tap events in your application, implement the MaknLongTapDetectorCallBack interface. +When the user makes long tap on the device screen, the framework sends events +through this interface. Use the method HandleLongTapEventL to +handle the events sent by the framework.

                +

                You need to have a separate instance of this class for each client component +using it to observe long taps in the component’s control area.

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E111C4E8-1342-4E87-ACB4-5B630AF1501C.dita --- a/Symbian3/SDK/Source/GUID-E111C4E8-1342-4E87-ACB4-5B630AF1501C.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-E111C4E8-1342-4E87-ACB4-5B630AF1501C.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,26 +1,26 @@ - - - - - -Internationalization -and localization -

                You need to take internationalization concerns into account as early -as possible when designing your application.

                -

                When localizing your application, there are two different concerns that -you need to manage in your project. These are as follows:

                -
                  -

                • Date, Times, Currency, and other locale-sensitive data types.

                  -
                  • -

                • UI text strings.

                  • -
                -

                For information on loading resources, see CONE -resource loader overview

                -

                This section describes internationalization and localization, including:

                + + + + + +Internationalization +and localization +

                You need to take internationalization concerns into account as early +as possible when designing your application.

                +

                When localizing your application, there are two different concerns that +you need to manage in your project. These are as follows:

                +
                  +

                • Date, Times, Currency, and other locale-sensitive data types.

                  +
                  • +

                • UI text strings.

                  • +
                +

                For information on loading resources, see CONE +resource loader overview

                +

                This section describes internationalization and localization, including:

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E1410365-7254-5326-B3F7-D7100D31E59F.dita --- a/Symbian3/SDK/Source/GUID-E1410365-7254-5326-B3F7-D7100D31E59F.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-E1410365-7254-5326-B3F7-D7100D31E59F.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,12 +1,12 @@ - - - - - -Array of variable length elements, segmented buffer

                This is a CArrayVarSeg<class T> object whose elements can have different lengths. Although each element is a class T object, the length of that object can vary.

                In this type of array, each element occupies its own individual cell allocated from the heap. The array buffer contains fixed length data structures, one for each element, which are logically contiguous within the buffer but are physically contiguous only within a segment. Each fixed length data structure contains the length of an element (a TInt value) and a pointer to it. The structure itself is part of the implementation but occupies no more than eight bytes on 32-bit machines.

                A segmented buffer is implemented as a doubly linked list of equally sized cells allocated from the heap and is always extended by allocating a new segment and inserting it into the appropriate place in the list. A segmented array buffer is implemented using a CBufSeg object.

                The following diagram illustrates how elements are organised within the array buffer:

                This kind of array is suitable for large arrays with a high turnover of elements.

                This class is immediately derived from the abstract templated base class CArrayVar<class T> which is itself derived from the abstract non-templated base class CArrayVarBase.

                See also

                Dynamic Buffers Guide.

                 \ No newline at end of file + + + + + +Array of variable length elements, segmented buffer

                This is a CArrayVarSeg<class T> object whose elements can have different lengths. Although each element is a class T object, the length of that object can vary.

                In this type of array, each element occupies its own individual cell allocated from the heap. The array buffer contains fixed length data structures, one for each element, which are logically contiguous within the buffer but are physically contiguous only within a segment. Each fixed length data structure contains the length of an element (a TInt value) and a pointer to it. The structure itself is part of the implementation but occupies no more than eight bytes on 32-bit machines.

                A segmented buffer is implemented as a doubly linked list of equally sized cells allocated from the heap and is always extended by allocating a new segment and inserting it into the appropriate place in the list. A segmented array buffer is implemented using a CBufSeg object.

                The following diagram illustrates how elements are organised within the array buffer:

                This kind of array is suitable for large arrays with a high turnover of elements.

                This class is immediately derived from the abstract templated base class CArrayVar<class T> which is itself derived from the abstract non-templated base class CArrayVarBase.

                See also

                Dynamic Buffers Guide.

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E161AB84-1B24-53AF-B313-D68CF9F8EE60.dita --- a/Symbian3/SDK/Source/GUID-E161AB84-1B24-53AF-B313-D68CF9F8EE60.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-E161AB84-1B24-53AF-B313-D68CF9F8EE60.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,54 +1,54 @@ - - - - - -Pointers -to the start and end of contiguous regionsThe Back() and End() functions -point to locations in memory for flat and segmented arrays. -

                For those arrays of same length elements which are derived from CArrayFix<class T>, -the elements are contained within an array buffer which can be implemented -as a flat buffer or as a segmented buffer. A flat buffer is implemented as -a single contiguous region of memory while a segmented buffer is implemented -as a set of separate but linked regions of memory

                -

                Given the position of an element within an array, it can be useful to fetch -a pointer to the first byte following the end of the contiguous region of -memory containing that element (the end pointer). Similarly, it can -be useful to fetch a pointer to the beginning of a contiguous region -of memory (the back pointer).

                -
                Array of same length elements

                An array of same -length elements uses the End() function to fetch the end -pointer and the Back() function to fetch the back pointer. -The implementation of these two functions differs between a fixed flat array -and a fixed segmented array.

                -
                Flat array

                For a flat array — i.e. an array whose -buffer is implemented using a flat buffer — the end pointer simply points -to the first byte following the single region of memory containing the array -buffer. The back pointer simply points to the first byte of the single region -of memory (as illustrated below); End() always returns a -pointer to the first byte following the end of the buffer, while Back() always -returns a pointer to the beginning of the buffer.

                -End() and Back() in fixed flat arrays - -
                -
                Segmented array

                For a segmented array, the situation -is different (as illustrated below). Looking at the segment containing elements n and n+1, End() returns a pointer to the first byte following the end of that segment. In -fact, End() returns the same pointer value for all elements -in that segment. Back() returns a pointer to the beginning -of that segment for element n+1 and for all subsequent elements -in that segment. However, for the first element in that segment, Back() returns -a pointer to the beginning of the previous segment. For the very first -element in the array, Back() returns a pointer with a NULL -value.

                -End() and Back() in fixed segmented arrays - -
                -
                See also

                Dynamic -Buffers Guide.

                + + + + + +Pointers +to the start and end of contiguous regionsThe Back() and End() functions +point to locations in memory for flat and segmented arrays. +

                For those arrays of same length elements which are derived from CArrayFix<class T>, +the elements are contained within an array buffer which can be implemented +as a flat buffer or as a segmented buffer. A flat buffer is implemented as +a single contiguous region of memory while a segmented buffer is implemented +as a set of separate but linked regions of memory

                +

                Given the position of an element within an array, it can be useful to fetch +a pointer to the first byte following the end of the contiguous region of +memory containing that element (the end pointer). Similarly, it can +be useful to fetch a pointer to the beginning of a contiguous region +of memory (the back pointer).

                +
                Array of same length elements

                An array of same +length elements uses the End() function to fetch the end +pointer and the Back() function to fetch the back pointer. +The implementation of these two functions differs between a fixed flat array +and a fixed segmented array.

                +
                Flat array

                For a flat array — i.e. an array whose +buffer is implemented using a flat buffer — the end pointer simply points +to the first byte following the single region of memory containing the array +buffer. The back pointer simply points to the first byte of the single region +of memory (as illustrated below); End() always returns a +pointer to the first byte following the end of the buffer, while Back() always +returns a pointer to the beginning of the buffer.

                +End() and Back() in fixed flat arrays + +
                +
                Segmented array

                For a segmented array, the situation +is different (as illustrated below). Looking at the segment containing elements n and n+1, End() returns a pointer to the first byte following the end of that segment. In +fact, End() returns the same pointer value for all elements +in that segment. Back() returns a pointer to the beginning +of that segment for element n+1 and for all subsequent elements +in that segment. However, for the first element in that segment, Back() returns +a pointer to the beginning of the previous segment. For the very first +element in the array, Back() returns a pointer with a NULL +value.

                +End() and Back() in fixed segmented arrays + +
                +
                See also

                Dynamic +Buffers Guide.

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E16E286C-FB6A-5D3E-95D6-044C39DBA2B4.dita --- a/Symbian3/SDK/Source/GUID-E16E286C-FB6A-5D3E-95D6-044C39DBA2B4.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-E16E286C-FB6A-5D3E-95D6-044C39DBA2B4.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,12 +1,12 @@ - - - - - -The object container

                All reference counting objects must be held in an object container. An object container acts as a home for a set of related reference counting objects.

                An object container is an instance of a CObjectCon class.

                After construction, a reference counting object must be added to an object container. Only one instance of a reference counting object can be held by an object container, i.e. each object within an object container must be distinct.

                The main characteristics of an object container can be summarised as follows:

                • they allow a logical collections of reference counting objects to be gathered together.

                • explicitly destroying a reference counting object causes that object to be removed from its object container.

                • removing a reference counting object from its object container causes that object to be destroyed.

                • each object container is assigned a unique ID on construction. This is an integer that forms part of the identity of all of its contained reference counting objects. All reference counting objects within an object container are associated with the same unique ID. The value of the unique ID can range from 1 to 16,383 (0x3fff).

                Object containers are constructed by an object container index, a CObjectConIx type. The maximum number of object containers which may be constructed and held in an object container index is 6,383 (0x3fff).

                An object container is implemented as a simple array, where each element of the array is a pointer to a contained reference counting object. Adding a reference counting object to the object container is simply a matter of adding the reference counting object's pointer into the array. The following diagram shows a simple situation where two object containers hold a number of reference counting objects.

                The CObjectCon::AddL() function adds a reference counting object to the object container.

                The CObjectCon::Remove() function removes a reference counting object from its object container and also destroys that reference counting object. Conversely, if the reference counting object is destroyed (typically, as a result of successive calls to CObject::Close()), it is removed from its object container.

                See also:

                • CObjectCon

                • CObject

                \ No newline at end of file + + + + + +The object container

                All reference counting objects must be held in an object container. An object container acts as a home for a set of related reference counting objects.

                An object container is an instance of a CObjectCon class.

                After construction, a reference counting object must be added to an object container. Only one instance of a reference counting object can be held by an object container, i.e. each object within an object container must be distinct.

                The main characteristics of an object container can be summarised as follows:

                • they allow a logical collections of reference counting objects to be gathered together.

                • explicitly destroying a reference counting object causes that object to be removed from its object container.

                • removing a reference counting object from its object container causes that object to be destroyed.

                • each object container is assigned a unique ID on construction. This is an integer that forms part of the identity of all of its contained reference counting objects. All reference counting objects within an object container are associated with the same unique ID. The value of the unique ID can range from 1 to 16,383 (0x3fff).

                Object containers are constructed by an object container index, a CObjectConIx type. The maximum number of object containers which may be constructed and held in an object container index is 6,383 (0x3fff).

                An object container is implemented as a simple array, where each element of the array is a pointer to a contained reference counting object. Adding a reference counting object to the object container is simply a matter of adding the reference counting object's pointer into the array. The following diagram shows a simple situation where two object containers hold a number of reference counting objects.

                The CObjectCon::AddL() function adds a reference counting object to the object container.

                The CObjectCon::Remove() function removes a reference counting object from its object container and also destroys that reference counting object. Conversely, if the reference counting object is destroyed (typically, as a result of successive calls to CObject::Close()), it is removed from its object container.

                See also:

                • CObjectCon

                • CObject

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E244744F-4837-5B46-8E37-4666A28BF0B7-GENID-1-8-1-3-1-1-7-1-7-1-5-1.dita --- a/Symbian3/SDK/Source/GUID-E244744F-4837-5B46-8E37-4666A28BF0B7-GENID-1-8-1-3-1-1-7-1-7-1-5-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,14 +0,0 @@ - - - - - -The run-time control hierarchy

                At run-time all controls in an application are related to each other in a tree hierarchy. The top-level window-owning controls are owned by the AppUi. This is similar to the hierarchy of windows that exists in the Window Server which has a group window for each application at the root. It is important to understand the relationships between window-owning and non-window owning controls. The diagram below attempts to illustrate these.

                - The run-time control hierarchy -

                A non-window-owning control is confined to the extent of its parent if the parent is window-owning, and must be confined to the extent of its parent if the parent is non-window-owning.

                A window-owning component is confined to the nearest window-owning control above it in the hierarchy.

                Screen drawing may be initiated by either the application (because it's running and it has changed its display) or by the Window Server (because something else has updated the screen and the application is visible).

                • Application-initiated redrawing follows the control framework run-time hierarchy: controls are drawn by their parents regardless of whether they are window-owning or not.

                • Window-Server-initiated redrawing, on the other hand, follows the Window Server hierarchy: parents do not draw their window-owning children.

                A control's container or parent control may not be changed after it has been set.

                The run time hierarchy of controls has been enhanced for version 9.1 of the Symbian OS. The distinction between the 'parent-child' relationship from the Window Server and the 'container-component' relationship from the control framework may be simplified with the addition of a parent pointer to CCoeControl.

                In UIQ v3 the parent pointer is enabled. In S60 and MOAP the parent pointer currently is not enabled.

                The addition of the parent pointer allows the framework to navigate the control hierarchy upwards as well as downwards. When enabled, the parent pointer is set automatically (see how to write a control).

                The run-time hierarchy is particularly significant when laying out and when refreshing the screen. Here are a few examples of how the framework uses the run-time hierarchy.

                • When a control is drawn it must have the correct Look and Feel: its colours, fonts, font style, size and shape must be correct. Controls use their parent's graphics contexts and text drawers.

                • If a control (lodger or a parent) changes size, the controls around or within it might have to move or resize. From 9.1 the framework provides a layout manager interface (MCoeLayoutManager). Controls use the run-time hierarchy to find the appropriate layout manager.

                • From 9.1 parent controls take responsibility for drawing behind their children. This allows flexibility with backgrounds, transparent controls and controls which appear non-rectangular. To enable this process to work with window-owning controls (necessary because the Window Server will not allow parent windows to draw behind child windows) a new interface, MCoeControlBackground, has been introduced. When a window owning control draws itself it first looks for an MCoeControlBackground in its chain of parents and calls MCoeControlBackground::Draw() before drawing itself.

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E244744F-4837-5B46-8E37-4666A28BF0B7-GENID-1-8-1-6-1-1-4-1-6-1-7-1-5-1.dita --- a/Symbian3/SDK/Source/GUID-E244744F-4837-5B46-8E37-4666A28BF0B7-GENID-1-8-1-6-1-1-4-1-6-1-7-1-5-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,14 +0,0 @@ - - - - - -The run-time control hierarchy

                At run-time all controls in an application are related to each other in a tree hierarchy. The top-level window-owning controls are owned by the AppUi. This is similar to the hierarchy of windows that exists in the Window Server which has a group window for each application at the root. It is important to understand the relationships between window-owning and non-window owning controls. The diagram below attempts to illustrate these.

                - The run-time control hierarchy -

                A non-window-owning control is confined to the extent of its parent if the parent is window-owning, and must be confined to the extent of its parent if the parent is non-window-owning.

                A window-owning component is confined to the nearest window-owning control above it in the hierarchy.

                Screen drawing may be initiated by either the application (because it's running and it has changed its display) or by the Window Server (because something else has updated the screen and the application is visible).

                • Application-initiated redrawing follows the control framework run-time hierarchy: controls are drawn by their parents regardless of whether they are window-owning or not.

                • Window-Server-initiated redrawing, on the other hand, follows the Window Server hierarchy: parents do not draw their window-owning children.

                A control's container or parent control may not be changed after it has been set.

                The run time hierarchy of controls has been enhanced for version 9.1 of the Symbian OS. The distinction between the 'parent-child' relationship from the Window Server and the 'container-component' relationship from the control framework may be simplified with the addition of a parent pointer to CCoeControl.

                In UIQ v3 the parent pointer is enabled. In S60 and MOAP the parent pointer currently is not enabled.

                The addition of the parent pointer allows the framework to navigate the control hierarchy upwards as well as downwards. When enabled, the parent pointer is set automatically (see how to write a control).

                The run-time hierarchy is particularly significant when laying out and when refreshing the screen. Here are a few examples of how the framework uses the run-time hierarchy.

                • When a control is drawn it must have the correct Look and Feel: its colours, fonts, font style, size and shape must be correct. Controls use their parent's graphics contexts and text drawers.

                • If a control (lodger or a parent) changes size, the controls around or within it might have to move or resize. From 9.1 the framework provides a layout manager interface (MCoeLayoutManager). Controls use the run-time hierarchy to find the appropriate layout manager.

                • From 9.1 parent controls take responsibility for drawing behind their children. This allows flexibility with backgrounds, transparent controls and controls which appear non-rectangular. To enable this process to work with window-owning controls (necessary because the Window Server will not allow parent windows to draw behind child windows) a new interface, MCoeControlBackground, has been introduced. When a window owning control draws itself it first looks for an MCoeControlBackground in its chain of parents and calls MCoeControlBackground::Draw() before drawing itself.

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E244744F-4837-5B46-8E37-4666A28BF0B7.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-E244744F-4837-5B46-8E37-4666A28BF0B7.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,14 @@ + + + + + +The run-time control hierarchy

                At run-time all controls in an application are related to each other in a tree hierarchy. The top-level window-owning controls are owned by the AppUi. This is similar to the hierarchy of windows that exists in the Window Server which has a group window for each application at the root. It is important to understand the relationships between window-owning and non-window owning controls. The diagram below attempts to illustrate these.

                + The run-time control hierarchy +

                A non-window-owning control is confined to the extent of its parent if the parent is window-owning, and must be confined to the extent of its parent if the parent is non-window-owning.

                A window-owning component is confined to the nearest window-owning control above it in the hierarchy.

                Screen drawing may be initiated by either the application (because it's running and it has changed its display) or by the Window Server (because something else has updated the screen and the application is visible).

                • Application-initiated redrawing follows the control framework run-time hierarchy: controls are drawn by their parents regardless of whether they are window-owning or not.

                • Window-Server-initiated redrawing, on the other hand, follows the Window Server hierarchy: parents do not draw their window-owning children.

                A control's container or parent control may not be changed after it has been set.

                The run time hierarchy of controls has been enhanced for version 9.1 of the Symbian OS. The distinction between the 'parent-child' relationship from the Window Server and the 'container-component' relationship from the control framework may be simplified with the addition of a parent pointer to CCoeControl.

                In UIQ v3 the parent pointer is enabled. In S60 and MOAP the parent pointer currently is not enabled.

                The addition of the parent pointer allows the framework to navigate the control hierarchy upwards as well as downwards. When enabled, the parent pointer is set automatically (see how to write a control).

                The run-time hierarchy is particularly significant when laying out and when refreshing the screen. Here are a few examples of how the framework uses the run-time hierarchy.

                • When a control is drawn it must have the correct Look and Feel: its colours, fonts, font style, size and shape must be correct. Controls use their parent's graphics contexts and text drawers.

                • If a control (lodger or a parent) changes size, the controls around or within it might have to move or resize. From 9.1 the framework provides a layout manager interface (MCoeLayoutManager). Controls use the run-time hierarchy to find the appropriate layout manager.

                • From 9.1 parent controls take responsibility for drawing behind their children. This allows flexibility with backgrounds, transparent controls and controls which appear non-rectangular. To enable this process to work with window-owning controls (necessary because the Window Server will not allow parent windows to draw behind child windows) a new interface, MCoeControlBackground, has been introduced. When a window owning control draws itself it first looks for an MCoeControlBackground in its chain of parents and calls MCoeControlBackground::Draw() before drawing itself.

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E2455472-49FA-5492-B7CB-2C33BD830591_d0e169127_href.jpg Binary file Symbian3/SDK/Source/GUID-E2455472-49FA-5492-B7CB-2C33BD830591_d0e169127_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E2455472-49FA-5492-B7CB-2C33BD830591_d0e175728_href.jpg Binary file Symbian3/SDK/Source/GUID-E2455472-49FA-5492-B7CB-2C33BD830591_d0e175728_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E24F15B4-D767-5B79-B0EB-88294B9BC16A_d0e202076_href.png Binary file Symbian3/SDK/Source/GUID-E24F15B4-D767-5B79-B0EB-88294B9BC16A_d0e202076_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E24F15B4-D767-5B79-B0EB-88294B9BC16A_d0e207084_href.png Binary file Symbian3/SDK/Source/GUID-E24F15B4-D767-5B79-B0EB-88294B9BC16A_d0e207084_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E2AB4BDF-8AFD-5776-A614-50DC3ACF3AD4_d0e135205_href.png Binary file Symbian3/SDK/Source/GUID-E2AB4BDF-8AFD-5776-A614-50DC3ACF3AD4_d0e135205_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E2AB4BDF-8AFD-5776-A614-50DC3ACF3AD4_d0e141739_href.png Binary file Symbian3/SDK/Source/GUID-E2AB4BDF-8AFD-5776-A614-50DC3ACF3AD4_d0e141739_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E2CB0826-FC44-5AC9-BBB1-B449073484F3.dita --- a/Symbian3/SDK/Source/GUID-E2CB0826-FC44-5AC9-BBB1-B449073484F3.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-E2CB0826-FC44-5AC9-BBB1-B449073484F3.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,36 +1,36 @@ - - - - - -Array -capacity and granularityDescribes the granularity and capacity of a dynamic array. -

                The capacity of an array is the number of elements which the array -can hold or represent within the space currently allocated to its array buffer.

                -

                For a flat array buffer, the increase in capacity of a buffer, when the -insertion of an additional element causes the buffer to be re-allocated, is -termed the granularity of the array. For example, adding a fifth element -to a fixed flat array constructed with a granularity of four, causes the array -buffer to be re-allocated so that its capacity increases from four to eight -elements.

                - - - -

                For a segmented array buffer, the granularity defines the capacity of a -single segment. A segmented array buffer is always expanded by allocating -additional segments.

                -

                The granularity of an array is defined at construction time. -The choice of value depends on the use to be made of the array and needs careful -consideration. Too small a value for an array with a high turnover of elements -can incur considerable overhead from the process of allocating memory. Too -large a value can result in wasted space if insufficient new elements are -subsequently added.

                -
                See also

                Using -Dynamic Buffers.

                + + + + + +Array +capacity and granularityDescribes the granularity and capacity of a dynamic array. +

                The capacity of an array is the number of elements which the array +can hold or represent within the space currently allocated to its array buffer.

                +

                For a flat array buffer, the increase in capacity of a buffer, when the +insertion of an additional element causes the buffer to be re-allocated, is +termed the granularity of the array. For example, adding a fifth element +to a fixed flat array constructed with a granularity of four, causes the array +buffer to be re-allocated so that its capacity increases from four to eight +elements.

                + + + +

                For a segmented array buffer, the granularity defines the capacity of a +single segment. A segmented array buffer is always expanded by allocating +additional segments.

                +

                The granularity of an array is defined at construction time. +The choice of value depends on the use to be made of the array and needs careful +consideration. Too small a value for an array with a high turnover of elements +can incur considerable overhead from the process of allocating memory. Too +large a value can result in wasted space if insufficient new elements are +subsequently added.

                +
                See also

                Using +Dynamic Buffers.

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E2E2FACF-5D4F-43E8-8B53-B268252CF572.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-E2E2FACF-5D4F-43E8-8B53-B268252CF572.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,84 @@ + + + + + +Defining +Connection Management ItemsYour application should define the connection management items +(destination networks, access points, default connection, and always ask) +it supports and show only the supported items in the UI. In this example, +the application supports default connection, always ask, and destination networks. +Access points (if supported) of a certain destination network can be seen +under the Options menu when the destination network is highlighted. +

                To define +the connection management items:

                 + +Request the connection +settings dialog for supported items using the Connection Settings UI API. + +Show the items that your application supports in the UI using the +Connection Settings UI API. After the user has made a selection, it is returned +to the application. + +Store the user selection in the application's connection setup. + For information on how to start the connection through a destination network, +see Starting the Connection +through the Destination Network. If you want to prompt the user to +make this selection, see Prompting the user to select a destination network. + + +#include <cmapplicationsettingsui.h>TCmSettingSelection userSelection; + +CCmApplicationSettingsUi* settings = CCmApplicationSettingsUi::NewL(); +CleanupStack::PushL( settings ); + +TUint listedItems = EShowAlwaysAsk | EShowDefaultConnection | + EShowDestinations | EShowConnectionMethods; + +TBearerFilterArray filter; + +settings->RunApplicationSettingsL( userSelection, + listedItems, + filter ); + CleanupStack::PopAndDestroy( settings ); + +switch ( userSelection.iResult ) + { + case EDestination: + { + TConnSnapPref prefs; + prefs.SetSnap( userSelection.iId ); + + iConnection.Start( prefs, iStatus ); + break; + } + case EConnectionMethod: + { + TCommDbConnPref prefs; + prefs.SetIapId( userSelection.iId ); + prefs.SetDialogPreference( ECommDbDialogPrefDoNotPrompt ); + + iConnection.Start( prefs, iStatus ); + break; + } + case EDefaultConnection: + { +iConnection.Start( iStatus ); + break; + } + default: // EAlwaysAsk + { + TCommDbConnPref prefs; + prefs.SetDialogPreference( ECommDbDialogPrefPrompt ); + + iConnection.Start( prefs, iStatus ); + } + } +SetActive(); +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E2F6A71A-4A18-5E0B-AE77-C059C59448E4_d0e368521_href.png Binary file Symbian3/SDK/Source/GUID-E2F6A71A-4A18-5E0B-AE77-C059C59448E4_d0e368521_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E2F6A71A-4A18-5E0B-AE77-C059C59448E4_d0e374591_href.png Binary file Symbian3/SDK/Source/GUID-E2F6A71A-4A18-5E0B-AE77-C059C59448E4_d0e374591_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E3A60844-EE37-4AF1-8921-59375C563723.dita --- a/Symbian3/SDK/Source/GUID-E3A60844-EE37-4AF1-8921-59375C563723.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-E3A60844-EE37-4AF1-8921-59375C563723.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,74 +1,74 @@ - - - - - -Removing -item-specific commands from the toolbarThis document describes the changes required to your code to remove -the item-specific commands from the toolbar. - -Remove all item-specifc -commands from your resource files. - - -

                Let us consider the following code snippet as a part of an application -that supports single-tap functionality. As single-tap functionality does not -support highlighting an item in a list, the item-specific commands are not -required to be in a toolbar and therefore can be removed.

                -RESOURCE AVKON_TOOLBAR r_application_toolbar - { - flags = KAknToolbarFlexiblePosition; - items = - { - // Top level buttons -//----------------------------------------------------------------------------- -/*------Remove this item specific command (Delete)----------- - TBAR_CTRL - { - type = EAknCtButton; - id = EToolbarDelete; - control = AVKON_BUTTON - { - flags = KAknButtonSizeFitText;; - states = - { - AVKON_BUTTON_STATE - { - bmpfile = "\\resource\\apps\\delete.mbm"; - bmpid = ECalInterIcon_delete_unpressed_38x38; - press_bmpid = EMCalInterIcon_delete_pressed_38x38; - helptxt = "Delete"; - } - }; - }; - }, - ----------------------------------------------------------------------------- */ - TBAR_CTRL - { - type = EAknCtButton; - id = EToolbarHelp; - control = AVKON_BUTTON - { - flags = 0; - states = - { - AVKON_BUTTON_STATE - { - bmpfile = "\\resource\\apps\\help.mbm"; - bmpid = ECalInterIcon_undo_unpressed_38x38; - press_bmpid = ECalInterIcon_undo_pressed_38x38; - helptxt = "Help"; - } - }; - }; - }; - }; - } -                 + + + + + +Removing +item-specific commands from the toolbarThis document describes the changes required to your code to remove +the item-specific commands from the toolbar. + +Remove all item-specifc +commands from your resource files. + + +

                Let us consider the following code snippet as a part of an application +that supports single-tap functionality. As single-tap functionality does not +support highlighting an item in a list, the item-specific commands are not +required to be in a toolbar and therefore can be removed.

                +RESOURCE AVKON_TOOLBAR r_application_toolbar + { + flags = KAknToolbarFlexiblePosition; + items = + { + // Top level buttons +//----------------------------------------------------------------------------- +/*------Remove this item specific command (Delete)----------- + TBAR_CTRL + { + type = EAknCtButton; + id = EToolbarDelete; + control = AVKON_BUTTON + { + flags = KAknButtonSizeFitText;; + states = + { + AVKON_BUTTON_STATE + { + bmpfile = "\\resource\\apps\\delete.mbm"; + bmpid = ECalInterIcon_delete_unpressed_38x38; + press_bmpid = EMCalInterIcon_delete_pressed_38x38; + helptxt = "Delete"; + } + }; + }; + }, + ----------------------------------------------------------------------------- */ + TBAR_CTRL + { + type = EAknCtButton; + id = EToolbarHelp; + control = AVKON_BUTTON + { + flags = 0; + states = + { + AVKON_BUTTON_STATE + { + bmpfile = "\\resource\\apps\\help.mbm"; + bmpid = ECalInterIcon_undo_unpressed_38x38; + press_bmpid = ECalInterIcon_undo_pressed_38x38; + helptxt = "Help"; + } + }; + }; + }; + }; + } +                                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E402616A-7ED8-45AC-B836-99C3A3760B33.dita --- a/Symbian3/SDK/Source/GUID-E402616A-7ED8-45AC-B836-99C3A3760B33.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-E402616A-7ED8-45AC-B836-99C3A3760B33.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,47 +1,47 @@ - - - - - -Key events -Key presses generate key events -

                Key events are generated when a device user presses one or more device -key buttons. The application framework delivers the event to the application -that has focus. The TKeyEvent structure is used to contain -the key event details delivered to the application. For more information on TKeyEvent, -see TKeyEvent.

                -

                The structure is as follows:

                -struct TKeyEvent - { - TUint iCode; - TInt iScanCode; - TUint iModifiers; // State of modifier keys - TInt iRepeats; // Count of auto repeats generated - }; - -

                The following events are generated by means of a single key press and -release:

                -EEventKeyDown -EEventKey -EEventKeyUp - - -

                The first event indicates that a key has been pressed down. The second -event indicates that a character has been received from the keyboard. The -third event is sent when the button has been released. These events are described -in the iCode and iSCanCode members -of TKeyEvent.

                -

                For more information on possible data contained in EEventKey, -see TKeyCode.

                -

                Key presses may be interpreted by a Front End Processor (FEP) and tied -to specific key events. For example, if a device user presses the 2 key -twice, an active FEP could generate a key event code of b.

                -

                For more information on FEPs, see Front -End Processor overview.

                + + + + + +Key events +Key presses generate key events +

                Key events are generated when a device user presses one or more device +key buttons. The application framework delivers the event to the application +that has focus. The TKeyEvent structure is used to contain +the key event details delivered to the application. For more information on TKeyEvent, +see TKeyEvent.

                +

                The structure is as follows:

                +struct TKeyEvent + { + TUint iCode; + TInt iScanCode; + TUint iModifiers; // State of modifier keys + TInt iRepeats; // Count of auto repeats generated + }; + +

                The following events are generated by means of a single key press and +release:

                +EEventKeyDown +EEventKey +EEventKeyUp + + +

                The first event indicates that a key has been pressed down. The second +event indicates that a character has been received from the keyboard. The +third event is sent when the button has been released. These events are described +in the iCode and iSCanCode members +of TKeyEvent.

                +

                For more information on possible data contained in EEventKey, +see TKeyCode.

                +

                Key presses may be interpreted by a Front End Processor (FEP) and tied +to specific key events. For example, if a device user presses the 2 key +twice, an active FEP could generate a key event code of b.

                +

                For more information on FEPs, see Front +End Processor overview.

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E449F309-F230-46F9-B777-EF64D0E3191D.dita --- a/Symbian3/SDK/Source/GUID-E449F309-F230-46F9-B777-EF64D0E3191D.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-E449F309-F230-46F9-B777-EF64D0E3191D.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,50 +1,60 @@ - - - - - -Information -note -

                Information notes give information about an unexpected situation during -the usage of the device. They have a longer duration and a more noticeable -tone than in a confirmation -note. Errors that are not too serious should cause an information note.

                - -Information note - - -
                Using -information notes in C++ applications

                You can create either a basic -information note that is displayed only when your application is in the foreground -or a global note that stays displayed even if the application launching the -note is not in the foreground. The related APIs are the Notes -API (for basic notes) and the Notifiers API (for global notes).

                To use an information -note with the default icon, text, sound, and duration, create an instance -of the note class CAknInformationNote. For implementation infomation, see Creating a non-waiting information (basic) note.

                To -create a global information note, use the class CAknGlobalNote in the Notifiers API. For implementation information, see Using global notes and Using global notes with user interaction.

                For -basic notes, you can change the icon or text displayed in the note, use a -different kind of sound, or change the note duration using the setter methods -in the class CAknNoteDialog: SetIconL(), SetTextL(), SetTone(), and SetTimeout().

                For information on customizing global notes, see Enhancing global notes. You can change the graphic, animation, -tone, and softkeys using the methods in the class CAknGlobalNote: SetGraphic(), SetAnimation(), SetTone(), and SetSoftkeys().

                - - -                 -Confirmation -note -Warning note - -Error note - -Permanent -note -Wait note - -Progress -note + + + + + +Information +note +

                Information notes give information about an unexpected situation during +the usage of the device. They have a longer duration and a more noticeable +tone than in a confirmation +note. Errors that are not too serious should cause an information note.

                + +Information note + + +
                Using +information notes in applications

                You can create either a basic +information note that is displayed only when your application is in the foreground +or a global note that stays displayed even if the application launching the +note is not in the foreground. The related APIs are the Notes +API (for basic notes) and the Notifiers API (for global notes).

                To use an information +note with the default icon, text, sound, and duration, create an instance +of the note CAknInformationNote class. For implementation +information, see Creating a non-waiting information (basic) note.

                To +create a global information note, use the CAknGlobalNote class +in the Notifiers API. For implementation information, see Using global notes and Using global notes with user interaction.

                For basic +notes, you can change the icon or text displayed in the note, use a different +kind of sound, or change the note duration using the setter methods in the CAknNoteDialog class:

                  +

                • CAknNoteDialog::SetIconL()

                  • +

                • CAknNoteDialog::SetTextL()

                  • +

                • CAknNoteDialog::SetTone()

                  • +

                • CAknNoteDialog::SetTimeout()

                  • +

                For information on customizing global notes, see Enhancing global notes. You can change the graphic, animation, +tone, and softkeys using the methods in the CAknGlobalNote class:

                  +

                • CAknGlobalNote::SetGraphic()

                  • +

                • CAknGlobalNote::SetAnimation()

                  • +

                • CAknGlobalNote::SetTone()

                  • +

                • CAknGlobalNote::SetSoftkeys()

                  • +

                + +                 +Confirmation +note +Warning note + +Error note + +Permanent +note +Wait note + +Progress +note                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E4543D60-A9D0-5121-9540-993BB15D3275_d0e332473_href.png Binary file Symbian3/SDK/Source/GUID-E4543D60-A9D0-5121-9540-993BB15D3275_d0e332473_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E4543D60-A9D0-5121-9540-993BB15D3275_d0e338630_href.png Binary file Symbian3/SDK/Source/GUID-E4543D60-A9D0-5121-9540-993BB15D3275_d0e338630_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E455ABFF-3EFF-5396-A52A-A33CDB2EB41A.dita --- a/Symbian3/SDK/Source/GUID-E455ABFF-3EFF-5396-A52A-A33CDB2EB41A.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-E455ABFF-3EFF-5396-A52A-A33CDB2EB41A.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,43 +1,43 @@ - - - - - -Cleanup -utilitiesThe Cleanup utility functions support four types of clean up operation. -

                The cleanup utility functions offer easy ways of constructing a TCleanUpItem and -pushing it onto the cleanup stack. They support four types of clean up operation:

                -
                  -

                • where the object is -deleted: template <class T> void CleanupDeletePushL(T*)

                  • -

                • where the object's Close() member -function is called: template <class T> void CleanupClosePushL(T&)

                  • -

                • where the object's Release() member -function is called: template <class T> void CleanupReleasePushL(T&)

                  • -

                • where an array of objects -is deleted: template <class T> void CleanupArrayDeletePushL(T*)

                  • -
                -

                The functions have the supporting templated classes:

                -
                  -

                • CleanupDelete<class -T>

                  • -

                • CleanupClose<class -T>

                  • -

                • CleanupRelease<class -T>

                  • -

                • CleanupArrayDelete<class -T>

                  • -
                -

                The way in which these work is best illustrated graphically by taking CleanupClosePushL() as -an example. See the diagram below.

                - -Effect of CleanupClosePushL and subsequent pop and destroy - - + + + + + +Cleanup +utilitiesThe Cleanup utility functions support four types of clean up operation. +

                The cleanup utility functions offer easy ways of constructing a TCleanUpItem and +pushing it onto the cleanup stack. They support four types of clean up operation:

                +
                  +

                • where the object is +deleted: template <class T> void CleanupDeletePushL(T*)

                  • +

                • where the object's Close() member +function is called: template <class T> void CleanupClosePushL(T&)

                  • +

                • where the object's Release() member +function is called: template <class T> void CleanupReleasePushL(T&)

                  • +

                • where an array of objects +is deleted: template <class T> void CleanupArrayDeletePushL(T*)

                  • +
                +

                The functions have the supporting templated classes:

                +
                  +

                • CleanupDelete<class +T>

                  • +

                • CleanupClose<class +T>

                  • +

                • CleanupRelease<class +T>

                  • +

                • CleanupArrayDelete<class +T>

                  • +
                +

                The way in which these work is best illustrated graphically by taking CleanupClosePushL() as +an example. See the diagram below.

                + +Effect of CleanupClosePushL and subsequent pop and destroy + +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E489F575-DD07-4949-AB98-8F6A11BF708A_d0e66511_href.png Binary file Symbian3/SDK/Source/GUID-E489F575-DD07-4949-AB98-8F6A11BF708A_d0e66511_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E489F575-DD07-4949-AB98-8F6A11BF708A_d0e71755_href.png Binary file Symbian3/SDK/Source/GUID-E489F575-DD07-4949-AB98-8F6A11BF708A_d0e71755_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E4B5C7CE-7820-5D80-8CD1-DCD692C11F23_d0e130564_href.png Binary file Symbian3/SDK/Source/GUID-E4B5C7CE-7820-5D80-8CD1-DCD692C11F23_d0e130564_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E4B5C7CE-7820-5D80-8CD1-DCD692C11F23_d0e137102_href.png Binary file Symbian3/SDK/Source/GUID-E4B5C7CE-7820-5D80-8CD1-DCD692C11F23_d0e137102_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E4E656BF-E5F7-5125-AE88-60C3E9FCF0D2.dita --- a/Symbian3/SDK/Source/GUID-E4E656BF-E5F7-5125-AE88-60C3E9FCF0D2.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-E4E656BF-E5F7-5125-AE88-60C3E9FCF0D2.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,48 +1,38 @@ - - - - - -InterfaceDefinition: -ECom Interface Definition Example Code -
                Download

                Click -on the following link to download the example: Ecom.zip

                Download some additional files required -by the example: CommonFramework

                Click: browse to view the example code.

                View the additional -files: browse.
                -
                Description

                InterfaceDefinition provides -an example ECom interface definition. It declares a base class, CExampleInterface, -from which implementations of the interface should derive.

                CExampleInterface provides -three NewL() functions that allow clients to get respectively:

                  -

                • the default implementation -of the interface, using a specified custom resolver to determine what is the -default

                  • -

                • an implementation determined -by the default resolver, using a specified string as a resolution parameter

                  • -

                • an implementation determined -by the default resolver, using a specified string as a resolution parameter, -and passing some data to the implementation

                  • -

                CExampleInterface uses the overloads of REComSession::CreateImplementation() to -implement these functions.

                CExampleInterface declares -one pure virtual function, DoMethodL(), which supplies a -service to the client. Implementations must implement this function.

                InterfaceDefinition also -provides an example of a custom resolver, called CExampleResolver. -Its behaviour is the same as ECom's default resolver. Because a resolver is -an implementation of the ECom CResolver interface, it requires -a registration resource file (100098ea.rss), and an exported -factory table (Proxy.cpp).

                -
                Class Summary

                REComSession

                TEComResolverParams

                RImplInfoPtrArray

                CResolver

                -
                Usage

                Building InterfaceDefinition exports -the files that contain the interface definition, Interface.h and Interface.inl, -to epoc32\include\; produces a DLL ExampleResolver.dll; -and compiles a resource file ExampleResolver.rsc in the \resource\plugins\ directory.

                Implementations -of the interface are provided in the Interface -Implementation example.

                A client program that accesses the -interface is provided in the Interface -Clientexample.

                + + + + + +InterfaceDefinition: ECom Interface Definition Example Code +
                Download

                Click on the following link to download the example: Ecom.zip

                Download some additional files +required by the example: CommonFramework

                Click: browse to view the example code.

                View the +additional files: browse.
                +
                Description

                InterfaceDefinition provides an example +ECom interface definition. It declares a base class, CExampleInterface, from which implementations of the interface should derive.

                CExampleInterface provides three NewL() functions that allow clients to get respectively:

                  +

                • the default +implementation of the interface, using a specified custom resolver +to determine what is the default

                  • +

                • an implementation +determined by the default resolver, using a specified string as a +resolution parameter

                  • +

                • an implementation +determined by the default resolver, using a specified string as a +resolution parameter, and passing some data to the implementation

                  • +

                CExampleInterface uses the overloads of REComSession::CreateImplementation(TUid, TUid &) to +implement these functions.

                CExampleInterface declares one pure virtual function, DoMethodL(), which supplies a service to the client. Implementations must implement +this function.

                InterfaceDefinition also provides an example of a custom resolver, called CExampleResolver. Its behaviour is the same as ECom's default resolver. Because a +resolver is an implementation of the ECom CResolver interface, it requires a registration resource file (100098ea.rss), and an exported factory table (Proxy.cpp).

                +
                Class +Summary

                REComSession

                TEComResolverParams

                RImplInfoPtrArray

                CResolver

                +
                Usage

                Building InterfaceDefinition exports the +files that contain the interface definition, Interface.h and Interface.inl, to epoc32\include\; produces a DLL ExampleResolver.dll; and compiles +a resource file ExampleResolver.rsc in the \resource\plugins\ directory.

                Implementations +of the interface are provided in the Interface Implementation example.

                A client program that accesses the interface is +provided in the Interface Clientexample.

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E51546A8-D000-540C-A757-56B323EA9DA7_d0e201740_href.png Binary file Symbian3/SDK/Source/GUID-E51546A8-D000-540C-A757-56B323EA9DA7_d0e201740_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E51546A8-D000-540C-A757-56B323EA9DA7_d0e206748_href.png Binary file Symbian3/SDK/Source/GUID-E51546A8-D000-540C-A757-56B323EA9DA7_d0e206748_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E5291BCB-D5D0-5175-B0A1-FE03CD14E1BD.dita --- a/Symbian3/SDK/Source/GUID-E5291BCB-D5D0-5175-B0A1-FE03CD14E1BD.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-E5291BCB-D5D0-5175-B0A1-FE03CD14E1BD.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,12 +1,12 @@ - - - - - -Configuring and clearing files

                You can configure the following settings for audio or video files, and the session log file:

                • Configuring audio files

                • Configuring video files

                • Configuring file metadata

                • Setting the video output screen

                • Enabling auto pause and resume for video

                • Clearing the log file

                Note: You can configure media files only when they are open, and when they are neither being recorded nor played.

                Configuring audio files

                To configure the settings of an audio file:

                1. In the File menu, click Open for Play, and select the audio file you want to configure.

                2. In the Settings menu, click Audio. The Audio Settings dialog box is displayed.

                3. In the Repeats box, enter the number of times to repeat the audio clip.

                4. In the Delay box, enter the interval between repeats in seconds.

                5. Select the Autoplay check box to play the file automatically when you open it for play.

                6. Select the Priority and Priority Preference.

                7. Select the Auto Pause&Resume check box to enable this functionality.

                8. Click OK to save the audio settings.

                Configuring video files

                Note: The ability to configure the video settings is not yet supported.

                To configure the settings of a video file:

                1. In the File menu, click Open for Play, and select the video file you want to configure.

                2. In the Settings menu, click Video. The Video Setting dialog box is displayed.

                3. Select the degree of Rotation.

                4. Enter percentages for the Scale Width and Scale Height.

                5. Select the Anti Alias Filtering check box to enable anti-alias filtering.

                6. Enter the coordinates in the top, bottom, left and right boxes to define the boundaries of the crop region.

                7. Select the Viewfinder check box to enable it.

                8. Enter values for the Camera Index and Camera Priority.

                9. Click OK to save the video settings.

                Configuring file metadata

                You can enter the metadata for any media file that is open for record. You can view but cannot modify the metadata of a file that is open for play.

                To enter or modify file metadata:

                1. In the File menu, select Open for Record.

                2. In the Settings menu, select Meta Data. The MetaData dialog box is displayed.

                3. Enter information into the Title, Author, Copyright, Revision, Category and Comments boxes.

                4. Click OK to save the metadata details entered.

                Setting the video output screen

                You can set the video output rendering to any specific screen number.

                To set the output screen:

                1. In the Settings menu, select Multiple Screen. The Set Output Screen dialog box is displayed.

                2. Enter the Screen Number in the Enter the Screen Number box.

                3. Click OK to save the output screen setting.

                  Note: If the Screen Number is not supported, the MVS displays a KErrNotSupported message.

                Enabling auto pause and resume for video

                You can enable auto pause and resume for video by registering for resource notification. Registering for resource notification means that the audio playback for a video can be paused and resumed efficiently if access to the resource is lost and subsequently regained.

                To enable auto pause and resume:

                1. In the Settings menu, select Register For Notification. The Register For Resource Notification dialog box is displayed.

                2. Select the Enable Auto Pause & Resume check box to enable this functionality.

                3. Click OK to save the auto pause and resume setting.

                  If you currently have a media file open for record, an information message is displayed to inform you that the setting has been applied. Otherwise, the setting is saved and applied when you next open a media file for record.

                To disable auto pause and resume, repeat the above steps but clear the Enable Auto Pause & Resume check box.

                Clearing the log file

                All events during a session are recorded in a log file.

                To clear the log for the current session, in the Settings menu, click ClearLog.

                Note: This feature is currently not available.

                See Also

                Introduction to the MVS

                MVS GUI layout

                Recording media files

                Playing media files

                Editing media files

                \ No newline at end of file + + + + + +Configuring and clearing files

                You can configure the following settings for audio or video files, and the session log file:

                • Configuring audio files

                • Configuring video files

                • Configuring file metadata

                • Setting the video output screen

                • Enabling auto pause and resume for video

                • Clearing the log file

                Note: You can configure media files only when they are open, and when they are neither being recorded nor played.

                Configuring audio files

                To configure the settings of an audio file:

                1. In the File menu, click Open for Play, and select the audio file you want to configure.

                2. In the Settings menu, click Audio. The Audio Settings dialog box is displayed.

                3. In the Repeats box, enter the number of times to repeat the audio clip.

                4. In the Delay box, enter the interval between repeats in seconds.

                5. Select the Autoplay check box to play the file automatically when you open it for play.

                6. Select the Priority and Priority Preference.

                7. Select the Auto Pause&Resume check box to enable this functionality.

                8. Click OK to save the audio settings.

                Configuring video files

                Note: The ability to configure the video settings is not yet supported.

                To configure the settings of a video file:

                1. In the File menu, click Open for Play, and select the video file you want to configure.

                2. In the Settings menu, click Video. The Video Setting dialog box is displayed.

                3. Select the degree of Rotation.

                4. Enter percentages for the Scale Width and Scale Height.

                5. Select the Anti Alias Filtering check box to enable anti-alias filtering.

                6. Enter the coordinates in the top, bottom, left and right boxes to define the boundaries of the crop region.

                7. Select the Viewfinder check box to enable it.

                8. Enter values for the Camera Index and Camera Priority.

                9. Click OK to save the video settings.

                Configuring file metadata

                You can enter the metadata for any media file that is open for record. You can view but cannot modify the metadata of a file that is open for play.

                To enter or modify file metadata:

                1. In the File menu, select Open for Record.

                2. In the Settings menu, select Meta Data. The MetaData dialog box is displayed.

                3. Enter information into the Title, Author, Copyright, Revision, Category and Comments boxes.

                4. Click OK to save the metadata details entered.

                Setting the video output screen

                You can set the video output rendering to any specific screen number.

                To set the output screen:

                1. In the Settings menu, select Multiple Screen. The Set Output Screen dialog box is displayed.

                2. Enter the Screen Number in the Enter the Screen Number box.

                3. Click OK to save the output screen setting.

                  Note: If the Screen Number is not supported, the MVS displays a KErrNotSupported message.

                Enabling auto pause and resume for video

                You can enable auto pause and resume for video by registering for resource notification. Registering for resource notification means that the audio playback for a video can be paused and resumed efficiently if access to the resource is lost and subsequently regained.

                To enable auto pause and resume:

                1. In the Settings menu, select Register For Notification. The Register For Resource Notification dialog box is displayed.

                2. Select the Enable Auto Pause & Resume check box to enable this functionality.

                3. Click OK to save the auto pause and resume setting.

                  If you currently have a media file open for record, an information message is displayed to inform you that the setting has been applied. Otherwise, the setting is saved and applied when you next open a media file for record.

                To disable auto pause and resume, repeat the above steps but clear the Enable Auto Pause & Resume check box.

                Clearing the log file

                All events during a session are recorded in a log file.

                To clear the log for the current session, in the Settings menu, click ClearLog.

                Note: This feature is currently not available.

                See Also

                Introduction to the MVS

                MVS GUI layout

                Recording media files

                Playing media files

                Editing media files

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E52D52C8-AC58-5550-8932-59B314A47313_d0e322816_href.jpg Binary file Symbian3/SDK/Source/GUID-E52D52C8-AC58-5550-8932-59B314A47313_d0e322816_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E52D52C8-AC58-5550-8932-59B314A47313_d0e328973_href.jpg Binary file Symbian3/SDK/Source/GUID-E52D52C8-AC58-5550-8932-59B314A47313_d0e328973_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E544A944-5A65-40BD-A3B4-EF14E6132130_d0e3249_href.png Binary file Symbian3/SDK/Source/GUID-E544A944-5A65-40BD-A3B4-EF14E6132130_d0e3249_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E544A944-5A65-40BD-A3B4-EF14E6132130_d0e4524_href.png Binary file Symbian3/SDK/Source/GUID-E544A944-5A65-40BD-A3B4-EF14E6132130_d0e4524_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E56D30B2-9EF7-555C-8119-9F5E0F959AB4_d0e203595_href.png Binary file Symbian3/SDK/Source/GUID-E56D30B2-9EF7-555C-8119-9F5E0F959AB4_d0e203595_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E56D30B2-9EF7-555C-8119-9F5E0F959AB4_d0e208603_href.png Binary file Symbian3/SDK/Source/GUID-E56D30B2-9EF7-555C-8119-9F5E0F959AB4_d0e208603_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E56EB25C-9B94-5486-9492-5151FDF79B6C.dita --- a/Symbian3/SDK/Source/GUID-E56EB25C-9B94-5486-9492-5151FDF79B6C.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-E56EB25C-9B94-5486-9492-5151FDF79B6C.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,49 +1,49 @@ - - - - - -Global -Surface Updates -

                Global surface updates are surface updates that are submitted to all displays -rather than just one display. By using global surface updates, the Video Renderer -can update surfaces on all displays including ones that it is not aware of. -When the Video Renderer sends a global surface update, the update is broadcast -by the Graphics Surface -Update component to all Composition Implementations present in the -system. Each Composition Implementation determines whether the surface is -displayed on its associated screen and if so, forces an update. For more information, -see Global Surface -Updates in the Graphics Guide.

                -

                The Video Renderer registers and unregisters surfaces with the Window Server -for all available displays. When the client calls CVideoRenderer::CreateSurfaceL(), -the Video Renderer creates the surface and then registers it with each display. -When the client calls CVideoRenderer::DestroySurfaceL(), -the Video Renderer unregisters the surface with each display and then destroys -it. The following sequence diagram shows how the Video Renderer registers -and unregisters surfaces:

                - - Surface registration - - -

                The Video Renderer uses the global constant KAllScreens (provided -by the Surface Update component) to ensure all displays are updated with new -data. The following sequence diagram shows the Video Renderer passing KAllScreens in -the call to RSurfaceUpdateSession::SubmitUpdate():

                - - Data flow between client, Video Renderer and Surface Update -client-side API - - -                 -Video Renderer -Component -Graphics -Composition Collection + + + + + +Global +Surface Updates +

                Global surface updates are surface updates that are submitted to all displays +rather than just one display. By using global surface updates, the Video Renderer +can update surfaces on all displays including ones that it is not aware of. +When the Video Renderer sends a global surface update, the update is broadcast +by the Graphics Surface +Update component to all Composition Implementations present in the +system. Each Composition Implementation determines whether the surface is +displayed on its associated screen and if so, forces an update. For more information, +see Global Surface +Updates in the Graphics Guide.

                +

                The Video Renderer registers and unregisters surfaces with the Window Server +for all available displays. When the client calls CVideoRenderer::CreateSurfaceL(), +the Video Renderer creates the surface and then registers it with each display. +When the client calls CVideoRenderer::DestroySurfaceL(), +the Video Renderer unregisters the surface with each display and then destroys +it. The following sequence diagram shows how the Video Renderer registers +and unregisters surfaces:

                + + Surface registration + + +

                The Video Renderer uses the global constant KAllScreens (provided +by the Surface Update component) to ensure all displays are updated with new +data. The following sequence diagram shows the Video Renderer passing KAllScreens in +the call to RSurfaceUpdateSession::SubmitUpdate():

                + + Data flow between client, Video Renderer and Surface Update +client-side API + + +                 +Video Renderer +Component +Graphics +Composition Collection                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E5962E2D-C2D1-40EC-96FB-79CA6D10417F_d0e3490_href.png Binary file Symbian3/SDK/Source/GUID-E5962E2D-C2D1-40EC-96FB-79CA6D10417F_d0e3490_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E5962E2D-C2D1-40EC-96FB-79CA6D10417F_d0e4765_href.png Binary file Symbian3/SDK/Source/GUID-E5962E2D-C2D1-40EC-96FB-79CA6D10417F_d0e4765_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E5FB2D04-D57E-4EEA-850F-40F813C75D8C_d0e4231_href.png Binary file Symbian3/SDK/Source/GUID-E5FB2D04-D57E-4EEA-850F-40F813C75D8C_d0e4231_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E5FB2D04-D57E-4EEA-850F-40F813C75D8C_d0e5506_href.png Binary file Symbian3/SDK/Source/GUID-E5FB2D04-D57E-4EEA-850F-40F813C75D8C_d0e5506_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E60F9268-35D5-4D3F-B219-22AECF13953B_d0e74415_href.png Binary file Symbian3/SDK/Source/GUID-E60F9268-35D5-4D3F-B219-22AECF13953B_d0e74415_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E60F9268-35D5-4D3F-B219-22AECF13953B_d0e79541_href.png Binary file Symbian3/SDK/Source/GUID-E60F9268-35D5-4D3F-B219-22AECF13953B_d0e79541_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E61A931D-6E66-5E17-AE61-ABFB74CB8EF2.dita --- a/Symbian3/SDK/Source/GUID-E61A931D-6E66-5E17-AE61-ABFB74CB8EF2.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-E61A931D-6E66-5E17-AE61-ABFB74CB8EF2.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,52 +1,52 @@ - - - - - -Life -cycle of active objectsThis document describes the life cycle of an active objet. -

                The diagram illustrates the life-cycle of an active object.

                - -Flow diagram showing the life cycle of an active object - - -

                Procedural flow follows the black arrows; control is transferred along -the blue links, as follows:

                -
                  -

                • the main program creates -and installs an active scheduler

                  • -

                • active objects are created; -their constructors ensure that every active object is added to the active -scheduler (which keeps a reference to the object in its queue)

                  • -

                • an active object is -called to issue an initial request. This sets the object's iActive true -(indicating a request was issued but not yet completed) and schedules the -underlying service, which sets the object's iStatus to KRequestPending. -(If this step is omitted, no service will be requested, so no handler will -be invoked and hence the active scheduler will wait forever in its loop, never -calling any object's RunL())

                  • -

                • the active scheduler -is started. This now takes over; control is only returned to the main program -for termination when the active scheduler is stopped

                  • -

                • when a requested service -completes, it's handler terminates by signaling service completion; this alters -the associated active object's iStatus

                  • -

                • when any service handler -signals completion, the active scheduler tests each object in its queues for -one with iActive true (request not completed) and iStatus not -set to KRequestPending (i.e. the request has been handled)

                  • -

                • if the active scheduler -finds an object with the above conditions, it sets iActive false -and calls the object's RunL()

                  • -

                • the RunL() may -reschedule the request (so that the handler is again invoked when the requested -service completes and the cycle continues.) or may stop the active scheduler, -returning control to the main program for termination.

                  • -
                + + + + + +Life +cycle of active objectsThis document describes the life cycle of an active objet. +

                The diagram illustrates the life-cycle of an active object.

                + +Flow diagram showing the life cycle of an active object + + +

                Procedural flow follows the black arrows; control is transferred along +the blue links, as follows:

                +
                  +

                • the main program creates +and installs an active scheduler

                  • +

                • active objects are created; +their constructors ensure that every active object is added to the active +scheduler (which keeps a reference to the object in its queue)

                  • +

                • an active object is +called to issue an initial request. This sets the object's iActive true +(indicating a request was issued but not yet completed) and schedules the +underlying service, which sets the object's iStatus to KRequestPending. +(If this step is omitted, no service will be requested, so no handler will +be invoked and hence the active scheduler will wait forever in its loop, never +calling any object's RunL())

                  • +

                • the active scheduler +is started. This now takes over; control is only returned to the main program +for termination when the active scheduler is stopped

                  • +

                • when a requested service +completes, it's handler terminates by signaling service completion; this alters +the associated active object's iStatus

                  • +

                • when any service handler +signals completion, the active scheduler tests each object in its queues for +one with iActive true (request not completed) and iStatus not +set to KRequestPending (i.e. the request has been handled)

                  • +

                • if the active scheduler +finds an object with the above conditions, it sets iActive false +and calls the object's RunL()

                  • +

                • the RunL() may +reschedule the request (so that the handler is again invoked when the requested +service completes and the cycle continues.) or may stop the active scheduler, +returning control to the main program for termination.

                  • +
                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E63545EC-172E-53F3-B0B3-EA5150FD92D8.dita --- a/Symbian3/SDK/Source/GUID-E63545EC-172E-53F3-B0B3-EA5150FD92D8.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-E63545EC-172E-53F3-B0B3-EA5150FD92D8.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,102 +1,104 @@ - - - - - -Asynchronous -Services Example CodesExplains how to use asynchronous requests. -
                  -

                • SingleRequest: asynchronous programming without active objects

                  • -

                • WaitLoop: asynchronous programming without active objects

                  • -

                • RealLifeWaitLoop: asynchronous programming without active objects

                  • -

                • RunComplete: asynchronous programming with active objects

                  • -

                • AcceptInput1-2: asynchronous programming with active objects

                  • -

                • AcceptPrintInput: asynchronous programming with active objects

                  • -

                • Fibonacci1-3: asynchronous programming with active objects.

                  • -
                -
                SingleRequest: -asynchronous programming without active objects

                Download

                Click -on the following link to download the example: SingleRequest.zip

                Click on the following link -to download additional file: CommonFramework.zip

                Click browse SingleRequest to view the example code.

                Click browse CommonFramework to view the additional file.

                Click -on the below link for S60 Example which demonstrates Asynchronous requests ClientServerAsync .zip .

                Browse the S60 files. ClientServerAsync .

                Description

                This -example shows how to issue and wait for a single request.

                The example -shows the general principles involved in asynchronous programming. It uses -a simple wait loop and shows how the completion of asynchronous events are -handled without active objects.

                This example does not use active -objects deliberately.

                Class summary

                TRequestStatus

                Security -issues

                The example requires no specific capabilities in order -to run - and does not demonstrate any security issues.

                -
                WaitLoop: asynchronous -programming without active objects

                Download

                Click -on the following link to download the example: Waitloop.zip

                Click on the following link to -download additional file: CommonFramework.zip

                Click browse Waitloop to view the example code.

                Click browse CommonFramework to view the additional file.

                Description

                This -example shows how a wait loop can be used to identify and handle a completed -request.

                It shows the general principles involved in asynchronous -programming. It uses a simple wait loop and shows how the completion of asynchronous -events are handled without active objects.

                This example does -not use active objects deliberately.

                Class summary

                TRequestStatus

                Security -issues

                The example requires no specific capabilities in order -to run - and does not demonstrate any security issues.

                -
                RealLifeWaitLoop: -asynchronous programming without active objects

                Download

                Click -on the following link to download the example: RealLifeWaitLoop.zip

                Click on the following -link to download additional files: CommonFramework.zip

                Click browse RealLifeWaitLoop to view example code.

                Click browse CommonFramework to view the additional file.

                Description

                As -with the WaitLoop example, -this example shows how a wait loop can be used to identify and handle a completed -request. However, this example shows how the wait loop can deal with multiple -asynchronous service providers.

                The example shows the general principles -involved in asynchronous programming; it uses a simple wait loop and shows -how the completion of asynchronous events are handled without active -objects.

                This example deliberately does not use active objects.

                Class -summary

                TRequestStatus

                Security issues

                The -example requires no specific capabilities in order to run - and does not demonstrate -any security issues.

                -
                RunComplete: -asynchronous programming with active objects

                Download

                Click -on the following link to download the example: RunComplete.zip

                Click on the following link -to download additional files: CommonFramework.zip

                Click browse RunComplete to view the example code.

                Click browse CommonFramework to view the additional file.

                Description

                The -example shows how active objects and an active scheduler can be used to handle -asynchronous events. Compare this with the following examples; SingleRequest, WaitLoop and RealLifeWaitLoop.

                It -demonstrates a single CMessageTimer active object which runs -until completion.

                Class summary

                TRequestStatus CActiveScheduler CActive CTimer

                Security issues

                The example -requires no specific capabilities in order to run - and does not demonstrate -any security issues.

                -
                AcceptInput1-2: -asynchronous programming with active objects

                Download

                Click -on the following links to download the examples:

                AcceptInput1.zip

                AcceptInput2.zip

                Click on the following link -to download additional files: CommonFramework.zip

                Click on the following -links to view the examples:

                browse AcceptInput1

                browse AcceptInput2

                Click browse CommonFramework to view the additional file.

                Description

                These -examples show how active objects and an active scheduler can be used to handle -asynchronous events.

                They demonstrate a single CKeyMessengerProcessor active -object (derived from class CActiveConsole), which accepts -input from keyboard, but does not print it. This object contains a CMessageTimer object -which it activates if the user inputs the character "m" and cancelled if the -user inputs "c".

                Class summary

                TRequestStatus CActiveScheduler CActive CTimer

                Security issues

                The example -requires no specific capabilities in order to run - and does not demonstrate -any security issues.

                -
                AcceptPrintInput: -asynchronous programming with active objects

                Download

                Click -on the following link to download the example: AcceptPrintInput.zip

                Click on the following -link to download additional files: CommonFramework.zip

                View the source code browse AcceptPrintInput. View the additional file: browse CommonFramework.

                Description

                This -example demonstrates how to accept and print keyboard input to a console using -active objects.

                The example implements a class called CWriteKeyProcessor which -is an active object that requests and handles keyboard input in its ProcessKeyPress() method. -An alphabetic or space character is printed as a character, anything else -is printed as an integer. Pressing the escape key terminates the application.

                Class -summary

                CActiveScheduler CActive CTimer

                Security -issues

                The example requires no specific capabilities in order -to run - and does not demonstrate any security issues.

                -
                Fibonacci1-3: -asynchronous programming with active objects

                Download

                Click -on the following links to download the examples: Fibonacii1.zip

                Fibonacii2.zip

                Fibonacii3.zip

                Click browse Fibonacii1

                browse Fibonacii2

                browse Fibonacii3

                Description

                These -examples show how active objects and an active scheduler can be used to handle -asynchronous events and long-running services to maintain system responsiveness.

                Class -summary

                TRequestStatus CActiveScheduler CActive CTimer

                Security issues

                The example requires no specific capabilities -in order to run - and does not demonstrate any security issues.

                + + + + + +Asynchronous +Services Example CodesExplains how to use asynchronous requests. +
                  +

                • SingleRequest: asynchronous programming without active objects

                  • +

                • WaitLoop: asynchronous programming without active objects

                  • +

                • RealLifeWaitLoop: asynchronous programming without active objects

                  • +

                • RunComplete: asynchronous programming with active objects

                  • +

                • AcceptInput1-2: asynchronous programming with active objects

                  • +

                • AcceptPrintInput: asynchronous programming with active objects

                  • +

                • Fibonacci1-3: asynchronous programming with active objects.

                  • +
                +
                SingleRequest: +asynchronous programming without active objects

                Download

                Click +on the following link to download the example: SingleRequest.zip

                Click on the following link +to download additional file: CommonFramework.zip

                Click browse SingleRequest to view the example code.

                Click browse CommonFramework to view the additional file.

                Click +on the below link for Example which demonstrates Asynchronous requests ClientServerAsync .zip .

                Browse +the S60 files. ClientServerAsync .

                Description

                This +example shows how to issue and wait for a single request.

                The example +shows the general principles involved in asynchronous programming. It uses +a simple wait loop and shows how the completion of asynchronous events are +handled without active objects.

                This example does not use active +objects deliberately.

                Class summary

                TRequestStatus

                Security +issues

                The example requires no specific capabilities in order +to run - and does not demonstrate any security issues.

                +
                WaitLoop: asynchronous +programming without active objects

                Download

                Click +on the following link to download the example: Waitloop.zip

                Click on the following link to +download additional file: CommonFramework.zip

                Click browse Waitloop to view the example code.

                Click browse CommonFramework to view the additional file.

                Description

                This +example shows how a wait loop can be used to identify and handle a completed +request.

                It shows the general principles involved in asynchronous +programming. It uses a simple wait loop and shows how the completion of asynchronous +events are handled without active objects.

                This example does +not use active objects deliberately.

                Class summary

                TRequestStatus

                Security +issues

                The example requires no specific capabilities in order +to run - and does not demonstrate any security issues.

                +
                RealLifeWaitLoop: +asynchronous programming without active objects

                Download

                Click +on the following link to download the example: RealLifeWaitLoop.zip

                Click on the following +link to download additional files: CommonFramework.zip

                Click browse RealLifeWaitLoop to view example code.

                Click browse CommonFramework to view the additional file.

                Description

                As +with the WaitLoop example, +this example shows how a wait loop can be used to identify and handle a completed +request. However, this example shows how the wait loop can deal with multiple +asynchronous service providers.

                The example shows the general principles +involved in asynchronous programming; it uses a simple wait loop and shows +how the completion of asynchronous events are handled without active +objects.

                This example deliberately does not use active objects.

                Class +summary

                TRequestStatus

                Security issues

                The +example requires no specific capabilities in order to run - and does not demonstrate +any security issues.

                +
                RunComplete: +asynchronous programming with active objects

                Download

                Click +on the following link to download the example: RunComplete.zip

                Click on the following link +to download additional files: CommonFramework.zip

                Click browse RunComplete to view the example code.

                Click browse CommonFramework to view the additional file.

                Description

                The +example shows how active objects and an active scheduler can be used to handle +asynchronous events. Compare this with the following examples; SingleRequest, WaitLoop and RealLifeWaitLoop.

                It +demonstrates a single CMessageTimer active object which runs +until completion.

                Class summary

                TRequestStatus CActiveScheduler CActive CTimer

                Security issues

                The example +requires no specific capabilities in order to run - and does not demonstrate +any security issues.

                +
                AcceptInput1-2: +asynchronous programming with active objects

                Download

                Click +on the following links to download the examples:

                AcceptInput1.zip

                AcceptInput2.zip

                Click on the following link +to download additional files: CommonFramework.zip

                Click on the following +links to view the examples:

                browse AcceptInput1

                browse AcceptInput2

                Click browse CommonFramework to view the additional file.

                Description

                These +examples show how active objects and an active scheduler can be used to handle +asynchronous events.

                They demonstrate a single CKeyMessengerProcessor active +object (derived from class CActiveConsole), which accepts +input from keyboard, but does not print it. This object contains a CMessageTimer object +which it activates if the user inputs the character "m" and cancelled if the +user inputs "c".

                Class summary

                TRequestStatus CActiveScheduler CActive CTimer

                Security issues

                The example +requires no specific capabilities in order to run - and does not demonstrate +any security issues.

                +
                AcceptPrintInput: +asynchronous programming with active objects

                Download

                Click +on the following link to download the example: AcceptPrintInput.zip

                Click on the following +link to download additional files: CommonFramework.zip

                View the source code browse AcceptPrintInput. View the additional file: browse CommonFramework.

                Description

                This +example demonstrates how to accept and print keyboard input to a console using +active objects.

                The example implements a class called CWriteKeyProcessor which +is an active object that requests and handles keyboard input in its ProcessKeyPress() method. +An alphabetic or space character is printed as a character, anything else +is printed as an integer. Pressing the escape key terminates the application.

                Class +summary

                CActiveScheduler CActive CTimer

                Security +issues

                The example requires no specific capabilities in order +to run - and does not demonstrate any security issues.

                +
                Fibonacci1-3: +asynchronous programming with active objects

                Download

                Click +on the following links to download the examples: Fibonacii1.zip

                Fibonacii2.zip

                Fibonacii3.zip

                Click browse Fibonacii1

                browse Fibonacii2

                browse Fibonacii3

                Description

                These +examples show how active objects and an active scheduler can be used to handle +asynchronous events and long-running services to maintain system responsiveness.

                An +alternative solution, not using a timer, is described on The Long Running Active Object wiki page.

                Class +summary

                TRequestStatus CActiveScheduler CActive CTimer

                Security issues

                The example requires no specific capabilities +in order to run - and does not demonstrate any security issues.

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E63899B3-8EA8-5EF7-982E-EC161B3A4794_d0e77341_href.png Binary file Symbian3/SDK/Source/GUID-E63899B3-8EA8-5EF7-982E-EC161B3A4794_d0e77341_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E63899B3-8EA8-5EF7-982E-EC161B3A4794_d0e84053_href.png Binary file Symbian3/SDK/Source/GUID-E63899B3-8EA8-5EF7-982E-EC161B3A4794_d0e84053_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E63D0A01-EF87-566F-9BFA-9E75AD6F3205.dita --- a/Symbian3/SDK/Source/GUID-E63D0A01-EF87-566F-9BFA-9E75AD6F3205.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-E63D0A01-EF87-566F-9BFA-9E75AD6F3205.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,14 +1,14 @@ - - - - - -Window HierarchyIn a running application, all window instances are arranged in a hierarchy, in which each window has a parent. The Window Server has a window not owned by the client, called the "root" window which is the parent of all the group windows.

                Variant: Both (ScreenPlay and non-ScreenPlay). Target audience: Application developers.

                Parent windows

                The following diagram shows the relationship between parent and child windows and window groups at run-time. Arrows indicate "is a parent of".

                - Window hierarchy -

                The relationships between parent and child windows have the following properties:

                • A window's parent is specified when the window is created.

                • The Window Server imposes no limit to the number of children a window can have. The number of children is limited only by the resources of the system.

                • When a parent window is destroyed, all its children are removed from the screen. However, the objects associated with them are not destroyed until the window or the client that owns them is destroyed.

                • A window's parent defines the region in which the window can be displayed. A child cannot be displayed outside its parent, and is clipped to the parent’s visible region. If a child window is moved so that part of it extends beyond its parent, that part of the child window will not be visible.

                • Note that if a window's parent is a window group, the window can be displayed anywhere on the screen, because window groups do not have a size.

                Sibling windows

                If a window has multiple children, these are known as siblings. Sibling windows are maintained in a list, and the parent window owns a link to the first window in the sibling list. The order of the windows in the sibling list represents the windows’ ordinal position. This determines which windows are displayed on top of which, if they overlap.

                Window Types                 \ No newline at end of file + + + + + +Window HierarchyIn a running application, all window instances are arranged in a hierarchy, in which each window has a parent. The Window Server has a window not owned by the client, called the "root" window which is the parent of all the group windows.

                Variant: Both (ScreenPlay and non-ScreenPlay). Target audience: Application developers.

                Parent windows

                The following diagram shows the relationship between parent and child windows and window groups at run-time. Arrows indicate "is a parent of".

                + Window hierarchy +

                The relationships between parent and child windows have the following properties:

                • A window's parent is specified when the window is created.

                • The Window Server imposes no limit to the number of children a window can have. The number of children is limited only by the resources of the system.

                • When a parent window is destroyed, all its children are removed from the screen. However, the objects associated with them are not destroyed until the window or the client that owns them is destroyed.

                • A window's parent defines the region in which the window can be displayed. A child cannot be displayed outside its parent, and is clipped to the parent’s visible region. If a child window is moved so that part of it extends beyond its parent, that part of the child window will not be visible.

                • Note that if a window's parent is a window group, the window can be displayed anywhere on the screen, because window groups do not have a size.

                Sibling windows

                If a window has multiple children, these are known as siblings. Sibling windows are maintained in a list, and the parent window owns a link to the first window in the sibling list. The order of the windows in the sibling list represents the windows’ ordinal position. This determines which windows are displayed on top of which, if they overlap.

                Window Types                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E64A8D76-28AD-4F75-9E92-3290488F85D9_d0e67410_href.png Binary file Symbian3/SDK/Source/GUID-E64A8D76-28AD-4F75-9E92-3290488F85D9_d0e67410_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E64A8D76-28AD-4F75-9E92-3290488F85D9_d0e72613_href.png Binary file Symbian3/SDK/Source/GUID-E64A8D76-28AD-4F75-9E92-3290488F85D9_d0e72613_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E651C7A7-D6EB-533E-A97A-360D089DE7A5.dita --- a/Symbian3/SDK/Source/GUID-E651C7A7-D6EB-533E-A97A-360D089DE7A5.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-E651C7A7-D6EB-533E-A97A-360D089DE7A5.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,56 +1,56 @@ - - - - - -Inter-thread -data transferDescribes how data is transferred between threads. -

                The client-server message protocol supports the passing of a 32-bit request -code and four 32-bit parameters from client to server and returning a 32-bit -result from the server to the client. The parameters may be interpreted as -plain integers or pointers; pointer types may be untyped (TAny*) -or descriptor types (TDesC8* and TDesC16*) -that the server can use to access the client’s address space. The request -code, parameters, and the parameter types are packaged into a TIpcArgs object. -The parameter types are stored in the kernel side message object so that the -kernel can check that subsequent operations requested by the server using -the message are:

                -
                  -

                • correct; for example, -checking that the source and target descriptors are either both 8-bit or both -16-bit descriptors

                  • -

                • permitted by the client; -for example, checking that when the server tries to write to a client descriptor, -that the client descriptor is TDes -derived (modifiable), -rather than TDesC -derived (non-modifiable)

                  • -
                -

                NOTE: although you can pass untyped pointers, it is not possible -to directly access memory in another thread’s address space using an arbitrary -pointer as this is inherently insecure. The ability to pass a pointer between -a client and server is therefore only of value when the client and server -are within the same process. In this case, the use of a pointer is obviously -not limited to pointing to a descriptor, but may also be used to point to -an arbitrary data structure containing information to be shared between the -client and server.

                -

                It is important to note that a server may not run until some arbitrary -time after a client issues a request. Any descriptor containing data to be -passed to the server must be guaranteed to exist until the request completes. -For this reason, any such descriptor must not live on the program stack. -Typically, such a descriptor would be a component of an object which is allocated -on the heap.

                -

                The following diagram illustrates the general idea. In this case, there -are three parameters, one of which is an integer, and the other two being -pointers to descriptors.

                - - -

                Inter-thread data transfer

                -                 -
                See also

                Descriptor -concepts.

                + + + + + +Inter-thread +data transferDescribes how data is transferred between threads. +

                The client-server message protocol supports the passing of a 32-bit request +code and four 32-bit parameters from client to server and returning a 32-bit +result from the server to the client. The parameters may be interpreted as +plain integers or pointers; pointer types may be untyped (TAny*) +or descriptor types (TDesC8* and TDesC16*) +that the server can use to access the client’s address space. The request +code, parameters, and the parameter types are packaged into a TIpcArgs object. +The parameter types are stored in the kernel side message object so that the +kernel can check that subsequent operations requested by the server using +the message are:

                +
                  +

                • correct; for example, +checking that the source and target descriptors are either both 8-bit or both +16-bit descriptors

                  • +

                • permitted by the client; +for example, checking that when the server tries to write to a client descriptor, +that the client descriptor is TDes -derived (modifiable), +rather than TDesC -derived (non-modifiable)

                  • +
                +

                NOTE: although you can pass untyped pointers, it is not possible +to directly access memory in another thread’s address space using an arbitrary +pointer as this is inherently insecure. The ability to pass a pointer between +a client and server is therefore only of value when the client and server +are within the same process. In this case, the use of a pointer is obviously +not limited to pointing to a descriptor, but may also be used to point to +an arbitrary data structure containing information to be shared between the +client and server.

                +

                It is important to note that a server may not run until some arbitrary +time after a client issues a request. Any descriptor containing data to be +passed to the server must be guaranteed to exist until the request completes. +For this reason, any such descriptor must not live on the program stack. +Typically, such a descriptor would be a component of an object which is allocated +on the heap.

                +

                The following diagram illustrates the general idea. In this case, there +are three parameters, one of which is an integer, and the other two being +pointers to descriptors.

                + + +

                Inter-thread data transfer

                +                 +
                See also

                Descriptor +concepts.

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E65D89C5-0472-573A-BD1C-B298848CD4CF.dita --- a/Symbian3/SDK/Source/GUID-E65D89C5-0472-573A-BD1C-B298848CD4CF.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-E65D89C5-0472-573A-BD1C-B298848CD4CF.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,12 +1,12 @@ - - - - - -Bluetooth Collection OverviewThe Bluetooth collection contains the SDP, GAVDP and notifier support components.
                Purpose

                The Bluetooth Collection contains the SDP, GAVDP and notifier support components.

                Architecture
                Components

                The Bluetooth collection contains the following components:

                • SDP

                  Bluetooth Service Discovery Protocol (SDP) enables a device to find out what services are available on another device. For example, when connecting a mobile phone to a bluetooth headset, SDP can find out which Bluetooth profiles the headset supports. The SDP component enables devices to register services to the SDP database and to query the database for available services. The SDP Agent and the SDP Database provide functionality for the SDP component.

                • GAVDP

                  Generic Audio Video Distribution Profile (GAVDP) enables audio or video streaming.

                • Bluetooth Notifiers Support

                  The Bluetooth Notifiers Support component enables you to create dialogs for interacting with device users about Bluetooth interactions. You can offer Bluetooth dialogs for several purposes, but the main purpose is to provide security for Bluetooth interactions.

                Using the Bluetooth collection

                The Bluetooth collection has the following uses:

                • using SDP to find out what services are available on another device

                • Using GAVDP to enable audio or video streaming

                • using the Bluetooth Notifiers Support to create dialogs for interacting with device users about Bluetooth interactions.

                \ No newline at end of file + + + + + +Bluetooth Collection OverviewThe Bluetooth collection contains the SDP, GAVDP and notifier support components.
                Purpose

                The Bluetooth Collection contains the SDP, GAVDP and notifier support components.

                Architecture
                Components

                The Bluetooth collection contains the following components:

                • SDP

                  Bluetooth Service Discovery Protocol (SDP) enables a device to find out what services are available on another device. For example, when connecting a mobile phone to a bluetooth headset, SDP can find out which Bluetooth profiles the headset supports. The SDP component enables devices to register services to the SDP database and to query the database for available services. The SDP Agent and the SDP Database provide functionality for the SDP component.

                • GAVDP

                  Generic Audio Video Distribution Profile (GAVDP) enables audio or video streaming.

                • Bluetooth Notifiers Support

                  The Bluetooth Notifiers Support component enables you to create dialogs for interacting with device users about Bluetooth interactions. You can offer Bluetooth dialogs for several purposes, but the main purpose is to provide security for Bluetooth interactions.

                Using the Bluetooth collection

                The Bluetooth collection has the following uses:

                • using SDP to find out what services are available on another device

                • Using GAVDP to enable audio or video streaming

                • using the Bluetooth Notifiers Support to create dialogs for interacting with device users about Bluetooth interactions.

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E6803961-14A0-44BD-A94E-5D8A38EA907F.dita --- a/Symbian3/SDK/Source/GUID-E6803961-14A0-44BD-A94E-5D8A38EA907F.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-E6803961-14A0-44BD-A94E-5D8A38EA907F.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,29 +1,29 @@ - - - - - -Lists -and grids -

                Vertical lists are used extensively in most applications. Two-dimensional -grids are less frequently used, but have obvious advantages in some situations. -In lists and grids, the user can move the focus from one item to another using -the Arrow keys. This is called browsing or scrolling.

                -

                In tap-enabled devices, a menu item can be opened by touch down and release.

                -

                In general, vertical browsing is preferred over horizontal browsing; the -keypad solutions should take this into account.

                - - -Lists and grids - - -
                Using -lists and grids in C++ applications

                The APIs to use for lists and -grids are the Lists API and the Grids API. For implementation information, see Using the Lists API and Using the Grids API.

                + + + + + +Lists +and grids +

                Vertical lists are used extensively in most applications. Two-dimensional +grids are less frequently used, but have obvious advantages in some situations. +In lists and grids, the user can move the focus from one item to another using +the Arrow keys. This is called browsing or scrolling.

                +

                In devices supporting touch, a menu item can be opened by +touch down and release.

                +

                In general, vertical browsing is preferred over horizontal browsing; the +keypad solutions should take this into account.

                + +Lists and grids + + +
                Using +lists and grids in applications

                The APIs to use for lists and grids +are the Lists API and the Grids API. For implementation information, see Using the Lists API and Using the Grids API.

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E71DEB5F-A13A-5675-B2DE-9BCFDB38A3EC.dita --- a/Symbian3/SDK/Source/GUID-E71DEB5F-A13A-5675-B2DE-9BCFDB38A3EC.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-E71DEB5F-A13A-5675-B2DE-9BCFDB38A3EC.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,12 +1,12 @@ - - - - - -What is the mechanism for reading, writing and searching for dataThis topic describes the mechanism for reading data from the Comms Database and writing data to the Comms Database.

                All elements that you can read and write have the class MMetaDatabase as a base class. This base class contains the functions that get and store that element.

                Tables, records, links and fields are all elements. The classes that represent tables, records, links and fields have MMetaDatabase in their class hierarchy. You use the functions in MMetaDatabase to load and store tables, records, links and fields.

                The MMetaDatabase class gives you:

                • the functions to get data from the Comms Database: LoadL(), FindL(), RefreshL()

                • the functions to put data into the Comms Database: StoreL(), ModifyL(), DeleteL()

                Getting data directly from the Comms Database

                If you know the record Id part of the element Id of a table, record, field or link, you can load the table, record, field or link from the Comms Database. Call SetRecordId() on the CMDBElement base class to set the record Id. Call LoadL() on the MMetaDatabase base class to load the table, record, field or link.

                The CommsDat API gets the data that the tool or application is allowed to see from the Comms database. The data that the tool or application can see depends on platform security capabilities and the access attributes for the session.

                A request to load a single element fails if the tool or application does not have the platform security capabilities.

                A request to load a table does not fail if some records in the table are not available. The tool or application can see only those records that are available.

                A request to load a record does not fail if some fields in the record are not available. The tool or application can see only those fields that are available.

                LoadL() writes over the content of the table, record, field or link object in memory.

                LoadL() opens a read-only transaction with the Comms Database if the tool or application has not already started a transaction.

                Finding data in the Comms Database

                You can search for records in the Comms Database. There are two patterns:

                Finding a single record that has specified field values

                You create a CMDBRecordBase object in memory. You select the fields for the search and set the field values. Call FindL() on the CMDBRecordBase object. FindL() is member of the MMetaDatabase base class. If the search is successful, the CommsDat API fills the CMDBRecordBase object with the values from the first record in the Comms Database that matches. The values include the element Id. If the search is not successful, the CMDBRecordBase object is not changed.

                FindL() opens a read-only transaction with the Comms Database if the tool or application has not already started a transaction.

                Note that you do not need to set the record Id part of the element Id of the table, the record, the field or the link object.

                Finding all records in a table that match a specified record

                You create a CMDBRecordSet object and append a single record to the array of records. You select the fields for the search and set the field values. This record is the 'search record'. Call FindL() on the CMDBRecordSet object. If the search is successful, the function returns a number of complete records. The first record found writes over the 'search record'. If the search is not successful, the CMDBRecordSet object is not changed

                FindL() opens a read-only transaction with the Comms Database if the tool or application has not already started a transaction.

                Note that you do not need to set the record Id part of the element Id of the table, the record, the field or the link object.

                Refreshing data in memory

                You can update your copy of the data in memory. You call RefreshL() to update the data. The method is similar to LoadL() but the method does not write over fields that the tool or application has changed. All other fields are refreshed from the Comms Database.

                RefreshL() is a member of the MMetaDatabase base class.

                RefreshL() is useful if a tool or application maintains a cache of Comms information.

                RefreshL() opens a read-only transaction with the Comms Database if the tool or application has not already started a transaction.

                Adding new data to the Comms Database

                If need to add or change the data in the Comms Database you must add or change the data in the table, the record, the link or the field object in memory.

                Call StoreL() to create new records, tables and fields. The CommsDat API only stores the fields that the tool or application has changed.

                A table, record, field or link object that exists must have a valid element Id before the call to StoreL().

                To add a new user defined table to the Comms Database set the record Id part of the element Id of the table to KCDNewTableRequest before the call to StoreL(). Call SetRecordId() on the CMDBElement base class to set the record Id.

                To add a new record to a table set the record Id part of the element Id of the table to KCDNewRecordRequest before the call to StoreL(). Call SetRecordId() on the CMDBElement base class to set the record Id. The table must exist before you add the new record.

                To add a new column to a user defined table set the record Id part of the element Id of the table to KCDNewColumnRequest before the call to StoreL(). Call SetRecordId() on the CMDBElement base class to set the record Id. The effect of a new column is to add a new field in the user defined records.

                The tool or application must have the platform security capabilities to write to the Comms Database.

                StoreL() opens a read/write transaction with the Comms Database if the tool or application has not already started a transaction.

                Changing data in the Comms Database

                If you need to change data in the Comms Database you must change the data in the table, the record, the link or the field object in memory. The table, the record, the link and the field must already exist in the database.

                Call ModifyL() to change existing data. The function cannot create new records or tables, but can store new fields in a record.

                The tool or application must have the platform security capabilities to write to the Comms Database.

                ModifyL() opens a read/write transaction with the Comms Database if the tool or application has not already started a transaction.

                Deleting data from the Comms Database

                Call DeleteL() to delete a table, a record, a field or a link from the Comms Database.

                The tool or application must have the platform security capabilities to write to the Comms Database.

                DeleteL() opens a read/write transaction with the Comms Database if the tool or application has not already started a transaction.

                \ No newline at end of file + + + + + +What is the mechanism for reading, writing and searching for dataThis topic describes the mechanism for reading data from the Comms Database and writing data to the Comms Database.

                All elements that you can read and write have the class MMetaDatabase as a base class. This base class contains the functions that get and store that element.

                Tables, records, links and fields are all elements. The classes that represent tables, records, links and fields have MMetaDatabase in their class hierarchy. You use the functions in MMetaDatabase to load and store tables, records, links and fields.

                The MMetaDatabase class gives you:

                • the functions to get data from the Comms Database: LoadL(), FindL(), RefreshL()

                • the functions to put data into the Comms Database: StoreL(), ModifyL(), DeleteL()

                Getting data directly from the Comms Database

                If you know the record Id part of the element Id of a table, record, field or link, you can load the table, record, field or link from the Comms Database. Call SetRecordId() on the CMDBElement base class to set the record Id. Call LoadL() on the MMetaDatabase base class to load the table, record, field or link.

                The CommsDat API gets the data that the tool or application is allowed to see from the Comms database. The data that the tool or application can see depends on platform security capabilities and the access attributes for the session.

                A request to load a single element fails if the tool or application does not have the platform security capabilities.

                A request to load a table does not fail if some records in the table are not available. The tool or application can see only those records that are available.

                A request to load a record does not fail if some fields in the record are not available. The tool or application can see only those fields that are available.

                LoadL() writes over the content of the table, record, field or link object in memory.

                LoadL() opens a read-only transaction with the Comms Database if the tool or application has not already started a transaction.

                Finding data in the Comms Database

                You can search for records in the Comms Database. There are two patterns:

                Finding a single record that has specified field values

                You create a CMDBRecordBase object in memory. You select the fields for the search and set the field values. Call FindL() on the CMDBRecordBase object. FindL() is member of the MMetaDatabase base class. If the search is successful, the CommsDat API fills the CMDBRecordBase object with the values from the first record in the Comms Database that matches. The values include the element Id. If the search is not successful, the CMDBRecordBase object is not changed.

                FindL() opens a read-only transaction with the Comms Database if the tool or application has not already started a transaction.

                Note that you do not need to set the record Id part of the element Id of the table, the record, the field or the link object.

                Finding all records in a table that match a specified record

                You create a CMDBRecordSet object and append a single record to the array of records. You select the fields for the search and set the field values. This record is the 'search record'. Call FindL() on the CMDBRecordSet object. If the search is successful, the function returns a number of complete records. The first record found writes over the 'search record'. If the search is not successful, the CMDBRecordSet object is not changed

                FindL() opens a read-only transaction with the Comms Database if the tool or application has not already started a transaction.

                Note that you do not need to set the record Id part of the element Id of the table, the record, the field or the link object.

                Refreshing data in memory

                You can update your copy of the data in memory. You call RefreshL() to update the data. The method is similar to LoadL() but the method does not write over fields that the tool or application has changed. All other fields are refreshed from the Comms Database.

                RefreshL() is a member of the MMetaDatabase base class.

                RefreshL() is useful if a tool or application maintains a cache of Comms information.

                RefreshL() opens a read-only transaction with the Comms Database if the tool or application has not already started a transaction.

                Adding new data to the Comms Database

                If need to add or change the data in the Comms Database you must add or change the data in the table, the record, the link or the field object in memory.

                Call StoreL() to create new records, tables and fields. The CommsDat API only stores the fields that the tool or application has changed.

                A table, record, field or link object that exists must have a valid element Id before the call to StoreL().

                To add a new user defined table to the Comms Database set the record Id part of the element Id of the table to KCDNewTableRequest before the call to StoreL(). Call SetRecordId() on the CMDBElement base class to set the record Id.

                To add a new record to a table set the record Id part of the element Id of the table to KCDNewRecordRequest before the call to StoreL(). Call SetRecordId() on the CMDBElement base class to set the record Id. The table must exist before you add the new record.

                To add a new column to a user defined table set the record Id part of the element Id of the table to KCDNewColumnRequest before the call to StoreL(). Call SetRecordId() on the CMDBElement base class to set the record Id. The effect of a new column is to add a new field in the user defined records.

                The tool or application must have the platform security capabilities to write to the Comms Database.

                StoreL() opens a read/write transaction with the Comms Database if the tool or application has not already started a transaction.

                Changing data in the Comms Database

                If you need to change data in the Comms Database you must change the data in the table, the record, the link or the field object in memory. The table, the record, the link and the field must already exist in the database.

                Call ModifyL() to change existing data. The function cannot create new records or tables, but can store new fields in a record.

                The tool or application must have the platform security capabilities to write to the Comms Database.

                ModifyL() opens a read/write transaction with the Comms Database if the tool or application has not already started a transaction.

                Deleting data from the Comms Database

                Call DeleteL() to delete a table, a record, a field or a link from the Comms Database.

                The tool or application must have the platform security capabilities to write to the Comms Database.

                DeleteL() opens a read/write transaction with the Comms Database if the tool or application has not already started a transaction.

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E726406A-2DAF-5A5F-91AF-7919C671F18F_d0e334814_href.png Binary file Symbian3/SDK/Source/GUID-E726406A-2DAF-5A5F-91AF-7919C671F18F_d0e334814_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E726406A-2DAF-5A5F-91AF-7919C671F18F_d0e340971_href.png Binary file Symbian3/SDK/Source/GUID-E726406A-2DAF-5A5F-91AF-7919C671F18F_d0e340971_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E764B4A3-4CEE-461D-B555-C8969A62130A.dita --- a/Symbian3/SDK/Source/GUID-E764B4A3-4CEE-461D-B555-C8969A62130A.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-E764B4A3-4CEE-461D-B555-C8969A62130A.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,36 +1,36 @@ - - - - - -Status -pane items -

                A tap on:

                -
                  -

                • Navi pane: -common items (such as tabs) should perform a function that is obvious and -clear. Common AVKON interaction does not change. However, it an application -can assign an appropriate function to its Navi pane items. It is also possible -not to assign any function where appropriate.

                  • -

                • Universal indicator -pane: opens a pop-up with more information on Status -pane indicators. It always includes battery and signal indicators and -digital clock. The user can tap any of those for more information. For each -visible universal indicator, there is one row reserved in the pop-up for displaying -the icon and a description text. The description text may also inform about -the current status and/or it may be a link to a view in corresponding application. -For example, a tap on "3 new messages" opens the relevant view from the messaging -application, and "Bluetooth active" switches view to the Bluetooth settings. -Content of the row is determined by the application originating the indicator.

                  • -

                • Clock in Idle state opens the Clock application.

                  • -
                -
                Using -status pane items in C++ applications

                The API to use for the status -pane is the Status Pane API. For implementation information, see Using the Status Pane API.

                + + + + + +Status +pane items +

                A tap on:

                +
                  +

                • Navi pane: +common items (such as tabs) should perform a function that is obvious and +clear. Common AVKON interaction does not change. However, it an application +can assign an appropriate function to its Navi pane items. It is also possible +not to assign any function where appropriate.

                  • +

                • Universal indicator +pane: opens a pop-up with more information on Status +pane indicators. It always includes battery and signal indicators and +digital clock. The user can tap any of those for more information. For each +visible universal indicator, there is one row reserved in the pop-up for displaying +the icon and a description text. The description text may also inform about +the current status and/or it may be a link to a view in corresponding application. +For example, a tap on "3 new messages" opens the relevant view from the messaging +application, and "Bluetooth active" switches view to the Bluetooth settings. +Content of the row is determined by the application originating the indicator.

                  • +

                • Clock in the home screen opens the Clock application.

                  • +
                +
                Using +status pane items in applications

                The API to use for the status +pane is the Status Pane API. For implementation information, see Using the Status Pane API.

                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E77E2E2A-2F2D-549E-ABD6-175E68A406CB_d0e337536_href.png Binary file Symbian3/SDK/Source/GUID-E77E2E2A-2F2D-549E-ABD6-175E68A406CB_d0e337536_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E77E2E2A-2F2D-549E-ABD6-175E68A406CB_d0e343733_href.png Binary file Symbian3/SDK/Source/GUID-E77E2E2A-2F2D-549E-ABD6-175E68A406CB_d0e343733_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E7A53792-5ABC-460C-87EA-36E8C6989A2C.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-E7A53792-5ABC-460C-87EA-36E8C6989A2C.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,22 @@ + + + + + +API +Changes and Compatibility BreaksThe purpose of this section is to highlight all the API changes +and compatibility breaks (binary & source) in Symbian^3. It provides all +the required information for Symbian application developers and eases their +migration process from S60 5th Edition to Symbian^3. +

                In Symbian^3, all the deprecated APIs from the earlier releases are removed. +In addition, a few more APIs are deprecated and the behavior for a few others +has changed based on issues found in earlier Symbian platform +releases. To avoid functionality duplication, support for a few APIs has been +removed.

                +                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E7EFAD50-3323-49A6-A5D9-95B95F0FBF0E.dita --- a/Symbian3/SDK/Source/GUID-E7EFAD50-3323-49A6-A5D9-95B95F0FBF0E.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-E7EFAD50-3323-49A6-A5D9-95B95F0FBF0E.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,103 +1,103 @@ - - - - - -Preview -pop-up -

                Preview pop-up is a floating component used for displaying more detailed -data about an item that has focus in the main pane.

                - -Preview pop-up - - -

                The preview is displayed with a 0.6 second delay after the focus is moved -(for example, scrolling down a list with the Arrow keys) to avoid too rapid -and continuous flicker. The default time-out for closing the preview pop-up -is the same as for the Information pop-up, but it is possible to adjust it -if necessary.

                -

                Preview pop-up contents cannot be scrolled and the component must not contain -any buttons or other elements that make it appear interactive: the component -is the same in both standard and touch-enabled devices and should the component -be used in a standard non-touch device, its elements should not look touch-enabled. -There can be a maximum of five text rows in a preview pop-up, and it is possible -to place a small icon in the start of the rows. It is even possible to have -more than one icon on a row instead of text, if necessary. The number of images -in a single preview pop-up is limited to one, and it can be accompanied by -up to two rows of text.

                -

                Preview pop-up shows always duplicate data in a given application to ensure -that the user will not miss any content or functionality even if a given product -does not utilize preview pop-up (that is, it has been switched OFF). Owing -to the special nature of preview pop-up, it is important to thoroughly consider -its genuine usefulness in various applications. Furthermore, the component -should not be confused with the Information pop-up note even though the data -displayed in these two components can at times be identical.

                -Default touch -events in Preview Pop-Up - - - -

                User action

                 -

                State change

                 -

                Feedback

                 -                 - - - -

                Touch down / release in Preview pop-up area

                 -

                Application-specific

                 -

                Tactile: Tactile feedback follows the component-specific functionality.

                 -                 - -

                Touch down / release outside Preview pop-up

                 -

                Dismisses Preview pop-up

                 -

                Tactile: No effect

                 -                 - -

                Touch down and hold

                 -

                Application-specific

                 -

                Tactile: Basic tactile feedback and audio feedback is provided with -touch down event.

                 -                 - - -
                - No tactile feedback is provided with preview pop-up. Applications need -to take care of tactile feedback for the interactive elements inside Preview -pop-up. -

                -

                Preview pop-up -in a touch interface

                Preview pop-up is a floating component used -for displaying more detailed data about an item that has the focus in the -main pane. It is not a touch-only component, and its basic functionality is -described above. Although it is not recommended to place buttons or other -items that appear touch-enabled into the preview pop-up, it is still possible -to give some items touch-only functions. It is up to each application to decide -whether to make use of this support in some sensible way. For example, a tap -on a www hyperlink displayed in the preview pop-up would open Browser and -open the Web site in question. However, it should be noted that using touch-enabled -items in the preview pop-up is an advanced, heavy-user feature.

                A tap -on an item in the preview pop-up can also open the stylus pop-up menu, when -there is no obvious direct function for that item. For more information, see Stylus pop-up menu.

                -
                Preview pop-up -for touch only

                The above section describes the general case for -touch and the preview pop-up. There is, however, a variance possibility for -the preview pop-up, which is to limit it strictly for touch. In this case, -the guideline for having no buttons or other obvious touch items in the preview -pop-up can be ignored for the most part: if the preview pop-up can only be -opened with a stylus, it is perfectly acceptable to make touch functions plainly -touch-enabled.

                -
                Using -preview pop-ups in C++ applications

                The API to use for creating -the preview pop-up component is the Information preview pop-up API.

                Preview pop-ups -can be used in two modes: in the default mode where the pop-up is hidden automatically -as a result of time-out or input event (either a key press or a pointer event), -or in permanent mode where the pop-up stays visible until it is dismissed -by the application code.

                For implementation information, see Using the Information Preview Pop-up API.

                + + + + + +Preview +pop-up +

                Preview pop-up is a floating component used for displaying more detailed +data about an item that has focus in the main pane.

                + +Preview pop-up + + +

                The preview is displayed with a 0.6 second delay after the focus is moved +(for example, scrolling down a list with the Arrow keys) to avoid too rapid +and continuous flicker. The default time-out for closing the preview pop-up +is the same as for the Information pop-up, but it is possible to adjust it +if necessary.

                +

                Preview pop-up contents cannot be scrolled and the component must not contain +any buttons or other elements that make it appear interactive: the component +is the same in both standard and touch-enabled devices and should the component +be used in a standard non-touch device, its elements should not look touch-enabled. +There can be a maximum of five text rows in a preview pop-up, and it is possible +to place a small icon in the start of the rows. It is even possible to have +more than one icon on a row instead of text, if necessary. The number of images +in a single preview pop-up is limited to one, and it can be accompanied by +up to two rows of text.

                +

                Preview pop-up shows always duplicate data in a given application to ensure +that the user will not miss any content or functionality even if a given product +does not utilize preview pop-up (that is, it has been switched OFF). Owing +to the special nature of preview pop-up, it is important to thoroughly consider +its genuine usefulness in various applications. Furthermore, the component +should not be confused with the Information pop-up note even though the data +displayed in these two components can at times be identical.

                +Default touch +events in Preview Pop-Up + + + +

                User action

                 +

                State change

                 +

                Feedback

                 +                 + + + +

                Touch down / release in Preview pop-up area

                 +

                Application-specific

                 +

                Tactile: Tactile feedback follows the component-specific functionality.

                 +                 + +

                Touch down / release outside Preview pop-up

                 +

                Application-specific

                 +

                Tactile: No effect

                 +                 + +

                Touch down and hold

                 +

                Application-specific

                 +

                Tactile: Basic tactile feedback and audio feedback is provided with +touch down event.

                 +                 + + +
                + No tactile feedback is provided with preview pop-up. Applications need +to take care of tactile feedback for the interactive elements inside Preview +pop-up. +

                +

                Preview pop-up +in a touch interface

                Preview pop-up is not a touch-only component, +and its basic functionality is described above. Although it is +not recommended to place buttons or other items that appear touch-enabled +into the preview pop-up, it is still possible to give some items touch-only +functions. It is up to each application to decide whether to make use of this +support in some sensible way. For example, a tap on a www hyperlink displayed +in the preview pop-up would open Browser and open the Web site in question. +However, it should be noted that using touch-enabled items in the preview +pop-up is an advanced, heavy-user feature.

                A tap on an item in the preview +pop-up can also open the stylus pop-up menu, when there is no obvious direct +function for that item. For more information, see Stylus +pop-up menu.

                +
                Preview pop-up +for touch only

                The above section describes the general case for +touch and the preview pop-up. There is, however, a variance possibility for +the preview pop-up, which is to limit it strictly for touch. In this case, +the guideline for having no buttons or other obvious touch items in the preview +pop-up can be ignored for the most part: if the preview pop-up can only be +opened with a stylus, it is perfectly acceptable to make touch functions plainly +touch-enabled.

                +
                Using +preview pop-ups in applications

                The API to use for creating the +preview pop-up component is the Information preview pop-up API.

                Preview pop-ups +can be used in two modes: in the default mode where the pop-up is hidden automatically +as a result of time-out or input event (either a key press or a pointer event), +or in permanent mode where the pop-up stays visible until it is dismissed +by the application code.

                For implementation information, see Using the Information Preview Pop-up API.

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E808AB2B-3A2D-5C91-9047-A74AAA770CE6_d0e117641_href.png Binary file Symbian3/SDK/Source/GUID-E808AB2B-3A2D-5C91-9047-A74AAA770CE6_d0e117641_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E808AB2B-3A2D-5C91-9047-A74AAA770CE6_d0e124179_href.png Binary file Symbian3/SDK/Source/GUID-E808AB2B-3A2D-5C91-9047-A74AAA770CE6_d0e124179_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E8266924-FA52-5171-BD73-423A46227A74.dita --- a/Symbian3/SDK/Source/GUID-E8266924-FA52-5171-BD73-423A46227A74.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-E8266924-FA52-5171-BD73-423A46227A74.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,201 +1,201 @@ - - - - - - Descriptor -Arrays -

                A descriptor array is a mechanism which allows descriptors to be aggregated -in a convenient way.

                -
                Introduction

                Descriptor arrays build on the behaviour -supplied by the Dynamic Arrays API and provides normal array operations for -inserting, appending, deleting, and accessing elements.

                There are -two types of descriptor array, based on the way data is represented by the -array:

                  -

                • an array whose elements -consist of non-modifiable pointer descriptors.

                  • -

                • an array whose elements -consist of memory pointers.

                  • -

                Either array can be used to represent descriptor data. The difference -between them is based on the way they are implemented, and this determines -which one is most suitable for a given situation.

                NOTE: All -array classes are provided in variants for narrow and wide characters (for -example, CDesC8Array and CDesC16Array). -These concrete types can be used directly, but it is usual to use typedefs -(for example, CDesCArray) that are conditionally defined -to map to the wide or narrow characters depending on the build. Only the conditional -types are used below.

                Descriptor arrays has three key concepts - descriptor -array protocol (MDesC16Array), general descriptor array (CDesC16Array) -and pointer descriptor array (CPtrC16Array).

                Descriptor -array protocol

                This array defines an interface implemented by -all descriptor array classes, and hence provides a degree of polymorphism. -It provides a count function, and can return a TPtrC for -an indexed element.

                The interface is defined by MDesCArray.

                General -descriptor array

                This array accepts elements of any descriptor -type. For each descriptor added, it creates a new heap descriptor (HBufC) -and copies the contents into it.

                The base class is CDesCArray. -Derived classes provide storage in flat arrays (CDesCArrayFlat) -and segmented arrays (CDesCArraySeg).

                Pointer -descriptor array

                This array holds only TPtrC descriptor -elements, that is, the descriptor type that points to data stored elsewhere. -The data pointed to by the TPtrC descriptors is not copied -or moved.

                The pointer descriptor array is CPtrCArray. -It implements MDesCArray, and can be used polymorphically -with general descriptor arrays.

                -
                Array of non-modifiable pointer descriptor elements

                The -array is supplied in two variants:

                  -

                • the 16-bit variant CPtrC16Array containing TPtrC16 types.

                  • -

                • the 8-bit variant CPtrC8Array containing TPtrC8 types.

                  • -

                The array is also supplied as a build independent type, CPtrCArray. -This is used whenever the descriptor elements are used to represent text strings. -By using the build independent type, the appropriate variant, either 16-bit -or 8-bit, is selected at build time depending on whether the _UNICODE macro -has been defined or not.

                Binary data always requires the 8-bit variant, -regardless of the build, and this should be explicitly used in program code.

                Explicit -use of the 16-bit variant is rare.

                The elements of this type of array -consist of non-modifiable pointer descriptors. These pointer descriptors represent -the data of the descriptors added to the array. The following diagram illustrates -this. The diagram is also true for TPtrC8 and TPtrC16.

                - Array of non-modifiable pointer descriptor elements - - -

                NOTE: delete() and reset() removes -the non-modifiable pointer descriptors from the array but does not delete -the data or descriptors that they point to.

                -
                Array of pointer elements

                The elements of this -type of array consist of pointers to heap descriptors.

                When -a descriptor is added to this type of array, a heap descriptor is allocated, -taking its data from the supplied descriptor. The pointer to this heap descriptor -is added as an array element. The following diagram illustrates this. The -diagram is also true for HBufC8 and HBufC16.

                - Array of pointer elements - -

                There are two implementations of the array, one using a flat buffer -and the other using a segmented buffer.

                The flat buffer implementation -is supplied in two variants:

                  -

                • the 16-bit variant implemented -using a flat buffer, a CDesC16ArrayFlat, constructed from TDesC16 types.

                  • -

                • the 8-bit variant implemented -using a flat buffer, a CDesC8ArrayFlat, constructed from TDesC8 types.

                  • -

                The segmented buffer implementation is supplied in two variants:

                  -

                • the 16-bit variant implemented -using a segmented buffer, a CDesC16ArraySeg, constructed -from TDesC16 types.

                  • -

                • the 8-bit variant implemented -using a segmented buffer, a CDesC8ArraySeg, constructed -from TDesC8 types.

                  • -

                Both array implementations are also supplied as build independent -types, CDesCArrayFlat and CDesCArraySeg. -These are used whenever the descriptors are used to represent text strings. -By using the build independent types, the appropriate variants, either 16-bit -or 8-bit, are selected at build time depending on whether the _UNICODE macro -has been defined or not.

                Binary data always requires the 8-bit variants, -regardless of the build, and this should be explicitly used in program code.

                Explicit -use of the 16-bit variants is rare.

                NOTE: delete() and reset() removes -the pointers from the array and also deletes the heap descriptors that they -point to.

                -
                Type of array to be used

                The advantages of using -one type over the other are subtle.

                When using an array of non-modifiable -pointer descriptors, the data represented by each TPtrC exists -independently of the TPtrC itself. The memory required -by the array is that required to contain the TPtrC elements. -The data represented by the TPtrC descriptors is not copied -or moved. On the other hand, that same data must be guaranteed to remain in -memory if the array is to have any purpose.

                When using an array of -pointers, a new heap descriptor is allocated for each descriptor to be added -to the array. This increases the total memory requirements of the array. On -the other hand, each array element is smaller because the size of a pointer -is slightly smaller than the size of a TPtrC object. The -original descriptor data can also be safely discarded once it has been added -to the array.

                This type also has the advantage that there is no commitment -to a concrete descriptor type.

                -
                Relationship between descriptor array classes

                The -following diagram illustrates the relationship between the descriptor array -concrete classes and the base classes which support them.

                - The class relationships for CDesCArrayFlat & CDesCArraySeg - - -

                - The class relationships for CPtrCArray - -
                -
                Copying Descriptor -Arrays

                An array of non-modifiable pointer descriptors, a CPtrCArray type, -provides a function which can copy elements from any descriptor array.

                The -source descriptor array must be one which satisfies the protocol defined by -the MDesCArray mixin class. Add the new TPtrC elements -to the CPtrCArray array to represent the source data.

                The -implementation of the copy does not and cannot depend on the type of the source -descriptor array,that is, whether it is a CPtrCArray type -or a CDesCArray type. However, the following diagram shows -the effect of the copy operation based on the concrete type of the source -array.

                - Copying descriptor arrays - -
                -
                8-Bit Variant, -16-Bit Variant and Build Independence

                Descriptor arrays are supplied -in two variants:

                  -

                • the 16-bit variant for -16-bit descriptors. These descriptors are used for handling Unicode strings -and double byte valued data.

                  • -

                • the 8-bit variant for -8-bit variant descriptors. These descriptors are used for handling non-Unicode -strings and single byte valued data. (binary data).

                  • -

                Descriptor arrays are also supplied as build independent types. These -are used for descriptors which are used to represent text strings.

                By -using build independent types, the appropriate variant, either 16-bit or 8-bit, -is selected at build time depending on whether the _UNICODE macro -has been defined or not.

                Binary data always requires the 8-bit variant -regardless of the build, and it must be explicitly used in program code. Explicit -use of the 16-bit variant is rare. With a few exceptions, the behaviour of -both 8-bit and 16-bit variants is the same.

                -
                The MDesCArray -mixin class

                The MDesCArray class is a mixin which -defines a protocol for:

                  -

                • returning the number -of elements in a descriptor array

                  • -

                • returning a non-modifiable -pointer descriptor, a TPtrC type representing a specific -indexed element.

                  • -

                The use of the mixin permits a degree of polymorphism amongst the -descriptor array classes. It permits the number of descriptor array elements -to be returned and a TPtrC type for a specific descriptor -array element to be returned without knowing the specific concrete descriptor -array type being accessed.

                MDesCArray -example

                The following code fragments illustrate how the MDesCArray mixin -class is used to return:

                  -

                • the number of descriptor -elements in a descriptor array.

                  • -

                • a TPtrC representing -a specific indexed descriptor element.

                  • -

                The code uses the build independent forms but the code is equally -valid while using the explicit 8-bit or 16-bit variants.

                In this case, CDesCArrayFlat, CDesCArraySeg and CPtrCArray can be handled by the single function foo().

                ... - CDesCArrayFlat* descflat = new( ELeave ) CDesCArrayFlat( 4 ); - CDesCArraySeg* descseg = new( ELeave ) CDesCArraySeg( 4 ); - CPtrCArray* ptrc = new( ELeave ) CPtrCArray( 4 ); - ... - ... // add descriptor elements to all three arrays - ... - foo( descflat ); - foo( descseg ); - foo( ptrc ); - ... void foo( MDesCArray* anArray ) - { - .. - TInt somenumber = anArray->MdcaCount(); - TPtrC someptrc = anArray->MdcaPoint( someindexvalue ); - .. - }
                -                 -Constructing -descriptor arrays -Using Dynamic -Arrays + + + + + + Descriptor +Arrays +

                A descriptor array is a mechanism which allows descriptors to be aggregated +in a convenient way.

                +
                Introduction

                Descriptor arrays build on the behaviour +supplied by the Dynamic Arrays API and provides normal array operations for +inserting, appending, deleting, and accessing elements.

                There are +two types of descriptor array, based on the way data is represented by the +array:

                  +

                • an array whose elements +consist of non-modifiable pointer descriptors.

                  • +

                • an array whose elements +consist of memory pointers.

                  • +

                Either array can be used to represent descriptor data. The difference +between them is based on the way they are implemented, and this determines +which one is most suitable for a given situation.

                NOTE: All +array classes are provided in variants for narrow and wide characters (for +example, CDesC8Array and CDesC16Array). +These concrete types can be used directly, but it is usual to use typedefs +(for example, CDesCArray) that are conditionally defined +to map to the wide or narrow characters depending on the build. Only the conditional +types are used below.

                Descriptor arrays has three key concepts - descriptor +array protocol (MDesC16Array), general descriptor array (CDesC16Array) +and pointer descriptor array (CPtrC16Array).

                Descriptor +array protocol

                This array defines an interface implemented by +all descriptor array classes, and hence provides a degree of polymorphism. +It provides a count function, and can return a TPtrC for +an indexed element.

                The interface is defined by MDesCArray.

                General +descriptor array

                This array accepts elements of any descriptor +type. For each descriptor added, it creates a new heap descriptor (HBufC) +and copies the contents into it.

                The base class is CDesCArray. +Derived classes provide storage in flat arrays (CDesCArrayFlat) +and segmented arrays (CDesCArraySeg).

                Pointer +descriptor array

                This array holds only TPtrC descriptor +elements, that is, the descriptor type that points to data stored elsewhere. +The data pointed to by the TPtrC descriptors is not copied +or moved.

                The pointer descriptor array is CPtrCArray. +It implements MDesCArray, and can be used polymorphically +with general descriptor arrays.

                +
                Array of non-modifiable pointer descriptor elements

                The +array is supplied in two variants:

                  +

                • the 16-bit variant CPtrC16Array containing TPtrC16 types.

                  • +

                • the 8-bit variant CPtrC8Array containing TPtrC8 types.

                  • +

                The array is also supplied as a build independent type, CPtrCArray. +This is used whenever the descriptor elements are used to represent text strings. +By using the build independent type, the appropriate variant, either 16-bit +or 8-bit, is selected at build time depending on whether the _UNICODE macro +has been defined or not.

                Binary data always requires the 8-bit variant, +regardless of the build, and this should be explicitly used in program code.

                Explicit +use of the 16-bit variant is rare.

                The elements of this type of array +consist of non-modifiable pointer descriptors. These pointer descriptors represent +the data of the descriptors added to the array. The following diagram illustrates +this. The diagram is also true for TPtrC8 and TPtrC16.

                + Array of non-modifiable pointer descriptor elements + + +

                NOTE: delete() and reset() removes +the non-modifiable pointer descriptors from the array but does not delete +the data or descriptors that they point to.

                +
                Array of pointer elements

                The elements of this +type of array consist of pointers to heap descriptors.

                When +a descriptor is added to this type of array, a heap descriptor is allocated, +taking its data from the supplied descriptor. The pointer to this heap descriptor +is added as an array element. The following diagram illustrates this. The +diagram is also true for HBufC8 and HBufC16.

                + Array of pointer elements + +

                There are two implementations of the array, one using a flat buffer +and the other using a segmented buffer.

                The flat buffer implementation +is supplied in two variants:

                  +

                • the 16-bit variant implemented +using a flat buffer, a CDesC16ArrayFlat, constructed from TDesC16 types.

                  • +

                • the 8-bit variant implemented +using a flat buffer, a CDesC8ArrayFlat, constructed from TDesC8 types.

                  • +

                The segmented buffer implementation is supplied in two variants:

                  +

                • the 16-bit variant implemented +using a segmented buffer, a CDesC16ArraySeg, constructed +from TDesC16 types.

                  • +

                • the 8-bit variant implemented +using a segmented buffer, a CDesC8ArraySeg, constructed +from TDesC8 types.

                  • +

                Both array implementations are also supplied as build independent +types, CDesCArrayFlat and CDesCArraySeg. +These are used whenever the descriptors are used to represent text strings. +By using the build independent types, the appropriate variants, either 16-bit +or 8-bit, are selected at build time depending on whether the _UNICODE macro +has been defined or not.

                Binary data always requires the 8-bit variants, +regardless of the build, and this should be explicitly used in program code.

                Explicit +use of the 16-bit variants is rare.

                NOTE: delete() and reset() removes +the pointers from the array and also deletes the heap descriptors that they +point to.

                +
                Type of array to be used

                The advantages of using +one type over the other are subtle.

                When using an array of non-modifiable +pointer descriptors, the data represented by each TPtrC exists +independently of the TPtrC itself. The memory required +by the array is that required to contain the TPtrC elements. +The data represented by the TPtrC descriptors is not copied +or moved. On the other hand, that same data must be guaranteed to remain in +memory if the array is to have any purpose.

                When using an array of +pointers, a new heap descriptor is allocated for each descriptor to be added +to the array. This increases the total memory requirements of the array. On +the other hand, each array element is smaller because the size of a pointer +is slightly smaller than the size of a TPtrC object. The +original descriptor data can also be safely discarded once it has been added +to the array.

                This type also has the advantage that there is no commitment +to a concrete descriptor type.

                +
                Relationship between descriptor array classes

                The +following diagram illustrates the relationship between the descriptor array +concrete classes and the base classes which support them.

                + The class relationships for CDesCArrayFlat & CDesCArraySeg + + +

                + The class relationships for CPtrCArray + +
                +
                Copying Descriptor +Arrays

                An array of non-modifiable pointer descriptors, a CPtrCArray type, +provides a function which can copy elements from any descriptor array.

                The +source descriptor array must be one which satisfies the protocol defined by +the MDesCArray mixin class. Add the new TPtrC elements +to the CPtrCArray array to represent the source data.

                The +implementation of the copy does not and cannot depend on the type of the source +descriptor array,that is, whether it is a CPtrCArray type +or a CDesCArray type. However, the following diagram shows +the effect of the copy operation based on the concrete type of the source +array.

                + Copying descriptor arrays + +
                +
                8-Bit Variant, +16-Bit Variant and Build Independence

                Descriptor arrays are supplied +in two variants:

                  +

                • the 16-bit variant for +16-bit descriptors. These descriptors are used for handling Unicode strings +and double byte valued data.

                  • +

                • the 8-bit variant for +8-bit variant descriptors. These descriptors are used for handling non-Unicode +strings and single byte valued data. (binary data).

                  • +

                Descriptor arrays are also supplied as build independent types. These +are used for descriptors which are used to represent text strings.

                By +using build independent types, the appropriate variant, either 16-bit or 8-bit, +is selected at build time depending on whether the _UNICODE macro +has been defined or not.

                Binary data always requires the 8-bit variant +regardless of the build, and it must be explicitly used in program code. Explicit +use of the 16-bit variant is rare. With a few exceptions, the behaviour of +both 8-bit and 16-bit variants is the same.

                +
                The MDesCArray +mixin class

                The MDesCArray class is a mixin which +defines a protocol for:

                  +

                • returning the number +of elements in a descriptor array

                  • +

                • returning a non-modifiable +pointer descriptor, a TPtrC type representing a specific +indexed element.

                  • +

                The use of the mixin permits a degree of polymorphism amongst the +descriptor array classes. It permits the number of descriptor array elements +to be returned and a TPtrC type for a specific descriptor +array element to be returned without knowing the specific concrete descriptor +array type being accessed.

                MDesCArray +example

                The following code fragments illustrate how the MDesCArray mixin +class is used to return:

                  +

                • the number of descriptor +elements in a descriptor array.

                  • +

                • a TPtrC representing +a specific indexed descriptor element.

                  • +

                The code uses the build independent forms but the code is equally +valid while using the explicit 8-bit or 16-bit variants.

                In this case, CDesCArrayFlat, CDesCArraySeg and CPtrCArray can be handled by the single function foo().

                ... + CDesCArrayFlat* descflat = new( ELeave ) CDesCArrayFlat( 4 ); + CDesCArraySeg* descseg = new( ELeave ) CDesCArraySeg( 4 ); + CPtrCArray* ptrc = new( ELeave ) CPtrCArray( 4 ); + ... + ... // add descriptor elements to all three arrays + ... + foo( descflat ); + foo( descseg ); + foo( ptrc ); + ... void foo( MDesCArray* anArray ) + { + .. + TInt somenumber = anArray->MdcaCount(); + TPtrC someptrc = anArray->MdcaPoint( someindexvalue ); + .. + }
                +                 +Constructing +descriptor arrays +Using Dynamic +Arrays                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E86347E8-8D3C-5FCB-BD9F-EA0DF8F0D9FD_d0e266235_href.png Binary file Symbian3/SDK/Source/GUID-E86347E8-8D3C-5FCB-BD9F-EA0DF8F0D9FD_d0e266235_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E86347E8-8D3C-5FCB-BD9F-EA0DF8F0D9FD_d0e269943_href.png Binary file Symbian3/SDK/Source/GUID-E86347E8-8D3C-5FCB-BD9F-EA0DF8F0D9FD_d0e269943_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E87018CD-01B4-5886-87FC-CD25EE90587D.dita --- a/Symbian3/SDK/Source/GUID-E87018CD-01B4-5886-87FC-CD25EE90587D.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-E87018CD-01B4-5886-87FC-CD25EE90587D.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,18 +1,18 @@ - - - - - -Central Repository Transactions

                This topic describes the concepts of Central Repository transactions.

                Overview of transactions

                In a typical use case, a repository is accessed by several different applications for different purposes such as reading, updating, caching and backing up. These applications are regarded as having a client-server relationship with the repository. When multiple applications can access a repository there is a danger of concurrent write operations corrupting the data. To prevent this, applications access repositories within sessions and perform operations on a repository within subdivisions of a session called transactions. The concept of a transaction is borrowed from database programming and is designed to ensure that only one application can modify a repository at any one time. Operations performed within a transaction are virtual, operating on a copy of the repository, until the transaction is successfully committed and the actual repository is modified. Transactions conform to a model which prevents them from being committed concurrently, so maintaining data integity.

                Only the following operations are permitted within a transaction:

                • Find()

                • Get()

                • Set()

                • Create()

                • Delete()

                • Move()

                Transactions are either synchronous or asynchronous. As the programmer you are responsible for avoiding errors such as beginning a transaction within a transaction which will cause a leave. You do this by conforming to a transaction model.

                The recommended transaction model is the optimistic non-serialised transaction model. It works on the principle that any number of clients may start a transaction at the same time, but as soon as one transaction is committed, any other transactions fail and must be started again.

                A session is in various states:

                • Not in transaction

                • Active

                • Failed

                An asynchronous transaction involves two other states:

                • Pending start

                • Pending commit

                Synchronous transactions

                A synchronous transaction has the following structure.

                • A session is initially in the state Not in transaction.

                • Call the synchronous form of StartTransaction() with the single parameter EConcurrentReadWriteTransaction.

                • The session changes state to Active.

                • Manipulate the repository with the functions Get() Set() Find() etc covered above.

                • The session continues in the Active state. The changes to the repository are cached but not actually applied during the Active state. You then either revoke or persist the changes.

                • To revoke the changes, call CancelTransaction()

                • The session returns to Not in transaction.

                • To persist the changes, call the synchronous form of CommitTransaction() with the parameter aKeyInfo of type TUint32 This function returns success or an error message and its parameter holds information about the transaction. On success, the parameter holds the number of settings which were changed. On failure, the parameter holds the settings which caused failure in the form of a key or partial key.

                • On success the session returns to Not in transaction. On failure it enters the Failed state. When a transaction fails, the operations already performed are discarded and no subsequent operations can reverse the failure.

                • If the reason for failure was the success of another transaction, the error message is KErrLocked and the session is Not in transaction. You try the same sequence of function calls until you get a successful commit.

                  If there was some other reason for failure you must close the transaction yourself. To do this, either call CancelTransaction() or else call CommitTransaction() a second time.

                  There is sometimes reason to fail the transaction deliberately by calling FailTransaction() For instance you might want to generate failure after an unsuccessful Get() operation and then cancel the transaction.

                - Synchronous transaction state diagram -
                Asynchronous transactions

                Synchronous transactions have the disadvantage that a busy server may block the client thread before any action takes place. To avoid this problem you can use the slightly more complicated asynchronous transactions. An asynchronous transaction has the same structure as a synchronous one except that there are two new states Pending Start and Pending Commit where a transaction waits until the server is ready to communicate with it. The transition from Not in transaction to Active now proceeds like this.

                • A session is initially in the state Not in transaction.

                • Call the asynchronous form of StartTransaction() with the parameters EConcurrentReadWriteTransaction and aStatus of type TRequestStatus This function returns void: success or the reasons for failure are determined from the state of aStatus after execution.

                • The session changes state to Pending Start. Activity on the server will eventually promote the session to Active.

                • Manipulate the repository with the functions Get(), Set(), Find() etc covered above.

                • The session continues in the Active state. The changes to the repository are cached but not actually applied during the Active state. You then either revoke or persist the changes.

                • To revoke the changes, call CancelTransaction() This call has different effects depending on whether it was called in the Pending Start state or the Active state. If it was called in the Pending Start state it sets aStatus to KErrCancel

                • The session returns to Not in transaction.

                • To persist the changes, call the asynchronous form of CommitTransaction() with the parameters aKeyInfo of type TUint32 and aStatus of type TRequestStatus This function returns void. Its first parameter holds information about the transaction.

                • On success, the aStatus parameter holds the number of settings which were changed. On failure, the parameter holds the settings which caused failure in the form of a key or partial key. The aStatus parameter is set to success or failure.

                • If the reason for failure was the success of another transaction, aStatus is set to KErrLocked and the session is Not in transaction. You try the same sequence of function calls until you get a successful commit.

                  If there was some other reason for failure you must close the transaction yourself. To do this, either call CancelTransaction() or else call CommitTransaction() a second time.

                  There is sometimes reason to fail the transaction deliberately by calling FailTransaction() For instance you might want to generate failure after an unsuccessful Get() operation and then cancel the transaction.

                - Asynchronous Transaction State Diagram -
                Cleanup

                There is a danger that a transaction might remain open for ever if it is opened by code which subsequently leaves. To avoid this possibility, the CCentralRepository class has two functions which cause the cleanup stack to end the transaction in the event of a leave. CleanupCancelTransactionPushL(), also named CleanupRollbackTransactionPushL(), causes a leave to be followed by a call to CancelTransaction(). CleanupFailTransactionPushL() causes a leave to be followed by a call to FailTransaction().

                Central Repository Guide Optimising Repository - Access Modifications to + + + + + +Central Repository Transactions

                This topic describes the concepts of Central Repository transactions.

                Overview of transactions

                In a typical use case, a repository is accessed by several different applications for different purposes such as reading, updating, caching and backing up. These applications are regarded as having a client-server relationship with the repository. When multiple applications can access a repository there is a danger of concurrent write operations corrupting the data. To prevent this, applications access repositories within sessions and perform operations on a repository within subdivisions of a session called transactions. The concept of a transaction is borrowed from database programming and is designed to ensure that only one application can modify a repository at any one time. Operations performed within a transaction are virtual, operating on a copy of the repository, until the transaction is successfully committed and the actual repository is modified. Transactions conform to a model which prevents them from being committed concurrently, so maintaining data integity.

                Only the following operations are permitted within a transaction:

                • Find()

                • Get()

                • Set()

                • Create()

                • Delete()

                • Move()

                Transactions are either synchronous or asynchronous. As the programmer you are responsible for avoiding errors such as beginning a transaction within a transaction which will cause a leave. You do this by conforming to a transaction model.

                The recommended transaction model is the optimistic non-serialised transaction model. It works on the principle that any number of clients may start a transaction at the same time, but as soon as one transaction is committed, any other transactions fail and must be started again.

                A session is in various states:

                • Not in transaction

                • Active

                • Failed

                An asynchronous transaction involves two other states:

                • Pending start

                • Pending commit

                Synchronous transactions

                A synchronous transaction has the following structure.

                • A session is initially in the state Not in transaction.

                • Call the synchronous form of StartTransaction() with the single parameter EConcurrentReadWriteTransaction.

                • The session changes state to Active.

                • Manipulate the repository with the functions Get() Set() Find() etc covered above.

                • The session continues in the Active state. The changes to the repository are cached but not actually applied during the Active state. You then either revoke or persist the changes.

                • To revoke the changes, call CancelTransaction()

                • The session returns to Not in transaction.

                • To persist the changes, call the synchronous form of CommitTransaction() with the parameter aKeyInfo of type TUint32 This function returns success or an error message and its parameter holds information about the transaction. On success, the parameter holds the number of settings which were changed. On failure, the parameter holds the settings which caused failure in the form of a key or partial key.

                • On success the session returns to Not in transaction. On failure it enters the Failed state. When a transaction fails, the operations already performed are discarded and no subsequent operations can reverse the failure.

                • If the reason for failure was the success of another transaction, the error message is KErrLocked and the session is Not in transaction. You try the same sequence of function calls until you get a successful commit.

                  If there was some other reason for failure you must close the transaction yourself. To do this, either call CancelTransaction() or else call CommitTransaction() a second time.

                  There is sometimes reason to fail the transaction deliberately by calling FailTransaction() For instance you might want to generate failure after an unsuccessful Get() operation and then cancel the transaction.

                + Synchronous transaction state diagram +
                Asynchronous transactions

                Synchronous transactions have the disadvantage that a busy server may block the client thread before any action takes place. To avoid this problem you can use the slightly more complicated asynchronous transactions. An asynchronous transaction has the same structure as a synchronous one except that there are two new states Pending Start and Pending Commit where a transaction waits until the server is ready to communicate with it. The transition from Not in transaction to Active now proceeds like this.

                • A session is initially in the state Not in transaction.

                • Call the asynchronous form of StartTransaction() with the parameters EConcurrentReadWriteTransaction and aStatus of type TRequestStatus This function returns void: success or the reasons for failure are determined from the state of aStatus after execution.

                • The session changes state to Pending Start. Activity on the server will eventually promote the session to Active.

                • Manipulate the repository with the functions Get(), Set(), Find() etc covered above.

                • The session continues in the Active state. The changes to the repository are cached but not actually applied during the Active state. You then either revoke or persist the changes.

                • To revoke the changes, call CancelTransaction() This call has different effects depending on whether it was called in the Pending Start state or the Active state. If it was called in the Pending Start state it sets aStatus to KErrCancel

                • The session returns to Not in transaction.

                • To persist the changes, call the asynchronous form of CommitTransaction() with the parameters aKeyInfo of type TUint32 and aStatus of type TRequestStatus This function returns void. Its first parameter holds information about the transaction.

                • On success, the aStatus parameter holds the number of settings which were changed. On failure, the parameter holds the settings which caused failure in the form of a key or partial key. The aStatus parameter is set to success or failure.

                • If the reason for failure was the success of another transaction, aStatus is set to KErrLocked and the session is Not in transaction. You try the same sequence of function calls until you get a successful commit.

                  If there was some other reason for failure you must close the transaction yourself. To do this, either call CancelTransaction() or else call CommitTransaction() a second time.

                  There is sometimes reason to fail the transaction deliberately by calling FailTransaction() For instance you might want to generate failure after an unsuccessful Get() operation and then cancel the transaction.

                + Asynchronous Transaction State Diagram +
                Cleanup

                There is a danger that a transaction might remain open for ever if it is opened by code which subsequently leaves. To avoid this possibility, the CCentralRepository class has two functions which cause the cleanup stack to end the transaction in the event of a leave. CleanupCancelTransactionPushL(), also named CleanupRollbackTransactionPushL(), causes a leave to be followed by a call to CancelTransaction(). CleanupFailTransactionPushL() causes a leave to be followed by a call to FailTransaction().

                Central Repository Guide Optimising Repository + Access Modifications to Keyspaces                 \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E88E64C6-5A80-59EE-8227-455EC033E6E9.dita --- a/Symbian3/SDK/Source/GUID-E88E64C6-5A80-59EE-8227-455EC033E6E9.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-E88E64C6-5A80-59EE-8227-455EC033E6E9.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,12 +1,12 @@ - - - - - -What are sessions with the Comms DatabaseThis topic describes the use of sessions to access the Comms Database.

                Tools and applications create and use a session to access the Comms Database. A session is an instance of the class CMDBSession. An instance of CMDBSession acts as a handle to the database. The functions provided by MMetaDatabase to access the Comms Database require an instance of CMDBSession.

                You must create a session before you get data from the Comms Database and before you update the Comms Database. To create a session, you create an instance of the CMDBSession class.

                You delete the session after you finish your use of the Comms Database. To delete a session, you delete the instance of the CMDBSession class.

                \ No newline at end of file + + + + + +What are sessions with the Comms DatabaseThis topic describes the use of sessions to access the Comms Database.

                Tools and applications create and use a session to access the Comms Database. A session is an instance of the class CMDBSession. An instance of CMDBSession acts as a handle to the database. The functions provided by MMetaDatabase to access the Comms Database require an instance of CMDBSession.

                You must create a session before you get data from the Comms Database and before you update the Comms Database. To create a session, you create an instance of the CMDBSession class.

                You delete the session after you finish your use of the Comms Database. To delete a session, you delete the instance of the CMDBSession class.

                \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E8B0BDC7-714E-48EF-89F3-D8B7B34552ED.dita --- a/Symbian3/SDK/Source/GUID-E8B0BDC7-714E-48EF-89F3-D8B7B34552ED.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,13 +0,0 @@ - - - - - -InteractionThis section explains the guidelines for rotation and basic interaction -style in Symbian devices. \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E8EF06D7-FB4E-598D-9D9D-4395AB6F51C8.dita --- a/Symbian3/SDK/Source/GUID-E8EF06D7-FB4E-598D-9D9D-4395AB6F51C8.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-E8EF06D7-FB4E-598D-9D9D-4395AB6F51C8.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,265 +1,265 @@ - - - - - -Creating a Charconv Plug-in DLL

                This section describes how to create a Charconv plug-in DLL.

                Introduction

                The flowchart below shows the steps to create a Charconv plug-in DLL.

                Procedure

                An example is used to explain the procedure for creating a Charconv plug-in DLL. This plug-in converts between the cp850 character set and Unicode.

                1. Create a cnvtool source file using a text editor and save it as, for example d:\charconvfiles\data\cp850.txt. This file contains pairs of hexadecimal numbers. The first number in each pair is the encoding of a character in cp850and the second is the Unicode encoding of the same character.

                  ... -0x00 0x0000 #NULL -0x01 0x0001 #START OF HEADING -0x02 0x0002 #START OF TEXT -0x03 0x0003 #END OF TEXT -0x04 0x0004 #END OF TRANSMISSION -0x05 0x0005 #ENQUIRY -0x06 0x0006 #ACKNOWLEDGE -...

                  For more information about the syntax of a cnvtool source file, refer to Cnvtool Source File.

                2. Create a cnvtool control file using a text editor and save it as, for example d:\charconvfiles\data\cp850.ctl. This file specifies the conversion algorithms to convert both ways between ranges of characters, and other information.

                  Endianness FixedBigEndian -ReplacementForUnconvertibleUnicodeCharacters 0x1a # ASCII "substitute" character - must be a single character, and must be little-endian if the "Endianness" above is "Unspecified", otherwise in the same endianness as specified - -StartForeignVariableByteData -# FirstInitialByteValueInRange LastInitialByteValueInRange NumberOfSubsequentBytes - 0x00 0xff 0 -EndForeignVariableByteData - -StartForeignToUnicodeData -# IncludePriority SearchPriority FirstInputCharacterCodeInRange LastInputCharacterCodeInRange Algorithm Parameters - 2 2 0x00 0x7f Direct {} # ASCII - 1 1 0x80 0xff KeyedTable16OfIndexedTables16 {} # CP850 -EndForeignToUnicodeData - -StartUnicodeToForeignData -# IncludePriority SearchPriority FirstInputCharacterCodeInRange LastInputCharacterCodeInRange Algorithm SizeOfOutputCharacterCodeInBytes Parameters - 2 2 0x0000 0x007f Direct 1 {} # ASCII - 1 1 0x00A0 0x25A0 KeyedTable1616 1 {} # CP850 -EndUnicodeToForeignData -

                  For more information about the syntax of a cnvtool control file, refer to Cnvtool Control File.

                3. Start a command prompt to run cnvtool on the source and control files as follows:

                  cd d:\Symbian\epoc32\tools

                  cnvtool.bat -generateSourceCode d:\charconvfiles\data\cp850.txt d:\charconvfiles\data\cp850.ctl d:\charconvfiles\data\g_cp850.cpp

                  This process generates a C++ source code file called g_cp850.cpp. It is referred to as the cnvtool -generated cpp file. It contains the SCnvConversionData data structure.

                  -#include <e32std.h> -#include <CONVDATA.H> -#include <CONVGENERATEDCPP.H> - -#define ARRAY_LENGTH(aArray) (sizeof(aArray)/sizeof((aArray)[0])) - - -_LIT8(KLit8ReplacementForUnconvertibleUnicodeCharacters, "\x1a"); - -GLDEF_C const TDesC8& ReplacementForUnconvertibleUnicodeCharacters_internal() - { - return KLit8ReplacementForUnconvertibleUnicodeCharacters; - } - -LOCAL_D const TUint16 keyedTables16OfIndexedTables16_indexedEntries_foreignToUnicode_1[]= - { - 0x00c7, - 0x00fc, -... - } - - -LOCAL_D const SCnvConversionData::SOneDirectionData::SRange::UData::SKeyedTable16OfIndexedTables16::SKeyedEntry keyedTables16OfIndexedTables16_keyedEntries_foreignToUnicode_1[]= - { - { - 0x80, - 0xff, - keyedTables16OfIndexedTables16_indexedEntries_foreignToUnicode_1 - } - }; - -LOCAL_D const SCnvConversionData::SOneDirectionData::SRange::UData::SKeyedTable1616::SEntry keyedTable1616_unicodeToForeign_1[]= - { - { - 0x00a0, - 0xff - }, -... - } -LOCAL_D const SCnvConversionData::SVariableByteData::SRange foreignVariableByteDataRanges[]= - { - { - 0x00, - 0xff, - 0, - 0 - } - }; - -.... - -GLDEF_D const SCnvConversionData conversionData= - { - SCnvConversionData::EFixedBigEndian, - { - ARRAY_LENGTH(foreignVariableByteDataRanges), - foreignVariableByteDataRanges - }, - { - ARRAY_LENGTH(foreignToUnicodeDataRanges), - foreignToUnicodeDataRanges - }, - { - ARRAY_LENGTH(unicodeToForeignDataRanges), - unicodeToForeignDataRanges - }, - NULL, - NULL - }; - -

                  For more information about the command syntax of cnvtool, refer to Cnvtool Command Syntax.

                4. Create a cpp file which implements the CCharacterSetConverterPluginInterface class.

                  All of the functions defined in the interface must be implemented by the plug-in DLL. The implementations of ConvertFromUnicode() and ConvertToUnicode() must fulfil the following behavioural requirements:

                  • They must return a negative error code (see CCnvCharacterSetConverter::TError), or the number of elements remaining in the input descriptor which have not been converted.

                  • They must not return an error when the output descriptor is too short or there is a truncated sequence at the end of the input descriptor.

                    • If the output descriptor is full, the input descriptor cannot be fully converted.

                    • If the input descriptor ends with a truncated sequence, such as the first half of a Unicode surrogate pair, the first byte of a multi-byte foreign character set character code, or a truncated escape sequence of a modal foreign character set, it cannot be fully converted.

                  • If the input descriptor consists purely of a truncated sequence they must return CCnvCharacterSetConverter::EErrorIllFormedInput.

                  For non-complex character sets, they can call CCnvCharacterSetConverter::DoConvertFromUnicode() and CCnvCharacterSetConverter::DoConvertToUnicode() functions respectively.

                  For complex character sets, for example JIS or Shift-JIS, the CnvUtilities class provides some utility functions.

                  To access the two (const) global objects implemented in the cnvtool-generated cpp file, you must include the convgeneratedcpp.h header file. The SCnvConversionData object generated can then be used to implement the ConvertFromUnicode() and ConvertToUnicode() functions.

                  Example implementation

                  #include <e32std.h> -#include <charconv.h> -#include <convgeneratedcpp.h> -#include <ecom/implementationproxy.h> -#include <charactersetconverter.h> - -class CCP850ConverterImpl : public CCharacterSetConverterPluginInterface - { - -public: - virtual const TDesC8& ReplacementForUnconvertibleUnicodeCharacters(); - - virtual TInt ConvertFromUnicode( - CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters, - const TDesC8& aReplacementForUnconvertibleUnicodeCharacters, - TDes8& aForeign, - const TDesC16& aUnicode, - CCnvCharacterSetConverter::TArrayOfAscendingIndices& aIndicesOfUnconvertibleCharacters); - - virtual TInt ConvertToUnicode( - CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters, - TDes16& aUnicode, - const TDesC8& aForeign, - TInt& aState, - TInt& aNumberOfUnconvertibleCharacters, - TInt& aIndexOfFirstByteOfFirstUnconvertibleCharacter); - - virtual TBool IsInThisCharacterSetL( - TBool& aSetToTrue, - TInt& aConfidenceLevel, - const TDesC8& aSample); - - static CCP850ConverterImpl* NewL(); - virtual ~CCP850ConverterImpl(); - -private: - CCP850ConverterImpl(); - - }; - - -const TDesC8& CCP850ConverterImpl::ReplacementForUnconvertibleUnicodeCharacters() - { - return ReplacementForUnconvertibleUnicodeCharacters_internal(); - } - -TInt CCP850ConverterImpl::ConvertFromUnicode( - CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters, - const TDesC8& aReplacementForUnconvertibleUnicodeCharacters, - TDes8& aForeign, - const TDesC16& aUnicode, - CCnvCharacterSetConverter::TArrayOfAscendingIndices& aIndicesOfUnconvertibleCharacters) - { - return CCnvCharacterSetConverter::DoConvertFromUnicode(conversionData, aDefaultEndiannessOfForeignCharacters, aReplacementForUnconvertibleUnicodeCharacters, aForeign, aUnicode, aIndicesOfUnconvertibleCharacters); - } - -TInt CCP850ConverterImpl::ConvertToUnicode( - CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters, - TDes16& aUnicode, - const TDesC8& aForeign, - TInt& /*aState*/, - TInt& aNumberOfUnconvertibleCharacters, - TInt& aIndexOfFirstByteOfFirstUnconvertibleCharacter) - { - return CCnvCharacterSetConverter::DoConvertToUnicode(conversionData, aDefaultEndiannessOfForeignCharacters, aUnicode, aForeign, aNumberOfUnconvertibleCharacters, aIndexOfFirstByteOfFirstUnconvertibleCharacter); - } - -TBool CCP850ConverterImpl::IsInThisCharacterSetL( - TBool& aSetToTrue, - TInt& aConfidenceLevel, - const TDesC8& /*aSample*/) - { - aSetToTrue=ETrue; - aConfidenceLevel=0; - return EFalse; - } - -CCP850ConverterImpl* CCP850ConverterImpl::NewL() - { - CCP850ConverterImpl* self = new(ELeave) CCP850ConverterImpl(); - return self; - } - -CCP850ConverterImpl::~CCP850ConverterImpl() - { - } - -CCP850ConverterImpl::CCP850ConverterImpl() - { - } - -const TImplementationProxy ImplementationTable[] = - { - IMPLEMENTATION_PROXY_ENTRY(0x102825AD, CCP850ConverterImpl::NewL) - }; - -EXPORT_C const TImplementationProxy* ImplementationGroupProxy(TInt& aTableCount) - { - aTableCount = sizeof(ImplementationTable) / sizeof(TImplementationProxy); - - return ImplementationTable; - } -

                5. Create an ECom registry resource file using a text editor.

                  102825ac.rss

                  #include "ecom/registryinfo.rh" - -RESOURCE REGISTRY_INFO theInfo - { - dll_uid = 0x102825AC; // UID acquired from Symbian - interfaces = - { - INTERFACE_INFO - { - interface_uid = 0x101F7F1D; // fixed UID for Charconv plug-ins - implementations = - { - IMPLEMENTATION_INFO - { - implementation_uid = 0x102825AD; // UID acquired from Symbian - version_no = 1; - display_name = "CP850"; - default_data = "CP850"; - opaque_data = ""; - } - }; - } - }; - } -

                6. Create an mmp file which is used to build the plug-in DLL.

                  TARGET cp850.dll -TARGETTYPE PLUGIN - -CAPABILITY All -Tcb - -UID 0x10009D8D 0x102825AC -VENDORID 0x70000001 - -SYSTEMINCLUDE /epoc32/include - -SOURCEPATH ../src/plugins -SOURCE cp850.cpp - -SOURCEPATH /epoc32/build/generatedcpp/charconv -SOURCE g_cp850.cpp - -SOURCEPATH ../resource -START RESOURCE cp850.rss -TARGETPATH /resource/charconv -LANG sc -END - -START RESOURCE 102825ac.rss -TARGET cp850.rsc -END - -LIBRARY euser.lib -LIBRARY charconv.lib -LIBRARY ecom.lib + + + + + +Creating a Charconv Plug-in DLL

                  This section describes how to create a Charconv plug-in DLL.

                  Introduction

                  The flowchart below shows the steps to create a Charconv plug-in DLL.

                  Procedure

                  An example is used to explain the procedure for creating a Charconv plug-in DLL. This plug-in converts between the cp850 character set and Unicode.

                  1. Create a cnvtool source file using a text editor and save it as, for example d:\charconvfiles\data\cp850.txt. This file contains pairs of hexadecimal numbers. The first number in each pair is the encoding of a character in cp850and the second is the Unicode encoding of the same character.

                    ... +0x00 0x0000 #NULL +0x01 0x0001 #START OF HEADING +0x02 0x0002 #START OF TEXT +0x03 0x0003 #END OF TEXT +0x04 0x0004 #END OF TRANSMISSION +0x05 0x0005 #ENQUIRY +0x06 0x0006 #ACKNOWLEDGE +...

                    For more information about the syntax of a cnvtool source file, refer to Cnvtool Source File.

                  2. Create a cnvtool control file using a text editor and save it as, for example d:\charconvfiles\data\cp850.ctl. This file specifies the conversion algorithms to convert both ways between ranges of characters, and other information.

                    Endianness FixedBigEndian +ReplacementForUnconvertibleUnicodeCharacters 0x1a # ASCII "substitute" character - must be a single character, and must be little-endian if the "Endianness" above is "Unspecified", otherwise in the same endianness as specified + +StartForeignVariableByteData +# FirstInitialByteValueInRange LastInitialByteValueInRange NumberOfSubsequentBytes + 0x00 0xff 0 +EndForeignVariableByteData + +StartForeignToUnicodeData +# IncludePriority SearchPriority FirstInputCharacterCodeInRange LastInputCharacterCodeInRange Algorithm Parameters + 2 2 0x00 0x7f Direct {} # ASCII + 1 1 0x80 0xff KeyedTable16OfIndexedTables16 {} # CP850 +EndForeignToUnicodeData + +StartUnicodeToForeignData +# IncludePriority SearchPriority FirstInputCharacterCodeInRange LastInputCharacterCodeInRange Algorithm SizeOfOutputCharacterCodeInBytes Parameters + 2 2 0x0000 0x007f Direct 1 {} # ASCII + 1 1 0x00A0 0x25A0 KeyedTable1616 1 {} # CP850 +EndUnicodeToForeignData +

                    For more information about the syntax of a cnvtool control file, refer to Cnvtool Control File.

                  3. Start a command prompt to run cnvtool on the source and control files as follows:

                    cd d:\Symbian\epoc32\tools

                    cnvtool.bat -generateSourceCode d:\charconvfiles\data\cp850.txt d:\charconvfiles\data\cp850.ctl d:\charconvfiles\data\g_cp850.cpp

                    This process generates a C++ source code file called g_cp850.cpp. It is referred to as the cnvtool -generated cpp file. It contains the SCnvConversionData data structure.

                    +#include <e32std.h> +#include <CONVDATA.H> +#include <CONVGENERATEDCPP.H> + +#define ARRAY_LENGTH(aArray) (sizeof(aArray)/sizeof((aArray)[0])) + + +_LIT8(KLit8ReplacementForUnconvertibleUnicodeCharacters, "\x1a"); + +GLDEF_C const TDesC8& ReplacementForUnconvertibleUnicodeCharacters_internal() + { + return KLit8ReplacementForUnconvertibleUnicodeCharacters; + } + +LOCAL_D const TUint16 keyedTables16OfIndexedTables16_indexedEntries_foreignToUnicode_1[]= + { + 0x00c7, + 0x00fc, +... + } + + +LOCAL_D const SCnvConversionData::SOneDirectionData::SRange::UData::SKeyedTable16OfIndexedTables16::SKeyedEntry keyedTables16OfIndexedTables16_keyedEntries_foreignToUnicode_1[]= + { + { + 0x80, + 0xff, + keyedTables16OfIndexedTables16_indexedEntries_foreignToUnicode_1 + } + }; + +LOCAL_D const SCnvConversionData::SOneDirectionData::SRange::UData::SKeyedTable1616::SEntry keyedTable1616_unicodeToForeign_1[]= + { + { + 0x00a0, + 0xff + }, +... + } +LOCAL_D const SCnvConversionData::SVariableByteData::SRange foreignVariableByteDataRanges[]= + { + { + 0x00, + 0xff, + 0, + 0 + } + }; + +.... + +GLDEF_D const SCnvConversionData conversionData= + { + SCnvConversionData::EFixedBigEndian, + { + ARRAY_LENGTH(foreignVariableByteDataRanges), + foreignVariableByteDataRanges + }, + { + ARRAY_LENGTH(foreignToUnicodeDataRanges), + foreignToUnicodeDataRanges + }, + { + ARRAY_LENGTH(unicodeToForeignDataRanges), + unicodeToForeignDataRanges + }, + NULL, + NULL + }; + +

                    For more information about the command syntax of cnvtool, refer to Cnvtool Command Syntax.

                  4. Create a cpp file which implements the CCharacterSetConverterPluginInterface class.

                    All of the functions defined in the interface must be implemented by the plug-in DLL. The implementations of ConvertFromUnicode() and ConvertToUnicode() must fulfil the following behavioural requirements:

                    • They must return a negative error code (see CCnvCharacterSetConverter::TError), or the number of elements remaining in the input descriptor which have not been converted.

                    • They must not return an error when the output descriptor is too short or there is a truncated sequence at the end of the input descriptor.

                      • If the output descriptor is full, the input descriptor cannot be fully converted.

                      • If the input descriptor ends with a truncated sequence, such as the first half of a Unicode surrogate pair, the first byte of a multi-byte foreign character set character code, or a truncated escape sequence of a modal foreign character set, it cannot be fully converted.

                    • If the input descriptor consists purely of a truncated sequence they must return CCnvCharacterSetConverter::EErrorIllFormedInput.

                    For non-complex character sets, they can call CCnvCharacterSetConverter::DoConvertFromUnicode() and CCnvCharacterSetConverter::DoConvertToUnicode() functions respectively.

                    For complex character sets, for example JIS or Shift-JIS, the CnvUtilities class provides some utility functions.

                    To access the two (const) global objects implemented in the cnvtool-generated cpp file, you must include the convgeneratedcpp.h header file. The SCnvConversionData object generated can then be used to implement the ConvertFromUnicode() and ConvertToUnicode() functions.

                    Example implementation

                    #include <e32std.h> +#include <charconv.h> +#include <convgeneratedcpp.h> +#include <ecom/implementationproxy.h> +#include <charactersetconverter.h> + +class CCP850ConverterImpl : public CCharacterSetConverterPluginInterface + { + +public: + virtual const TDesC8& ReplacementForUnconvertibleUnicodeCharacters(); + + virtual TInt ConvertFromUnicode( + CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters, + const TDesC8& aReplacementForUnconvertibleUnicodeCharacters, + TDes8& aForeign, + const TDesC16& aUnicode, + CCnvCharacterSetConverter::TArrayOfAscendingIndices& aIndicesOfUnconvertibleCharacters); + + virtual TInt ConvertToUnicode( + CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters, + TDes16& aUnicode, + const TDesC8& aForeign, + TInt& aState, + TInt& aNumberOfUnconvertibleCharacters, + TInt& aIndexOfFirstByteOfFirstUnconvertibleCharacter); + + virtual TBool IsInThisCharacterSetL( + TBool& aSetToTrue, + TInt& aConfidenceLevel, + const TDesC8& aSample); + + static CCP850ConverterImpl* NewL(); + virtual ~CCP850ConverterImpl(); + +private: + CCP850ConverterImpl(); + + }; + + +const TDesC8& CCP850ConverterImpl::ReplacementForUnconvertibleUnicodeCharacters() + { + return ReplacementForUnconvertibleUnicodeCharacters_internal(); + } + +TInt CCP850ConverterImpl::ConvertFromUnicode( + CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters, + const TDesC8& aReplacementForUnconvertibleUnicodeCharacters, + TDes8& aForeign, + const TDesC16& aUnicode, + CCnvCharacterSetConverter::TArrayOfAscendingIndices& aIndicesOfUnconvertibleCharacters) + { + return CCnvCharacterSetConverter::DoConvertFromUnicode(conversionData, aDefaultEndiannessOfForeignCharacters, aReplacementForUnconvertibleUnicodeCharacters, aForeign, aUnicode, aIndicesOfUnconvertibleCharacters); + } + +TInt CCP850ConverterImpl::ConvertToUnicode( + CCnvCharacterSetConverter::TEndianness aDefaultEndiannessOfForeignCharacters, + TDes16& aUnicode, + const TDesC8& aForeign, + TInt& /*aState*/, + TInt& aNumberOfUnconvertibleCharacters, + TInt& aIndexOfFirstByteOfFirstUnconvertibleCharacter) + { + return CCnvCharacterSetConverter::DoConvertToUnicode(conversionData, aDefaultEndiannessOfForeignCharacters, aUnicode, aForeign, aNumberOfUnconvertibleCharacters, aIndexOfFirstByteOfFirstUnconvertibleCharacter); + } + +TBool CCP850ConverterImpl::IsInThisCharacterSetL( + TBool& aSetToTrue, + TInt& aConfidenceLevel, + const TDesC8& /*aSample*/) + { + aSetToTrue=ETrue; + aConfidenceLevel=0; + return EFalse; + } + +CCP850ConverterImpl* CCP850ConverterImpl::NewL() + { + CCP850ConverterImpl* self = new(ELeave) CCP850ConverterImpl(); + return self; + } + +CCP850ConverterImpl::~CCP850ConverterImpl() + { + } + +CCP850ConverterImpl::CCP850ConverterImpl() + { + } + +const TImplementationProxy ImplementationTable[] = + { + IMPLEMENTATION_PROXY_ENTRY(0x102825AD, CCP850ConverterImpl::NewL) + }; + +EXPORT_C const TImplementationProxy* ImplementationGroupProxy(TInt& aTableCount) + { + aTableCount = sizeof(ImplementationTable) / sizeof(TImplementationProxy); + + return ImplementationTable; + } +

                  5. Create an ECom registry resource file using a text editor.

                    102825ac.rss

                    #include "ecom/registryinfo.rh" + +RESOURCE REGISTRY_INFO theInfo + { + dll_uid = 0x102825AC; // UID acquired from Symbian + interfaces = + { + INTERFACE_INFO + { + interface_uid = 0x101F7F1D; // fixed UID for Charconv plug-ins + implementations = + { + IMPLEMENTATION_INFO + { + implementation_uid = 0x102825AD; // UID acquired from Symbian + version_no = 1; + display_name = "CP850"; + default_data = "CP850"; + opaque_data = ""; + } + }; + } + }; + } +

                  6. Create an mmp file which is used to build the plug-in DLL.

                    TARGET cp850.dll +TARGETTYPE PLUGIN + +CAPABILITY All -Tcb + +UID 0x10009D8D 0x102825AC +VENDORID 0x70000001 + +SYSTEMINCLUDE /epoc32/include + +SOURCEPATH ../src/plugins +SOURCE cp850.cpp + +SOURCEPATH /epoc32/build/generatedcpp/charconv +SOURCE g_cp850.cpp + +SOURCEPATH ../resource +START RESOURCE cp850.rss +TARGETPATH /resource/charconv +LANG sc +END + +START RESOURCE 102825ac.rss +TARGET cp850.rsc +END + +LIBRARY euser.lib +LIBRARY charconv.lib +LIBRARY ecom.lib

                  Build the plug-in DLL and install it into the \system\charconv\ directory. The DLL is then available to be loaded when CCnvCharacterSetConverter::PrepareToConvertToOrFromL() is invoked.

                  \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E9191C31-4D09-4C95-85E4-4282ADEE1D82.dita --- a/Symbian3/SDK/Source/GUID-E9191C31-4D09-4C95-85E4-4282ADEE1D82.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-E9191C31-4D09-4C95-85E4-4282ADEE1D82.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,138 +1,137 @@ - - - - - -Handling -pointer events in custom controlsThe Symbian platform passes touch events to applications by calling CCoeControl::HandlePointerEventL(). -The application that receives these events is the one that owns the window. -

                  While this method has been available since S60 3.0, it previously has been -an optional method. If you have derived a custom control from CCoeControl, -then you must implement the CCoeControl::HandlePointerEventL() method. -Otherwise, your application cannot react to the touch events passed to it.

                  -

                  You have to implement at least CCoeControl::HandlePointerEventL() into -your own custom UI components. If you have a container control that owns other -controls, you have to remember to call the base class implementation of CCoeControl::HandlePointerEventL() before -your additional code as illustrated below:

                  -void CMyContainerControl::HandlePointerEventL() - { - // Remember to call base class implementation - CCoeControl::HandlePointerEventL(); - - // Your additional code here - // ... - } -

                  The following figure illustrates changes in the code. Items marked with -a black frame indicate usage of features in earlier editions, and items marked -with a red frame are new features.

                  - -<parmname>CCoeControl::HandlePointerEventL()</parmname> usage - - -

                  To handle pointer events in your custom control:

                  -
                    -

                  1. In your custom -control header file, include the CCoeControl::HandlePointerEventL() method.

                    public: // from CCoeControl - void HandlePointerEventL(const TPointerEvent& aPointerEvent);
                    2. -

                  2. In your custom -control, implement the CCoeControl::HandlePointerEventL() method.

                    void CMyControl::HandlePointerEventL(const TPointerEvent& aPointerEvent) - { - switch( aPointerEvent.iType ) - { - case TPointerEvent::EButton1Up: - { - // Is the pointer position on this component? - if (Rect().Contains(aPointerEvent.iPosition)) - { - SetFocus(ETrue); - // Tell container control that this is focused control - CMyContainerControl* parent = static_cast<CMyContainerControl*>(Parent()); - parent->SetLastFocusedControl(this); - } - break; - } - default: - { - break; - } - } - }

                    By default, the Symbian platform only passes EButton1Down and EButton1Up events -to CCoeControl::HandlePointerEventL(). To enable drag -events, see Enabling -additional touch events for your application.

                    3. -

                  3. In your custom -container control header file, include the CCoeControl::HandlePointerEventL() method.

                    void HandlePointerEventL(const TPointerEvent& aPointerEvent);
                    4. -

                  4. In your custom -container control, implement the CCoeControl::HandlePointerEventL() method.

                    void CMyContainerControl::HandlePointerEventL(const TPointerEvent& aPointerEvent) - { - // Check if touch is enabled or not - if( !AknLayoutUtils::PenEnabled() ) - { - return; - } - - // Remove last focus - if (iLastFocusedControl) - { - iLastFocusedControl->SetFocus(EFalse); - } - - // Call base class method, that forwards pointer event the right child - // component - CCoeControl::HandlePointerEventL(aPointerEvent); - - // Check all button up cases again - if (aPointerEvent.iType == TPointerEvent::EButton1Up) - { - // Find which control was focused / received pointer event - CCoeControlArray::TCursor cursor = Components().Begin(); - CCoeControl* ctrl = NULL; - TInt counter = 0; - while ((ctrl = cursor.Control<CCoeControl>()) != NULL) - { - if (ctrl->Rect().Contains(aPointerEvent.iPosition)) - { - // Set focused index for the scroll bar - iFocusedIndex = counter; - break; - } - cursor.Next(); - counter++; - } - } - - // Do drawing - UpdateScrollBarFrameL(); - DrawNow(); - }

                    For information on the AknLayoutUtils::PenEnabled() method, -see Checking for touch -support at runtime.

                    5. -
                  -
                    -

                  • Features introduced:

                      -

                    • Optional TPointerEvent::EDrag() for receiving -events indicating that a mobile device user is dragging it across the screen.

                      For -more information on this and other touch event options, see Enabling -additional touch events for your application.

                      • -

                    • Optional MTouchFeedback observer for sending a -vibration when a mobile device user touches a control with the feedback interface.

                      For -more information on tactile feedback, see Tactile -feedback.

                      • -
                    • -
                  -                   -Related information -Enabling -additional touch events for your application -Providing -tactile feedback -Handling -key events in your application - + + + + + +Handling +pointer events in custom controlsThe Symbian platform passes touch events to applications by calling CCoeControl::HandlePointerEventL(). +The application that receives these events is the one that owns the window. +

                  While this method has been available since S60 3.0, it previously has been +an optional method. If you have derived a custom control from CCoeControl, +then you must implement the CCoeControl::HandlePointerEventL() method. +Otherwise, your application cannot react to the touch events passed to it.

                  +

                  You have to implement at least CCoeControl::HandlePointerEventL() into +your own custom UI components. If you have a container control that owns other +controls, you have to remember to call the base class implementation of CCoeControl::HandlePointerEventL() before +your additional code as illustrated below:

                  +void CMyContainerControl::HandlePointerEventL() + { + // Remember to call base class implementation + CCoeControl::HandlePointerEventL(); + + // Your additional code here + // ... + } +

                  The following figure illustrates changes in the code. Items marked with +a black frame indicate usage of features in earlier editions, and items marked +with a red frame are new features.

                  + +<parmname>CCoeControl::HandlePointerEventL()</parmname> usage + + +

                  To handle pointer events in your custom control:

                  +
                    +

                  1. In your custom +control header file, include the CCoeControl::HandlePointerEventL() method.

                    public: // from CCoeControl + void HandlePointerEventL(const TPointerEvent& aPointerEvent);
                    2. +

                  2. In your custom +control, implement the CCoeControl::HandlePointerEventL() method.

                    void CMyControl::HandlePointerEventL(const TPointerEvent& aPointerEvent) + { + switch( aPointerEvent.iType ) + { + case TPointerEvent::EButton1Up: + { + // Is the pointer position on this component? + if (Rect().Contains(aPointerEvent.iPosition)) + { + SetFocus(ETrue); + // Tell container control that this is focused control + CMyContainerControl* parent = static_cast<CMyContainerControl*>(Parent()); + parent->SetLastFocusedControl(this); + } + break; + } + default: + { + break; + } + } + }

                    By default, the Symbian platform only passes EButton1Down and EButton1Up events +to CCoeControl::HandlePointerEventL(). To enable drag +events, see Enabling +additional touch events for your application.

                    3. +

                  3. In your custom +container control header file, include the CCoeControl::HandlePointerEventL() method.

                    void HandlePointerEventL(const TPointerEvent& aPointerEvent);
                    4. +

                  4. In your custom +container control, implement the CCoeControl::HandlePointerEventL() method.

                    void CMyContainerControl::HandlePointerEventL(const TPointerEvent& aPointerEvent) + { + // Check if touch is enabled or not + if( !AknLayoutUtils::PenEnabled() ) + { + return; + } + + // Remove last focus + if (iLastFocusedControl) + { + iLastFocusedControl->SetFocus(EFalse); + } + + // Call base class method, that forwards pointer event the right child + // component + CCoeControl::HandlePointerEventL(aPointerEvent); + + // Check all button up cases again + if (aPointerEvent.iType == TPointerEvent::EButton1Up) + { + // Find which control was focused / received pointer event + CCoeControlArray::TCursor cursor = Components().Begin(); + CCoeControl* ctrl = NULL; + TInt counter = 0; + while ((ctrl = cursor.Control<CCoeControl>()) != NULL) + { + if (ctrl->Rect().Contains(aPointerEvent.iPosition)) + { + // Set focused index for the scroll bar + iFocusedIndex = counter; + break; + } + cursor.Next(); + counter++; + } + } + + // Do drawing + UpdateScrollBarFrameL(); + DrawNow(); + }

                    For information on the AknLayoutUtils::PenEnabled() method, +see Checking for touch +support at runtime.

                    5. +
                  +
                    +

                  • Features introduced:

                      +

                    • Optional TPointerEvent::EDrag() for receiving +events indicating that a mobile device user is dragging it across the screen.

                      For +more information on this and other touch event options, see Enabling additional touch events for your application.

                      • +

                    • Optional MTouchFeedback observer for sending a +vibration when a mobile device user touches a control with the feedback interface.

                      For +more information on tactile feedback, see Tactile +feedback.

                      • +
                    • +
                  +                   +Related information +Enabling +additional touch events for your application +Providing +tactile feedback +Handling +key events in your application +                   \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E91931D8-E433-58FB-B064-70903FA4C4A5_d0e111110_href.png Binary file Symbian3/SDK/Source/GUID-E91931D8-E433-58FB-B064-70903FA4C4A5_d0e111110_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E91931D8-E433-58FB-B064-70903FA4C4A5_d0e117648_href.png Binary file Symbian3/SDK/Source/GUID-E91931D8-E433-58FB-B064-70903FA4C4A5_d0e117648_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E93EE459-8CF4-42A1-B06C-E78E56FD25A0.dita --- a/Symbian3/SDK/Source/GUID-E93EE459-8CF4-42A1-B06C-E78E56FD25A0.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-E93EE459-8CF4-42A1-B06C-E78E56FD25A0.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,68 +1,68 @@ - - - - - -Listening -for Property ChangesThe sensor channel APIs enable the client applications to be notified -about the changes to properties associated with a sensor channel. - Before listening for -the property changes of a sensor channel, you must open the sensor channel. -

                  The client applications -can use the property listener to monitor the property changes made by other -clients.

                   - -Create a property -listener implementation for the MSensrvPropertyListener interface. -class PropertyListener:public MSensrvPropertyListener - { - public: - void PropertyChanged(CSensrvChannel &aChannel, const TSensrvProperty &aChangedProperty) - { - ... - //Implementation - } - void PropertyError(CSensrvChannel &aChannel, TSensrvErrorSeverity aError) - { - ... - //Implementation - } - void SetPropertySuccessIndicationChanged(TSetPropertySuccessIndicator aIndication) - { - ... - //Implementation - } - void GetPropertyListenerInterfaceL(TUid aInterfaceUid, TAny *&aInterface) - { - ... - //Implementation - } - }; - -Start property listening -by passing an instance of property listener implementation using CSensrvChannel::SetPropertyListenerL(). -//Instance of the property listener implementation -PropertyListener propListener; -... -CSensrvChannel* channel; -... -channel->SetPropertyListenerL(&propListener); -... -When a property change occurs, a PropertyChanged() notification -is delivered through the MSensrvPropertyListener callback -interface to the clients that are listening for property changes. The -client that set the property is not notified. - -Once you get the -required property changes associated with the sensor channel, you can stop -property listening by passing a NULL parameter to the CSensrvChannel::SetPropertyListenerL() function. -channel->SetPropertyListenerL(); - - + + + + + +Listening +for Property ChangesThe sensor channel APIs enable the client applications to be notified +about the changes to properties associated with a sensor channel. + Before listening for +the property changes of a sensor channel, you must open the sensor channel. +

                  The client applications +can use the property listener to monitor the property changes made by other +clients.

                   + +Create a property +listener implementation for the MSensrvPropertyListener interface. +class PropertyListener:public MSensrvPropertyListener + { + public: + void PropertyChanged(CSensrvChannel &aChannel, const TSensrvProperty &aChangedProperty) + { + ... + //Implementation + } + void PropertyError(CSensrvChannel &aChannel, TSensrvErrorSeverity aError) + { + ... + //Implementation + } + void SetPropertySuccessIndicationChanged(TSetPropertySuccessIndicator aIndication) + { + ... + //Implementation + } + void GetPropertyListenerInterfaceL(TUid aInterfaceUid, TAny *&aInterface) + { + ... + //Implementation + } + }; + +Start property listening +by passing an instance of property listener implementation using CSensrvChannel::SetPropertyListenerL(). +//Instance of the property listener implementation +PropertyListener propListener; +... +CSensrvChannel* channel; +... +channel->SetPropertyListenerL(&propListener); +... +When a property change occurs, a PropertyChanged() notification +is delivered through the MSensrvPropertyListener callback +interface to the clients that are listening for property changes. The +client that set the property is not notified. + +Once you get the +required property changes associated with the sensor channel, you can stop +property listening by passing a NULL parameter to the CSensrvChannel::SetPropertyListenerL() function. +channel->SetPropertyListenerL(); + +                   \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E9C620EF-4C77-56C3-8023-A6F13989246A_d0e413261_href.png Binary file Symbian3/SDK/Source/GUID-E9C620EF-4C77-56C3-8023-A6F13989246A_d0e413261_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E9C620EF-4C77-56C3-8023-A6F13989246A_d0e413423_href.png Binary file Symbian3/SDK/Source/GUID-E9C620EF-4C77-56C3-8023-A6F13989246A_d0e413423_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E9E21C82-13F6-50D4-A271-F9E5F1BD982F.dita --- a/Symbian3/SDK/Source/GUID-E9E21C82-13F6-50D4-A271-F9E5F1BD982F.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-E9E21C82-13F6-50D4-A271-F9E5F1BD982F.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,42 +1,88 @@ - - - - - -Background Processing for EcamThis topic describes how to capture an image using standalone background processing in Ecam.

                  Before you start you should understand the Onboard Camera Overview topic.

                  The Ecam API has been extended for background processing by having it as a standalone process. In order to use standalone background processing you need to implement the MCameraObserver2, MPreImageCaptureControlObserver, MCaptureImageObserver interfaces and use with the CCamera API.

                  To prepare image capturing using the CCamera API call CCameraPreImageCaptureControl::GetSupportedProcessingOptionsL(Tint&) to get support for processing specified by TECamProcessingTypes. pass the EECamBackgroundProcessing option instead of the SetImageProcessingOptions value within the TPrepareImageParameters values to the required processing option specified in TECamProcessingOptions for the background processing. call CCameraPreImageCaptureControl::PrepareImageCapture(const - CCameraPreImageCaptureControl:: TPrepareImageParameters&, - MCaptureImageObserver&) to perform setup and allocation of memory for the image capture operation. This implementation creates a new CCameraImageCapture() object which internally implements the MCameraImageCapture() interface. If an error occurs while preparing an image, call CCameraPreImageCaptureControl::PrepareImageComplete(CCameraPreImageCaptureControl*, - TInt) to pass the aErrorCode value to CCamera. Call CCameraImageCapture::CaptureImage() to capture an image. This implements MCameraImageCapture(). Call CCameraPostImageCaptureControl::CreateL(CCameraImageCapture*, - TPostCaptureControlId) if you wish to capture another image. The CCameraPostImageCaptureControl object from the previous capture is preserved. This callback function creates a CCameraPostImageCaptureControl object for every individual image captured. Call MCaptureImageObserver::IndividualImageControlHandle(CCameraImageCapture&, - TPostCaptureControlId) to destroy the individual captured image. Call CCameraPostImageCaptureControl::~CCameraPostImageCaptureControl() to destroy any captured image objects created by CCameraPostImageCaptureControl::CreateL(). Call CCameraImageCapture::PauseProcessing(TUint) to pause any processing options associated with the relevant image capture function. Note: You can call PauseProcessing() for any processing options used during image capture. Call CCameraImageCapture::ResumeProcessingL(TUint) to resume any processing options associated with the relevant image capture function. Note: You can call ResumeProcessingL() for any processing options used during image capture. Call CCameraPostImageCaptureControl::GetImageStateL(TImageState&) to retrieve the image state of the individual image given by the CCameraPostImageCaptureControl object. Example

                  The following example shows you how to capture an image using standalone background processing in Ecam:

                  - -CCamera* camera; -MCameraObserver2* observer2; -camera = CCamera::New2L(*observer2, 0); -MPreImageCaptureControlObserver* preImageCaptureControlObserver; -CCamera::CCameraPreImageCaptureControl* preImgCapture = CCamera::CCameraPreImageCaptureControl::NewL(*camera, preImageCaptureControlObserver)); -TInt supportedProcessingOptions; -preImgCapture->GetSupportedProcessingOptionsL(supportedProcessingOptions); // provides supported image processing options -CCamera::CCameraPreImageCaptureControl::TPrepareImageParameters prepareImageParameters; -prepareImageParameters::iImageProcessingOptions = EECamBackgroundProcessing; -... -... -// Capture image -... -... -TUint processingOptions = EECamBackgroundProcessing; -imgCapture->PauseProcessing(processingOptions); // Pauses any background processing associated with this image capture -imgCapture->ResumeProcessingL(processingOptions); // Resumes any background processing associated with this image capture - - // Retrieve the information for any stage of captured image. -TImageState imgState; -postImgCapture->GetImageStateL(imgState); // Retrieves the stage of any processing on the current image - - -                   Capturing Image                   \ No newline at end of file + + + + + +Background +Processing for EcamThis topic describes how to capture an image using standalone background +processing in Ecam. +

                  Before you start +you should understand the Onboard +Camera Overview topic.

                  +

                  The Ecam API has +been extended for background processing by having it as a standalone process. +In order to use standalone background processing you need to implement the MCameraObserver2, MPreImageCaptureControlObserver, MCaptureImageObserver interfaces and use with the CCamera API.

                  + + + To prepare image capturing +using the CCamera API + +Call CCamera::CCameraPreImageCaptureControl::GetSupportedProcessingOptionsL(TUint& +aECamProcessingOptionsSupported) const to get support for processing +specified by TECamProcessingTypes. + + +Pass the EECamBackgroundProcessing option instead of +the SetImageProcessingOptions value within the TPrepareImageParameters values +to the required processing option specified in TECamProcessingOptions for +the background processing. + + +Call CCamera::CCameraPreImageCaptureControl::PrepareImageCapture(const + CCameraPreImageCaptureControl::TPrepareImageParameters&, MCaptureImageObserver&) to +perform setup and allocation of memory for the image capture operation. This +implementation creates a new CCameraImageCapture() object +which internally implements the MCameraImageCapture() interface. +If an error occurs while preparing an image, call MPreImageCaptureControlObserver::PrepareImageComplete(CCamera::CCameraImageCapture +*,TInt) to pass the aErrorCode value to CCamera. + + + + +Call CCamera::CCameraImageCapture::CaptureImage() to +capture an image. This implements MCameraImageCapture. + + +Call CCamera::CCameraPostImageCaptureControl::CreateL(CCameraImageCapture*, + TPostCaptureControlId) if you wish to capture another +image. The CCameraPostImageCaptureControl object from the +previous capture is preserved. This callback function creates a CCameraPostImageCaptureControl object +for every individual image captured. + + +Call MCaptureImageObserver::IndividualImageControlHandle(CCamera::CCameraImageCapture +&,TPostCaptureControlId) to destroy the individual captured +image. + + +Call CCamera::CCameraPostImageCaptureControl::~CCameraPostImageCaptureControl() to +destroy any captured image objects created by CCameraPostImageCaptureControl::CreateL(). + + +Call CCamera::CCameraImageCapture::PauseProcessing(TUint) to +pause any processing options associated with the relevant image capture function. +Note: You can call PauseProcessing() for any processing +options used during image capture. + + +Call CCamera::CCameraImageCapture::ResumeProcessingL(TUint) to +resume any processing options associated with the relevant image capture function. +Note: You can call ResumeProcessingL() for any processing +options used during image capture. + + +Call CCamera::CCameraPostImageCaptureControl::GetImageStateL(TImageState +&)const to retrieve the image state of the individual +image given by the CCameraPostImageCaptureControl object. + + +                   +Capturing +Still Images +                   \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E9F08BCA-39F6-55D3-8974-BD0FFB90DE11_d0e283704_href.png Binary file Symbian3/SDK/Source/GUID-E9F08BCA-39F6-55D3-8974-BD0FFB90DE11_d0e283704_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E9F08BCA-39F6-55D3-8974-BD0FFB90DE11_d0e287390_href.png Binary file Symbian3/SDK/Source/GUID-E9F08BCA-39F6-55D3-8974-BD0FFB90DE11_d0e287390_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-E9F203A6-D9E3-41B7-9FC4-24EDE20C4753.dita --- a/Symbian3/SDK/Source/GUID-E9F203A6-D9E3-41B7-9FC4-24EDE20C4753.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-E9F203A6-D9E3-41B7-9FC4-24EDE20C4753.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,57 +1,67 @@ - - - - - -Error -note -

                  Error notes are a warning to the user. They should only be used when the -user has tried to do something that may cause a considerable problem.

                  - -Error note - - -
                  Guidelines -for using error notes

                  Use an error note when the user does -something that may cause considerable harm immediately or later. For example, -the user gives a wrong PIN code. Repeating this couple of times would block -the SIM card.

                  To keep error notes effective, they should be used very -sparingly. In most ordinary error cases, an information -note should be used instead of an error note. It has a less aggressive -sound and graphics.

                  It should also be noted that if the information -to be given is such that the user must see and acknowledge it, a confirmation -query is a better component to use than a note. Then the user must press a -key to dismiss the information, and there is time to read and think about -the notification.

                  -
                  Using -error notes in C++ applications

                  You can create either a basic error -note that is displayed only when your application is in the foreground or -a global note that stays displayed even if the application launching the note -is not in the foreground. The related APIs are the Notes API (for basic notes) and the Notifiers API (for global notes).

                  To use an error -note with the default icon, text, sound, and duration, create an instance -of the note class CAknErrorNote.

                  To create a global error note, use the class CAknGlobalNote in the Notifiers API. For implementation information, see Using global notes and Using global notes with user interaction.

                  For basic -notes, you can change the icon or text displayed in the note, use a different -kind of sound, or change the note duration using the setter methods in the -class CAknNoteDialog: SetIconL(), SetTextL(), SetTone(), and SetTimeout().

                  For information on customizing global notes, see Enhancing global notes. You can change the graphic, animation, -tone, and softkeys using the methods in the class CAknGlobalNote: SetGraphic(), SetAnimation(), SetTone(), and SetSoftkeys().

                  - -                   -Confirmation -note -Information -note -Warning note - -Permanent -note -Wait note - -Progress -note + + + + + +Error +note +

                  Error notes are a warning to the user. They should only be used when the +user has tried to do something that may cause a considerable problem.

                  + +Error note + + +
                  Guidelines +for using error notes

                  Use an error note when the user does +something that may cause considerable harm immediately or later. For example, +the user gives a wrong PIN code. Repeating this couple of times would block +the SIM card.

                  To keep error notes effective, they should be used very +sparingly. In most ordinary error cases, an information +note should be used instead of an error note. It has a less aggressive +sound and graphics.

                  It should also be noted that if the information +to be given is such that the user must see and acknowledge it, a confirmation +query is a better component to use than a note. Then the user must press a +key to dismiss the information, and there is time to read and think about +the notification.

                  +
                  Using +error notes in applications

                  You can create either a basic error +note that is displayed only when your application is in the foreground or +a global note that stays displayed even if the application launching the note +is not in the foreground. The related APIs are the Notes API (for basic notes) and the Notifiers API (for global notes).

                  To use an error +note with the default icon, text, sound, and duration, create an instance +of the note CAknErrorNote class.

                  To create a global +error note, use the CAknGlobalNote class in the Notifiers API. For implementation information, see Using global notes and Using global notes with user interaction.

                  For basic +notes, you can change the icon or text displayed in the note, use a different +kind of sound, or change the note duration using the setter methods in the CAknNoteDialog class:

                    +

                  • CAknNoteDialog::SetIconL()

                    • +

                  • CAknNoteDialog::SetTextL()

                    • +

                  • CAknNoteDialog::SetTone()

                    • +

                  • CAknNoteDialog::SetTimeout()

                    • +

                  For information on customizing global notes, see Enhancing global notes. You can change the graphic, animation, +tone, and softkeys using the methods in the CAknGlobalNote class:

                    +

                  • CAknGlobalNote::SetGraphic()

                    • +

                  • CAknGlobalNote::SetAnimation()

                    • +

                  • CAknGlobalNote::SetTone()

                    • +

                  • CAknGlobalNote::SetSoftkeys()

                    • +

                  + +                   +Confirmation +note +Information +note +Warning note + +Permanent +note +Wait note + +Progress +note                   \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EA107811-240C-5F95-922B-7C042FA00A87.dita --- a/Symbian3/SDK/Source/GUID-EA107811-240C-5F95-922B-7C042FA00A87.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-EA107811-240C-5F95-922B-7C042FA00A87.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,119 +1,119 @@ - - - - - -Reading -a String Resource

                  The simplest use of a resource file involves reading string resources -and interpreting the source data.

                  -

                  Resources are defined in terms of structs which are accessed and -read by the RResourceFile class, and interpreted by the TResourceReader. -An application may also use resources from multiple files simultaneously. -See Resource File examples for -more information.

                  Consider a sample resource file where a struct of -STRING is defined having a single member of type LTEXT:

                  // define structures -STRUCT STRING - { - LTEXT text; - } -// define resources -RESOURCE STRING hello - { - text=Bonjour tout le monde!; - } -                   - - -Compile the resource file using the -resource compiler (rcomp) to generate an .rsc file -and an .rsg file. - - - .rsc file contains the resource data; this is -the resource file that must be referred to at run-time by the RResourceFile class -in the C++ code. - - - .rsg file is a generated - header file that contains #define statements -for each resource defined in the source file. In the resource file generated -here, the only resource is called hello and the generated -header file contains: -#define HELLO 1 -Note that the name in the generated header file is converted to upper -case. - - - - - #include the .rsg file in the -file containing the C++ code, to access the resource IDs generated by the -resource compiler. For example, for a project refered as ReadText, -this might be: -#include ReadText.rsg - - -Initialize the RResourceFile object in the C++ program, -specifying the name of the resource file: - -RResourceFile resourceFile; -resourceFile.OpenL( fsSession,_L( Z:\\system\\data\\ReadText.rsc ) ); -Note: To access the resource file contents, a session with the file -server must be started using an instance of RFs class. - - -Use one of the three functions (RResourceFile::AllocReadLC(), RResourceFile::AllocReadL() or RResourceFile::ReadL() to read a resource as shown in the following -code fragment: -HBufC8* dataBuffer = resourceFile.AllocReadLC( HELLO ); - - -Interpret the resource data using a TResourceReader object. -This provides access to the text string through a pointer descriptor as shown -in the following code fragment: - -TResourceReader theReader; -... -theReader.SetBuffer( datafBuffer ); -TPtrC textdata = reader.ReadTPtrC(); - - -

                  In this example, once the resource data is no longer needed, the -heap descriptor, dataBuffer, can be removed from the cleanup stack and destroyed -as shown in the code fragment:

                  CleanupStack::PopAndDestroy();

                  When -all operations on the resource file are complete, the resource file can be -closed using the RResourceFile::close() function as:

                  resourceFile.Close();                   -Example

                  Consider a resource constructed -from the following definition.

                  RESOURCE ARRAY anarray -{ -items= - { - LBUF { txt="Esc"; }, - LBUF { txt="Enter"; }, - LBUF { txt="Tab"; }, - LBUF { txt="Del"; }, - LBUF { txt="Space"; } - }; -}

                  A TPtrC representing the second item can -be constructed using the ReadTPtrC() function. The example -simply takes the length of the text Enter:

                  // open the resource file -... -HBufC8* res = resourceFile.AllocReadLC( ANARRAY ); -TResourceReader theReader; -... -TInt len; -len = ( theReader.ReadTPtrC( 1,res ) ).Length(); // len == 5 -...                   -                   -Resource -files -Resource -file format -Resource -compilation + + + + + +Reading +a String Resource

                  The simplest use of a resource file involves reading string resources +and interpreting the source data.

                  +

                  Resources are defined in terms of structs which are accessed and +read by the RResourceFile class, and interpreted by the TResourceReader. +An application may also use resources from multiple files simultaneously. +See Resource File examples for +more information.

                  Consider a sample resource file where a struct of +STRING is defined having a single member of type LTEXT:

                  // define structures +STRUCT STRING + { + LTEXT text; + } +// define resources +RESOURCE STRING hello + { + text=Bonjour tout le monde!; + } +                   + + +Compile the resource file using the +resource compiler (rcomp) to generate an .rsc file +and an .rsg file. + + + .rsc file contains the resource data; this is +the resource file that must be referred to at run-time by the RResourceFile class +in the C++ code. + + + .rsg file is a generated + header file that contains #define statements +for each resource defined in the source file. In the resource file generated +here, the only resource is called hello and the generated +header file contains: +#define HELLO 1 +Note that the name in the generated header file is converted to upper +case. + + + + + #include the .rsg file in the +file containing the C++ code, to access the resource IDs generated by the +resource compiler. For example, for a project refered as ReadText, +this might be: +#include ReadText.rsg + + +Initialize the RResourceFile object in the C++ program, +specifying the name of the resource file: + +RResourceFile resourceFile; +resourceFile.OpenL( fsSession,_L( Z:\\system\\data\\ReadText.rsc ) ); +Note: To access the resource file contents, a session with the file +server must be started using an instance of RFs class. + + +Use one of the three functions (RResourceFile::AllocReadLC(), RResourceFile::AllocReadL() or RResourceFile::ReadL() to read a resource as shown in the following +code fragment: +HBufC8* dataBuffer = resourceFile.AllocReadLC( HELLO ); + + +Interpret the resource data using a TResourceReader object. +This provides access to the text string through a pointer descriptor as shown +in the following code fragment: + +TResourceReader theReader; +... +theReader.SetBuffer( datafBuffer ); +TPtrC textdata = reader.ReadTPtrC(); + + +

                  In this example, once the resource data is no longer needed, the +heap descriptor, dataBuffer, can be removed from the cleanup stack and destroyed +as shown in the code fragment:

                  CleanupStack::PopAndDestroy();

                  When +all operations on the resource file are complete, the resource file can be +closed using the RResourceFile::close() function as:

                  resourceFile.Close();                   +Example

                  Consider a resource constructed +from the following definition.

                  RESOURCE ARRAY anarray +{ +items= + { + LBUF { txt="Esc"; }, + LBUF { txt="Enter"; }, + LBUF { txt="Tab"; }, + LBUF { txt="Del"; }, + LBUF { txt="Space"; } + }; +}

                  A TPtrC representing the second item can +be constructed using the ReadTPtrC() function. The example +simply takes the length of the text Enter:

                  // open the resource file +... +HBufC8* res = resourceFile.AllocReadLC( ANARRAY ); +TResourceReader theReader; +... +TInt len; +len = ( theReader.ReadTPtrC( 1,res ) ).Length(); // len == 5 +...                   +                   +Resource +files +Resource +file format +Resource +compilation                   \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EA20E614-C911-4EE9-92B5-C8F9B657D59E.dita --- a/Symbian3/SDK/Source/GUID-EA20E614-C911-4EE9-92B5-C8F9B657D59E.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-EA20E614-C911-4EE9-92B5-C8F9B657D59E.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,56 +1,54 @@ - - - - - -Platform -security architecture -

                  The purpose of the Symbian platform security architecture is to enable -users to use their mobile devices in an easy and trusted manner. For more -information, see platform security.

                  -

                  This section introduces some central platform security concepts. These -include the following:

                  -
                    -

                  • Capabilities

                    -
                    • -

                  • Application -signing

                    • -

                  • Data -caging

                    • -
                  -

                  For more details on the above concepts, see the Symbian -Signed website.

                  -
                  Additional information -on security -
                    -

                  • For more information on how to test and certify your applications -and how to access capabilities, -see The Complete Guide -to Symbian Signed.

                    • -

                  • For more information about security in Symbian C++ application -development, see the Security -Articles in the Forum Nokia Developer Community Wiki.

                    • -

                  • For more advanced information and practical examples on how -to use various security options provided by the platform, see the following -Forum Nokia resources:All these examples -are listed as compatible with the 3rd Edition on Forum Nokia, and therefore -it is unclear whether they apply to 5th Edition.

                    -
                      -

                    • System Information Example

                      • -

                    • ECom Plug-in Architecture and ECom Plug-In Examples

                      • -

                    • HTTP Client API Example

                      • -

                    • End-to-End HTTP API Example

                      • -

                    • End-to-End Sockets API Example

                      • -

                    • Access Points Example with Roaming Support

                      -
                      • -
                    -
                    • -
                  -
                  + + + + + +Platform +security architecture +

                  The purpose of the Symbian platform security architecture is to enable +users to use their mobile devices in an easy and trusted manner.

                  +

                  This section introduces some central platform security concepts. These +include the following:

                  +
                    +

                  • Capabilities

                    +
                    • +

                  • Application +signing

                    • +

                  • Data +caging

                    • +
                  +

                  For more details on the above concepts, see the Symbian +Signed website.

                  +
                  Additional information +on security +
                    +

                  • For more information on how to test and certify your applications +and how to access capabilities, +see The +Complete Guide to Symbian Signed.

                    • +

                  • For more information about security in Symbian C++ application +development, see the Security +Articles in the Forum Nokia Developer Community Wiki.

                    • +

                  • For more advanced information and practical examples on how +to use various security options provided by the platform, see the following +Forum Nokia resources:All these examples +are listed as compatible with the 3rd Edition on Forum Nokia, and therefore +it is unclear whether they apply to 5th Edition.

                    +
                      +

                    • System Information Example

                      • +

                    • ECom Plug-in Architecture and ECom Plug-In Examples

                      • +

                    • HTTP Client API Example

                      • +

                    • End-to-End HTTP API Example

                      • +

                    • End-to-End Sockets API Example

                      • +

                    • Access Points Example with Roaming Support

                      • +
                    +
                    • +
                  +
                   \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EA2AAE86-0BD3-52C9-BD13-75E9F04DE77F_d0e229007_href.png Binary file Symbian3/SDK/Source/GUID-EA2AAE86-0BD3-52C9-BD13-75E9F04DE77F_d0e229007_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EA2AAE86-0BD3-52C9-BD13-75E9F04DE77F_d0e232744_href.png Binary file Symbian3/SDK/Source/GUID-EA2AAE86-0BD3-52C9-BD13-75E9F04DE77F_d0e232744_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EA3419BD-D757-5AC3-AE6F-DF21F794AE47.dita --- a/Symbian3/SDK/Source/GUID-EA3419BD-D757-5AC3-AE6F-DF21F794AE47.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-EA3419BD-D757-5AC3-AE6F-DF21F794AE47.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,75 +1,75 @@ - - - - - -Descriptor -basicsThis document describes buffer descriptors, heap descriptors, pointer -descriptors and resizable buffer descriptors. -

                  Descriptors provide a safe, consistent and economical mechanism for accessing -and manipulating strings and general binary data.

                  -

                  A descriptor represents data which can reside in any memory location, either -ROM or RAM. A descriptor object maintains pointer and length information to -describe the data. All access to the data is made through the descriptor object.

                  -

                  The area occupied by data represented by a given descriptor is considered -to be non-expandable, even though the length of data represented can shrink -or expand to fill that area.

                  -

                  The set of operations which can be performed on data represented by a descriptor -is divided into those that can modify the data and those which provide access -but do not modify the data. This split is reflected in the structure of the -descriptor classes.

                  -

                  Operations on data represented by a descriptor are safe. Accidental or -deliberate attempts to access memory outside the data area represented by -a descriptor are caught. An illegal access is treated as bad programming rather -than an environment or resource problem and raises an exception known as a -panic.

                  -

                  Descriptors make no distinction between the type of data represented; both -strings and binary data are treated in the same way. Although some operations -on a descriptor are intended to operate on a string, they also work on binary -data. This unifies the handling of both strings and binary data and increases -efficiency by allowing code to be shared. This also means that data can consist -of a mix of string data and binary data.

                  -

                  The concrete descriptors that programs create come in four types:

                  -
                    -

                  • Buffer descriptors - -where the data is part of the descriptor object and the descriptor object -lives on the program stack.

                    • -

                  • Heap descriptors - where -the data is part of the descriptor object and the descriptor object lives -on the heap.

                    • -

                  • Pointer descriptors -- where the descriptor object is separate from the data it represents.

                    • -

                  • Resizable buffer descriptors -- where the descriptor is separate from the data it represents, and the data -resides in a buffer allocated on the heap.

                    • -
                  - - Buffer descriptor - - - - Heap descriptor - - - - Pointer descriptor - - - - Resizable buffer descriptor - - -

                  Although the four types seem to be different, the underlying class structure -makes such differences transparent allowing them to be treated in the same -way.

                  -

                  Descriptor objects generally, behave as built-in types, as they can be -safely created on the program stack and can also be safely orphaned. The heap -descriptor is an exception to this rule.

                  -

                  The design also avoids the memory overhead associated with virtual functions.

                  + + + + + +Descriptor +basicsThis document describes buffer descriptors, heap descriptors, pointer +descriptors and resizable buffer descriptors. +

                  Descriptors provide a safe, consistent and economical mechanism for accessing +and manipulating strings and general binary data.

                  +

                  A descriptor represents data which can reside in any memory location, either +ROM or RAM. A descriptor object maintains pointer and length information to +describe the data. All access to the data is made through the descriptor object.

                  +

                  The area occupied by data represented by a given descriptor is considered +to be non-expandable, even though the length of data represented can shrink +or expand to fill that area.

                  +

                  The set of operations which can be performed on data represented by a descriptor +is divided into those that can modify the data and those which provide access +but do not modify the data. This split is reflected in the structure of the +descriptor classes.

                  +

                  Operations on data represented by a descriptor are safe. Accidental or +deliberate attempts to access memory outside the data area represented by +a descriptor are caught. An illegal access is treated as bad programming rather +than an environment or resource problem and raises an exception known as a +panic.

                  +

                  Descriptors make no distinction between the type of data represented; both +strings and binary data are treated in the same way. Although some operations +on a descriptor are intended to operate on a string, they also work on binary +data. This unifies the handling of both strings and binary data and increases +efficiency by allowing code to be shared. This also means that data can consist +of a mix of string data and binary data.

                  +

                  The concrete descriptors that programs create come in four types:

                  +
                    +

                  • Buffer descriptors - +where the data is part of the descriptor object and the descriptor object +lives on the program stack.

                    • +

                  • Heap descriptors - where +the data is part of the descriptor object and the descriptor object lives +on the heap.

                    • +

                  • Pointer descriptors +- where the descriptor object is separate from the data it represents.

                    • +

                  • Resizable buffer descriptors +- where the descriptor is separate from the data it represents, and the data +resides in a buffer allocated on the heap.

                    • +
                  + + Buffer descriptor + + + + Heap descriptor + + + + Pointer descriptor + + + + Resizable buffer descriptor + + +

                  Although the four types seem to be different, the underlying class structure +makes such differences transparent allowing them to be treated in the same +way.

                  +

                  Descriptor objects generally, behave as built-in types, as they can be +safely created on the program stack and can also be safely orphaned. The heap +descriptor is an exception to this rule.

                  +

                  The design also avoids the memory overhead associated with virtual functions.

                  \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EA5E9A07-587C-5E64-A157-1077AD9E56ED_d0e390209_href.png Binary file Symbian3/SDK/Source/GUID-EA5E9A07-587C-5E64-A157-1077AD9E56ED_d0e390209_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EA5E9A07-587C-5E64-A157-1077AD9E56ED_d0e390371_href.png Binary file Symbian3/SDK/Source/GUID-EA5E9A07-587C-5E64-A157-1077AD9E56ED_d0e390371_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EA8038F6-8727-5ABE-805C-9FF095293EB7.dita --- a/Symbian3/SDK/Source/GUID-EA8038F6-8727-5ABE-805C-9FF095293EB7.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-EA8038F6-8727-5ABE-805C-9FF095293EB7.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,262 +1,262 @@ - - - - - -Bluetooth -Comms Profiles Collection OverviewProvides implementations of some Bluetooth profiles and support -for others. (Some Bluetooth profiles are omitted.) -
                  Purpose

                  This document introduces -Bluetooth profiles and indicates the current status of those profiles within -the Symbian platform Bluetooth subsystem. A Bluetooth profile encompasses -a defined set of functionality for an operation or task, identifies the Bluetooth -stack features required to perform the operation or tasks and describes how -those features are used.

                  By specifying these details Bluetooth profiles -make a significant contribution to realising the interoperability goals of -the Bluetooth consortium. If all device manufactures implement the profiles -according to the standards users can confidently purchase Bluetooth enabled -devices knowing that they will all work.

                  In this overview

                  You will learn about the status of the Bluetooth -profiles, those that are implemented, those that are supported and -those that are omitted from the current Symbian platform Bluetooth -subsystem. Documentation will be provided for each of the supported profiles -and this page will be updated with links as they become available.

                  The -standards define terminology specific to individual profiles. Please refer -to the latest Bluetooth standard at www.bluetooth.com for all official definitions.

                  -
                  Architecture - -
                  -
                  Description

                  There -are two kinds of profiles provided for by Symbian platform: implemented and -supported. Implemented profiles can be used directly from the existing components. -When a profile is supported the licensee will need to provide its own APIs -to make the functionality of that profile available to application developers.

                  - Figure 1. Profile dependencies -

                  Figure 1 above shows the dependencies of profiles. The shaded profiles, -discussed in the next section, are implemented by the Symbian platform Bluetooth -subsystem.

                  - -

                  Implemented -Bluetooth profiles

                  The following profiles are implemented by Symbian -platform Bluetooth:

                    -

                  • Generic Access Profile -(GAP)

                    • -

                  • Serial Port Profile -(SPP)

                    • -

                  • Generic Object Exchange -Profile (GOEP)

                    • -

                  • Personal Area Networking -(PAN) Profile

                    • -

                  • Audio Video Remote Control -Profile (AVRCP)

                    • -

                  • Generic Audio Video -Distribution Profile (GAVDP)

                    • -

                  • Advanced Audio Distribution -Profile (A2DP)

                    • -

                  The profiles are introduced here:

                  GAP

                  The Generic -Access Profile is the foundation Bluetooth profile. It enables two devices -to discover and connect to each other in a piconet. GAP defines the mode of -operation for participating devices, handles role assignment, and controls -the connection and link functionality at protocol level.

                  The Generic -Access profile, as the basic piconet enabler, uses features of the RFCOMM, -L2CAP, Link Manager and Link Controller layers of the Bluetooth stack. As an application developer you do not need to concern -yourself with the details of the protocols as this is handled internally. -The APIs will handle all of the connection, linking and role negotiation for -you. Note however that there are no explicit GAP APIs. The GAP functionality -is implicit in other APIs within Symbian platform.

                  SPP

                  The Serial -Port Profile gives Bluetooth devices RS-232 emulation capabilities, allowing -applications that were written with cable connection in mind to make the transition -to Bluetooth. The application establishes a link over the Bluetooth connection -without being aware of Bluetooth. The SPP simply emulates a typical RS-232 -serial cable communications session. The SPP enables multiplexing and provides -support for two device types: communication endpoint devices and intermediate -devices. SPP operates on the RFCOMM and L2CAP layers of the Bluetooth stack.

                  The -SPP is an integral part of the following profiles:

                  - - - -Bluetooth Profile -Supported - - - - -

                  Fax Profile

                  -

                  Yes

                  -                   - -

                  Dial-up Networking Profile(DUNP)

                  -

                  Yes

                  -                   - -

                  LAN Access Profile

                  -

                  Yes

                  -                   - -

                  Headset Profile

                  -

                  Yes

                  -                   - -

                  Hands Free Profile

                  -

                  Yes

                  -                   - -

                  Generic Object Exchange Profile

                  -

                  Implemented

                  -                   - -

                  Phonebook Access Profile

                  -

                  No

                  -                   - -

                  SIM Access Profile

                  -

                  No

                  -                   - - -

                  Links to examples, guides, and tutorials that use the SPP will -be provided here as they become available.

                  GOEP

                  The Generic -Object Exchange Profile provides the functionality needed to use the Object -Exchange (OBEX) Protocol over Bluetooth. GOEP is used by the following profiles:

                  - - - -Bluetooth Profile -Supported - - - - -

                  Object Push Profile

                  -

                  Yes

                  -                   - -

                  File Transfer Profile

                  -

                  Yes

                  -                   - -

                  Synchronisation Profile

                  -

                  Yes

                  -                   - - -

                  GOEP makes a significant contribution to the overall offering -by providing client and server roles to the devices of the Bluetooth Piconet. -Applications using GOEP can push and pull objects from other devices in the -piconet.

                  PAN Profile

                  The -Personal Area Networking profile provides a simplification to the LAN Access -and Dial-up Networking profiles (both now deprecated), by reducing the number -of layers in a network connection. PAN enhances networking over Bluetooth -by providing new functionality such as the Group Ad-hoc Networking role, discussed -below.

                  The PAN profile provides for three possible roles: the User -(PANU), Group Ad-hoc Networking (GN) and Network Access Point (NAP).

                  When -a device is operating in the PANU role it can connect to a device operating -in any of the three roles. This allows it to act as a client to one of these -devices. When operating in the GN role the device can accept a connection -request from a PANU device or make its own request to connect to such a device. -PANU and GN roles can be switched but a PANU device connecting to a NAP device -can not switch roles because NAP is not supported.

                  PAN is integrated -into the networking framework as a plug-in. See the Networking documentation -for more information about networking with the Bluetooth PAN profile plug-in. -Therefore applications can treat a Bluetooth PAN as any other networking technology.

                  AVRCP

                  The Audio -video remote control profile implements certain aspects of the AV/C Digital -Interface Command Set (IEEE 1394) for use over a Bluetooth connection. This -profile defines two possible roles: controller (CT) and target (TG). The controller -device sends commands to the target who acts on those commands.

                  Role -switching is possible. Consider a Bluetooth headset with integrated command -functions. When the headset is acting in the CT role it can begin music playback -or switch songs on the TG Symbian device. The Symbian device can become the -CT to send a volume control command to the headset, making the headset the -TG for that transaction.

                  Features of the profile implemented in the -Symbian platform Bluetooth subsystem are presented in the following table -according to defined role.

                  - - - -CT -TG - - - - -

                  All Mandatory features.

                  -

                  All Mandatory features.

                  -                   - -

                  Sending UNIT info command.

                  -

                  Initiating connection for control.

                  -                   - -

                  Sending subunit info command.

                  -

                  Receiving pass through commands.

                  -                   - -

                  Sending pass through commands.

                  -

                  Sending all operation_ids.

                  -                   - -

                  Sending all operation_ids.

                  -

                  Receiving all operation_ids.

                  -                   - -

                  Receiving all operation_ids.

                  -

                   -                   - - -

                  AVRCP operates over a GAP connection, communicating via the Audio -Video Control Transport Protocol (AVCTP) on a channel in the L2CAP layer. -Application developers will use the Remote Control Framework for creating -apps that use the AVRCP.

                  GAVDP

                  The Generic -audio video distribution profile provides the mechanism for distributing audio -and video content over a Bluetooth connection. There are two roles defined -for GAVDP, they are: Initiator (INT) and Acceptor (ACP). INT begins a signalling -procedure and ACP responds. The roles are not linked to the master / slave -relationship between devices and can switch when a new procedure is initiated.

                  GAVDP -has been implemented in the Symbian platform Bluetooth subsystem specifically -to support the Bluetooth stereo headset usecase. The Audio Video Distribution -Transport Protocol (AVDTP) manages the transmission of audio packets over -an L2CAP channel. The GAVDP component of the Bluetooth subsystem provides -an API to configure, send and receive data over the AVDTP within an ESock -plug-in.

                  A2DP

                  The Advanced -Audio Distribution Profile describes the protocols and procedures to stream -high quality stereo audio over Bluetooth.

                  Supported Bluetooth Profiles

                  The following list indicates -profiles for which the Symbian platform subsystem has provided the necessary -framework should a licensee have a need to implement them. Application developers -should refer to the documentation for the platform(s) they are targeting to -determine which additional profiles (if any) are available for a particular -device.

                  The Bluetooth profile implementers guide, available soon, -describes how licensees can enable profiles on their devices.

                    -

                  • Advanced Audio Distribution -Profile

                    Linked to MMF.

                    • -

                  • Video Distribution Profile

                    Linked -to MMF.

                    • -

                  • File Transfer Profile

                    • -

                  • Synchronization Profile

                    • -

                  • Fax Profile

                    • -

                  • Dial Up Networking (DUN) -Profile

                    • -

                  • Headset Profile

                    • -

                  • Hands Free Profile

                    Use -the Remote Control Framework.

                    • -

                  • HID Profile

                    • -

                  • Device ID Profile

                    • -

                  • Basic Printing Profile

                    • -

                  • Basic Imaging Profile

                    • -

                  • Service Discovery Application -Profile

                    • -

                  • Unrestricted Digital -Information Profile

                    • -

                  Omitted -Bluetooth profiles

                  The following profiles are explicitly omitted -from the Current Symbian platform Bluetooth subsystem:

                    -

                  • Cordless Telephony Profile

                    • -

                  • Intercom Profile

                    • -

                  • SIM Access Profile

                    • -
                  + + + + + +Bluetooth +Comms Profiles Collection OverviewProvides implementations of some Bluetooth profiles and support +for others. (Some Bluetooth profiles are omitted.) +
                  Purpose

                  This document introduces +Bluetooth profiles and indicates the current status of those profiles within +the Symbian platform Bluetooth subsystem. A Bluetooth profile encompasses +a defined set of functionality for an operation or task, identifies the Bluetooth +stack features required to perform the operation or tasks and describes how +those features are used.

                  By specifying these details Bluetooth profiles +make a significant contribution to realising the interoperability goals of +the Bluetooth consortium. If all device manufactures implement the profiles +according to the standards users can confidently purchase Bluetooth enabled +devices knowing that they will all work.

                  In this overview

                  You will learn about the status of the Bluetooth +profiles, those that are implemented, those that are supported and +those that are omitted from the current Symbian platform Bluetooth +subsystem. Documentation will be provided for each of the supported profiles +and this page will be updated with links as they become available.

                  The +standards define terminology specific to individual profiles. Please refer +to the latest Bluetooth standard at www.bluetooth.com for all official definitions.

                  +
                  Architecture + +
                  +
                  Description

                  There +are two kinds of profiles provided for by Symbian platform: implemented and +supported. Implemented profiles can be used directly from the existing components. +When a profile is supported the licensee will need to provide its own APIs +to make the functionality of that profile available to application developers.

                  + Figure 1. Profile dependencies +

                  Figure 1 above shows the dependencies of profiles. The shaded profiles, +discussed in the next section, are implemented by the Symbian platform Bluetooth +subsystem.

                  + +

                  Implemented +Bluetooth profiles

                  The following profiles are implemented by Symbian +platform Bluetooth:

                    +

                  • Generic Access Profile +(GAP)

                    • +

                  • Serial Port Profile +(SPP)

                    • +

                  • Generic Object Exchange +Profile (GOEP)

                    • +

                  • Personal Area Networking +(PAN) Profile

                    • +

                  • Audio Video Remote Control +Profile (AVRCP)

                    • +

                  • Generic Audio Video +Distribution Profile (GAVDP)

                    • +

                  • Advanced Audio Distribution +Profile (A2DP)

                    • +

                  The profiles are introduced here:

                  GAP

                  The Generic +Access Profile is the foundation Bluetooth profile. It enables two devices +to discover and connect to each other in a piconet. GAP defines the mode of +operation for participating devices, handles role assignment, and controls +the connection and link functionality at protocol level.

                  The Generic +Access profile, as the basic piconet enabler, uses features of the RFCOMM, +L2CAP, Link Manager and Link Controller layers of the Bluetooth stack. As an application developer you do not need to concern +yourself with the details of the protocols as this is handled internally. +The APIs will handle all of the connection, linking and role negotiation for +you. Note however that there are no explicit GAP APIs. The GAP functionality +is implicit in other APIs within Symbian platform.

                  SPP

                  The Serial +Port Profile gives Bluetooth devices RS-232 emulation capabilities, allowing +applications that were written with cable connection in mind to make the transition +to Bluetooth. The application establishes a link over the Bluetooth connection +without being aware of Bluetooth. The SPP simply emulates a typical RS-232 +serial cable communications session. The SPP enables multiplexing and provides +support for two device types: communication endpoint devices and intermediate +devices. SPP operates on the RFCOMM and L2CAP layers of the Bluetooth stack.

                  The +SPP is an integral part of the following profiles:

                  + + + +Bluetooth Profile +Supported + + + + +

                  Fax Profile

                  +

                  Yes

                  +                   + +

                  Dial-up Networking Profile(DUNP)

                  +

                  Yes

                  +                   + +

                  LAN Access Profile

                  +

                  Yes

                  +                   + +

                  Headset Profile

                  +

                  Yes

                  +                   + +

                  Hands Free Profile

                  +

                  Yes

                  +                   + +

                  Generic Object Exchange Profile

                  +

                  Implemented

                  +                   + +

                  Phonebook Access Profile

                  +

                  No

                  +                   + +

                  SIM Access Profile

                  +

                  No

                  +                   + + +

                  Links to examples, guides, and tutorials that use the SPP will +be provided here as they become available.

                  GOEP

                  The Generic +Object Exchange Profile provides the functionality needed to use the Object +Exchange (OBEX) Protocol over Bluetooth. GOEP is used by the following profiles:

                  + + + +Bluetooth Profile +Supported + + + + +

                  Object Push Profile

                  +

                  Yes

                  +                   + +

                  File Transfer Profile

                  +

                  Yes

                  +                   + +

                  Synchronisation Profile

                  +

                  Yes

                  +                   + + +

                  GOEP makes a significant contribution to the overall offering +by providing client and server roles to the devices of the Bluetooth Piconet. +Applications using GOEP can push and pull objects from other devices in the +piconet.

                  PAN Profile

                  The +Personal Area Networking profile provides a simplification to the LAN Access +and Dial-up Networking profiles (both now deprecated), by reducing the number +of layers in a network connection. PAN enhances networking over Bluetooth +by providing new functionality such as the Group Ad-hoc Networking role, discussed +below.

                  The PAN profile provides for three possible roles: the User +(PANU), Group Ad-hoc Networking (GN) and Network Access Point (NAP).

                  When +a device is operating in the PANU role it can connect to a device operating +in any of the three roles. This allows it to act as a client to one of these +devices. When operating in the GN role the device can accept a connection +request from a PANU device or make its own request to connect to such a device. +PANU and GN roles can be switched but a PANU device connecting to a NAP device +can not switch roles because NAP is not supported.

                  PAN is integrated +into the networking framework as a plug-in. See the Networking documentation +for more information about networking with the Bluetooth PAN profile plug-in. +Therefore applications can treat a Bluetooth PAN as any other networking technology.

                  AVRCP

                  The Audio +video remote control profile implements certain aspects of the AV/C Digital +Interface Command Set (IEEE 1394) for use over a Bluetooth connection. This +profile defines two possible roles: controller (CT) and target (TG). The controller +device sends commands to the target who acts on those commands.

                  Role +switching is possible. Consider a Bluetooth headset with integrated command +functions. When the headset is acting in the CT role it can begin music playback +or switch songs on the TG Symbian device. The Symbian device can become the +CT to send a volume control command to the headset, making the headset the +TG for that transaction.

                  Features of the profile implemented in the +Symbian platform Bluetooth subsystem are presented in the following table +according to defined role.

                  + + + +CT +TG + + + + +

                  All Mandatory features.

                  +

                  All Mandatory features.

                  +                   + +

                  Sending UNIT info command.

                  +

                  Initiating connection for control.

                  +                   + +

                  Sending subunit info command.

                  +

                  Receiving pass through commands.

                  +                   + +

                  Sending pass through commands.

                  +

                  Sending all operation_ids.

                  +                   + +

                  Sending all operation_ids.

                  +

                  Receiving all operation_ids.

                  +                   + +

                  Receiving all operation_ids.

                  +

                   +                   + + +

                  AVRCP operates over a GAP connection, communicating via the Audio +Video Control Transport Protocol (AVCTP) on a channel in the L2CAP layer. +Application developers will use the Remote Control Framework for creating +apps that use the AVRCP.

                  GAVDP

                  The Generic +audio video distribution profile provides the mechanism for distributing audio +and video content over a Bluetooth connection. There are two roles defined +for GAVDP, they are: Initiator (INT) and Acceptor (ACP). INT begins a signalling +procedure and ACP responds. The roles are not linked to the master / slave +relationship between devices and can switch when a new procedure is initiated.

                  GAVDP +has been implemented in the Symbian platform Bluetooth subsystem specifically +to support the Bluetooth stereo headset usecase. The Audio Video Distribution +Transport Protocol (AVDTP) manages the transmission of audio packets over +an L2CAP channel. The GAVDP component of the Bluetooth subsystem provides +an API to configure, send and receive data over the AVDTP within an ESock +plug-in.

                  A2DP

                  The Advanced +Audio Distribution Profile describes the protocols and procedures to stream +high quality stereo audio over Bluetooth.

                  Supported Bluetooth Profiles

                  The following list indicates +profiles for which the Symbian platform subsystem has provided the necessary +framework should a licensee have a need to implement them. Application developers +should refer to the documentation for the platform(s) they are targeting to +determine which additional profiles (if any) are available for a particular +device.

                  The Bluetooth profile implementers guide, available soon, +describes how licensees can enable profiles on their devices.

                    +

                  • Advanced Audio Distribution +Profile

                    Linked to MMF.

                    • +

                  • Video Distribution Profile

                    Linked +to MMF.

                    • +

                  • File Transfer Profile

                    • +

                  • Synchronization Profile

                    • +

                  • Fax Profile

                    • +

                  • Dial Up Networking (DUN) +Profile

                    • +

                  • Headset Profile

                    • +

                  • Hands Free Profile

                    Use +the Remote Control Framework.

                    • +

                  • HID Profile

                    • +

                  • Device ID Profile

                    • +

                  • Basic Printing Profile

                    • +

                  • Basic Imaging Profile

                    • +

                  • Service Discovery Application +Profile

                    • +

                  • Unrestricted Digital +Information Profile

                    • +

                  Omitted +Bluetooth profiles

                  The following profiles are explicitly omitted +from the Current Symbian platform Bluetooth subsystem:

                    +

                  • Cordless Telephony Profile

                    • +

                  • Intercom Profile

                    • +

                  • SIM Access Profile

                    • +
                   \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EADC4EA6-4492-5A00-A29E-6F7747FCAAC9_d0e184763_href.png Binary file Symbian3/SDK/Source/GUID-EADC4EA6-4492-5A00-A29E-6F7747FCAAC9_d0e184763_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EADC4EA6-4492-5A00-A29E-6F7747FCAAC9_d0e191359_href.png Binary file Symbian3/SDK/Source/GUID-EADC4EA6-4492-5A00-A29E-6F7747FCAAC9_d0e191359_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EAFD71DD-0EB2-402A-9511-D0F3362BDCE3-master.png Binary file Symbian3/SDK/Source/GUID-EAFD71DD-0EB2-402A-9511-D0F3362BDCE3-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EAFD71DD-0EB2-402A-9511-D0F3362BDCE3_d0e67688_href.png Binary file Symbian3/SDK/Source/GUID-EAFD71DD-0EB2-402A-9511-D0F3362BDCE3_d0e67688_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EAFD71DD-0EB2-402A-9511-D0F3362BDCE3_d0e72825_href.png Binary file Symbian3/SDK/Source/GUID-EAFD71DD-0EB2-402A-9511-D0F3362BDCE3_d0e72825_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EB212C35-5416-4CA7-8091-61B45D78E220.dita --- a/Symbian3/SDK/Source/GUID-EB212C35-5416-4CA7-8091-61B45D78E220.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-EB212C35-5416-4CA7-8091-61B45D78E220.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,190 +1,191 @@ - - - - - -Toolbar -

                  The toolbar offers quick access to some of the key functions in the application -view. All of the functions must also be found from the Options menu.

                  - -Toolbar - - -

                  A tooltip is an information pop-up containing information regarding each -button must be shown.

                  -

                  Following toolbar button types can be used:

                  -
                    -

                  • Command button offering direct action (functions/view access) -like Send or New contact with a button press feedback. Related -tooltip indicates the function of the button. Command button may have a long -press functionality included such as Fast forward.

                    • -

                  • ON/OFF button can be used for active/inactive type of functions -such as Loudspeaker or Font italics. Button has related latched -down effect. Button icon graphic and tooltip indicate the function of the -button, and they stay the same regardless of the button state. No long tap -allowed.

                    • -

                  • Mode toggle button can be used for switching between several -modes as in Flash. Button icon graphic and tooltip change and should -indicate the current status.

                    • -
                  -

                  Toolbar buttons are view specific, thus within one application some views -may have toolbar and some do not. It is recommended though to keep the toolbars -as consistent as possible within an application. Changing toolbar buttons -within one view is not allowed, but button can be dimmed in case function -is not available, for example, depending on focused item in the view or currently -available services. Application may change the buttons according to product -concept.

                  -

                  The order of the toolbar buttons in different orientations is according -to the reading direction the first item is placed topmost when the toolbar -is vertical and leftmost when the toolbar is horizontal in western languages. -The appearance of functions in Toolbar should follow the order presented below.

                  -Appearance order -of toolbar functions - - - -Function type -Description - - - - -Call -Call initiation related functions - - -Reply -Replying to a message - - -Send -For sending the content in focus - - -Create new -For creating a new message, note, folder, contact or some other item - - -View switching -For functions such as Go-to or View mode switching - - -Editing -For switching to editing mode - - -Opening extension -For opening the toolbar extension in case all the functions within -the extension are a collection of options of similar type and can be grouped -under one command, for example, Insert -extension for inserting image, video, -presentation and so on. - - -Delete -Deleting the item in focus - - -More -extension -For opening the toolbar extension “More” in case the functions within -the extension are various kinds and cannot be grouped. - - - -
                  -

                  Application specific commands that do not fit into any function type described -above are to be placed between Create new and Opening the extension in the -order list.

                  -

                  The application may decide the initial state of ON/OFF and Mode toggle -button in application launch. They can also be reset or resumed from the previous -session.

                  - -Toolbar button states: example of ON/OFF type of button - - -
                  Floating toolbar

                  Floating -toolbar is a component for showing the key functions on top of the Main pane -or full screen content. It can be used in non-touch UI, but also in touch -UI.

                  Floating toolbar owns the focus, and thus it can be used only if -other content in the view does not need the focus. It means that floating -toolbar cannot be used with lists and grids.

                  Opening and closing the -floating toolbar can be done with the Show toolbar / Hide -toolbar command via the Options menu. In this case the toolbar -is open by default.

                  Floating toolbar can also be designed to be opened -via MSK labeled as Toolbar. For closing the toolbar, -there has to be then a Hide button or the toolbar is -closed after selecting a function. Navigation keys can be used as a shortcut -for opening and closing the toolbar, when not used for anything else in the -view. Time-out can be used for closing the toolbar.

                  There -can be 3-6 buttons in the floating toolbar depending on used resolution. Thus -the most important functions must be designed to be the first ones in the -toolbar; so that they are visible, for example, in case only three buttons -fit the layout.

                  When the toolbar is open, it owns the Selection key -for selecting the focused toolbar button. Toolbar does not own the right and -left softkeys. The user can move the focus over the toolbar buttons with the -Arrow keys (left and right). The focus loops, and the toolbar itself does -not scroll.

                  -
                  Floating toolbar -extension

                  Toolbar button can be reserved for opening a toolbar extension, -where more options can be found. Placement of the extension button within -toolbar can be found from the appearance order in the table Appearance order of toolbar functions. The button has a default graphic, -which the application can change if needed.

                  Toolbar extension buttons -are for similar actions as buttons in toolbar, which means the same types -and rules apply for toolbar extension buttons. Extension should be used for -accessing a set of logically similar options, for example, when selecting -content to be inserted to a message or for adjusting imaging session related -values in camera.

                  Extension can have 2 – 12 buttons (3x4 in landscape -and 4x3 in portrait). The filling order follows the grid filling rules, thus -for example most important one should be placed as first. In floating toolbar -extension, the last extension button is reserved for closing the toolbar.

                  -
                  Toolbar component -in touch UI

                  In touch UI the toolbar is either fixed in the layout, -or a floating component. Both toolbars cannot exist in one view.

                  Toolbars -are view specific, thus all views of an application do not have to have a -toolbar.

                  Selection in touch toolbars is done with a single tap, and -related tooltip is shown with stylus down.

                  -
                  Floating toolbar -in touch UI

                  The number of floating toolbar buttons in the nHD (640 -x 360 pixels) layout is three. In case floating toolbar is used in full screen, -there can be four buttons.

                  Floating toolbar owns the focus also in -touch UI, and thus cannot be used in views that have focus for main pane content.

                  Floating -toolbar can be opened and closed as in non-touch UI via the Options menu or -with the Selection key, or it can be opened by tapping the main pane area. -In this case closing is done by tapping the main pane area again, with time-out -or by selecting a function.

                  -
                  Fixed toolbar -in touch UI

                  The number of fixed toolbar buttons in the nHD (640 -x 360 pixels) layout is three. It reserves own space from the layout and does -not cover the content of main pane area.

                  Fixed toolbar does not have -a highlight, and thus it can be used in all views (whether main pane needs -the highlight or not).

                  Fixed toolbar cannot be opened or closed, but -it is always visible. Toolbar can be hidden in case other controls are also -hidden (in full screen views).

                  -Toolbar in touch UI fixed in the layout - -
                  -
                  Toolbar extension -in touch UI

                  As in non-touch UI, toolbars can have extensions also -in touch UI. For floating toolbar in touch UI, the same rules apply as defined -for floating toolbar extension in general. In touch UI, the toolbar extension -can always be closed with the same toolbar button as it was opened, or by -tapping outside the extension area.

                  In addition to general extension -rules, the toolbar extension for fixed toolbar has certain specific guidelines. -Besides buttons, the extension of fixed toolbar can include editor fields, -for example, for entering an URL or for the Find function in the browser. -The most important editor field is to be the topmost and has the cursor by -default.

                  In case editor field(s) exists, there is less space for -buttons in landscape layout compared to portrait layout.
                  -
                  Using -toolbars in C++ applications

                  The APIs to use for creating a toolbar -are the Toolbar API for -the toolbar itself and the Generic -button API for the buttons in the toolbar.

                  For implementation -information, see Enabling -quick access to functions with a toolbar.

                  + + + + + +Toolbar +

                  The toolbar offers quick access to some of the key functions in the application +view. All of the functions must also be found from the Options menu.

                  + Toolbar buttons are Generic +buttons that have touch functionality. + +Toolbar + + +

                  A tooltip is an information pop-up containing information regarding each +button must be shown.

                  +

                  Following toolbar button types can be used:

                  +
                    +

                  • Command button offering direct action (functions/view access) +like Send or New contact with a button press feedback. Related +tooltip indicates the function of the button. Command button may have a long +press functionality included such as Fast forward.

                    • +

                  • ON/OFF button can be used for active/inactive type of functions +such as Loudspeaker or Font italics. Button has related latched +down effect. Button icon graphic and tooltip indicate the function of the +button, and they stay the same regardless of the button state. No long tap +allowed.

                    • +

                  • Mode toggle button can be used for switching between several +modes as in Flash. Button icon graphic and tooltip change and should +indicate the current status.

                    • +
                  +

                  Toolbar buttons are view specific, thus within one application some views +may have toolbar and some do not. It is recommended though to keep the toolbars +as consistent as possible within an application. Changing toolbar buttons +within one view is not allowed, but button can be dimmed in case function +is not available, for example, depending on focused item in the view or currently +available services. Application may change the buttons according to product +concept.

                  +

                  The order of the toolbar buttons in different orientations is according +to the reading direction the first item is placed topmost when the toolbar +is vertical and leftmost when the toolbar is horizontal in western languages. +The appearance of functions in Toolbar should follow the order presented below.

                  +Appearance order +of toolbar functions + + + +Function type +Description + + + + +Call +Call initiation related functions + + +Reply +Replying to a message + + +Send +For sending the content in focus + + +Create new +For creating a new message, note, folder, contact or some other item + + +View switching +For functions such as Go-to or View mode switching + + +Editing +For switching to editing mode + + +Opening extension +For opening the toolbar extension in case all the functions within +the extension are a collection of options of similar type and can be grouped +under one command, for example, Insert -extension for inserting image, video, +presentation and so on. + + +Delete +Deleting the item in focus + + +More -extension +For opening the toolbar extension “More” in case the functions within +the extension are various kinds and cannot be grouped. + + + +
                  +

                  Application specific commands that do not fit into any function type described +above are to be placed between Create new and Opening the extension in the +order list.

                  +

                  The application may decide the initial state of ON/OFF and Mode toggle +button in application launch. They can also be reset or resumed from the previous +session.

                  + +Toolbar button states: example of ON/OFF type of button + + +
                  Floating toolbar

                  Floating +toolbar is a component for showing the key functions on top of the Main pane +or full screen content. It can be used in non-touch UI, but also in touch +UI.

                  Floating toolbar owns the focus, and thus it can be used only if +other content in the view does not need the focus. It means that floating +toolbar cannot be used with lists and grids.

                  Opening and closing the +floating toolbar can be done with the Show toolbar / Hide +toolbar command via the Options menu. In this case the toolbar +is open by default.

                  Floating toolbar can also be designed to be opened +via MSK labeled as Toolbar. For closing the toolbar, +there has to be then a Hide button or the toolbar is +closed after selecting a function. Navigation keys can be used as a shortcut +for opening and closing the toolbar, when not used for anything else in the +view. Time-out can be used for closing the toolbar.

                  There can be 3-6 +buttons in the floating toolbar depending on used resolution. Thus the most +important functions must be designed to be the first ones in the toolbar; +so that they are visible, for example, in case only three buttons fit the +layout.

                  When the toolbar is open, it owns the Selection key for selecting +the focused toolbar button. Toolbar does not own the right and left softkeys. +The user can move the focus over the toolbar buttons with the Arrow keys (left +and right). The focus loops, and the toolbar itself does not scroll.

                  +
                  Floating toolbar +extension

                  Toolbar button can be reserved for opening a toolbar extension, +where more options can be found. Placement of the extension button within +toolbar can be found from the appearance order in the table Appearance order of toolbar functions. The button has a default graphic, +which the application can change if needed.

                  Toolbar extension buttons +are for similar actions as buttons in toolbar, which means the same types +and rules apply for toolbar extension buttons. Extension should be used for +accessing a set of logically similar options, for example, when selecting +content to be inserted to a message or for adjusting imaging session related +values in camera.

                  Extension can have 2 – 12 buttons (3x4 in landscape +and 4x3 in portrait). The filling order follows the grid filling rules, thus +for example most important one should be placed as first. In floating toolbar +extension, the last extension button is reserved for closing the toolbar.

                  +
                  Toolbar component +in touch UI

                  In touch UI the toolbar is either fixed in the layout, +or a floating component. Both toolbars cannot exist in one view.

                  Toolbars +are view specific, thus all views of an application do not have to have a +toolbar.

                  Selection in touch toolbars is done with a single tap, and +related tooltip is shown with stylus down.

                  +
                  Floating toolbar +in touch UI

                  The number of floating toolbar buttons in the nHD (640 +x 360 pixels) layout is three. In case floating toolbar is used in full screen, +there can be four buttons.

                  Floating toolbar owns the focus also in +touch UI, and thus cannot be used in views that have focus for main pane content.

                  Floating +toolbar can be opened and closed as in non-touch UI via the Options menu or +with the Selection key, or it can be opened by tapping the main pane area. +In this case closing is done by tapping the main pane area again, with time-out +or by selecting a function.

                  +
                  Fixed toolbar +in touch UI

                  The number of fixed toolbar buttons in the nHD (640 +x 360 pixels) layout is three. It reserves own space from the layout and does +not cover the content of main pane area.

                  Fixed toolbar does not have +a highlight, and thus it can be used in all views (whether main pane needs +the highlight or not).

                  Fixed toolbar cannot be opened or closed, but +it is always visible. Toolbar can be hidden in case other controls are also +hidden (in full screen views).

                  +Toolbar in touch UI fixed in the layout + +
                  +
                  Toolbar extension +in touch UI

                  As in non-touch UI, toolbars can have extensions also +in touch UI. For floating toolbar in touch UI, the same rules apply as defined +for floating toolbar extension in general. In touch UI, the toolbar extension +can always be closed with the same toolbar button as it was opened, or by +tapping outside the extension area.

                  In addition to general extension +rules, the toolbar extension for fixed toolbar has certain specific guidelines. +Besides buttons, the extension of fixed toolbar can include editor fields, +for example, for entering an URL or for the Find function in the browser. +The most important editor field is to be the topmost and has the cursor by +default.

                  In case editor field(s) exists, there is less space for +buttons in landscape layout compared to portrait layout.
                  +
                  Using +toolbars in applications

                  The APIs to use for creating a toolbar +are the Toolbar API for +the toolbar itself and the Generic +button API for the buttons in the toolbar.

                  For implementation +information, see Enabling +quick access to functions with a toolbar.

                   \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EB58901D-66BD-56BF-B0CD-5FC4F73F06F3.dita --- a/Symbian3/SDK/Source/GUID-EB58901D-66BD-56BF-B0CD-5FC4F73F06F3.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-EB58901D-66BD-56BF-B0CD-5FC4F73F06F3.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,14 +1,14 @@ - - - - - -DevVideo Library Overview

                  This document provides an overview of the DevVideo library.

                  Purpose

                  DevVideo provides the interface between the Symbian platform and the video processing hardware for all video functionality.

                  DevVideo Library Details

                  The DLL that provides the functionality and the library to which your code must link is identified below.

                  DLL LIB Short Description

                  devvideo.dll

                  devvideo.lib

                  These files are used for implementing DevVideo.

                  Architectural Relationship

                  DevVideo provides middleware components, such as MMF controller plug-ins, access to video codecs, pre-processors and post-processors. DevVideo interacts with:

                  • MMF Controller Framework

                    The controller framework helps to manage the interface to DevVideo and provides controller plug-ins for playing and recording video data.

                  • Controller plug-ins

                    Video play and video record controller plug-ins implement play and record functionality respectively.

                  • Video Hardware Device interface

                    CMMFVideoHwDevice is the base class for all video hardware devices. Video playback hardware devices are video decoders and video post-processors. Video recording hardware devices are video pre-processors and encoders.

                    Note that, although the interface is called "Hardware Device" interface, it is possible that the codecs, and pre-processors and post-processors, are not running on a separate hardware device. They could be running on the same processor as all the other software.

                  Shown below is a representation of how DevVideo interacts with the Multimedia Framework and Media Device Framework components:

                  - DevVideo and related components -
                  Description

                  DevVideo is a hardware abstraction layer that provides access to video functionality. DevVideo functionality includes video decoding, encoding, pre-processing and post-processing.

                  Key DevVideo Classes

                  The video play and record functionality provided by DevVideo is contained within the following key classes:

                  • MMMFDevVideoPlayProxy - the interface to CMMFDevVideoPlay. Hardware devices use this interface to deliver data back to the client.

                  • CMMFDevVideoPlay - DevVideoPlay interface and implementation.

                  • MMMFDevVideoPlayObserver - set of callback functions that any client using CMMFDevVideoPlay must implement.

                  • MMMFDevVideoRecordProxy - the interface to CMMFDevVideoRecord. Hardware devices use this interface to deliver data back to the client.

                  • CMMFDevVideoRecord - DevVideoRecord interface and implementation.

                  • MMMFDevVideoRecordObserver - set of callback functions that any client using CMMFDevVideoRecord must implement.

                  Using DevVideo

                  Clients can use DevVideo to:

                  • Select the video decoder to use.

                  • Configure the video decoder.

                  • Select the video post-processor to use.

                  • Configure the video post-processor.

                  • Set clock source for timing video playback.

                  • Set video output destination.

                  • Start video playback.

                  • Pause video playback.

                  • Stop video playback.

                  • Select the video encoder to use.

                  • Configure the video encoder.

                  • Select the video pre-processor to use.

                  • Configure the video pre-processor.

                  • Set clock source for timing of video recording.

                  • Start video recording.

                  • Pause video recording.

                  • Stop video recording.

                  • Pass video buffers to and from the client.

                  • Pass pictures to and from the client.

                  See Also

                  Video Client Overview

                  \ No newline at end of file + + + + + +DevVideo Library Overview

                  This document provides an overview of the DevVideo library.

                  Purpose

                  DevVideo provides the interface between the Symbian platform and the video processing hardware for all video functionality.

                  DevVideo Library Details

                  The DLL that provides the functionality and the library to which your code must link is identified below.

                  DLL LIB Short Description

                  devvideo.dll

                  devvideo.lib

                  These files are used for implementing DevVideo.

                  Architectural Relationship

                  DevVideo provides middleware components, such as MMF controller plug-ins, access to video codecs, pre-processors and post-processors. DevVideo interacts with:

                  • MMF Controller Framework

                    The controller framework helps to manage the interface to DevVideo and provides controller plug-ins for playing and recording video data.

                  • Controller plug-ins

                    Video play and video record controller plug-ins implement play and record functionality respectively.

                  • Video Hardware Device interface

                    CMMFVideoHwDevice is the base class for all video hardware devices. Video playback hardware devices are video decoders and video post-processors. Video recording hardware devices are video pre-processors and encoders.

                    Note that, although the interface is called "Hardware Device" interface, it is possible that the codecs, and pre-processors and post-processors, are not running on a separate hardware device. They could be running on the same processor as all the other software.

                  Shown below is a representation of how DevVideo interacts with the Multimedia Framework and Media Device Framework components:

                  + DevVideo and related components +
                  Description

                  DevVideo is a hardware abstraction layer that provides access to video functionality. DevVideo functionality includes video decoding, encoding, pre-processing and post-processing.

                  Key DevVideo Classes

                  The video play and record functionality provided by DevVideo is contained within the following key classes:

                  • MMMFDevVideoPlayProxy - the interface to CMMFDevVideoPlay. Hardware devices use this interface to deliver data back to the client.

                  • CMMFDevVideoPlay - DevVideoPlay interface and implementation.

                  • MMMFDevVideoPlayObserver - set of callback functions that any client using CMMFDevVideoPlay must implement.

                  • MMMFDevVideoRecordProxy - the interface to CMMFDevVideoRecord. Hardware devices use this interface to deliver data back to the client.

                  • CMMFDevVideoRecord - DevVideoRecord interface and implementation.

                  • MMMFDevVideoRecordObserver - set of callback functions that any client using CMMFDevVideoRecord must implement.

                  Using DevVideo

                  Clients can use DevVideo to:

                  • Select the video decoder to use.

                  • Configure the video decoder.

                  • Select the video post-processor to use.

                  • Configure the video post-processor.

                  • Set clock source for timing video playback.

                  • Set video output destination.

                  • Start video playback.

                  • Pause video playback.

                  • Stop video playback.

                  • Select the video encoder to use.

                  • Configure the video encoder.

                  • Select the video pre-processor to use.

                  • Configure the video pre-processor.

                  • Set clock source for timing of video recording.

                  • Start video recording.

                  • Pause video recording.

                  • Stop video recording.

                  • Pass video buffers to and from the client.

                  • Pass pictures to and from the client.

                  See Also

                  Video Client Overview

                  \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EBD1242B-6BD9-5ABB-B471-24ABC78A918C.dita --- a/Symbian3/SDK/Source/GUID-EBD1242B-6BD9-5ABB-B471-24ABC78A918C.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-EBD1242B-6BD9-5ABB-B471-24ABC78A918C.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,14 +1,14 @@ - - - - - -MIME Recognition Framework Overview

                  The MIME (Multipurpose Internet Mail Extension) recognition framework enables data type identification.

                  The MIME recognition framework implements data type recognition using MIME (data) recognizers. The MIME recognizers are ECOM plug-ins. A MIME recognizer reads a small piece of the data. A data type can be recognized by more than one MIME recognizer. The framework uses the concepts of priority and confidence level to determine the data type.

                  The Application Architecture (AppArc) launches the appropriate application using the MIME framework to handle the data.

                  It is not guaranteed that an application will be available to handle a data type, even if it was successfully recognized.

                  Purpose

                  MIME type recognition enables devices to identify data type in streams or files and start appropriate application automatically.

                  Key concepts and terms
                  MIME

                  MIME (Multipurpose Internet Mail Extension) is an internet standard system for identifying the type of data in a file or stream. Types can include graphics, photos, audio, video files and formatted text.

                  Priority

                  The plug-in developer assigns a priority (EHigh, ENormal or ELow) to the data recognizers. A data type can be handled by more than one application and may therefore be recognized by more than one recognizer.

                  The priority determines the position at which the recognizer is inserted into the recognizer list. The higher priority recognizers are placed at the start of the list. If more than one recognizer recognizes a data type with the same confidence, the recognizer with the higher priority takes precedence. The sequence in which recognizers are invoked by the framework is determined by their priority. High priority recognizers are invoked first.

                  For more details refer to CApaDataRecognizerType::TRecognizerPriority.

                  Recognizer list

                  The MIME recognition framework maintains a list of MIME recognizers. The recognizer list is constructed based on the data types the MIME recognizers claim to support and is ordered by priority.

                  Confidence level

                  A MIME recognizer reads a small piece of data from the start of a file or stream. It attempts to match the data with one of its known types. If the match is complete it returns the associated data type with full confidence (ECertain) and if there is no match it returns no data type with no confidence (ENotRecognized). If there is a partial match it can return a data type with an intermediate confidence level (EPossible, EUnlikely, ENotRecognized).

                  The confidence of MIME recognizers can be expressed in 5 different levels:

                  • ECertain

                  • EProbable

                  • EPossible

                  • EUnlikely

                  • ENotRecognized

                  By default, the confidence level of the MIME Recognizer is ECertain.

                  For more details refer CApaDataRecognizerType::TRecognitionConfidence.

                  Architecture

                  MIME recognizers are ECOM plugins, located under \sys\bin\.

                  - MIME framework architecture -

                  • AppArc is the main client of the MIME recognition framework.

                  • Applications that need data type recognition use the MIME recognition framework via AppArc APIs.

                  • The MIME recognition framework delegates the data type identification task to an appropriate MIME recognizer.

                  • The MIME recognizer identifies the data type.

                  • AppArc launches the application for the identified data type.

                  APIs API Description

                  CApaDataRecognizerType

                  Is the abstract base class for a recognizer. Recognizers need to define and implement a derived class and provide an implementation of the functions.This class contains the MIME APIs related to MIME recognition framework.

                  RApaLsSession

                  A session with the application architecture server. The server provides access to a cached list of the applications on the device. This class contains the AppArc APIs related to MIME recognition framework.

                  Typical uses

                  The MIME recognition framework allows the plug-in writers to:

                  • Write Data(MIME) Recogzisers

                  \ No newline at end of file + + + + + +MIME Recognition Framework Overview

                  The MIME (Multipurpose Internet Mail Extension) recognition framework enables data type identification.

                  The MIME recognition framework implements data type recognition using MIME (data) recognizers. The MIME recognizers are ECOM plug-ins. A MIME recognizer reads a small piece of the data. A data type can be recognized by more than one MIME recognizer. The framework uses the concepts of priority and confidence level to determine the data type.

                  The Application Architecture (AppArc) launches the appropriate application using the MIME framework to handle the data.

                  It is not guaranteed that an application will be available to handle a data type, even if it was successfully recognized.

                  Purpose

                  MIME type recognition enables devices to identify data type in streams or files and start appropriate application automatically.

                  Key concepts and terms
                  MIME

                  MIME (Multipurpose Internet Mail Extension) is an internet standard system for identifying the type of data in a file or stream. Types can include graphics, photos, audio, video files and formatted text.

                  Priority

                  The plug-in developer assigns a priority (EHigh, ENormal or ELow) to the data recognizers. A data type can be handled by more than one application and may therefore be recognized by more than one recognizer.

                  The priority determines the position at which the recognizer is inserted into the recognizer list. The higher priority recognizers are placed at the start of the list. If more than one recognizer recognizes a data type with the same confidence, the recognizer with the higher priority takes precedence. The sequence in which recognizers are invoked by the framework is determined by their priority. High priority recognizers are invoked first.

                  For more details refer to CApaDataRecognizerType::TRecognizerPriority.

                  Recognizer list

                  The MIME recognition framework maintains a list of MIME recognizers. The recognizer list is constructed based on the data types the MIME recognizers claim to support and is ordered by priority.

                  Confidence level

                  A MIME recognizer reads a small piece of data from the start of a file or stream. It attempts to match the data with one of its known types. If the match is complete it returns the associated data type with full confidence (ECertain) and if there is no match it returns no data type with no confidence (ENotRecognized). If there is a partial match it can return a data type with an intermediate confidence level (EPossible, EUnlikely, ENotRecognized).

                  The confidence of MIME recognizers can be expressed in 5 different levels:

                  • ECertain

                  • EProbable

                  • EPossible

                  • EUnlikely

                  • ENotRecognized

                  By default, the confidence level of the MIME Recognizer is ECertain.

                  For more details refer CApaDataRecognizerType::TRecognitionConfidence.

                  Architecture

                  MIME recognizers are ECOM plugins, located under \sys\bin\.

                  + MIME framework architecture +

                  • AppArc is the main client of the MIME recognition framework.

                  • Applications that need data type recognition use the MIME recognition framework via AppArc APIs.

                  • The MIME recognition framework delegates the data type identification task to an appropriate MIME recognizer.

                  • The MIME recognizer identifies the data type.

                  • AppArc launches the application for the identified data type.

                  APIs API Description

                  CApaDataRecognizerType

                  Is the abstract base class for a recognizer. Recognizers need to define and implement a derived class and provide an implementation of the functions.This class contains the MIME APIs related to MIME recognition framework.

                  RApaLsSession

                  A session with the application architecture server. The server provides access to a cached list of the applications on the device. This class contains the AppArc APIs related to MIME recognition framework.

                  Typical uses

                  The MIME recognition framework allows the plug-in writers to:

                  • Write Data(MIME) Recogzisers

                  \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EC7E0C0E-EEB0-45B5-BE4A-11CAF78EC366-master.png Binary file Symbian3/SDK/Source/GUID-EC7E0C0E-EEB0-45B5-BE4A-11CAF78EC366-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EC7E0C0E-EEB0-45B5-BE4A-11CAF78EC366_d0e51873_href.png Binary file Symbian3/SDK/Source/GUID-EC7E0C0E-EEB0-45B5-BE4A-11CAF78EC366_d0e51873_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EC7E0C0E-EEB0-45B5-BE4A-11CAF78EC366_d0e57480_href.png Binary file Symbian3/SDK/Source/GUID-EC7E0C0E-EEB0-45B5-BE4A-11CAF78EC366_d0e57480_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EC7E0C0E-EEB0-45B5-BE4A-11CAF78EC366_d0e58382_href.png Binary file Symbian3/SDK/Source/GUID-EC7E0C0E-EEB0-45B5-BE4A-11CAF78EC366_d0e58382_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EC7E0C0E-EEB0-45B5-BE4A-11CAF78EC366_d0e62404_href.png Binary file Symbian3/SDK/Source/GUID-EC7E0C0E-EEB0-45B5-BE4A-11CAF78EC366_d0e62404_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EC7E0C0E-EEB0-45B5-BE4A-11CAF78EC366_d0e69109_href.png Binary file Symbian3/SDK/Source/GUID-EC7E0C0E-EEB0-45B5-BE4A-11CAF78EC366_d0e69109_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EC7E0C0E-EEB0-45B5-BE4A-11CAF78EC366_d0e74252_href.png Binary file Symbian3/SDK/Source/GUID-EC7E0C0E-EEB0-45B5-BE4A-11CAF78EC366_d0e74252_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EC824DA2-CA19-567C-8218-7C6E1C5ED461_d0e280024_href.png Binary file Symbian3/SDK/Source/GUID-EC824DA2-CA19-567C-8218-7C6E1C5ED461_d0e280024_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EC824DA2-CA19-567C-8218-7C6E1C5ED461_d0e283710_href.png Binary file Symbian3/SDK/Source/GUID-EC824DA2-CA19-567C-8218-7C6E1C5ED461_d0e283710_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EC98E7E0-872D-467D-BDC8-6471F6165705.dita --- a/Symbian3/SDK/Source/GUID-EC98E7E0-872D-467D-BDC8-6471F6165705.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-EC98E7E0-872D-467D-BDC8-6471F6165705.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,67 +1,69 @@ - - - - - -Universal -indicator pop-up -

                  Universal indicator pop-up is touch-only component. It is activated by -tapping the universal indicators or the digital clock. It always includes -battery and connectivity indicators and digital clock. For each visible universal -indicator, there is one row reserved in the pop-up for displaying the icon -and the description text. Hence, the user can view the preferred indicator. -The description text also informs the current status and/or it may be a link -to a view in corresponding application. For example, by tapping the text “3 -new messages” opens the relevant view from the messaging application, tapping -“Bluetooth active” switches view to the Bluetooth settings. Content of the -row is determined by the application originating the indicator.

                  - -Universal indicator pop-up - - -

                  -Default touch events in Universal indicator pop-up - - - - - - -

                  User action

                   -

                  State change

                   -

                  Feedback

                   -                   - - - -

                  Touch down and release in Universal indicator pop-up area (anywhere -except on link).

                   -

                  No change.

                  The ’information area’, which is plain text, -has no touch interaction.

                   -

                  Tactile: No effect

                   -                   - -

                  Touch down and release on function link

                   -

                  Performs appropriate action. The ’activation area’ (= link) works -with touch down and release.

                   -

                  Highlight is shown on touch down and it disappears on release.

                  Tactile: -Sensitive button effect and audio given with touch down event. No effect on -touch release.

                   -                   - -

                  Touch down and release outside Universal indicator pop-up

                   -

                  Dismisses pop-up, but no ’underlying’ action is performed.

                  Touch -down, move and touch release outside the status indicator area cancels any -action.

                   -

                  Tactile: Pop-up effect when opening and closing, irrespective of -the theme effects being ON or OFF.

                   -                   - - + + + + + +Universal +indicator pop-up +

                  Universal indicator pop-up is touch-only component. It is activated by +tapping the universal indicators or the digital clock. It always includes +battery and connectivity indicators and digital clock. For each visible universal +indicator, there is one row reserved in the pop-up for displaying the icon +and the description text. Hence, the user can view the indicator displayed +in the Universal Indicator pane. The description text also informs the current +status and/or it may be a link to a view in corresponding application. For +example, by tapping the text “3 new messages” opens the relevant view from +the messaging application, tapping “Bluetooth active” switches view to the +Bluetooth settings. Content of the row is determined by the application originating +the indicator.

                  + +Universal indicator pop-up + + +

                  +

                  Default touch +events in Universal indicator pop-up + + + + + + +

                  User action

                   +

                  State change

                   +

                  Feedback

                   +                   + + + +

                  Touch down and release in Universal indicator pop-up area (anywhere +except on link).

                   +

                  No change.

                  The ’information area’, which is plain text, +has no touch interaction.

                   +

                  Tactile: No effect

                   +                   + +

                  Touch down and release on function link

                   +

                  Performs appropriate action. The ’activation area’ (= link) works +with touch down and release.

                   +

                  Highlight is shown on touch down and it disappears on release.

                  Tactile: +Sensitive button effect and audio given with touch down event. No effect on +touch release.

                   +                   + +

                  Touch down and release outside Universal indicator pop-up

                   +

                  Dismisses pop-up, but no ’underlying’ action is performed.

                  Touch +down, move and touch release outside the status indicator area cancels any +action.

                   +

                  Tactile: Pop-up effect when opening and closing, irrespective of +the theme effects being ON or OFF.

                   +                   + +
                  \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-ECACB935-AD19-5BE6-AC27-A63465244087_d0e177456_href.png Binary file Symbian3/SDK/Source/GUID-ECACB935-AD19-5BE6-AC27-A63465244087_d0e177456_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-ECACB935-AD19-5BE6-AC27-A63465244087_d0e184050_href.png Binary file Symbian3/SDK/Source/GUID-ECACB935-AD19-5BE6-AC27-A63465244087_d0e184050_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-ECBA6331-2187-52C9-A5DF-20CD1EEFE781.dita --- a/Symbian3/SDK/Source/GUID-ECBA6331-2187-52C9-A5DF-20CD1EEFE781.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-ECBA6331-2187-52C9-A5DF-20CD1EEFE781.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,54 +1,54 @@ - - - - - -Audio Output Streaming Tutorial

                  This tutorial describes how to use Audio Output Streaming.

                  Purpose

                  The purpose of this tutorial is to show you how to open, play and then close an audio output stream.

                  Required Background

                  The user needs to maintain the data packets in a queue before starting to send it to the server. There is no need for the entire sound clip to arrive to be able to pass on to the low level audio controller. They can be forwarded as they arrive. If the server tends to receive data more than it can read or process, then a separate queue is maintained in the client side whose elements are references to the buffers passed to it. Once the server is free to receive more data the client sends the data in the queue and receives a notification from the server by means of a callback. As a result of this, the client deletes the data fragments from the queue.

                  Upon receiving the data packets the audio controller maintains them in the received buffers. A read function is instantiated to read the data into the destination descriptors.

                  Introduction

                  The Audio streaming API is the interface providing the functionalities for playing, stopping, and recording the audio stream to and from the audio buffers. The audio output stream interface class, CMdaAudioOutputStream, enables client applications to:

                  • Stream raw audio data from specified buffers to audio devices.

                  • Specify the priority of the audio stream relative to other clients trying to use the same hardware.

                  • Set the sample rate and the number of audio channels before playback.

                  • Adjust the volume and channel balance during playback.

                  Using Audio Output Streaming

                  Typically, using an audio output stream involves the following steps as shown in the sequence diagram below:

                  The following tasks will be covered in this tutorial:

                  • Constructing an audio output stream

                  • Opening an audio output stream

                  • Getting and setting the stream properties

                  • Playing an audio output stream

                  • Stopping an audio output stream

                  Basic Procedure for Constructing an Audio Output Stream

                  The high level step to construct an audio output stream is shown here:

                  • The client application creates an audio output stream object using the static function CMdaAudioOutputStream::NewL(). Optionally, it also sets the audio priorities to be able to access the audio hardware in relation to the other clients trying to access the same device.

                    static IMPORT_C CMdaAudioOutputStream *NewL(MMdaAudioOutputStreamCallback &aCallBack, -TInt aPriority, TMdaPriorityPreference aPref=EMdaPriorityPreferenceTimeAndQuality);

                  Basic Procedure for Opening an Audio Output Stream

                  The high level steps to open an audio output stream are shown here:

                  1. To open the output stream, use the Open() member function. For example:

                    virtual void Open(TMdaPackage* aSettings);

                  2. Once the stream is open MMdaAudioOutputStreamCallback::MaoscOpenComplete() is invoked to indicate that the stream is ready to use.

                    void CIOStreamAudio::MaoscOpenComplete(TInt aError) - { - ASSERT(iState==EStateOpeningOutput); - TInt error = aError; - if (error==KErrNone) - { - iState = EStateWriting; - iOutputStream->SetVolume(iOutputStream->MaxVolume()/2); - TRAP(error, iOutputStream->WriteL(iMainBuffer)); - } - if (error!=KErrNone) - { - Complete(aError); - } - }

                  Basic Procedure for Getting and Setting the Stream Properties

                  The high level steps to get and set stream properties are shown here:

                  1. To set the sampling rate and number of audio channels use SetAudioPropertiesL(). For example:

                    virtual void SetAudioPropertiesL(TInt aSampleRate, TInt aChannels);

                    You cannot set these values while playing the stream. Also, you must specify them as enums; for example, TMdaAudioDataSettings::ESampleRate8000Hz rather than 8000 (Hz).

                  2. The Volume() and GetbalanceL() member functions let you determine current volume and balance settings. For example:

                    • IMPORT_C TInt GetBalanceL() const;
                    • virtual TInt Volume();

                  3. The SetVolume() and SetBalanceL() member functions let you set the volume and balance respectively. You can use them while the stream is open, with the new settings taking immediate effect.

                  Basic Procedure for Playing an Audio Output Stream

                  The high level steps to play an audio output stream are shown here:

                  1. To play an audio stream from the current position use the WriteL() member function. For example:

                    virtual void WriteL(const TDesC8& aData);

                    This function is asynchronous.

                    When aData is received, the client is notified by a call to MdaAudioOutputStreamCallback::MaoscBufferCopied().

                    void CIOStreamAudio::MaoscBufferCopied(TInt aError, const TDesC8& IFDEBUG(aBuffer)) - { - ASSERT(iState==EStateWriting); - if (aError!=KErrNone) - { - // ignore any KErrAbort returns - this would happen during a Stop() call - // if we were playing - if (aError!=KErrAbort) - { - Complete(aError); - } - } - else - { - ASSERT(aBuffer.Length()==iMainBuffer.Length()); - // output almost complete - have been asked for more data - iState = EStateWritingPostBuffer; - } - }

                    The WriteL() can be called again before this notification is triggered because the buffers are held in a client-side queue until they have been sent.

                  2. When the audio stream has completed playing, the callback function MMdaAudioOutputStreamCallback::MaoscPlayComplete() is invoked.

                    void CIOStreamAudio::MaoscPlayComplete(TInt aError) - { - ASSERT(iState==EStateWriting || iState==EStateWritingPostBuffer); - TInt error = aError; - if (aError==KErrUnderflow && iState==EStateWritingPostBuffer) - { - error = KErrNone; // normal termination is underflow following buffer request - } - Complete(error); + + + + + +Audio Output Streaming Tutorial

                    This tutorial describes how to use Audio Output Streaming.

                    Purpose

                    The purpose of this tutorial is to show you how to open, play and then close an audio output stream.

                    Required Background

                    The user needs to maintain the data packets in a queue before starting to send it to the server. There is no need for the entire sound clip to arrive to be able to pass on to the low level audio controller. They can be forwarded as they arrive. If the server tends to receive data more than it can read or process, then a separate queue is maintained in the client side whose elements are references to the buffers passed to it. Once the server is free to receive more data the client sends the data in the queue and receives a notification from the server by means of a callback. As a result of this, the client deletes the data fragments from the queue.

                    Upon receiving the data packets the audio controller maintains them in the received buffers. A read function is instantiated to read the data into the destination descriptors.

                    Introduction

                    The Audio streaming API is the interface providing the functionalities for playing, stopping, and recording the audio stream to and from the audio buffers. The audio output stream interface class, CMdaAudioOutputStream, enables client applications to:

                    • Stream raw audio data from specified buffers to audio devices.

                    • Specify the priority of the audio stream relative to other clients trying to use the same hardware.

                    • Set the sample rate and the number of audio channels before playback.

                    • Adjust the volume and channel balance during playback.

                    Using Audio Output Streaming

                    Typically, using an audio output stream involves the following steps as shown in the sequence diagram below:

                    The following tasks will be covered in this tutorial:

                    • Constructing an audio output stream

                    • Opening an audio output stream

                    • Getting and setting the stream properties

                    • Playing an audio output stream

                    • Stopping an audio output stream

                    Basic Procedure for Constructing an Audio Output Stream

                    The high level step to construct an audio output stream is shown here:

                    • The client application creates an audio output stream object using the static function CMdaAudioOutputStream::NewL(). Optionally, it also sets the audio priorities to be able to access the audio hardware in relation to the other clients trying to access the same device.

                      static IMPORT_C CMdaAudioOutputStream *NewL(MMdaAudioOutputStreamCallback &aCallBack, +TInt aPriority, TMdaPriorityPreference aPref=EMdaPriorityPreferenceTimeAndQuality);

                    Basic Procedure for Opening an Audio Output Stream

                    The high level steps to open an audio output stream are shown here:

                    1. To open the output stream, use the Open() member function. For example:

                      virtual void Open(TMdaPackage* aSettings);

                    2. Once the stream is open MMdaAudioOutputStreamCallback::MaoscOpenComplete() is invoked to indicate that the stream is ready to use.

                      void CIOStreamAudio::MaoscOpenComplete(TInt aError) + { + ASSERT(iState==EStateOpeningOutput); + TInt error = aError; + if (error==KErrNone) + { + iState = EStateWriting; + iOutputStream->SetVolume(iOutputStream->MaxVolume()/2); + TRAP(error, iOutputStream->WriteL(iMainBuffer)); + } + if (error!=KErrNone) + { + Complete(aError); + } + }

                    Basic Procedure for Getting and Setting the Stream Properties

                    The high level steps to get and set stream properties are shown here:

                    1. To set the sampling rate and number of audio channels use SetAudioPropertiesL(). For example:

                      virtual void SetAudioPropertiesL(TInt aSampleRate, TInt aChannels);

                      You cannot set these values while playing the stream. Also, you must specify them as enums; for example, TMdaAudioDataSettings::ESampleRate8000Hz rather than 8000 (Hz).

                    2. The Volume() and GetbalanceL() member functions let you determine current volume and balance settings. For example:

                      • IMPORT_C TInt GetBalanceL() const;
                      • virtual TInt Volume();

                    3. The SetVolume() and SetBalanceL() member functions let you set the volume and balance respectively. You can use them while the stream is open, with the new settings taking immediate effect.

                    Basic Procedure for Playing an Audio Output Stream

                    The high level steps to play an audio output stream are shown here:

                    1. To play an audio stream from the current position use the WriteL() member function. For example:

                      virtual void WriteL(const TDesC8& aData);

                      This function is asynchronous.

                      When aData is received, the client is notified by a call to MdaAudioOutputStreamCallback::MaoscBufferCopied().

                      void CIOStreamAudio::MaoscBufferCopied(TInt aError, const TDesC8& IFDEBUG(aBuffer)) + { + ASSERT(iState==EStateWriting); + if (aError!=KErrNone) + { + // ignore any KErrAbort returns - this would happen during a Stop() call + // if we were playing + if (aError!=KErrAbort) + { + Complete(aError); + } + } + else + { + ASSERT(aBuffer.Length()==iMainBuffer.Length()); + // output almost complete - have been asked for more data + iState = EStateWritingPostBuffer; + } + }

                      The WriteL() can be called again before this notification is triggered because the buffers are held in a client-side queue until they have been sent.

                    2. When the audio stream has completed playing, the callback function MMdaAudioOutputStreamCallback::MaoscPlayComplete() is invoked.

                      void CIOStreamAudio::MaoscPlayComplete(TInt aError) + { + ASSERT(iState==EStateWriting || iState==EStateWritingPostBuffer); + TInt error = aError; + if (aError==KErrUnderflow && iState==EStateWritingPostBuffer) + { + error = KErrNone; // normal termination is underflow following buffer request + } + Complete(error); }

                      This closes the stream and sets the callback aError to KErrUnderFlow.

                    Basic Procedure for Stopping an Audio Output Stream

                    The high level step to stop an audio output stream is shown here:

                    • To stop audio playback (stop data being sent to the stream) use the Stop() member function.

                      For example:

                      virtual void Stop();

                      This invokes MMdaAudioOutputStreamCallback::MaoscPlayComplete() to notify successful closure of the stream.

                    See Also

                    Audio Input Streaming Tutorial

                    \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-ED198434-94C0-4842-8353-B2FA319BA5C7.dita --- a/Symbian3/SDK/Source/GUID-ED198434-94C0-4842-8353-B2FA319BA5C7.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-ED198434-94C0-4842-8353-B2FA319BA5C7.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,46 +1,55 @@ - - - - - -Warning -note -

                    Warning -notes are used when the user must be notified about something that may require -action. They have a fairly long duration, and a sound that can be heard (and -distinguished) even when not concentrating on the phone. For example, the -battery low warning.

                    -
                    Using -warning notes in C++ applications

                    You can create either a basic -warning note that is displayed only when your application is in the foreground -or a global note that stays displayed even if the application launching the -note is not in the foreground. The related APIs are the Notes -API (for basic notes) and the Notifiers API (for global notes).

                    To use a warning -note with the default icon, text, sound, and duration, create an instance -of the note class CAknWarningNote.

                    To create a global -warning note, use the class CAknGlobalNote in the Notifiers API. For implementation information, see Using global notes and Using global notes with user interaction.

                    For basic -notes, you can change the icon or text displayed in the note, use a different -kind of sound, or change the note duration using the setter methods in the -class CAknNoteDialog: SetIconL(),SetTextL(), SetTone() and SetTimeout().

                    For information on customizing global notes, see Enhancing global notes. You can change the -graphic, animation, tone, and softkeys using the methods in the class CAknGlobalNote: SetGraphic(), SetAnimation(), SetTone(), and SetSoftkeys().

                    - -                     -Confirmation -note -Information -note -Error note - -Permanent -note -Wait note - -Progress -note + + + + + +Warning +note +

                    Warning +notes are used when the user must be notified about something that may require +action. They have a fairly long duration, and a sound that can be heard (and +distinguished) even when not concentrating on the phone. For example, the +battery low warning.

                    +
                    Using +warning notes in applications

                    You can create either a basic warning +note that is displayed only when your application is in the foreground or +a global note that stays displayed even if the application launching the note +is not in the foreground. The related APIs are the Notes API (for basic notes) and the Notifiers API (for global notes).

                    To use a warning +note with the default icon, text, sound, and duration, create an instance +of the note class CAknWarningNote.

                    To create a global +warning note, use the class CAknGlobalNote in the Notifiers API. For implementation information, see Using global notes and Using global notes with user interaction.

                    For basic +notes, you can change the icon or text displayed in the note, use a different +kind of sound, or change the note duration using the setter methods in the +class CAknNoteDialog:

                      +

                    • CAknNoteDialog::SetIconL()

                      • +

                    • CAknNoteDialog::SetTextL()

                      • +

                    • CAknNoteDialog::SetTone()

                      • +

                    • CAknNoteDialog::SetTimeout()

                      • +

                    For information on customizing global notes, see Enhancing global notes. You can change the graphic, animation, +tone, and softkeys using the methods in the class CAknGlobalNote:

                      +

                    • CAknGlobalNote::SetGraphic()

                      • +

                    • CAknGlobalNote::SetAnimation()

                      • +

                    • CAknGlobalNote::SetTone()

                      • +

                    • CAknGlobalNote::SetSoftkeys()

                      • +

                    + +                     +Confirmation +note +Information +note +Error note + +Permanent +note +Wait note + +Progress +note                     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-ED784025-4E65-4BE9-ADA8-A13427B6EA30.dita --- a/Symbian3/SDK/Source/GUID-ED784025-4E65-4BE9-ADA8-A13427B6EA30.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-ED784025-4E65-4BE9-ADA8-A13427B6EA30.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,173 +1,173 @@ - - - - - -Markable -list -

                    A markable list is a selection list with the added marking feature. The -user can mark any number of items on the list while browsing it, and then -execute a single command, which is applied to all the marked items. This is -analogous to the multiple-item highlight feature used in computer GUIs.

                    -

                    The marking feature is typically applied to lists the user manages, containing -a large number of items that may be for example sent, moved, or deleted. By -marking items first and then selecting a command, the user can perform certain -operations more quickly and with less key presses than by performing the command -separately for each of the items.

                    -

                    Marked items are indicated graphically.

                    - -Markable list. Marked items are indicated graphically in the list. - - -

                    The Mark and Unmark functions are available in the Options -menu of the markable list. Alternatively, or as a shortcut, the user can keep -the Hash (#) key pressed while using the Arrow keys and the Selection key -in the following way:

                    -
                      -

                    • Pressing the Hash (#) key marks the current item. This is a toggling -function, so pressing the Hash (#) key on a marked item unmarks the item.

                      • -

                    • Pressing an Arrow key (up or down) while holding down the Hash (#) -key marks both the current item and the one onto which the focus moves. If -the user keeps holding the Hash (#) key and scrolls further in the same direction, -all the scrolled items become marked; to unmark the items in reverse order -the user can scroll into the opposite direction while holding the Hash (#) -key down.

                      • -

                    • Items can be unmarked by pressing the Hash (#) key together with scrolling: -if the user starts holding the Hash (#) key down when on a marked item and -then scrolls, all the scrolled items become unmarked.

                      • -

                    • Several marking actions can be done subsequently. The user can mark -an item, then release the Hash (#) key, browse and move the focus onto some -other item on the list, and then mark that item. The first item remains marked, -and the ones between the two do not become marked.

                      • -

                    • All items become unmarked when the user exits the list, for example -by back stepping. There may be exceptions to this rule in certain applications -that require selecting items from several levels of folder hierarchy. An example -of this is creating a play list in the Media Player application. Items remain -marked if the user opens and cancels the Options menu, or swaps applications.

                      • -

                    • Pressing the Selection key when there are marked items on the list -opens the context sensitive Options menu containing only those functions -that apply to multiple items.

                      • -
                    -

                    A markable list functions exactly like a normal selection list, except -for the marking feature.

                    -

                    Devices that have the optional Edit key perform these same functions by -using the Edit key and arrow keys instead of the Hash (#) key.

                    -

                    The user may access the Options menu to perform functions on all -marked items at once. When user has one or more items marked, Options menu -does not contain items that apply to one item only (such as Open). -Exceptions are Help and Exit, which should appear in every Options menu. -Appropriate error handling must be designed for functions that do not apply -to some or all of the marked items.

                    -
                      -

                    • When executing a function, if any of the items are marked, all the -marked items are affected by the function. If the focus is on an item that -is not marked, the function does not affect that item.

                      • -

                    • After the selected function is successfully done, all items are unmarked. -In an error case, when the function cannot be applied, the marks should remain -in place.

                      • -
                    -

                    The Options menu includes the marking and unmarking functions in a submenu -so that any user can find the feature. The submenu has also the Mark all and Unmark all -options.

                    -

                    For other keypad actions, see Selection -list.

                    -Default touch -events for Markable lists - - - -

                    User action

                     -

                    State change

                     -

                    Feedback

                     -                     - - - -

                    Touch down

                     -

                    The marked/unmarked status of all items remains unchanged.

                     -

                    Highlight is shown.

                    Tactile: Basic list effect and audio -feedback is provided with touch down.

                     -                     - -

                    Touch release, while no item is marked

                     -

                    Activates the item

                     -

                    Highlight disappears.

                    Tactile: Basic list effect is provided -with touch release event.

                     -                     - -

                    Touch down and hold, while no item is marked

                     -

                    Stylus pop-up menu is opened with an option Mark §QTN_OPTIONS_LIST_MARK_ONE§.

                    If -user selects Mark, the pop-up is closed, highlight removed and the item becomes -marked.

                     -

                    Highlight is shown. Animation is shown to indicate the opening pop-up.

                    Tactile: -If activates a long touch, then increasing long touch effect is provided with -hold event and pop-up effect is provided when the pop-up is opened.

                     -                     - -

                    Touch release, while at least one item is marked

                     -

                    A context specific options menu opens. The marked/unmarked status -of all items remains unchanged.

                    Context specific options menu should -contain items for Mark/Unmark and any needed items that apply to all marked -items.

                     -

                    Highlight disappears. Tactile: Pop-up open effect is provided. If -pop-up has theme effects and they are ON, then increasing long touch effect -is provided with touch release.

                     -                     - -

                    Touch down and hold, while at least one item is marked

                     -

                    Inactive

                     -

                    Tactile: No effect

                     -                     - - -
                    -

                    -Default touch/key -events for markable lists - - - -

                    User action

                     -

                    State change

                     -

                    Feedback

                     -                     - - - -

                    Control and touch down

                     -

                    Mark/unmark the item touched.

                    Toggle between marked and unmarked.

                     -

                    Highlight is shown.

                    Tactile: Basic list effect and audio -feedback is provided with touch down.

                     -                     - -

                    Control and touch release

                     -

                    No effect

                     -

                    Highlight disappears.

                    Tactile: No effect.

                     -                     - -

                    Shift and touch down

                     -

                    If there is highlight brought by the hardware key event, mark/unmark -all items between focused and touched down item.

                    If the item touched -down is unmarked, then all items between the item and focused item are marked, -and vice versa.

                     -

                    Highlight is shown.

                    Tactile: Basic list effect and audio feedback -is provided with touch down.

                     -                     - -

                    Control/Shift and touch down and hold

                     -

                    Inactive

                     -

                    Tactile: No effect

                     -                     - - -
                    -

                    Using -markable lists in C++ applications

                    The API to use for markable lists -is the Lists API. For implementation information, see Using the Lists API.

                    + + + + + +Markable +list +

                    A markable list is a selection list with the added marking feature. The +user can mark any number of items on the list while browsing it, and then +execute a single command, which is applied to all the marked items. This is +analogous to the multiple-item highlight feature used in computer GUIs.

                    +

                    The marking feature is typically applied to lists the user manages, containing +a large number of items that may be for example sent, moved, or deleted. By +marking items first and then selecting a command, the user can perform certain +operations more quickly and with less key presses than by performing the command +separately for each of the items.

                    +

                    Marked items are indicated graphically.

                    + +Markable list. Marked items are indicated graphically in the list. + + +

                    The Mark and Unmark functions are available in the Options +menu of the markable list. Alternatively, or as a shortcut, the user can keep +the Hash (#) key pressed while using the Arrow keys and the Selection key +in the following way:

                    +
                      +

                    • Pressing the Hash (#) key marks the current item. This is a toggling +function, so pressing the Hash (#) key on a marked item unmarks the item.

                      • +

                    • Pressing an Arrow key (up or down) while holding down the Hash (#) +key marks both the current item and the one onto which the focus moves. If +the user keeps holding the Hash (#) key and scrolls further in the same direction, +all the scrolled items become marked; to unmark the items in reverse order +the user can scroll into the opposite direction while holding the Hash (#) +key down.

                      • +

                    • Items can be unmarked by pressing the Hash (#) key together with scrolling: +if the user starts holding the Hash (#) key down when on a marked item and +then scrolls, all the scrolled items become unmarked.

                      • +

                    • Several marking actions can be done subsequently. The user can mark +an item, then release the Hash (#) key, browse and move the focus onto some +other item on the list, and then mark that item. The first item remains marked, +and the ones between the two do not become marked.

                      • +

                    • All items become unmarked when the user exits the list, for example +by back stepping. There may be exceptions to this rule in certain applications +that require selecting items from several levels of folder hierarchy. An example +of this is creating a play list in the Media Player application. Items remain +marked if the user opens and cancels the Options menu, or swaps applications.

                      • +

                    • Pressing the Selection key when there are marked items on the list +opens the context sensitive Options menu containing only those functions +that apply to multiple items.

                      • +
                    +

                    A markable list functions exactly like a normal selection list, except +for the marking feature.

                    +

                    Devices that have the optional Edit key perform these same functions by +using the Edit key and arrow keys instead of the Hash (#) key.

                    +

                    The user may access the Options menu to perform functions on all +marked items at once. When user has one or more items marked, Options menu +does not contain items that apply to one item only (such as Open). +Exceptions are Help and Exit, which should appear in every Options menu. +Appropriate error handling must be designed for functions that do not apply +to some or all of the marked items.

                    +
                      +

                    • When executing a function, if any of the items are marked, all the +marked items are affected by the function. If the focus is on an item that +is not marked, the function does not affect that item.

                      • +

                    • After the selected function is successfully done, all items are unmarked. +In an error case, when the function cannot be applied, the marks should remain +in place.

                      • +
                    +

                    The Options menu includes the marking and unmarking functions in a submenu +so that any user can find the feature. The submenu has also the Mark all and Unmark all +options.

                    +

                    For other keypad actions, see Selection +list.

                    +Default touch +events for Markable lists + + + +

                    User action

                     +

                    State change

                     +

                    Feedback

                     +                     + + + +

                    Touch down

                     +

                    The marked/unmarked status of all items remains unchanged.

                     +

                    Highlight is shown.

                    Tactile: Basic list effect and audio +feedback is provided with touch down.

                     +                     + +

                    Touch release, while no item is marked

                     +

                    Activates the item

                     +

                    Highlight disappears.

                    Tactile: Basic list effect is provided +with touch release event.

                     +                     + +

                    Touch down and hold, while no item is marked

                     +

                    Stylus pop-up menu is opened with an option Mark §QTN_OPTIONS_LIST_MARK_ONE§.

                    If +user selects Mark, the pop-up is closed, highlight removed and the item becomes +marked.

                     +

                    Highlight is shown. Animation is shown to indicate the opening pop-up.

                    Tactile: +If activates a long touch, then increasing long touch effect is provided with +hold event and pop-up effect is provided when the pop-up is opened.

                     +                     + +

                    Touch release, while at least one item is marked

                     +

                    A context specific options menu opens. The marked/unmarked status +of all items remains unchanged.

                    Context specific options menu should +contain items for Mark/Unmark and any needed items that apply to all marked +items.

                     +

                    Highlight disappears. Tactile: Pop-up open effect is provided. If +pop-up has theme effects and they are ON, then increasing long touch effect +is provided with touch release.

                     +                     + +

                    Touch down and hold, while at least one item is marked

                     +

                    Inactive

                     +

                    Tactile: No effect

                     +                     + + +
                    +

                    +Default touch/key +events for markable lists + + + +

                    User action

                     +

                    State change

                     +

                    Feedback

                     +                     + + + +

                    Control and touch down

                     +

                    Mark/unmark the item touched.

                    Toggle between marked and unmarked.

                     +

                    Highlight is shown.

                    Tactile: Basic list effect and audio +feedback is provided with touch down.

                     +                     + +

                    Control and touch release

                     +

                    No effect

                     +

                    Highlight disappears.

                    Tactile: No effect.

                     +                     + +

                    Shift and touch down

                     +

                    If there is highlight brought by the hardware key event, mark/unmark +all items between focused and touched down item.

                    If the item touched +down is unmarked, then all items between the item and focused item are marked, +and vice versa.

                     +

                    Highlight is shown.

                    Tactile: Basic list effect and audio feedback +is provided with touch down.

                     +                     + +

                    Control/Shift and touch down and hold

                     +

                    Inactive

                     +

                    Tactile: No effect

                     +                     + + +
                    +

                    Using +markable lists in applications

                    The API to use for markable lists +is the Lists API. For implementation information, see Using the Lists API.

                     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-ED823C5E-A59B-476A-BF88-0FCBA5D35FED_d0e72175_href.png Binary file Symbian3/SDK/Source/GUID-ED823C5E-A59B-476A-BF88-0FCBA5D35FED_d0e72175_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-ED823C5E-A59B-476A-BF88-0FCBA5D35FED_d0e77324_href.png Binary file Symbian3/SDK/Source/GUID-ED823C5E-A59B-476A-BF88-0FCBA5D35FED_d0e77324_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-ED823C5E-A59B-476A-BF88-0FCBA5D35FED_d0e79634_href.png Binary file Symbian3/SDK/Source/GUID-ED823C5E-A59B-476A-BF88-0FCBA5D35FED_d0e79634_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EDBCCC26-BA4D-4318-9F0D-62272FA97BBF-master.png Binary file Symbian3/SDK/Source/GUID-EDBCCC26-BA4D-4318-9F0D-62272FA97BBF-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EDBCCC26-BA4D-4318-9F0D-62272FA97BBF_d0e51678_href.png Binary file Symbian3/SDK/Source/GUID-EDBCCC26-BA4D-4318-9F0D-62272FA97BBF_d0e51678_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EDBCCC26-BA4D-4318-9F0D-62272FA97BBF_d0e67259_href.png Binary file Symbian3/SDK/Source/GUID-EDBCCC26-BA4D-4318-9F0D-62272FA97BBF_d0e67259_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EDBCCC26-BA4D-4318-9F0D-62272FA97BBF_d0e72462_href.png Binary file Symbian3/SDK/Source/GUID-EDBCCC26-BA4D-4318-9F0D-62272FA97BBF_d0e72462_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EDC16636-B24E-598B-9084-EAE782A4A213.dita --- a/Symbian3/SDK/Source/GUID-EDC16636-B24E-598B-9084-EAE782A4A213.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-EDC16636-B24E-598B-9084-EAE782A4A213.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,76 +1,76 @@ - - - - - -What -is Bearer MobilityThis topic describes the concept of Bearer Mobility in the -Communications Framework. -

                    Bearer Mobility is a feature that allows a device to change bearers without -interruption to the user's data sessions. An example of a bearer change is -if a device moves into the range of a Wi-Fi hot spot and the device moves -the GPRS connections over to Wi-Fi. Example data sessions include: streaming -videos; surfing the internet; and downloading emails. Example bearers include: -Wireless LAN (eg Wi-Fi); 3G (including HSUPA and HSDPA); Circuit Switched -Data (CSD); and GPRS.

                    - - Example of a bearer change -

                    A device is connected to a mobile network using GPRS. The device -comes into range of a Wi-Fi network. The device decides to change to the Wi-Fi -network and creates a bearer to access the Wi-Fi network. The device then -moves all the existing connections across to the Wi-Fi bearer. In the final -step the device disconnects from the GPRS network.

                    - -                     -

                    Bearer Mobility operates in response to changes in the environment of the -device. A bearer is known as available when the device is in range -of the bearer and the device can potentially use the bearer.

                    -

                    NOTE: The bearer can be available but unusable because of the security -requirements of the bearer.

                    -

                    Symbian platform uses non-seamless Bearer Mobility. Non-seamless -indicates that clients of the Socket Server must reconnect all sockets after -the bearer has changed. The local IP address of the link changes if the bearer -changes.

                    -
                    Bearer Mobility APIs

                    Two Socket Server Bearer Mobility -APIs are available: RCommsMobilityApiExt and CActiveCommsMobilityApiExt. -A client of the Socket Server cannot change bearer if the client does not -use at least one Bearer Mobility API. A device can have clients that support -Bearer Mobility and clients that do not support Bearer Mobility. If clients -that support Bearer Mobility change bearer, the device does not disconnect -a client that does not support Bearer Mobility unless that client's bearer -is no longer available.

                    A client of the socket server can ask the -user to accept or deny the change of bearer. For example, the client can display -a dialog box to ask the user to accept or deny the change. The decision to -ask the user remains with the client.

                    A client of the socket server -can ask to use the default bearer. The default bearer is the highest priority -bearer that is available. The device manufacturer or network operator creates -the list of bearer priorities.

                    -
                    Bearer Mobility -Blacklists

                    The Bearer Mobility components in the Communications -Architecture implement a blacklist feature. The Socket Server implements -the blacklist feature on the server side. The blacklist feature affects the -notifications that a Socket Server client receives. The blacklist feature -stops notifications for bearer changes that have previously been rejected. -The device keeps a blacklist for each client.

                    For example:

                      -

                    1. A client receives a -notification for a bearer change

                      2. -

                    2. The client sends a response -to reject the bearer change

                      3. -

                    3. The device adds the -rejected bearer to the blacklist for that client

                      4. -

                    4. The device does not -notify the client of any further opportunities to change to that bearer

                      5. -

                    There can be variations in the operation of the blacklist. For example, -there can be a limit on the lifetime of the blacklist.

                    NOTE: The -blacklist scheme is dependent on the plug-ins and settings used for the Communications -Architecture for the particular device.

                    -                     -Using the - Bearer Mobility APIs + + + + + +What +is Bearer MobilityThis topic describes the concept of Bearer Mobility in the +Communications Framework. +

                    Bearer Mobility is a feature that allows a device to change bearers without +interruption to the user's data sessions. An example of a bearer change is +if a device moves into the range of a Wi-Fi hot spot and the device moves +the GPRS connections over to Wi-Fi. Example data sessions include: streaming +videos; surfing the internet; and downloading emails. Example bearers include: +Wireless LAN (eg Wi-Fi); 3G (including HSUPA and HSDPA); Circuit Switched +Data (CSD); and GPRS.

                    + + Example of a bearer change +

                    A device is connected to a mobile network using GPRS. The device +comes into range of a Wi-Fi network. The device decides to change to the Wi-Fi +network and creates a bearer to access the Wi-Fi network. The device then +moves all the existing connections across to the Wi-Fi bearer. In the final +step the device disconnects from the GPRS network.

                    + +                     +

                    Bearer Mobility operates in response to changes in the environment of the +device. A bearer is known as available when the device is in range +of the bearer and the device can potentially use the bearer.

                    +

                    NOTE: The bearer can be available but unusable because of the security +requirements of the bearer.

                    +

                    Symbian platform uses non-seamless Bearer Mobility. Non-seamless +indicates that clients of the Socket Server must reconnect all sockets after +the bearer has changed. The local IP address of the link changes if the bearer +changes.

                    +
                    Bearer Mobility APIs

                    Two Socket Server Bearer Mobility +APIs are available: RCommsMobilityApiExt and CActiveCommsMobilityApiExt. +A client of the Socket Server cannot change bearer if the client does not +use at least one Bearer Mobility API. A device can have clients that support +Bearer Mobility and clients that do not support Bearer Mobility. If clients +that support Bearer Mobility change bearer, the device does not disconnect +a client that does not support Bearer Mobility unless that client's bearer +is no longer available.

                    A client of the socket server can ask the +user to accept or deny the change of bearer. For example, the client can display +a dialog box to ask the user to accept or deny the change. The decision to +ask the user remains with the client.

                    A client of the socket server +can ask to use the default bearer. The default bearer is the highest priority +bearer that is available. The device manufacturer or network operator creates +the list of bearer priorities.

                    +
                    Bearer Mobility +Blacklists

                    The Bearer Mobility components in the Communications +Architecture implement a blacklist feature. The Socket Server implements +the blacklist feature on the server side. The blacklist feature affects the +notifications that a Socket Server client receives. The blacklist feature +stops notifications for bearer changes that have previously been rejected. +The device keeps a blacklist for each client.

                    For example:

                      +

                    1. A client receives a +notification for a bearer change

                      2. +

                    2. The client sends a response +to reject the bearer change

                      3. +

                    3. The device adds the +rejected bearer to the blacklist for that client

                      4. +

                    4. The device does not +notify the client of any further opportunities to change to that bearer

                      5. +

                    There can be variations in the operation of the blacklist. For example, +there can be a limit on the lifetime of the blacklist.

                    NOTE: The +blacklist scheme is dependent on the plug-ins and settings used for the Communications +Architecture for the particular device.

                    +                     +Using the + Bearer Mobility APIs                     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EDC405DC-F222-59CD-836E-180F8E1D2D11_d0e190360_href.png Binary file Symbian3/SDK/Source/GUID-EDC405DC-F222-59CD-836E-180F8E1D2D11_d0e190360_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EDC405DC-F222-59CD-836E-180F8E1D2D11_d0e195368_href.png Binary file Symbian3/SDK/Source/GUID-EDC405DC-F222-59CD-836E-180F8E1D2D11_d0e195368_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EDDEA6A0-D45D-5241-B594-94ADDD803646.dita --- a/Symbian3/SDK/Source/GUID-EDDEA6A0-D45D-5241-B594-94ADDD803646.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-EDDEA6A0-D45D-5241-B594-94ADDD803646.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,44 +1,44 @@ - - - - - -Rendezvous -Thread rendezvous example codeThis example demonstrates the use of Rendezvous() API. -
                    Purpose

                    The code is a simple example that shows -the principle of synchronization using the thread rendezvous technique.

                    -
                    Class summary
                      -

                    • RThread - A handle to a thread.

                      • -
                    -
                    Download

                    Download the example: Rendezvous.zip.

                    Download some additional files -required by the example: CommonFramework.zip.

                    View the source code: browse. View the additional files: browse

                    -
                    Building and -configuring
                      -

                    • You can build the example -from your IDE or the command line.

                      If you use an IDE, import the bld.inf file -of the example into your IDE, and use the build command of the IDE.

                      If -you use the command line, open a command prompt, and set the current directory -to the source code directory of the example. You can then build the example -with the SBSv1 build tools with the following commands:

                      bldmake -bldfiles

                      abld build

                      How to use bldmake and How to use abld describe -how to use the SBSv1 build tools.

                      • -

                    • For the emulator, the -example builds an executable called threadrendezvous.exe in -the epoc32\release\winscw\<udeb or urel>\ folder.

                      • -
                    -
                    Running the example

                    When running the example, the -user is presented with various menu options that are self explanatory. The -code is a simple example that shows the principle of synchronization using -the thread rendezvous technique.

                    -                     - -Synchronisation -techniques - + + + + + +Rendezvous +Thread rendezvous example codeThis example demonstrates the use of Rendezvous() API. +
                    Purpose

                    The code is a simple example that shows +the principle of synchronization using the thread rendezvous technique.

                    +
                    Class summary
                      +

                    • RThread - A handle to a thread.

                      • +
                    +
                    Download

                    Download the example: Rendezvous.zip.

                    Download some additional files +required by the example: CommonFramework.zip.

                    View the source code: browse. View the additional files: browse

                    +
                    Building and +configuring
                      +

                    • You can build the example +from your IDE or the command line.

                      If you use an IDE, import the bld.inf file +of the example into your IDE, and use the build command of the IDE.

                      If +you use the command line, open a command prompt, and set the current directory +to the source code directory of the example. You can then build the example +with the SBSv1 build tools with the following commands:

                      bldmake +bldfiles

                      abld build

                      How to use bldmake and How to use abld describe +how to use the SBSv1 build tools.

                      • +

                    • For the emulator, the +example builds an executable called threadrendezvous.exe in +the epoc32\release\winscw\<udeb or urel>\ folder.

                      • +
                    +
                    Running the example

                    When running the example, the +user is presented with various menu options that are self explanatory. The +code is a simple example that shows the principle of synchronization using +the thread rendezvous technique.

                    +                     + +Synchronisation +techniques +                     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EDE54D27-D902-5C67-BF8E-5E7E0A33A98E.dita --- a/Symbian3/SDK/Source/GUID-EDE54D27-D902-5C67-BF8E-5E7E0A33A98E.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-EDE54D27-D902-5C67-BF8E-5E7E0A33A98E.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,12 +1,12 @@ - - - - - -ASN-PKCS OverviewThe ASN-PKCS component provides interfaces for:

                    • Performing ASN.1 -DER (Abstract Syntax Notation One - Distinguished Encoding Rules) encoding and decoding of PKCS (Public-Key Cryptography Standards) private keys in raw text as well as PBE (Password-Based Encryption) encrypted forms.

                    • Performing ASN.1 encoding and decoding of PBE parameters associated with the private keys.

                    Key concepts and terms
                    Key

                    A cryptography key is a constant value applied using a cryptographic algorithm to encrypt text or to decrypt encrypted text.

                    Keys are classified as symmetric and asymmetric based on the type of algorithm applied. If the same key is used for both encryption and decryption, it is symmetric. If different keys are used for encryption and decryption, they are asymmetric. Asymmetric keys exist in the form of a public and private key pair, where the public key is used for encryption and the private key is used for decryption.

                    Key Store

                    A key store is a repository of keys that can be retrieved and used to accomplish a variety of tasks.

                    The key store provides the following functionality:

                    • Generation, import and export of RSA, DSA, and DH key pairs

                    • Listing of stored keys

                    • Authentication of users

                    • Private key operations for authenticated users

                    Architecture

                    The following block diagram describes the interaction of the ASN-PKCS component with the certificate and key stores:

                    The client application accesses the various certificates and keys of the device stored in the respective stores. Depending on the requests received from the store management and implementation components, ASN-PKCS acts on the keys during certain key and certificate manipulation operations. For details of the operations during which the ASN-PKCS APIs are invoked, see Typical uses.

                    APIs API Description

                    CDecPKCS8Data

                    Provides the means to decode PKCS#8 encoded private keys.

                    Typical uses

                    ASN-PKCS APIs are used for encoding and decoding purposes during the following key and certificate manipulation operations:

                    • Encoding and decoding of PKCS private keys (in raw text and PBE-encrypted forms) during import and export of keys. When PBE-encrypted PKCS keys are imported or exported, the ASN-PKCS APIs also help in encoding or decoding of the PBE parameters.

                    • Encoding of the private keys accompanying public key certificates (according to PKCS#12 standards) while creating certificate requests.

                    • Creation of PKCS#7 messages for creating the certificate requests.

                    Notes:

                    • Device creators can use the ASN-PKCS component along with their own implementation of the certificate and key stores.

                    • For details of the key and certificate operations, see Unified Keystore Tutorials and Unified Certificate Store Tutorial respectively.

                    Unified Stores                     \ No newline at end of file + + + + + +ASN-PKCS OverviewThe ASN-PKCS component provides interfaces for:

                    • Performing ASN.1 -DER (Abstract Syntax Notation One - Distinguished Encoding Rules) encoding and decoding of PKCS (Public-Key Cryptography Standards) private keys in raw text as well as PBE (Password-Based Encryption) encrypted forms.

                    • Performing ASN.1 encoding and decoding of PBE parameters associated with the private keys.

                    Key concepts and terms
                    Key

                    A cryptography key is a constant value applied using a cryptographic algorithm to encrypt text or to decrypt encrypted text.

                    Keys are classified as symmetric and asymmetric based on the type of algorithm applied. If the same key is used for both encryption and decryption, it is symmetric. If different keys are used for encryption and decryption, they are asymmetric. Asymmetric keys exist in the form of a public and private key pair, where the public key is used for encryption and the private key is used for decryption.

                    Key Store

                    A key store is a repository of keys that can be retrieved and used to accomplish a variety of tasks.

                    The key store provides the following functionality:

                    • Generation, import and export of RSA, DSA, and DH key pairs

                    • Listing of stored keys

                    • Authentication of users

                    • Private key operations for authenticated users

                    Architecture

                    The following block diagram describes the interaction of the ASN-PKCS component with the certificate and key stores:

                    The client application accesses the various certificates and keys of the device stored in the respective stores. Depending on the requests received from the store management and implementation components, ASN-PKCS acts on the keys during certain key and certificate manipulation operations. For details of the operations during which the ASN-PKCS APIs are invoked, see Typical uses.

                    APIs API Description

                    CDecPKCS8Data

                    Provides the means to decode PKCS#8 encoded private keys.

                    Typical uses

                    ASN-PKCS APIs are used for encoding and decoding purposes during the following key and certificate manipulation operations:

                    • Encoding and decoding of PKCS private keys (in raw text and PBE-encrypted forms) during import and export of keys. When PBE-encrypted PKCS keys are imported or exported, the ASN-PKCS APIs also help in encoding or decoding of the PBE parameters.

                    • Encoding of the private keys accompanying public key certificates (according to PKCS#12 standards) while creating certificate requests.

                    • Creation of PKCS#7 messages for creating the certificate requests.

                    Notes:

                    • Device creators can use the ASN-PKCS component along with their own implementation of the certificate and key stores.

                    • For details of the key and certificate operations, see Unified Keystore Tutorials and Unified Certificate Store Tutorial respectively.

                    Unified Stores                     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EE556214-BFB8-582E-ACD9-5287D7C64EFA_d0e334772_href.jpg Binary file Symbian3/SDK/Source/GUID-EE556214-BFB8-582E-ACD9-5287D7C64EFA_d0e334772_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EE556214-BFB8-582E-ACD9-5287D7C64EFA_d0e340929_href.jpg Binary file Symbian3/SDK/Source/GUID-EE556214-BFB8-582E-ACD9-5287D7C64EFA_d0e340929_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EE5937B6-9103-4711-B13B-06A62D56AF79_d0e69754_href.png Binary file Symbian3/SDK/Source/GUID-EE5937B6-9103-4711-B13B-06A62D56AF79_d0e69754_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EE5937B6-9103-4711-B13B-06A62D56AF79_d0e74928_href.png Binary file Symbian3/SDK/Source/GUID-EE5937B6-9103-4711-B13B-06A62D56AF79_d0e74928_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EEF2F892-8900-475F-926B-A49D0D98C1C6.dita --- a/Symbian3/SDK/Source/GUID-EEF2F892-8900-475F-926B-A49D0D98C1C6.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,28 +0,0 @@ - - - - - -Navigation -

                    The model of navigation is based on states arranged as hierarchical trees. -The following features provide the flexibility for navigation:

                    -
                      -

                    • Tabs

                      • -

                    • Home / Menu key and the Menu

                      • -

                    • Direct navigation between sibling folders

                      • -

                    • Links to applications and documents

                      • -
                    -                     - -UI concepts - -Framework -requirements for GUI applications - -                     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EF3DB813-B0B9-5099-9E57-561A32111BF0.dita --- a/Symbian3/SDK/Source/GUID-EF3DB813-B0B9-5099-9E57-561A32111BF0.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-EF3DB813-B0B9-5099-9E57-561A32111BF0.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,15 +1,15 @@ - - - - - -Feature Manager Server GuideThis document describes the feature management server.
                    Purpose

                    The feature management server maintains the table which contains and maintains the list of features available on the device.

                    Required background

                    The feature management system uses the standard client server architecture that is the feature manager server that does the work associated with the feature management functionality. Communication between the application and the server is undertaken by two dlls.

                    Architecture

                    The relationship between the parts of the feature management system is :

                    - Architecture of the feature management system -
                    APIs

                    Communication to and from the feature management server is only provided by the methods available in the Feature Manager Client API and the Feature Manager Discovery API.

                    Typical uses

                    These are the same as for feature management (since it does all the work). They include adding, disabling, enabling and removing features.

                    For the description of the APIs used in feature management look at the component overview for featmgr.dll and featdiscovery.dll.

                    Feature Manager Overview Feature Manager Client + + + + + +Feature Manager Server GuideThis document describes the feature management server.
                    Purpose

                    The feature management server maintains the table which contains and maintains the list of features available on the device.

                    Required background

                    The feature management system uses the standard client server architecture that is the feature manager server that does the work associated with the feature management functionality. Communication between the application and the server is undertaken by two dlls.

                    Architecture

                    The relationship between the parts of the feature management system is :

                    + Architecture of the feature management system +
                    APIs

                    Communication to and from the feature management server is only provided by the methods available in the Feature Manager Client API and the Feature Manager Discovery API.

                    Typical uses

                    These are the same as for feature management (since it does all the work). They include adding, disabling, enabling and removing features.

                    For the description of the APIs used in feature management look at the component overview for featmgr.dll and featdiscovery.dll.

                    Feature Manager Overview Feature Manager Client Overview Feature Discovery Overview                     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EF7F79E4-21B1-59E3-A063-ABD2C6426E7C_d0e134536_href.png Binary file Symbian3/SDK/Source/GUID-EF7F79E4-21B1-59E3-A063-ABD2C6426E7C_d0e134536_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EF7F79E4-21B1-59E3-A063-ABD2C6426E7C_d0e141070_href.png Binary file Symbian3/SDK/Source/GUID-EF7F79E4-21B1-59E3-A063-ABD2C6426E7C_d0e141070_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EFAEDFA5-3807-56EB-8D47-3A6960C4056C.dita --- a/Symbian3/SDK/Source/GUID-EFAEDFA5-3807-56EB-8D47-3A6960C4056C.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-EFAEDFA5-3807-56EB-8D47-3A6960C4056C.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,37 +1,37 @@ - - - - - -How -to use the SDP Codec API -
                    Protocols

                    The -following steps describe how to use the SDP Codec API to create an SDP description:

                      -

                    • Create a CSdpDocument object -and open the string pool before use. Note: The string table includes -predefined SDP constants for which handles are retrieved when SdpCodecStringPool::StringPoolL() is -called. The string table includes all predefined SDP related constants.

                      • -

                    • The net type and the -address type of the connection and origin field parameters that are predefined -are retrieved from the string pool.

                      • -

                    • Create the origin field -with origin field parameters, and set the CSdpDocument object.

                      • -

                    • Create the connection -field from the connection parameters, and set the CSdpDocument object.

                      • -

                    • When you finish with -the SDP description, delete the CSdpDocument object and -close the string pool.

                      • -

                    The following illustration shows how to create an SDP description.

                    - -

                    Note: In the following illustration only required SDP fields -are included.

                    -
                    Error handling

                    All -function calls are synchronous. When an error occurs the functions leave with -SDP Codec specific error codes and Symbian platform error codes.

                    + + + + + +How +to use the SDP Codec API +
                    Protocols

                    The +following steps describe how to use the SDP Codec API to create an SDP description:

                      +

                    • Create a CSdpDocument object +and open the string pool before use. Note: The string table includes +predefined SDP constants for which handles are retrieved when SdpCodecStringPool::StringPoolL() is +called. The string table includes all predefined SDP related constants.

                      • +

                    • The net type and the +address type of the connection and origin field parameters that are predefined +are retrieved from the string pool.

                      • +

                    • Create the origin field +with origin field parameters, and set the CSdpDocument object.

                      • +

                    • Create the connection +field from the connection parameters, and set the CSdpDocument object.

                      • +

                    • When you finish with +the SDP description, delete the CSdpDocument object and +close the string pool.

                      • +

                    The following illustration shows how to create an SDP description.

                    + +

                    Note: In the following illustration only required SDP fields +are included.

                    +
                    Error handling

                    All +function calls are synchronous. When an error occurs the functions leave with +SDP Codec specific error codes and Symbian platform error codes.

                    \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EFE378EA-C668-5CD5-A630-B8041027791A_d0e76890_href.png Binary file Symbian3/SDK/Source/GUID-EFE378EA-C668-5CD5-A630-B8041027791A_d0e76890_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EFE378EA-C668-5CD5-A630-B8041027791A_d0e83602_href.png Binary file Symbian3/SDK/Source/GUID-EFE378EA-C668-5CD5-A630-B8041027791A_d0e83602_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EFEBDE65-293C-40AC-B57D-363158E77DA0.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-EFEBDE65-293C-40AC-B57D-363158E77DA0.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,76 @@ + + + + + +Qt on SymbianSome links to useful information about developing for Symbian +using QT. +
                    Useful +links

                    The links below give you a starting point for learning +about +Qt on the Symbian platform.

                      +

                    • Getting started

                        +

                      • Getting started with Qt on Nokia devices (forum.nokia.com) +— is a very good place to start.

                        • +

                      • Nokia Qt SDK (forum.nokia.com) — the toolset +you need to go from application concept to a fully tested, ready to +deploy application.

                        • +

                      • Qt for the Symbian platform (developer.symbian.org) +— describes Qt from a Symbian C++ developer perspective

                        • +

                      • Qt code examples (forum.nokia.com) — example +applications developed and optimised for mobile devices.

                        • +

                      • Qt and Symbian Platform Security (developer.symbian.org) +— an introduction to Symbian's security model and how it works with +Qt.

                        • +

                      • Deploying a Qt Application (developer.symbian.org) +— how to get your Qt application on other Symbian devices.

                        • +
                      • +

                    • More detailed information about Qt on Symbian devices

                        +

                      • Qt's platform notes for Symbian (doc.qt.nokia.com) +— describes the status of the port of Qt 4.6 to the Symbian platform.

                        • +

                      • Qt and Symbian C++ together (developer.symbian.org) +— provides technical details about how to make Qt and Symbian C++ +cooperate.

                        • +

                      • qmake extensions for Symbian (doc.qt.nokia.com) +— Qt's qmake tool has some Symbian-specific extensions.

                        • +

                      • Smart installer for Symbian (forum.nokia.com) +— a tool to package with an application installation file. The tool +checks the version of Qt on the device and downloads the latest version +of Qt if necessary.

                        • +
                      • +

                    • Support

                        +

                      • Qt Developer Zone (qt.nokia.com) — Qt's main +page for developers.

                        • +

                      • Qt's +main support page (qt.nokia.com) — official support options +from Qt.

                        • +

                      • Forum Nokia's Qt wiki (forum.nokia.com) — +wiki articles about Qt on Symbian and MeeGo devices.

                        • +

                      • Qt discussion board (forum.nokia.com) — find +help from other developers using Qt on Symbian devices.

                        • +

                      • Forum Nokia knowledge base (forum.nokia.com) +— code snippets, technical solutions, and known issues.

                        • +

                      • Qt Developer Network (qt.nokia.com) — beta +version of the +Qt support network.

                        • +

                      • New Qt APIs (qt.nokia.com) — information about +the latest updates to Qt.

                        • +

                      • New Qt APIs for mobile development (qt.nokia.com) +— information +about QT's latest mobile-related APIs.

                        • +
                      • +

                    • Qt books

                        +

                      • C++ GUI Programming with Qt 4, Second Edition (qt.nokia.com) — the official Qt book.

                        • +

                      • C++ GUI Programming with Qt 4, First Edition (www.qtrac.eu) — this older version of the official Qt book is available +online.

                        • +

                      • Qt for Symbian (eu.wiley.com) — goes into +depth about how Qt works on the Symbian platform.

                        • +
                      • +
                    +                     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-EFF8D1A1-00D5-5F96-8285-414DC0044AB8.dita --- a/Symbian3/SDK/Source/GUID-EFF8D1A1-00D5-5F96-8285-414DC0044AB8.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-EFF8D1A1-00D5-5F96-8285-414DC0044AB8.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,104 +1,104 @@ - - - - - -Setting -Use PoliciesA use policy denotes the security check required to use the key. -The use policy associated with the key is of type TSecurityPolicy. -The policy can be set to check capabilities or the Secure ID associated with -the calling process. The calling process should have a WriteUserData capability. -

                    The following steps explain the process of setting a use policy -for a key:

                     - -Create a file system -session using an RFs object. - - -Create an object of type CUnifiedKeyStore using CUnifiedKeyStore::NewL() or CUnifiedKeyStore::NewLC(). - - -Initialise the member functions and keystore using the asynchronous -function CUnifiedKeyStore::Initialize(). - - -List all keys in the keystore using the CUnifiedKeyStore::List() function. -Retrieve the handle of the key for which the use policy needs to be set. - - -Set the use policy for the key using the CUnifiedKeyStore::SetUsePolicy() function. - - -

                    Use policy is set for the selected key.

                    -Example

                    The -following code snippet shows how to set use policy for a key.

                    // Create a file system session object -RFs iFs; -CleanupClosePushL(&iFs); - - -... - - -// Initialise the keystore and member functions -CUnifiedKeyStore* keyStore = CUnifiedKeyStore::NewL(fs); -keyStore->Initialize(iStatus); //iStatus is a TRequestStatus object - - -... - - - -// Retrieve the handle of the key for which use policy has to be set -TCTKeyAttributeFilter filter.iUsage = EPKCS15UsageAll; -RPointerArray<CCTKeyInfo> iKeys; // This variable will contain the result of the set use policy operation -keyStore->List(iKeys, filter, iStatus); - - -... - - - -// Retrieve the key handle of the appropriate key -_LIT(KLabel,”keylabel”); - -// Select the key with the label you are looking for -TInt keyIndex; -for (TInt j = 0; j < iKeys.Count(); j++) - { - if (iKeys[j]->Label() == KLabel) - { - keyIndex = j; - break; - } - } - - -... - - - -// Set the use policy - -TSecurityPolicy usePolicy; -TUint secureId = 0x101FFFFF; -TCapability caps[3]; -caps[0] = ECapabilityWriteUserData; -caps[1] = ECapabilityDRM; -caps[2] = ECapabilityReadUserData; - -usePolicy = TSecurityPolicy(TSecureId(secureId), caps[0], caps[1], caps[2]); -keyStore->SetUsePolicy(*iKeys, usePolicy, iStatus); - - -// Clean up -CleanupStack::PopAndDestroy(); // iFs                     -                     -Set Management -Policies + + + + + +Setting +Use PoliciesA use policy denotes the security check required to use the key. +The use policy associated with the key is of type TSecurityPolicy. +The policy can be set to check capabilities or the Secure ID associated with +the calling process. The calling process should have a WriteUserData capability. +

                    The following steps explain the process of setting a use policy +for a key:

                     + +Create a file system +session using an RFs object. + + +Create an object of type CUnifiedKeyStore using CUnifiedKeyStore::NewL() or CUnifiedKeyStore::NewLC(). + + +Initialise the member functions and keystore using the asynchronous +function CUnifiedKeyStore::Initialize(). + + +List all keys in the keystore using the CUnifiedKeyStore::List() function. +Retrieve the handle of the key for which the use policy needs to be set. + + +Set the use policy for the key using the CUnifiedKeyStore::SetUsePolicy() function. + + +

                    Use policy is set for the selected key.

                    +Example

                    The +following code snippet shows how to set use policy for a key.

                    // Create a file system session object +RFs iFs; +CleanupClosePushL(&iFs); + + +... + + +// Initialise the keystore and member functions +CUnifiedKeyStore* keyStore = CUnifiedKeyStore::NewL(fs); +keyStore->Initialize(iStatus); //iStatus is a TRequestStatus object + + +... + + + +// Retrieve the handle of the key for which use policy has to be set +TCTKeyAttributeFilter filter.iUsage = EPKCS15UsageAll; +RPointerArray<CCTKeyInfo> iKeys; // This variable will contain the result of the set use policy operation +keyStore->List(iKeys, filter, iStatus); + + +... + + + +// Retrieve the key handle of the appropriate key +_LIT(KLabel,”keylabel”); + +// Select the key with the label you are looking for +TInt keyIndex; +for (TInt j = 0; j < iKeys.Count(); j++) + { + if (iKeys[j]->Label() == KLabel) + { + keyIndex = j; + break; + } + } + + +... + + + +// Set the use policy + +TSecurityPolicy usePolicy; +TUint secureId = 0x101FFFFF; +TCapability caps[3]; +caps[0] = ECapabilityWriteUserData; +caps[1] = ECapabilityDRM; +caps[2] = ECapabilityReadUserData; + +usePolicy = TSecurityPolicy(TSecureId(secureId), caps[0], caps[1], caps[2]); +keyStore->SetUsePolicy(*iKeys, usePolicy, iStatus); + + +// Clean up +CleanupStack::PopAndDestroy(); // iFs                     +                     +Set Management +Policies                     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F057FFF8-EA6A-5719-BE6B-B37950A07A7B_d0e219908_href.png Binary file Symbian3/SDK/Source/GUID-F057FFF8-EA6A-5719-BE6B-B37950A07A7B_d0e219908_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F057FFF8-EA6A-5719-BE6B-B37950A07A7B_d0e223645_href.png Binary file Symbian3/SDK/Source/GUID-F057FFF8-EA6A-5719-BE6B-B37950A07A7B_d0e223645_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F09DA1AD-6D83-5267-B479-C857DFA2B939.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-F09DA1AD-6D83-5267-B479-C857DFA2B939.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,29 @@ + + + + + +Ordinal: ordinal position, drag and drop +
                    Description

                    Ordinal uses five numbered, draggable windows, similar to the draggable +window used in the previous example to demonstrate the ordinal positioning +of windows.

                    +
                    Class Summary

                    RWindowTreeNode

                    +
                    Download

                    Click on the following link to download the example: Ordinal.zip

                    Click: browse to view the example code.

                    +
                    Running on the emulator

                    Clicking in a window +with the left mouse button brings that window to the front by giving +it an ordinal position of 0. Dragging with the left mouse button moves +the windows around on the screen.

                    Clicking in a window with +the right mouse button cascades the children of that window in the +top left corner (using RWindowTreeNode::Child()const, RWindowTreeNode::NextSibling()const and RWindowTreeNode::PrevSibling()const). The windows are cascaded +according to their ordinal position in the top window's list of siblings.

                    +
                    Running on the target phone

                    The behaviour +invoked by the right mouse button click is unavailable on the target +phone. Windows can be dragged using the pointer, and tapping on a +window brings it to the front.

                    +                     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F0DCFAB5-DE92-5336-B4E2-1ED40BE05DEC_d0e431942_href.png Binary file Symbian3/SDK/Source/GUID-F0DCFAB5-DE92-5336-B4E2-1ED40BE05DEC_d0e431942_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F0DCFAB5-DE92-5336-B4E2-1ED40BE05DEC_d0e432104_href.png Binary file Symbian3/SDK/Source/GUID-F0DCFAB5-DE92-5336-B4E2-1ED40BE05DEC_d0e432104_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F149726A-CC79-42A1-8A25-E15AC14ABE9A.dita --- a/Symbian3/SDK/Source/GUID-F149726A-CC79-42A1-8A25-E15AC14ABE9A.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-F149726A-CC79-42A1-8A25-E15AC14ABE9A.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,205 +1,205 @@ - - - - - -Setting -list -

                    A setting list is a specific kind of selection list containing setting -items that the user can adjust. Setting lists are displayed in the main pane.

                    - -Setting list - - -

                    A setting item can be adjusted by selecting it in the same way as selection -list items are selected in general; that is, by pressing the Selection key, -or choosing the Change command from the Options menu. The main pane then displays -the setting item editor where the value can be changed.

                    -

                    There are several setting item types available. They look the same in the -setting list: each item displays an attribute text (the title of the setting) -on one line and the current value on another line within the item. The adjusting -and editing functions differ between the setting item types.

                    -Setting item -types - - - -Setting -Description - - - - -

                    Pop-up setting

                     -

                    A pop-up setting allows the user to choose one value from a pre-defined -list. The setting editor displays the available values in a menu list. A pop-up -setting may also allow the user to enter a new textual value in addition to -the pre-defined values. In that case, the last option is named Other (or equivalent), -and selecting it opens a Data query for entering the new value.

                     -                     - -

                    Multi-selection list setting

                     -

                    A multi-selection list setting allows the user to choose several -simultaneous values from a pre-defined list. The setting editor displays the -available values as a multi-selection list. The setting item displays the -number of selected items versus all the items in the value field; for example: -3/8.

                     -                     - -

                    Text setting

                     -

                    The value of a text setting item is an alphanumeric or numeric string. -The editor can be of a specific type, such as the Date and Time editor.

                     -                     - -

                    Slider setting

                     -

                    With a slider, the user can adjust the value of a setting by sliding -a marker. The value of a slider is adjusted using the Arrow left and Arrow -right keys.

                     -                     - - -
                    - -Pop-up setting - - - -Multi-selection setting - - - -Text setting - - - -Slider setting - - -

                    By default, in a setting editor, the keypad functions are as follows:

                    -Default key events -in setting editor - - - -Key -Action - - - - -

                    Arrow up / down

                     -

                    Pop-up, multi-selection: browses the list. Text: moves the cursor. -Slider: ignored.

                     -                     - -

                    Arrow left / right

                     -

                    Pop-up: ignored. Multi-selection: ignored. Text: moves the cursor. -Slider: adjusts the slider value (a key repeat event may move the slider by -several steps).

                     -                     - -

                    Selection key

                     -

                    All except multi-selection: accepts the value, returns to the setting -list. Multi-selection: toggles Mark/Unmark.

                     -                     - -

                    Left softkey (OK)

                     -

                    Accepts the current item or value, returns.

                    Note: may -also be Options in certain instances.

                     -                     - -

                    Right softkey (Cancel)

                     -

                    Cancels the setting editor, returns.

                     -                     - -

                    Clear

                     -

                    Pop-up, multi-selection: ignored. Text: deletes characters. Slider: -ignored.

                     -                     - -

                    Edit

                     -

                    Pop-up, multi-selection: ignored. Text: opens the editing menu. -Slider: ignored.

                     -                     - -

                    Numeric keypad

                     -

                    Pop-up, multi-selection: ignored. Text: input functions. Slider: -ignored; if the value is numeric, it may be adjustable using the Numeric keys.

                     -                     - -

                    Other keys

                     -

                    Do the default action of the key.

                     -                     - - -
                    -

                    -Default touch -events to setting list - - - - - - -

                    User action

                     -

                    State change

                     -

                    Feedback

                     -                     - - - -

                    Touch down

                     -

                    No change

                     -

                    Highlight is shown.

                    Tactile: Basic list effect and audio -given with touch down event.

                     -                     - -

                    Touch release

                     -

                    The setting item is opened. Exception for only two values in a setting -list. Refer to 19.2 Setting item with two available values.

                     -

                    Highlight disappears. Tactile: Basic list effect given with touch -release event.

                     -                     - -

                    Touch down and hold

                     -

                    Inactive

                     -

                    Tactile: No effect

                     -                     - -

                    Touch down and move

                     -

                    Refer to Dragging -and flicking events

                     -

                    Tactile: Refer to Dragging -and flicking events.

                     -                     - - -
                    -

                    In the setting editor, the Navi pane is empty, or in case of a text editor, -contains the editing indicators.

                    -

                    Further guidelines:

                    -
                      -

                    • Typically, a setting list is accessed via the Options menu (see Options menu).

                      • -

                    • Setting lists can only contain setting items, not other types of items -mixed with them. (In case the settings are arranged in a hierarchical structure, -both setting items and setting folders may exist in one list.)

                      • -

                    • All the setting item types can co-exist in the same setting list.

                      • -
                    -

                    If a pop-up setting has only two available values (such as On and Off) -and no special procedure is needed when switching from one value to the other, -then the setting editor (list) must not be displayed when the user presses -the Selection key; the item's value is changed immediately. However, if the -user opens the setting item via the Options menu, or if an additional -procedure is required (for example a password) before the item's value can -be changed, the list is opened normally.

                    -
                    Using -setting lists in C++ applications

                    The APIs to use for setting lists -are the Lists API and the Setting pages API. For implementation information, see Using the Lists API and Using the Setting pages API.

                    + + + + + +Setting +list +

                    A setting list is a specific kind of selection list containing setting +items that the user can adjust. Setting lists are displayed in the main pane.

                    + +Setting list + + +

                    A setting item can be adjusted by selecting it in the same way as selection +list items are selected in general; that is, by pressing the Selection key, +or choosing the Change command from the Options menu. The main pane then displays +the setting item editor where the value can be changed.

                    +

                    There are several setting item types available. They look the same in the +setting list: each item displays an attribute text (the title of the setting) +on one line and the current value on another line within the item. The adjusting +and editing functions differ between the setting item types.

                    +Setting item +types + + + +Setting +Description + + + + +

                    Pop-up setting

                     +

                    A pop-up setting allows the user to choose one value from a pre-defined +list. The setting editor displays the available values in a menu list. A pop-up +setting may also allow the user to enter a new textual value in addition to +the pre-defined values. In that case, the last option is named Other (or equivalent), +and selecting it opens a Data query for entering the new value.

                     +                     + +

                    Multi-selection list setting

                     +

                    A multi-selection list setting allows the user to choose several +simultaneous values from a pre-defined list. The setting editor displays the +available values as a multi-selection list. The setting item displays the +number of selected items versus all the items in the value field; for example: +3/8.

                     +                     + +

                    Text setting

                     +

                    The value of a text setting item is an alphanumeric or numeric string. +The editor can be of a specific type, such as the Date and Time editor.

                     +                     + +

                    Slider setting

                     +

                    With a slider, the user can adjust the value of a setting by sliding +a marker. The value of a slider is adjusted using the Arrow left and Arrow +right keys.

                     +                     + + +
                    + +Pop-up setting + + + +Multi-selection setting + + + +Text setting + + + +Slider setting + + +

                    By default, in a setting editor, the keypad functions are as follows:

                    +Default key events +in setting editor + + + +Key +Action + + + + +

                    Arrow up / down

                     +

                    Pop-up, multi-selection: browses the list. Text: moves the cursor. +Slider: ignored.

                     +                     + +

                    Arrow left / right

                     +

                    Pop-up: ignored. Multi-selection: ignored. Text: moves the cursor. +Slider: adjusts the slider value (a key repeat event may move the slider by +several steps).

                     +                     + +

                    Selection key

                     +

                    All except multi-selection: accepts the value, returns to the setting +list. Multi-selection: toggles Mark/Unmark.

                     +                     + +

                    Left softkey (OK)

                     +

                    Accepts the current item or value, returns.

                    Note: may +also be Options in certain instances.

                     +                     + +

                    Right softkey (Cancel)

                     +

                    Cancels the setting editor, returns.

                     +                     + +

                    Clear

                     +

                    Pop-up, multi-selection: ignored. Text: deletes characters. Slider: +ignored.

                     +                     + +

                    Edit

                     +

                    Pop-up, multi-selection: ignored. Text: opens the editing menu. +Slider: ignored.

                     +                     + +

                    Numeric keypad

                     +

                    Pop-up, multi-selection: ignored. Text: input functions. Slider: +ignored; if the value is numeric, it may be adjustable using the Numeric keys.

                     +                     + +

                    Other keys

                     +

                    Do the default action of the key.

                     +                     + + +
                    +

                    +Default touch +events to setting list + + + + + + +

                    User action

                     +

                    State change

                     +

                    Feedback

                     +                     + + + +

                    Touch down

                     +

                    No change

                     +

                    Highlight is shown.

                    Tactile: Basic list effect and audio +given with touch down event.

                     +                     + +

                    Touch release

                     +

                    The setting item is opened. Exception for only two values in a setting +list. Refer to 19.2 Setting item with two available values.

                     +

                    Highlight disappears. Tactile: Basic list effect given with touch +release event.

                     +                     + +

                    Touch down and hold

                     +

                    Inactive

                     +

                    Tactile: No effect

                     +                     + +

                    Touch down and move

                     +

                    Refer to Dragging +and flicking events

                     +

                    Tactile: Refer to Dragging +and flicking events.

                     +                     + + +
                    +

                    In the setting editor, the Navi pane is empty, or in case of a text editor, +contains the editing indicators.

                    +

                    Further guidelines:

                    +
                      +

                    • Typically, a setting list is accessed via the Options menu (see Options menu).

                      • +

                    • Setting lists can only contain setting items, not other types of items +mixed with them. (In case the settings are arranged in a hierarchical structure, +both setting items and setting folders may exist in one list.)

                      • +

                    • All the setting item types can co-exist in the same setting list.

                      • +
                    +

                    If a pop-up setting has only two available values (such as On and Off) +and no special procedure is needed when switching from one value to the other, +then the setting editor (list) must not be displayed when the user presses +the Selection key; the item's value is changed immediately. However, if the +user opens the setting item via the Options menu, or if an additional +procedure is required (for example a password) before the item's value can +be changed, the list is opened normally.

                    +
                    Using +setting lists in applications

                    The APIs to use for setting +lists are the Lists API and the Setting pages API. For implementation information, see Using the Lists API and Using the Setting pages API.

                     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F14A2252-7D7B-5631-9796-3C9AC54014E7.dita --- a/Symbian3/SDK/Source/GUID-F14A2252-7D7B-5631-9796-3C9AC54014E7.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-F14A2252-7D7B-5631-9796-3C9AC54014E7.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,86 +1,86 @@ - - - - - -Repetitive -Search -

                    When a new search-sort asynchronous operation is successful, a unique ID -is returned to the client, which is referred as query ID. This query ID can -be used to repeat the same search-sort query.

                    -
                    Required background

                    To do a repetitive search operation, -that is searching messages using a query ID, you must first get the query -ID of that search operation.

                    -
                    Introduction

                    Every new search-sort asynchronous -query that is successful is assigned with a unique 32 bit integer value, which -is referred to as a query ID. This query ID is -used to initiate the same search-sort operation (initiate a repetitive query) -in future. The query ID can be retrieved using the CMsvSearchSortOperation::GetQueryIdL() function.

                    Marking

                    When the search-sort cache reaches its maximum size the message server -deletes the least recently used query to accommodate a new one. However, there -may be some queries and their results which the client wants to keep in the -cache, irrespective of how frequently they are being used.

                    Such queries -can be marked by the client to indicate to the Messaging server that the query -should not be disposed from the search-sort cache when the cache is full. -Marked queries are considered for deletion only if all of the remaining queries -are also marked.

                    To mark a query ID, use the TBool aMarkQuery parameter -in the CMsvSearchSortOperation::RequestL() function in -your client application.

                    IMPORT_C void RequestL (CMsvSearchSortQuery* aQuery, TBool aMarkQuery, TRequestStatus& aQueryStatus, TInt aIterator=0)

                    Unmarking

                    To unmark a query ID, use the CMsvSearchSortOperation::UnmarkQuery() -function in your client application.

                    IMPORT_C TInt UnmarkQuery (const TInt aQueryId ) - Repetitive search request process - -
                    -
                    Procedure
                      -

                    1. To get a query ID, complete -the steps from 1 to 10 in New -Search.

                      2. -

                    2. Get the query ID from -step 10 and start the search operation using the query ID as the search parameter.

                      3. -
                    void CSearchsortExample::SeachSortRequestByQueryIdL() - { - //1. Create a session with message server - // NOTE: CMsvSession::OpenSyncL requires a &MMsvObserver parameter. This example assumes that - // CSearchSortExample implements MMsvObserver. - CMsvSession* session = CMsvSession::OpenSyncL(*this); - CleanupStack::PushL(session); - - //2. Create an instance of CMsvSearchSortOperation to perform a - //search-sort operation - CMSvSearchSortOperation* search = CMSvSearchSortOperation::NewL(*session); - CleanupStack::PushL(search); - - //3. Start the search operation using the query ID as the search parameter - TRequestStatus aStatus; - search->RequestL(iQueryId, aStatus); - - //4. Wait for the result - User::WaitForRequest(aStatus); - - //5. Create an array to hold Search-sort results - RArray<TMsvId> resultArray; - - //6. Retrieve the results of the search. The format for the results should be the same as - // what is configured in step 2. Else, will leave with the KErrMsvInvalidResultRequest - // error - TInt err = search->GetResultsL(resultArray); - if(ret == KErrNone) - { - TInt count = resultArray.Count(); - } - - //7. Store the query ID. This ID can be used in repetitive search queries. - iQueryId = search->GetQueryIdL(); - - CleanupStack::PopAndDestroy(2); //search, session - }
                    -Search-sort example

                    SearchSortExample: -Enhanced Search and Sort for Message Store

                    -
                    See also

                    For conceptual information on search-sort -APIs, see Search-Sort -Introduction.

                    + + + + + +Repetitive +Search +

                    When a new search-sort asynchronous operation is successful, a unique ID +is returned to the client, which is referred as query ID. This query ID can +be used to repeat the same search-sort query.

                    +
                    Required background

                    To do a repetitive search operation, +that is searching messages using a query ID, you must first get the query +ID of that search operation.

                    +
                    Introduction

                    Every new search-sort asynchronous +query that is successful is assigned with a unique 32 bit integer value, which +is referred to as a query ID. This query ID is +used to initiate the same search-sort operation (initiate a repetitive query) +in future. The query ID can be retrieved using the CMsvSearchSortOperation::GetQueryIdL() function.

                    Marking

                    When the search-sort cache reaches its maximum size the message server +deletes the least recently used query to accommodate a new one. However, there +may be some queries and their results which the client wants to keep in the +cache, irrespective of how frequently they are being used.

                    Such queries +can be marked by the client to indicate to the Messaging server that the query +should not be disposed from the search-sort cache when the cache is full. +Marked queries are considered for deletion only if all of the remaining queries +are also marked.

                    To mark a query ID, use the TBool aMarkQuery parameter +in the CMsvSearchSortOperation::RequestL() function in +your client application.

                    IMPORT_C void RequestL (CMsvSearchSortQuery* aQuery, TBool aMarkQuery, TRequestStatus& aQueryStatus, TInt aIterator=0)

                    Unmarking

                    To unmark a query ID, use the CMsvSearchSortOperation::UnmarkQuery() +function in your client application.

                    IMPORT_C TInt UnmarkQuery (const TInt aQueryId ) + Repetitive search request process + +
                    +
                    Procedure
                      +

                    1. To get a query ID, complete +the steps from 1 to 10 in New +Search.

                      2. +

                    2. Get the query ID from +step 10 and start the search operation using the query ID as the search parameter.

                      3. +
                    void CSearchsortExample::SeachSortRequestByQueryIdL() + { + //1. Create a session with message server + // NOTE: CMsvSession::OpenSyncL requires a &MMsvObserver parameter. This example assumes that + // CSearchSortExample implements MMsvObserver. + CMsvSession* session = CMsvSession::OpenSyncL(*this); + CleanupStack::PushL(session); + + //2. Create an instance of CMsvSearchSortOperation to perform a + //search-sort operation + CMSvSearchSortOperation* search = CMSvSearchSortOperation::NewL(*session); + CleanupStack::PushL(search); + + //3. Start the search operation using the query ID as the search parameter + TRequestStatus aStatus; + search->RequestL(iQueryId, aStatus); + + //4. Wait for the result + User::WaitForRequest(aStatus); + + //5. Create an array to hold Search-sort results + RArray<TMsvId> resultArray; + + //6. Retrieve the results of the search. The format for the results should be the same as + // what is configured in step 2. Else, will leave with the KErrMsvInvalidResultRequest + // error + TInt err = search->GetResultsL(resultArray); + if(ret == KErrNone) + { + TInt count = resultArray.Count(); + } + + //7. Store the query ID. This ID can be used in repetitive search queries. + iQueryId = search->GetQueryIdL(); + + CleanupStack::PopAndDestroy(2); //search, session + }
                    +Search-sort example

                    SearchSortExample: +Enhanced Search and Sort for Message Store

                    +
                    See also

                    For conceptual information on search-sort +APIs, see Search-Sort +Introduction.

                    \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F15B9BDF-EDF8-5684-A0FC-C0A08F9C1F22.dita --- a/Symbian3/SDK/Source/GUID-F15B9BDF-EDF8-5684-A0FC-C0A08F9C1F22.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-F15B9BDF-EDF8-5684-A0FC-C0A08F9C1F22.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,124 +1,124 @@ - - - - - -linkedlist: -Using the Linked List classes -

                    The following examples -show the use of the linked list classes:

                      -

                    • Singly linked list example

                      • -

                    • Doubly linked list example

                      • -

                    • Delta queue example

                      • -
                    -
                    Singly linked -list example

                    This example application demonstrates the use of singly -linked lists. The templated TSglQue class is used to create -a singly linked list.

                    Download

                    Click on the following -link to download the example: sgllist.zip

                    Click: browse to view the example.

                    Description

                    The -example creates a singly linked list of objects of the TDigit class. -This list represents a long number. An object of class CLongNumber owns -the list. The user can edit this list using the functions defined in the CLongNumber class. -The following edit operations are possible:

                      -

                    • Insert an object of -the TDigit class at the start of the singly linked list

                      • -

                    • Insert an object of -the TDigit class at the end of the singly linked list

                      • -

                    • Remove an object of -the TDigit class from the end of the singly linked list

                      • -

                    The user can perform any of these operations by pressing keys specified -in the menu. CLongNumber is an active object class and handles -the key press events in the CLongNumber::RunL() function.The CLongNumber::ReadFunc() function -displays a menu and waits for an asynchronous key press event.

                    An -object of the templated TSglQueIter class is used to traverse -this linked list. The sum of all digits of the number represented by the linked -list is displayed to the user.

                    An object of the CAdder class -is used to traverse the CLongNumber::iNumber list and print -the sum of all digits of the number represented by this list. The CAdder::Add() function -gets this sum.

                    Related APIs

                      -

                    • CAdder

                      • -

                    • CLongNumber

                      • -

                    • TDigit

                      • -

                    • TSglQueIter

                      • -

                    Design and implementation

                    Figure 1 shows the classes -in the example.

                    - Figure 1. Classes in the singly linked list example - - -

                    Class summary

                      -

                    • TSglQue

                      • -

                    • TSglQueIter

                      • -

                    Build

                    The -Symbian build process describes how to build this example.

                    For -the emulator, the example builds an executable called sgllist.exe in -the epoc32\release\winscw\<udeb or urel>\ folder.

                    See -also:

                    Using -Singly Linked Lists

                    -
                    Doubly linked -list example

                    This example application demonstrates the use of doubly -linked lists. The templated TDblQue class is used create -a doubly linked list.

                    Download

                    Click on the following -link to download the example: dbllist.zip

                    Click: browse to view the example code

                    Description

                    The -example creates a doubly linked list of objects of the TLetter class. -This list represents a character string. An object of class CMyStringReverse owns -this string. The user can edit this string using the functions defined in -the CMyStringReverse class. The following edit operations -are possible:

                      -

                    • Insert a character at -the start of the list

                      • -

                    • Insert a character at -the end of the list

                      • -

                    The user can perform either of these operations by pressing keys -specified in the menu. CMyStringReverse is an active object -class and handles key press events in the CMyStringReverse::RunL() function. -The CMyStringReverse::ReadFunc() function displays a menu -and waits for an asynchronous key press event.

                    The CMyStringReverse class -has a doubly linked list iterator, iIteratorString. The iIteratorString object -iterates through the list iString from start to end to print -the string reversed.

                    Design and implementation

                    Figure -2 shows the classes in the example.

                    - Figure 2. Classes in the doubly linked list example - -

                    Class summary

                      -

                    • TDblQue - A templated class that provides the behaviour -for managing a doubly linked list.

                      • -

                    Build

                    The -Symbian build process describes how to build this example.

                    For -the emulator, the example builds an executable called dbllist.exe in -the epoc32\release\winscw\<udeb or urel>\ folder.

                    See -also

                    Using -Doubly Linked Lists

                    Example code

                    -
                    Delta queue -example

                    This example application demonstrates the use of the delta -queue. The templated TDeltaQue class is used create a delta -queue.

                    Download

                    Click on the following link to download -the example: deltaque.zip

                    Click: browse to view the example code.

                    Description

                    The -example creates an object of the CTimerEntry class. This -is a CTimer derived class. An object of this class generates -timer events by using the CTimer::After() function. The -data member of this class, iQueue is a delta list. The offset -value of each node in this list is the tick count after each timer event. -The CTimerEntry::Arbitrator() function decides the action -to be performed for each event generated by the timer. It either adds tick -counts to the list or removes elements from the list based on the state of -the queue.

                    Related APIs

                      -

                    • CTimer - Base class for a timer active object.

                      • -

                    • CTimer::After()

                      • -

                    Design and implementation

                    Figure 3 shows the classes -of the example.

                    - Figure 3. Classes of the delta queue example - -

                    Class summary

                      -

                    • TDeltaQue

                      • -

                    • CTimer - Base class for a timer active object.

                      • -

                    Build

                    The -Symbian build process describes how to build this example.

                    For -the emulator, the example builds an executable called deltaque.exe in -the epoc32\release\winscw\<udeb or urel>\ folder.

                    + + + + + +linkedlist: +Using the Linked List classes +

                    The following examples +show the use of the linked list classes:

                      +

                    • Singly linked list example

                      • +

                    • Doubly linked list example

                      • +

                    • Delta queue example

                      • +
                    +
                    Singly linked +list example

                    This example application demonstrates the use of singly +linked lists. The templated TSglQue class is used to create +a singly linked list.

                    Download

                    Click on the following +link to download the example: sgllist.zip

                    Click: browse to view the example.

                    Description

                    The +example creates a singly linked list of objects of the TDigit class. +This list represents a long number. An object of class CLongNumber owns +the list. The user can edit this list using the functions defined in the CLongNumber class. +The following edit operations are possible:

                      +

                    • Insert an object of +the TDigit class at the start of the singly linked list

                      • +

                    • Insert an object of +the TDigit class at the end of the singly linked list

                      • +

                    • Remove an object of +the TDigit class from the end of the singly linked list

                      • +

                    The user can perform any of these operations by pressing keys specified +in the menu. CLongNumber is an active object class and handles +the key press events in the CLongNumber::RunL() function.The CLongNumber::ReadFunc() function +displays a menu and waits for an asynchronous key press event.

                    An +object of the templated TSglQueIter class is used to traverse +this linked list. The sum of all digits of the number represented by the linked +list is displayed to the user.

                    An object of the CAdder class +is used to traverse the CLongNumber::iNumber list and print +the sum of all digits of the number represented by this list. The CAdder::Add() function +gets this sum.

                    Related APIs

                      +

                    • CAdder

                      • +

                    • CLongNumber

                      • +

                    • TDigit

                      • +

                    • TSglQueIter

                      • +

                    Design and implementation

                    Figure 1 shows the classes +in the example.

                    + Figure 1. Classes in the singly linked list example + + +

                    Class summary

                      +

                    • TSglQue

                      • +

                    • TSglQueIter

                      • +

                    Build

                    The +Symbian build process describes how to build this example.

                    For +the emulator, the example builds an executable called sgllist.exe in +the epoc32\release\winscw\<udeb or urel>\ folder.

                    See +also:

                    Using +Singly Linked Lists

                    +
                    Doubly linked +list example

                    This example application demonstrates the use of doubly +linked lists. The templated TDblQue class is used create +a doubly linked list.

                    Download

                    Click on the following +link to download the example: dbllist.zip

                    Click: browse to view the example code

                    Description

                    The +example creates a doubly linked list of objects of the TLetter class. +This list represents a character string. An object of class CMyStringReverse owns +this string. The user can edit this string using the functions defined in +the CMyStringReverse class. The following edit operations +are possible:

                      +

                    • Insert a character at +the start of the list

                      • +

                    • Insert a character at +the end of the list

                      • +

                    The user can perform either of these operations by pressing keys +specified in the menu. CMyStringReverse is an active object +class and handles key press events in the CMyStringReverse::RunL() function. +The CMyStringReverse::ReadFunc() function displays a menu +and waits for an asynchronous key press event.

                    The CMyStringReverse class +has a doubly linked list iterator, iIteratorString. The iIteratorString object +iterates through the list iString from start to end to print +the string reversed.

                    Design and implementation

                    Figure +2 shows the classes in the example.

                    + Figure 2. Classes in the doubly linked list example + +

                    Class summary

                      +

                    • TDblQue - A templated class that provides the behaviour +for managing a doubly linked list.

                      • +

                    Build

                    The +Symbian build process describes how to build this example.

                    For +the emulator, the example builds an executable called dbllist.exe in +the epoc32\release\winscw\<udeb or urel>\ folder.

                    See +also

                    Using +Doubly Linked Lists

                    Example code

                    +
                    Delta queue +example

                    This example application demonstrates the use of the delta +queue. The templated TDeltaQue class is used create a delta +queue.

                    Download

                    Click on the following link to download +the example: deltaque.zip

                    Click: browse to view the example code.

                    Description

                    The +example creates an object of the CTimerEntry class. This +is a CTimer derived class. An object of this class generates +timer events by using the CTimer::After() function. The +data member of this class, iQueue is a delta list. The offset +value of each node in this list is the tick count after each timer event. +The CTimerEntry::Arbitrator() function decides the action +to be performed for each event generated by the timer. It either adds tick +counts to the list or removes elements from the list based on the state of +the queue.

                    Related APIs

                      +

                    • CTimer - Base class for a timer active object.

                      • +

                    • CTimer::After()

                      • +

                    Design and implementation

                    Figure 3 shows the classes +of the example.

                    + Figure 3. Classes of the delta queue example + +

                    Class summary

                      +

                    • TDeltaQue

                      • +

                    • CTimer - Base class for a timer active object.

                      • +

                    Build

                    The +Symbian build process describes how to build this example.

                    For +the emulator, the example builds an executable called deltaque.exe in +the epoc32\release\winscw\<udeb or urel>\ folder.

                    \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F161C184-2016-4331-A57C-78C753453EFE-master.png Binary file Symbian3/SDK/Source/GUID-F161C184-2016-4331-A57C-78C753453EFE-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F161C184-2016-4331-A57C-78C753453EFE_d0e51832_href.png Binary file Symbian3/SDK/Source/GUID-F161C184-2016-4331-A57C-78C753453EFE_d0e51832_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F161C184-2016-4331-A57C-78C753453EFE_d0e57438_href.png Binary file Symbian3/SDK/Source/GUID-F161C184-2016-4331-A57C-78C753453EFE_d0e57438_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F161C184-2016-4331-A57C-78C753453EFE_d0e58481_href.png Binary file Symbian3/SDK/Source/GUID-F161C184-2016-4331-A57C-78C753453EFE_d0e58481_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F161C184-2016-4331-A57C-78C753453EFE_d0e62503_href.png Binary file Symbian3/SDK/Source/GUID-F161C184-2016-4331-A57C-78C753453EFE_d0e62503_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F161C184-2016-4331-A57C-78C753453EFE_d0e64048_href.png Binary file Symbian3/SDK/Source/GUID-F161C184-2016-4331-A57C-78C753453EFE_d0e64048_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F161C184-2016-4331-A57C-78C753453EFE_d0e69073_href.png Binary file Symbian3/SDK/Source/GUID-F161C184-2016-4331-A57C-78C753453EFE_d0e69073_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F161C184-2016-4331-A57C-78C753453EFE_d0e69279_href.png Binary file Symbian3/SDK/Source/GUID-F161C184-2016-4331-A57C-78C753453EFE_d0e69279_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F161C184-2016-4331-A57C-78C753453EFE_d0e74217_href.png Binary file Symbian3/SDK/Source/GUID-F161C184-2016-4331-A57C-78C753453EFE_d0e74217_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F18A6C91-136D-450E-90F0-7C2B9263777C_d0e4714_href.png Binary file Symbian3/SDK/Source/GUID-F18A6C91-136D-450E-90F0-7C2B9263777C_d0e4714_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F18A6C91-136D-450E-90F0-7C2B9263777C_d0e5989_href.png Binary file Symbian3/SDK/Source/GUID-F18A6C91-136D-450E-90F0-7C2B9263777C_d0e5989_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F18AA5AC-80C6-51B2-8D15-61C59D877520_d0e388871_href.jpg Binary file Symbian3/SDK/Source/GUID-F18AA5AC-80C6-51B2-8D15-61C59D877520_d0e388871_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F18AA5AC-80C6-51B2-8D15-61C59D877520_d0e389033_href.jpg Binary file Symbian3/SDK/Source/GUID-F18AA5AC-80C6-51B2-8D15-61C59D877520_d0e389033_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F1CC06C0-0D3A-4BBC-97E1-E52D2856D7A7.dita --- a/Symbian3/SDK/Source/GUID-F1CC06C0-0D3A-4BBC-97E1-E52D2856D7A7.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-F1CC06C0-0D3A-4BBC-97E1-E52D2856D7A7.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,35 +1,35 @@ - - - - - -Find -pane -

                    The Find pane is a component intended to help find items in a list. The -Find pane is situated in the bottom part of the main pane.

                    - -Find pane within a selection list of names in Phonebook - - -

                    The standard functionality of the Find pane is as follows:

                    -
                      -

                    • Characters typed from the numeric keypad appear at the end of the string -in the Find pane.

                      • -

                    • The user can only add and remove characters at the end.

                      • -

                    • The Find pane may be hidden until the user types in a character.

                      • -

                    • Whenever the find string changes, the list in the main pane is filtered, -and only the items matching the string are displayed. The user can browse -the list normally using the Arrow up and Arrow down keys.

                      • -
                    -

                    The Find pane can also be a pop-up window. In this case, it is only displayed -when it is specifically activated.

                    -
                    Using -the Find pane in C++ applications

                    The APIs to use for the Find pane -are the Searchfield API and the Popups API.

                    + + + + + +Find +pane +

                    The Find pane is a component intended to help find items in a list. The +Find pane is situated in the bottom part of the main pane.

                    + +Find pane within a selection list of names in Phonebook + + +

                    The standard functionality of the Find pane is as follows:

                    +
                      +

                    • Characters typed from the numeric keypad appear at the end of the string +in the Find pane.

                      • +

                    • The user can only add and remove characters at the end.

                      • +

                    • The Find pane may be hidden until the user types in a character.

                      • +

                    • Whenever the find string changes, the list in the main pane is filtered, +and only the items matching the string are displayed. The user can browse +the list normally using the Arrow up and Arrow down keys.

                      • +
                    +

                    The Find pane can also be a pop-up window. In this case, it is only displayed +when it is specifically activated.

                    +
                    Using +the Find pane in applications

                    The APIs to use for the Find pane +are the Searchfield API and the Popups API.

                     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F1EFB7C3-BC06-4822-BA37-06B02BECE80A_d0e74305_href.png Binary file Symbian3/SDK/Source/GUID-F1EFB7C3-BC06-4822-BA37-06B02BECE80A_d0e74305_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F1EFB7C3-BC06-4822-BA37-06B02BECE80A_d0e79427_href.png Binary file Symbian3/SDK/Source/GUID-F1EFB7C3-BC06-4822-BA37-06B02BECE80A_d0e79427_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F21A1ABE-4844-54E2-83E0-4AD25E867A72.dita --- a/Symbian3/SDK/Source/GUID-F21A1ABE-4844-54E2-83E0-4AD25E867A72.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-F21A1ABE-4844-54E2-83E0-4AD25E867A72.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,59 +1,59 @@ - - - - - -ABIv1 -to ABIv2 toolchain changes -

                    The principal task of Symbian platform build tools such as abld/makmake is -to read the specified project (.mmp) files and then call the appropriate compiler -and linker with the necessary inputs and option settings. The binaries output -from commercial compiler and linkers, such as ARM's RVCT and GNU GCC, cannot -however be directly used by Symbian platform. Symbian platform requires binaries -to be in Symbian-specific format, known as the E32Image format.

                    -

                    In order to create binaries in this format, the toolchain must perform -additional steps on the compiler/linker output. How these steps are performed -is considerably different between builds for the ABIv1 and ABIv2 targets. -Essentially, a number of small tools used for ABIv1 targets, are replaced -for ABIv2 targets by a single tool called the post-linker (file name elf2e32.exe). -This redesign is intended to simplify the work needed to introduce support -for a new ABIv2 compatible compiler into the toolchain.

                    -

                    The following diagram shows the steps (somewhat simplified) performed by -the toolchain for the creation of a DLL for ABIv1 and v2 respectively:

                    - - ABIv1 and v2 toolchains compared - - -

                    The elf2e32 tool replaces the ABIv1 toolchain tools def2dll.bat, elf2inf.pl, makedef.pl and elftran.exe.

                    -
                    .dso files

                    In the ABIv2 toolchain, .lib files -are replaced by .dso files. These files are used in similar -situations to .lib files. However, the format of these -two files is completely different. A .lib file is an -archive file created from stubs generated for each of the exported symbols. -A .dso file is an ELF object similar to other objects -created with the compiler. It has all the associated sections required for -an ELF object, such as the symbol table, string table, etc. The .dso file -also has the information required for the linker to link to the correct ordinals -to the DLL. .lib files cannot be used by the ABIv2 toolchain, -and .dso files cannot be used by the ABIv1 toolchain.

                    -
                    Linked objects

                    The compiler toolchain that supports -ABIv2 produces linked objects that are different to those produced by the -ABIv1 toolchain. The linked objects produced are both ELF format, but they -have extra information that can be used by a postlinker to create platform -specific binaries. As the ELF produced by ABIv2 has more information, it is -not necessary to perform the sort of manipulations performed by the many small -tools in the ABIv1 toolchain. As the linked objects differ significantly in -their content, it is not possible to mix ABIv1 and ABIv2 toolchain objects -in the same build tree.

                    -
                    E32Image format

                    The final E32image produced by -the ABIv2 toolchain is in the same format as that of the ABIv1 toolchain. -However, a byte by byte comparison of the same E32image file in ABIv1 and -ABIv2 is not possible. The layout of the code produced by the linker is different, -although the code is still binary compatible.

                    + + + + + +ABIv1 +to ABIv2 toolchain changes +

                    The principal task of Symbian platform build tools such as abld/makmake is +to read the specified project (.mmp) files and then call the appropriate compiler +and linker with the necessary inputs and option settings. The binaries output +from commercial compiler and linkers, such as ARM's RVCT and GNU GCC, cannot +however be directly used by Symbian platform. Symbian platform requires binaries +to be in Symbian-specific format, known as the E32Image format.

                    +

                    In order to create binaries in this format, the toolchain must perform +additional steps on the compiler/linker output. How these steps are performed +is considerably different between builds for the ABIv1 and ABIv2 targets. +Essentially, a number of small tools used for ABIv1 targets, are replaced +for ABIv2 targets by a single tool called the post-linker (file name elf2e32.exe). +This redesign is intended to simplify the work needed to introduce support +for a new ABIv2 compatible compiler into the toolchain.

                    +

                    The following diagram shows the steps (somewhat simplified) performed by +the toolchain for the creation of a DLL for ABIv1 and v2 respectively:

                    + + ABIv1 and v2 toolchains compared + + +

                    The elf2e32 tool replaces the ABIv1 toolchain tools def2dll.bat, elf2inf.pl, makedef.pl and elftran.exe.

                    +
                    .dso files

                    In the ABIv2 toolchain, .lib files +are replaced by .dso files. These files are used in similar +situations to .lib files. However, the format of these +two files is completely different. A .lib file is an +archive file created from stubs generated for each of the exported symbols. +A .dso file is an ELF object similar to other objects +created with the compiler. It has all the associated sections required for +an ELF object, such as the symbol table, string table, etc. The .dso file +also has the information required for the linker to link to the correct ordinals +to the DLL. .lib files cannot be used by the ABIv2 toolchain, +and .dso files cannot be used by the ABIv1 toolchain.

                    +
                    Linked objects

                    The compiler toolchain that supports +ABIv2 produces linked objects that are different to those produced by the +ABIv1 toolchain. The linked objects produced are both ELF format, but they +have extra information that can be used by a postlinker to create platform +specific binaries. As the ELF produced by ABIv2 has more information, it is +not necessary to perform the sort of manipulations performed by the many small +tools in the ABIv1 toolchain. As the linked objects differ significantly in +their content, it is not possible to mix ABIv1 and ABIv2 toolchain objects +in the same build tree.

                    +
                    E32Image format

                    The final E32image produced by +the ABIv2 toolchain is in the same format as that of the ABIv1 toolchain. +However, a byte by byte comparison of the same E32image file in ABIv1 and +ABIv2 is not possible. The layout of the code produced by the linker is different, +although the code is still binary compatible.

                    \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F220E2B7-DE9B-5230-A396-15853369C176_d0e184149_href.png Binary file Symbian3/SDK/Source/GUID-F220E2B7-DE9B-5230-A396-15853369C176_d0e184149_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F220E2B7-DE9B-5230-A396-15853369C176_d0e190745_href.png Binary file Symbian3/SDK/Source/GUID-F220E2B7-DE9B-5230-A396-15853369C176_d0e190745_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F23BB1F1-CF90-597F-8410-34AB8B567501.dita --- a/Symbian3/SDK/Source/GUID-F23BB1F1-CF90-597F-8410-34AB8B567501.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-F23BB1F1-CF90-597F-8410-34AB8B567501.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,82 +1,82 @@ - - - - - -PIM Subsystem -Overview -
                    Purpose

                    This -document describes storage, organisation and utility functionalities within -Symbian platform Personal Information Management (PIM) technology, as defined -by its subsystems: Application Engines and Application Services.

                    -
                    Key Concepts

                    Application -Engines - provide PIM data storage and manipulation.

                    Application -Services - provide a collection of utility components.

                    Application -Engines and Application Services enable user applications to acquire, organise, -maintain, and retrieve personal information.

                    Subsystem - a -cohesive group of components within a single technology.

                    Component - -the smallest unit of architectural significance and the finest grained unit -of description.

                    -
                    Architectural -Relationships

                    PIM Application -Services technology delivers high-level OS services for storage and -manipulation of user data (such as a collection of Calendar and Contacts items). -PIM subsystem components are part of Application Engines and Application Services. -The Symbian platform Generic Middleware layer contains the following PIM components: -Alarm Server, Time Zone Server and Help Model.

                    All the components -are contained between the OS Services layer and the User Interface layer.

                    Key -clients of these components are licensee applications that use subsystems -such as Telephony, SyncML and Messaging.

                    -PIM Subsystem components are part of the Application Services and Generic -Middleware layers - -
                    -
                    Application -Engines

                    Application Engines provide data storage and manipulation -for user data.

                      -

                    • Calendar enables -management of calendar entries and provides access to calendar stores. The -CalInterimAPI library is the Calendar data store.

                      • -

                    • The Contacts -model provides a unified interface for managing contact information.

                      • -
                    -
                    Application -Services

                    Application Services are used by multiple application -engines or applications running on Symbian.

                      -

                    • Alarm -Server maintains a queue of system-wide alarms.

                      • -

                    • Calendar -Conversion converts dates between Gregorian and Chinese lunar calendar -dates for applications requiring Chinese date support.

                      • -

                    • Help -model manages a collection of files that provide context-sensitive -help information.

                      • -

                    • Notepad API is a middleware tool that you can write simple text to -and save for future reference.

                      • -

                    • The Calendar Interim Utils2 is an Organizer API that provides methods -you can use to keep track of your time. It displays the individual days of -a given time period. You can add notes and memos to these dates to organize -your schedule.

                      • -

                    • Phonebook APIs provide methods useful in creating a contacts database -and performing various operations on it. These APIs expand on the Contact -model.

                      • -

                    • Time -zone localization provides localized versions of time zone and city -names.

                      • -

                    • Time -zone server allows clients to obtain accurate conversion between any -time expressed in UTC and local time for a user's time zone.

                      • -

                    • Versit is -a set of utility classes that support the import and export of data that is -formatted according to a set of standards initially defined by the Versit -consortium.

                      • -

                    There are no strong relationships between any of the subsystem components. -They are presented as a subsystem because they enable development of a set -of related applications.

                    + + + + + +PIM Subsystem +Overview +
                    Purpose

                    This +document describes storage, organisation and utility functionalities within +Symbian platform Personal Information Management (PIM) technology, as defined +by its subsystems: Application Engines and Application Services.

                    +
                    Key Concepts

                    Application +Engines - provide PIM data storage and manipulation.

                    Application +Services - provide a collection of utility components.

                    Application +Engines and Application Services enable user applications to acquire, organise, +maintain, and retrieve personal information.

                    Subsystem - a +cohesive group of components within a single technology.

                    Component - +the smallest unit of architectural significance and the finest grained unit +of description.

                    +
                    Architectural +Relationships

                    PIM Application +Services technology delivers high-level OS services for storage and +manipulation of user data (such as a collection of Calendar and Contacts items). +PIM subsystem components are part of Application Engines and Application Services. +The Symbian platform Generic Middleware layer contains the following PIM components: +Alarm Server, Time Zone Server and Help Model.

                    All the components +are contained between the OS Services layer and the User Interface layer.

                    Key +clients of these components are licensee applications that use subsystems +such as Telephony, SyncML and Messaging.

                    +PIM Subsystem components are part of the Application Services and Generic +Middleware layers + +
                    +
                    Application +Engines

                    Application Engines provide data storage and manipulation +for user data.

                      +

                    • Calendar enables +management of calendar entries and provides access to calendar stores. The +CalInterimAPI library is the Calendar data store.

                      • +

                    • The Contacts +model provides a unified interface for managing contact information.

                      • +
                    +
                    Application +Services

                    Application Services are used by multiple application +engines or applications running on Symbian.

                      +

                    • Alarm +Server maintains a queue of system-wide alarms.

                      • +

                    • Calendar +Conversion converts dates between Gregorian and Chinese lunar calendar +dates for applications requiring Chinese date support.

                      • +

                    • Help +model manages a collection of files that provide context-sensitive +help information.

                      • +

                    • Notepad API is a middleware tool that you can write simple text to +and save for future reference.

                      • +

                    • The Calendar Interim Utils2 is an Organizer API that provides methods +you can use to keep track of your time. It displays the individual days of +a given time period. You can add notes and memos to these dates to organize +your schedule.

                      • +

                    • Phonebook APIs provide methods useful in creating a contacts database +and performing various operations on it. These APIs expand on the Contact +model.

                      • +

                    • Time +zone localization provides localized versions of time zone and city +names.

                      • +

                    • Time +zone server allows clients to obtain accurate conversion between any +time expressed in UTC and local time for a user's time zone.

                      • +

                    • Versit is +a set of utility classes that support the import and export of data that is +formatted according to a set of standards initially defined by the Versit +consortium.

                      • +

                    There are no strong relationships between any of the subsystem components. +They are presented as a subsystem because they enable development of a set +of related applications.

                     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F263A3D1-EA96-5D4B-B8C9-4B8471082DBA.dita --- a/Symbian3/SDK/Source/GUID-F263A3D1-EA96-5D4B-B8C9-4B8471082DBA.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-F263A3D1-EA96-5D4B-B8C9-4B8471082DBA.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,14 +1,14 @@ - - - - - -MVS GUI layout

                    The MVS GUI is shown below.

                    This example shows the GUI while an audio file is playing, and includes the tool bar (at the top), the information pane (in the middle), and the status bar (at the bottom).

                    Tool bar

                    The tool bar buttons let you control the currently loaded media file.

                    From left to right, the buttons let you:

                    • play, pause, stop and record a file. These buttons have the standard symbols for AV devices.

                    • set the number of repeats for the file (curved arrow)

                    • set the playback sound volume (megaphone)

                    • set the stereo balance (arrows pointing left and right)

                    • fast reverse the file (standard symbol)

                    • fast forward the file (standard symbol).

                    Information pane

                    The information pane displays details of the current media file:

                    • The state of the file: AUDIO or VIDEO, PLAYING, RECORDING, PAUSED or STOPPED

                    • The sound volume as a percentage of the maximum

                    • The sound balance: Left, Right or Centre

                    • The number of times the file contents are played

                    • The audio priority

                    • The length of the clip in milliseconds

                    • The bit rate (per second).

                    When the a video file is loaded, the pane also contains:

                    • The frame size

                    • The frame rate.

                    Status bar

                    The status bar displays the current state of the GUI.

                    - Status bar -

                    From left to right, the boxes show:

                    • The path and name of the file (if any) being recorded or played.

                    • What the GUI is doing; for example: Recording, Opened, Playing or Idle.

                    • The elapsed time of clip being recorded or played, in hours, minutes, seconds and hundredths of a second (centiseconds): hh:mm:ss:cs.

                    See Also

                    Introduction to the MVS

                    Recording media files

                    Playing media files

                    Editing media files

                    Configuring and clearing files

                    \ No newline at end of file + + + + + +MVS GUI layout

                    The MVS GUI is shown below.

                    This example shows the GUI while an audio file is playing, and includes the tool bar (at the top), the information pane (in the middle), and the status bar (at the bottom).

                    Tool bar

                    The tool bar buttons let you control the currently loaded media file.

                    From left to right, the buttons let you:

                    • play, pause, stop and record a file. These buttons have the standard symbols for AV devices.

                    • set the number of repeats for the file (curved arrow)

                    • set the playback sound volume (megaphone)

                    • set the stereo balance (arrows pointing left and right)

                    • fast reverse the file (standard symbol)

                    • fast forward the file (standard symbol).

                    Information pane

                    The information pane displays details of the current media file:

                    • The state of the file: AUDIO or VIDEO, PLAYING, RECORDING, PAUSED or STOPPED

                    • The sound volume as a percentage of the maximum

                    • The sound balance: Left, Right or Centre

                    • The number of times the file contents are played

                    • The audio priority

                    • The length of the clip in milliseconds

                    • The bit rate (per second).

                    When the a video file is loaded, the pane also contains:

                    • The frame size

                    • The frame rate.

                    Status bar

                    The status bar displays the current state of the GUI.

                    + Status bar +

                    From left to right, the boxes show:

                    • The path and name of the file (if any) being recorded or played.

                    • What the GUI is doing; for example: Recording, Opened, Playing or Idle.

                    • The elapsed time of clip being recorded or played, in hours, minutes, seconds and hundredths of a second (centiseconds): hh:mm:ss:cs.

                    See Also

                    Introduction to the MVS

                    Recording media files

                    Playing media files

                    Editing media files

                    Configuring and clearing files

                    \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F27A92CB-1C02-562B-A93D-57675C53BFEB-master.png Binary file Symbian3/SDK/Source/GUID-F27A92CB-1C02-562B-A93D-57675C53BFEB-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F27A92CB-1C02-562B-A93D-57675C53BFEB_d0e18408_href.png Binary file Symbian3/SDK/Source/GUID-F27A92CB-1C02-562B-A93D-57675C53BFEB_d0e18408_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F27A92CB-1C02-562B-A93D-57675C53BFEB_d0e54310_href.png Binary file Symbian3/SDK/Source/GUID-F27A92CB-1C02-562B-A93D-57675C53BFEB_d0e54310_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F2877A25-1FBC-5C7C-9542-9EDED2748AD3_d0e335623_href.png Binary file Symbian3/SDK/Source/GUID-F2877A25-1FBC-5C7C-9542-9EDED2748AD3_d0e335623_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F2877A25-1FBC-5C7C-9542-9EDED2748AD3_d0e341780_href.png Binary file Symbian3/SDK/Source/GUID-F2877A25-1FBC-5C7C-9542-9EDED2748AD3_d0e341780_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F2D86E40-279A-5B48-B91F-922803FEF5DE.dita --- a/Symbian3/SDK/Source/GUID-F2D86E40-279A-5B48-B91F-922803FEF5DE.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-F2D86E40-279A-5B48-B91F-922803FEF5DE.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,231 +1,231 @@ - - - - - -SMS -MTM Overview -

                    SMS MTM provides APIs for sending SMS text messages. This section provides -an overview of the SMS MTM component.

                    -
                    Description

                    The Messaging Application module provides -a SMS MTM for handling SMS messages in the Message Store. For further SMS -support available on the Symbian platform, see Cellular -Baseband Services Guide documentation.

                    Supported functionality

                    SMS -MTM provides functionality to create, store and retrieve an SMS message entry -in the Message Store, send an SMS, reply to a received SMS and forward existing -SMS. A reply to a received SMS may include the original message text, including -any EMS components.

                    SMS that are received by SMS MTM are stored in -the Message Store. The type and class of the received SMS affects the storage -of a message. All received class 2 SMS are stored in a non-Symbian platform -store.

                    Storing SMS

                    SMS messages that are received by -SMS MTM are stored in both the Message Store and a non-Symbian platform store. -Messages can be moved, copied to, from the non-Symbian platform store and -the Message Store. The non-Symbian platform store can be enumerated so that -its contents can be reflected in the folder in the Message Store, except any -of the standard folders (for example, the global inbox).

                    The type -and class of the received SMS affects message storage. All received class -2 SMS message are stored in the class 2 folder in a non-Symbian platform store. -The class 2 folder is a configurable location in the Message Store and may -be set to be the global inbox. All received non-class 2 SMS messages are stored -in the global inbox folder of the Message Store.

                    Sending SMS

                    SMS -MTM can send the message immediately or schedule it for a specific time. Before -SMS MTM sends an SMS, it checks the global outbox in the Message Store for -any SMS that are waiting to be sent (these can also be scheduled for sending). -If an SMS failed to be sent, then the MTM may re-schedule that SMS to be sent -at a later time. A re-schedule is configurable against the failure error code. -The schedule send functionality handles this configuration. A SMS that is -successfully sent is moved to the sent folder in the Message Store by SMS -MTM.

                    This MTM supports multiple recipients for an SMS message. An -outgoing SMS message may have multiple recipients. When this message is being -sent, one message is sent for each recipient.

                    BIO messages

                    SMS -MTM is aware of BIO messages and uses the BIO Framework to tag SMS with the -appropriate BIO type. This includes support for WAP messages.

                    Unsupported -functionality

                    SMS MTM does not support sending and receiving OTA -(Over The Air) SMS messages.

                    -
                    Architecture

                    The Messaging Middleware architecture -defines a framework in which modules (MTMs) can be implemented that provide -support for particular messaging protocols. A client MTM provides the API -for application engines to use the protocol. SMS MTM API provides the client -MTM API, server MTM API, and supporting classes for SMS.

                    SMS MTM integrates -SMS into the Messaging architecture, so that SMS can be used by a messaging -client program in a similar way to other message types such as email. SMS -MTM uses the SMS interface provided by the Telephony sub-system. This provides -support for 7, 8, and 16-bit text messages, and message concatenation.

                    The -following figure shows the SMS architecture:

                    - SMS MTM architecture - -

                    SMS Client MTM

                    The SMS Client MTM implements the -standard set of Client -MTM APIs described in Client -MTM. In addition, it provides the following functionality:

                      -

                    • Access to the CSmsHeader object -that is used to represent the SMS message.

                      • -

                    • Access to the SMS settings -stored in the associated SMS service centre.

                      • -

                    • Provides the APIs required -by SendAs to allow SendAs to create SMS, including setting the BIO type message -to allow clients of SendAs to send BIO messages, such as vCards and vCals. -The data of the BIO message is stored in the body text of the SMS.

                      • -

                    • Simple check for valid -SMS addresses; an SMS address is considered valid if it contains at least -one digit.

                      • -

                    • Reading and writing -SIM parameters.

                      • -
                    MS receiving is normally done automatically by the Cellular Baseband -and messaging components, with received SMS messages placed in the Inbox. -Generic message receiving operations are not supported by the MTM. Also, UI -functionality, such as SMS message viewing and editing, is not provided by -the Symbian platform.

                    The SMS Client MTM class is CSmsClientMtm.

                    SMS Server MTM

                    SMS -Server MTM implements the Server-side -MTM interface, and primarily provides functionality to handle requests -from the client MTM to send SMS messages. Incoming SMS messages are handled -by a group of components called SMS watchers.

                    These components provide -a layer over the SMS support provided in the Narrow Band Protocols Stack subsystem. -This has SMS stacks for GSM which offer an encapsulation of an SMS message, -together with the ability to send and receive messages. At the lowest level, -below the SMS stacks, is the ETel multimode API, which provides low-level -access to the phone drivers.

                    The SMS Server MTM provides access to -messages under remote services. It is loaded in the Message Server’s process -space and handles the following tasks:

                      -

                    • Connecting to remote -servers to handle updating the cache of SMS messages.

                      • -

                    • Sending messages that -are copied to remote services when messages are copied to a remote service.

                      The -SMS Server MTM handles sending of SMS and WAP messages through the SMS stack -and the WAP stack respectively. To support this, it implements the CBaseServerMtm::CopyFromLocal() function -inherited from the Server -MTM base class. It implements this for sending SMS and moving the successfully -sent messages to the Sent folder. When sending the SMS, the Server -MTM checks the BIO type of the message and uses the BIO database to check -the transport type for the BIO message. The MTM supports ENbs that -is sent through the SMS stack and EWap, EWapSecure that -are sent through the WAP stack. The MTM does not support EWsp or EWspSecure although -the watchers do support receiving them.

                      • -

                    • Scheduling messages

                      The -SMS Server MTM implements scheduled sending API by sub-classing from the Schedule -send Server MTM. It accepts requests from client applications either through -the SMS Client MTM's CBaseMtm::InvokeAsyncFunctionL() API -or through the CMsvSession::TransferCommand() API to schedule -messages to be sent or to delete existing schedules. When it receives a request -to schedule a message, it packages the command and uses the Scheduled Send -functionality to request that the task scheduler ask it to send the messages -at a future point in time.

                      • -

                    • Managing phone store

                      The -phone store is a storage for SMS outside the Message Store. For example, for -GSM phones it is the SIM. The SMS Server MTM accepts requests from -client applications to copy or move messages to and from the SIM and delete -messages from the SIM. For example, when copying to the SIM, it packages SMS -and passes it to the SMS stack with a request to write it to the SIM. If the -class2 folder is set in the SMS settings class, the Server MTM copies the -SMS to the SIM and then updates the SMS in the message store. The Server MTM -also provides the details of the space used to store on the SIM and the reason -for storing on the SIM.

                      • -

                    • Providing SIM parameters

                      The -Server MTM provides functions to read and write SIM parameters.

                      • -

                    The SMS Server MTM class is CSmsServerMtm.

                    SMS -Utilities

                    SMS Utilities provide the following:

                      -

                    • Classes to represent -and store SMS (CSmsHeader), and SMS settings (CSmsSettings, CSmsMessageSettings) -and a SMS number (CSmsNumber).

                      • -

                    • Functions to generate -descriptions and details fields to store with SMS. The details includes decoding -special messages (such as, message indication and status report messages), -reading resource file for descriptions strings of special messages, and using -the contacts database to replace phone numbers with names.

                      • -

                    • Function to validate -a GSM number.

                      • -

                    • Mode to find the TMsvId of -the SMS service entry.

                      • -

                    SMS Watchers

                    SMS Watchers are made up of two watchers, -the nbswatcher.dll and the wapwatcher.dll, -and some common base classes in biowatcher.dll. The watchers -listen for incoming messages from the SMS Stack, part of Cellular Baseband -Services, and the WAP stack, part of High-level Internet Protocols.

                    SMS -Stack

                    SMS Stack is one of a number of protocol stacks that is -supported by the ESock Server client-server framework. The SMS Stack’s principal -clients are the messaging applications, WAP Stack and third party applications. -The Messaging Application and the third party applications access the stack -as clients of the ESock Server, while the WAP Stack accesses directly the -SMS Stack. For more information on SMS Stack, see SMS -Stack for GSM Networks.

                    SMS service settings

                    Settings -for SMS connections, such as service centre addresses, are stored in the Message -Store (CMsvStore) for the SMS service entry. Encapsulation -of service settings is provided by CSmsSettings.

                    Progress -information

                    The progress information can be obtained for messaging -operations. For SMS operations, progress information includes such things -as type of operation, and number of messages processed. Progress information -is provided by TSmsProgress.

                    -
                    APIs - -

                    The following are the important classes for SMS Client MTM:

                    - - - -

                    Class

                    -

                    Purpose

                    -                     - -

                    CSmsClientMtm

                    -

                    Implements the messaging architecture client MTM interface for SMS. -It allows messages to be created, replied to, and forwarded, and MTM-specific -commands to be given.

                    It provides an accessor function SmsHeader() to -get the CSmsHeader for a message.

                    -                     - -

                    CSmsHeader

                    -

                    Encapsulates an SMS message in a message store.

                    It provides -information about message recipients as an array of CSmsNumber objects, -and access to the family of classes derived from TMsvMessageBio, -which allow fields of a message to be set and accessed.

                    For compatibility -with the API of the v8 (GSM only) SMS MTM, it also provides access to the -GSM SMS stack's message class CSmsMessage.

                    -                     - -

                    TMsvMessageGsm

                    -

                    Provides access to GSM-specific fields.

                    -                     - -

                    TMsvSmsEntry

                    -

                    Provides a specialisation of the message server index class TMsvEntry for -SMS message entries.

                    Putting selected SMS-specific fields in the index -entry allows message clients to quickly get important message properties without -having to create a message object.

                    -                     - -

                    CSmsNumber

                    -

                    Encapsulates recipient information for an SMS message.

                    -                     - -

                    CSmsSettings

                    -

                    Defines settings for the SMS service.

                    It contains some GSM-specific -functions to maintain compability with the GSM SMS MTM.

                    It also provides -access to CSmsMessageSettingsProxy for outgoing message -defaults.

                    -                     - -

                    CSmsAccount

                    -

                    Stores SMS service and Schedule Send settings to Central Repository.

                    -                     - -

                    CSmsServiceCenter

                    -

                    Used to store Service Centre numbers and their associated name.

                    -                     - - -
                    -                     -SMS MTM Concepts - -Message Type -Module -Using the -Policy Evaluator Plug-in -SMS - Tutorial + + + + + +SMS +MTM Overview +

                    SMS MTM provides APIs for sending SMS text messages. This section provides +an overview of the SMS MTM component.

                    +
                    Description

                    The Messaging Application module provides +a SMS MTM for handling SMS messages in the Message Store. For further SMS +support available on the Symbian platform, see Cellular +Baseband Services Guide documentation.

                    Supported functionality

                    SMS +MTM provides functionality to create, store and retrieve an SMS message entry +in the Message Store, send an SMS, reply to a received SMS and forward existing +SMS. A reply to a received SMS may include the original message text, including +any EMS components.

                    SMS that are received by SMS MTM are stored in +the Message Store. The type and class of the received SMS affects the storage +of a message. All received class 2 SMS are stored in a non-Symbian platform +store.

                    Storing SMS

                    SMS messages that are received by +SMS MTM are stored in both the Message Store and a non-Symbian platform store. +Messages can be moved, copied to, from the non-Symbian platform store and +the Message Store. The non-Symbian platform store can be enumerated so that +its contents can be reflected in the folder in the Message Store, except any +of the standard folders (for example, the global inbox).

                    The type +and class of the received SMS affects message storage. All received class +2 SMS message are stored in the class 2 folder in a non-Symbian platform store. +The class 2 folder is a configurable location in the Message Store and may +be set to be the global inbox. All received non-class 2 SMS messages are stored +in the global inbox folder of the Message Store.

                    Sending SMS

                    SMS +MTM can send the message immediately or schedule it for a specific time. Before +SMS MTM sends an SMS, it checks the global outbox in the Message Store for +any SMS that are waiting to be sent (these can also be scheduled for sending). +If an SMS failed to be sent, then the MTM may re-schedule that SMS to be sent +at a later time. A re-schedule is configurable against the failure error code. +The schedule send functionality handles this configuration. A SMS that is +successfully sent is moved to the sent folder in the Message Store by SMS +MTM.

                    This MTM supports multiple recipients for an SMS message. An +outgoing SMS message may have multiple recipients. When this message is being +sent, one message is sent for each recipient.

                    BIO messages

                    SMS +MTM is aware of BIO messages and uses the BIO Framework to tag SMS with the +appropriate BIO type. This includes support for WAP messages.

                    Unsupported +functionality

                    SMS MTM does not support sending and receiving OTA +(Over The Air) SMS messages.

                    +
                    Architecture

                    The Messaging Middleware architecture +defines a framework in which modules (MTMs) can be implemented that provide +support for particular messaging protocols. A client MTM provides the API +for application engines to use the protocol. SMS MTM API provides the client +MTM API, server MTM API, and supporting classes for SMS.

                    SMS MTM integrates +SMS into the Messaging architecture, so that SMS can be used by a messaging +client program in a similar way to other message types such as email. SMS +MTM uses the SMS interface provided by the Telephony sub-system. This provides +support for 7, 8, and 16-bit text messages, and message concatenation.

                    The +following figure shows the SMS architecture:

                    + SMS MTM architecture + +

                    SMS Client MTM

                    The SMS Client MTM implements the +standard set of Client +MTM APIs described in Client +MTM. In addition, it provides the following functionality:

                      +

                    • Access to the CSmsHeader object +that is used to represent the SMS message.

                      • +

                    • Access to the SMS settings +stored in the associated SMS service centre.

                      • +

                    • Provides the APIs required +by SendAs to allow SendAs to create SMS, including setting the BIO type message +to allow clients of SendAs to send BIO messages, such as vCards and vCals. +The data of the BIO message is stored in the body text of the SMS.

                      • +

                    • Simple check for valid +SMS addresses; an SMS address is considered valid if it contains at least +one digit.

                      • +

                    • Reading and writing +SIM parameters.

                      • +
                    MS receiving is normally done automatically by the Cellular Baseband +and messaging components, with received SMS messages placed in the Inbox. +Generic message receiving operations are not supported by the MTM. Also, UI +functionality, such as SMS message viewing and editing, is not provided by +the Symbian platform.

                    The SMS Client MTM class is CSmsClientMtm.

                    SMS Server MTM

                    SMS +Server MTM implements the Server-side +MTM interface, and primarily provides functionality to handle requests +from the client MTM to send SMS messages. Incoming SMS messages are handled +by a group of components called SMS watchers.

                    These components provide +a layer over the SMS support provided in the Narrow Band Protocols Stack subsystem. +This has SMS stacks for GSM which offer an encapsulation of an SMS message, +together with the ability to send and receive messages. At the lowest level, +below the SMS stacks, is the ETel multimode API, which provides low-level +access to the phone drivers.

                    The SMS Server MTM provides access to +messages under remote services. It is loaded in the Message Server’s process +space and handles the following tasks:

                      +

                    • Connecting to remote +servers to handle updating the cache of SMS messages.

                      • +

                    • Sending messages that +are copied to remote services when messages are copied to a remote service.

                      The +SMS Server MTM handles sending of SMS and WAP messages through the SMS stack +and the WAP stack respectively. To support this, it implements the CBaseServerMtm::CopyFromLocal() function +inherited from the Server +MTM base class. It implements this for sending SMS and moving the successfully +sent messages to the Sent folder. When sending the SMS, the Server +MTM checks the BIO type of the message and uses the BIO database to check +the transport type for the BIO message. The MTM supports ENbs that +is sent through the SMS stack and EWap, EWapSecure that +are sent through the WAP stack. The MTM does not support EWsp or EWspSecure although +the watchers do support receiving them.

                      • +

                    • Scheduling messages

                      The +SMS Server MTM implements scheduled sending API by sub-classing from the Schedule +send Server MTM. It accepts requests from client applications either through +the SMS Client MTM's CBaseMtm::InvokeAsyncFunctionL() API +or through the CMsvSession::TransferCommand() API to schedule +messages to be sent or to delete existing schedules. When it receives a request +to schedule a message, it packages the command and uses the Scheduled Send +functionality to request that the task scheduler ask it to send the messages +at a future point in time.

                      • +

                    • Managing phone store

                      The +phone store is a storage for SMS outside the Message Store. For example, for +GSM phones it is the SIM. The SMS Server MTM accepts requests from +client applications to copy or move messages to and from the SIM and delete +messages from the SIM. For example, when copying to the SIM, it packages SMS +and passes it to the SMS stack with a request to write it to the SIM. If the +class2 folder is set in the SMS settings class, the Server MTM copies the +SMS to the SIM and then updates the SMS in the message store. The Server MTM +also provides the details of the space used to store on the SIM and the reason +for storing on the SIM.

                      • +

                    • Providing SIM parameters

                      The +Server MTM provides functions to read and write SIM parameters.

                      • +

                    The SMS Server MTM class is CSmsServerMtm.

                    SMS +Utilities

                    SMS Utilities provide the following:

                      +

                    • Classes to represent +and store SMS (CSmsHeader), and SMS settings (CSmsSettings, CSmsMessageSettings) +and a SMS number (CSmsNumber).

                      • +

                    • Functions to generate +descriptions and details fields to store with SMS. The details includes decoding +special messages (such as, message indication and status report messages), +reading resource file for descriptions strings of special messages, and using +the contacts database to replace phone numbers with names.

                      • +

                    • Function to validate +a GSM number.

                      • +

                    • Mode to find the TMsvId of +the SMS service entry.

                      • +

                    SMS Watchers

                    SMS Watchers are made up of two watchers, +the nbswatcher.dll and the wapwatcher.dll, +and some common base classes in biowatcher.dll. The watchers +listen for incoming messages from the SMS Stack, part of Cellular Baseband +Services, and the WAP stack, part of High-level Internet Protocols.

                    SMS +Stack

                    SMS Stack is one of a number of protocol stacks that is +supported by the ESock Server client-server framework. The SMS Stack’s principal +clients are the messaging applications, WAP Stack and third party applications. +The Messaging Application and the third party applications access the stack +as clients of the ESock Server, while the WAP Stack accesses directly the +SMS Stack. For more information on SMS Stack, see SMS +Stack for GSM Networks.

                    SMS service settings

                    Settings +for SMS connections, such as service centre addresses, are stored in the Message +Store (CMsvStore) for the SMS service entry. Encapsulation +of service settings is provided by CSmsSettings.

                    Progress +information

                    The progress information can be obtained for messaging +operations. For SMS operations, progress information includes such things +as type of operation, and number of messages processed. Progress information +is provided by TSmsProgress.

                    +
                    APIs + +

                    The following are the important classes for SMS Client MTM:

                    + + + +

                    Class

                    +

                    Purpose

                    +                     + +

                    CSmsClientMtm

                    +

                    Implements the messaging architecture client MTM interface for SMS. +It allows messages to be created, replied to, and forwarded, and MTM-specific +commands to be given.

                    It provides an accessor function SmsHeader() to +get the CSmsHeader for a message.

                    +                     + +

                    CSmsHeader

                    +

                    Encapsulates an SMS message in a message store.

                    It provides +information about message recipients as an array of CSmsNumber objects, +and access to the family of classes derived from TMsvMessageBio, +which allow fields of a message to be set and accessed.

                    For compatibility +with the API of the v8 (GSM only) SMS MTM, it also provides access to the +GSM SMS stack's message class CSmsMessage.

                    +                     + +

                    TMsvMessageGsm

                    +

                    Provides access to GSM-specific fields.

                    +                     + +

                    TMsvSmsEntry

                    +

                    Provides a specialisation of the message server index class TMsvEntry for +SMS message entries.

                    Putting selected SMS-specific fields in the index +entry allows message clients to quickly get important message properties without +having to create a message object.

                    +                     + +

                    CSmsNumber

                    +

                    Encapsulates recipient information for an SMS message.

                    +                     + +

                    CSmsSettings

                    +

                    Defines settings for the SMS service.

                    It contains some GSM-specific +functions to maintain compability with the GSM SMS MTM.

                    It also provides +access to CSmsMessageSettingsProxy for outgoing message +defaults.

                    +                     + +

                    CSmsAccount

                    +

                    Stores SMS service and Schedule Send settings to Central Repository.

                    +                     + +

                    CSmsServiceCenter

                    +

                    Used to store Service Centre numbers and their associated name.

                    +                     + + +
                    +                     +SMS MTM Concepts + +Message Type +Module +Using the +Policy Evaluator Plug-in +SMS + Tutorial                     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F2D96A30-7264-5CAF-9CC7-8AF05EF978E1_d0e117673_href.png Binary file Symbian3/SDK/Source/GUID-F2D96A30-7264-5CAF-9CC7-8AF05EF978E1_d0e117673_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F2D96A30-7264-5CAF-9CC7-8AF05EF978E1_d0e124211_href.png Binary file Symbian3/SDK/Source/GUID-F2D96A30-7264-5CAF-9CC7-8AF05EF978E1_d0e124211_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F2E8CB4B-C1BB-577D-B018-7FF231B70D8C_d0e189694_href.png Binary file Symbian3/SDK/Source/GUID-F2E8CB4B-C1BB-577D-B018-7FF231B70D8C_d0e189694_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F2E8CB4B-C1BB-577D-B018-7FF231B70D8C_d0e194747_href.png Binary file Symbian3/SDK/Source/GUID-F2E8CB4B-C1BB-577D-B018-7FF231B70D8C_d0e194747_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F2F19F40-E87B-4FF2-ABE8-4E14AE728364-master.png Binary file Symbian3/SDK/Source/GUID-F2F19F40-E87B-4FF2-ABE8-4E14AE728364-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F2F19F40-E87B-4FF2-ABE8-4E14AE728364_d0e66931_href.png Binary file Symbian3/SDK/Source/GUID-F2F19F40-E87B-4FF2-ABE8-4E14AE728364_d0e66931_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F2F19F40-E87B-4FF2-ABE8-4E14AE728364_d0e72186_href.png Binary file Symbian3/SDK/Source/GUID-F2F19F40-E87B-4FF2-ABE8-4E14AE728364_d0e72186_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F31EC49A-FE01-58B2-9CB5-4A3BBCCB7DA7_d0e184746_href.png Binary file Symbian3/SDK/Source/GUID-F31EC49A-FE01-58B2-9CB5-4A3BBCCB7DA7_d0e184746_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F31EC49A-FE01-58B2-9CB5-4A3BBCCB7DA7_d0e191342_href.png Binary file Symbian3/SDK/Source/GUID-F31EC49A-FE01-58B2-9CB5-4A3BBCCB7DA7_d0e191342_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F32E2F00-B68F-59B2-AABA-181E16354C86-GENID-1-8-1-3-1-1-7-1-7-1-9-1.dita --- a/Symbian3/SDK/Source/GUID-F32E2F00-B68F-59B2-AABA-181E16354C86-GENID-1-8-1-3-1-1-7-1-7-1-9-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,48 +0,0 @@ - - - - - -The -object provider (MOP) mechanism -
                    Purpose

                    The object provider mechanism -exists to enable control types to be established at run time. It's a form -of Run Time Type Identification (RTTI). More specifically it allows a caller -to find a control in the run-time hierarchy that implements a particular interface, -or mixin. From the caller's point of view it's pretty simple: all that's required -is to ask a control, any control, to get an object that supports the specified -interface, cast the pointer returned to the correct interface and then call -the desired function.

                    -
                    History

                    The Object Provider interface pre-dates -the parent pointer in CCoeControl. Instead it uses a MopParent pointer -which is normally the parent control but may be the AppUi or even the CoeEnv object. -It was designed to meet Series 60 requirements for navigation of the run-time -hierarchy. Internally it is now implemented by the framework using the parent -pointer where possible which simplifies the control development process.

                    -
                    Description

                    Interfaces are only identifiable by -the Object Provider framework if they have an associated Interface UID. The -Interface UID must be declared in the class definition. Fortunately the UID -is invisible to the caller which simply uses the interface (mixin) name.

                    A -class which implements an identifiable mixin, i.e. one with an Interface UID, -can 'supply' a pointer to itself when the Object Provider framework requests -it. If a control is not able to supply the mixin requested it passes the request -on to the next control in the hierarchy.

                    The sequence diagram below -illustrates the Object Provider process for supplying an interface pointer -from the run-time hierarchy.

                    - -

                    Object1 wishes to call a function on MInterface. -It calls MopGetObject() on the nearest control in the run-time -hierarchy. The Object Provider Framework identifies the Uid for Minterface and -then passes the request up the hierarchy until an object is found (Object4) -that implements Minterface.

                    Calling MopGetGetObjectNoChaining() will -call MopSupplyObject() but not MopNext(). -It returns Null if the class does not implement the specified mixin.

                    -
                    See also

                    How -to write controls

                    -                     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F32E2F00-B68F-59B2-AABA-181E16354C86-GENID-1-8-1-6-1-1-4-1-6-1-7-1-9-1.dita --- a/Symbian3/SDK/Source/GUID-F32E2F00-B68F-59B2-AABA-181E16354C86-GENID-1-8-1-6-1-1-4-1-6-1-7-1-9-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,48 +0,0 @@ - - - - - -The -object provider (MOP) mechanism -
                    Purpose

                    The object provider mechanism -exists to enable control types to be established at run time. It's a form -of Run Time Type Identification (RTTI). More specifically it allows a caller -to find a control in the run-time hierarchy that implements a particular interface, -or mixin. From the caller's point of view it's pretty simple: all that's required -is to ask a control, any control, to get an object that supports the specified -interface, cast the pointer returned to the correct interface and then call -the desired function.

                    -
                    History

                    The Object Provider interface pre-dates -the parent pointer in CCoeControl. Instead it uses a MopParent pointer -which is normally the parent control but may be the AppUi or even the CoeEnv object. -It was designed to meet Series 60 requirements for navigation of the run-time -hierarchy. Internally it is now implemented by the framework using the parent -pointer where possible which simplifies the control development process.

                    -
                    Description

                    Interfaces are only identifiable by -the Object Provider framework if they have an associated Interface UID. The -Interface UID must be declared in the class definition. Fortunately the UID -is invisible to the caller which simply uses the interface (mixin) name.

                    A -class which implements an identifiable mixin, i.e. one with an Interface UID, -can 'supply' a pointer to itself when the Object Provider framework requests -it. If a control is not able to supply the mixin requested it passes the request -on to the next control in the hierarchy.

                    The sequence diagram below -illustrates the Object Provider process for supplying an interface pointer -from the run-time hierarchy.

                    - -

                    Object1 wishes to call a function on MInterface. -It calls MopGetObject() on the nearest control in the run-time -hierarchy. The Object Provider Framework identifies the Uid for Minterface and -then passes the request up the hierarchy until an object is found (Object4) -that implements Minterface.

                    Calling MopGetGetObjectNoChaining() will -call MopSupplyObject() but not MopNext(). -It returns Null if the class does not implement the specified mixin.

                    -
                    See also

                    How -to write controls

                    -                     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F32E2F00-B68F-59B2-AABA-181E16354C86.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-F32E2F00-B68F-59B2-AABA-181E16354C86.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,48 @@ + + + + + +The +object provider (MOP) mechanism +
                    Purpose

                    The object provider mechanism +exists to enable control types to be established at run time. It's a form +of Run Time Type Identification (RTTI). More specifically it allows a caller +to find a control in the run-time hierarchy that implements a particular interface, +or mixin. From the caller's point of view it's pretty simple: all that's required +is to ask a control, any control, to get an object that supports the specified +interface, cast the pointer returned to the correct interface and then call +the desired function.

                    +
                    History

                    The Object Provider interface pre-dates +the parent pointer in CCoeControl. Instead it uses a MopParent pointer +which is normally the parent control but may be the AppUi or even the CoeEnv object. +It was designed to meet Series 60 requirements for navigation of the run-time +hierarchy. Internally it is now implemented by the framework using the parent +pointer where possible which simplifies the control development process.

                    +
                    Description

                    Interfaces are only identifiable by +the Object Provider framework if they have an associated Interface UID. The +Interface UID must be declared in the class definition. Fortunately the UID +is invisible to the caller which simply uses the interface (mixin) name.

                    A +class which implements an identifiable mixin, i.e. one with an Interface UID, +can 'supply' a pointer to itself when the Object Provider framework requests +it. If a control is not able to supply the mixin requested it passes the request +on to the next control in the hierarchy.

                    The sequence diagram below +illustrates the Object Provider process for supplying an interface pointer +from the run-time hierarchy.

                    + +

                    Object1 wishes to call a function on MInterface. +It calls MopGetObject() on the nearest control in the run-time +hierarchy. The Object Provider Framework identifies the Uid for Minterface and +then passes the request up the hierarchy until an object is found (Object4) +that implements Minterface.

                    Calling MopGetGetObjectNoChaining() will +call MopSupplyObject() but not MopNext(). +It returns Null if the class does not implement the specified mixin.

                    +
                    See also

                    How +to write controls

                    +                     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F342B002-0667-5D51-AE2D-3CF534D70B62_d0e213719_href.png Binary file Symbian3/SDK/Source/GUID-F342B002-0667-5D51-AE2D-3CF534D70B62_d0e213719_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F342B002-0667-5D51-AE2D-3CF534D70B62_d0e217456_href.png Binary file Symbian3/SDK/Source/GUID-F342B002-0667-5D51-AE2D-3CF534D70B62_d0e217456_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F392355C-C499-555A-85B7-1DF40492E9B2_d0e220085_href.png Binary file Symbian3/SDK/Source/GUID-F392355C-C499-555A-85B7-1DF40492E9B2_d0e220085_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F392355C-C499-555A-85B7-1DF40492E9B2_d0e223822_href.png Binary file Symbian3/SDK/Source/GUID-F392355C-C499-555A-85B7-1DF40492E9B2_d0e223822_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F3EE1000-71A6-4D48-A30B-3D2357BF20FB.dita --- a/Symbian3/SDK/Source/GUID-F3EE1000-71A6-4D48-A30B-3D2357BF20FB.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-F3EE1000-71A6-4D48-A30B-3D2357BF20FB.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,65 +1,67 @@ - - - - - -Generic -button APIThe Generic button API is used for enabling touch support for buttons. -

                    An Avkon button is a generic button component specifically designed for -touch support. The generic button component (CAknButton, defined in aknbutton.h) is used, for example, in -a toolbar and a status pane. The button can contain text, an image, or both.

                    -

                    Buttons can have multiple states, and each of the states can have three -different states according to user actions. The possible user-action states -for the button states are:

                    -
                      -

                    • Normal

                      • -

                    • Pressed down

                      • -

                    • Dimmed

                      • -
                    -

                    By default, the button has a frame, it responds to tap (press) event, has -a latchable view in the pressed-down state, and has horizontally and vertically -aligned text in it. Some default behavior can be changed with button flags -or with the help of member functions.

                    -

                    To observe the buttons in your application, use the MCoeControlObserver observer -interface.

                    - -Generic button used in a toolbar - - -

                    The Generic button API is used for creating buttons that are displayed -as parts of container components, such as a toolbar. It is not used for creating -CBA buttons displayed in the control pane at the bottom of the device screen. -The API for creating CBA buttons is the Buttons API.

                     -

                    For look and feel guidelines on the generic button component as part of -a toolbar, see the toolbar -UI component description.

                    -

                    For information on using the API, see Enabling -touch support for buttons.

                    -

                    For the Generic button API classes and header files, see Classes and Definitions.

                    -
                    Constraints

                    This -API is valid for all platforms running on Symbian OS v9.3 or later.

                    -
                    Emulator support

                    This -API is supported in the WINS/WINSCW emulator environment, with the following -exception:

                      -

                    • Tactile feedback is not supported.

                      • -
                    -                     -Related APIs -Skins API - for adding skin support to the button - -Toolbar API - for creating a toolbar containing generic buttons - -Touch UI -utilities API - for using long-tap events - - + + + + + +Generic +button APIThe Generic button API is used for enabling touch support for buttons. +

                    An Avkon button is a generic button component specifically designed for +touch support. The generic button component (CAknButton, defined in aknbutton.h) is used, for example, in +a toolbar and a status pane. The button can contain text, an image, or both.

                    +

                    Buttons can have multiple states, and each of the states can have three +different states according to user actions. The possible user-action states +for the button states are:

                    +
                      +

                    • Normal

                      • +

                    • Pressed down

                      • +

                    • Dimmed

                      • +
                    +

                    By default, the button has a frame, it responds to tap (press) event, has +a latchable view in the pressed-down state, and has horizontally and vertically +aligned text in it. Some default behavior can be changed with button flags +or with the help of member functions.

                    +

                    To observe the buttons in your application, use the MCoeControlObserver observer +interface.

                    + +Generic button used in a toolbar + + +

                    The Generic button API is used for creating buttons that are displayed +as parts of container components, such as a toolbar. It is not used for creating +CBA buttons displayed in the control pane at the bottom of the device screen. +The API for creating CBA buttons is the Buttons API.

                     +

                    For look and feel guidelines on the generic button component as part of +a toolbar, see the toolbar +UI component description.

                    +

                    For information on using the API, see Enabling +touch support for buttons.

                    +

                    For the Generic button API classes and header files, see Classes and Definitions.

                    +
                    Changes and release information

                    The Generic button +API is an SDK API and first released in S60 5th Edition.

                    +
                    Constraints

                    This +API is valid for all platforms running on Symbian OS v9.3 or later.

                    +
                    Emulator support

                    This +API is supported in the WINS/WINSCW emulator environment, with the following +exception:

                      +

                    • Tactile feedback is not supported.

                      • +
                    +                     +Related APIs +Skins API + for adding skin support to the button + +Toolbar API + for creating a toolbar containing generic buttons + +Touch UI +utilities API + for using long-tap events + +                     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F4203C60-EB2A-4644-8B2D-291087724BA9_d0e143081_href.png Binary file Symbian3/SDK/Source/GUID-F4203C60-EB2A-4644-8B2D-291087724BA9_d0e143081_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F4203C60-EB2A-4644-8B2D-291087724BA9_d0e149615_href.png Binary file Symbian3/SDK/Source/GUID-F4203C60-EB2A-4644-8B2D-291087724BA9_d0e149615_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F43A54C0-E82B-5790-8493-1372D214C642.dita --- a/Symbian3/SDK/Source/GUID-F43A54C0-E82B-5790-8493-1372D214C642.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-F43A54C0-E82B-5790-8493-1372D214C642.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,142 +1,142 @@ - - - - - -What -are PlanesThis topic describes the concept of a Plane in the Communications -Framework. -

                    The transmission of data and the management of connections is divided into -separate operations. Symbian platform gives the name Plane to -these operations. The Communications Framework defines three Planes. Each -Plane has a separate role and a separate responsibility. Each Plane matches -a Sockets Server API.

                    -

                    The Planes are called: the Data Plane, the Control Plane and the Management -Plane.

                    -

                    Layers span all three Planes. Code in each Plane operates together to deliver -the required Communications protocol behaviour.

                    -

                    A connection can have a number of subconnections. Subconnections can be -called channels. The concepts of connection and subconnection make it useful -to divide the Control Plane into two parts. The following diagram shows the -concept. The blue arrows indicate dependencies. The vertical dotted lines -indicate the division of Planes.

                    - - Planes in the Communications Framework - - -

                    The following diagram overlays the Planes with an example series of Layers

                    - - Planes and Layers in the Communications Framework - - - -
                      -

                    • Data Plane

                      • -

                    • Control Plane

                      • -

                    • Management Plane

                      • -
                    -
                    Data Plane

                    The -Data Plane carries data and uses Communications protocols. The Data Plane -handles conversations with remote peers.The Control -Plane and the Management -Plane exist to serve the Data Plane.

                    The Data Plane exists -to minimise interruptions to the flow of data. The Data Plane assigns the -response to interruptions to the Control Plane. Interruptions include: the -start of a new network connection, the management of a timeout and the management -of changes to the status of the network.

                    To make sure that interruptions -cannot interfere with the Data Plane, a thread divide exists between the Data -Plane and the Control/Management Planes. The thread division allows the Communications -Framework to give the Data Plane thread a higher priority than the Control -and Management Plane thread. The difference in thread priorities allows the -Communications Framework to give the task of data transfer the highest priority.

                    The -Communications Framework provides a mechanism to send messages between the -threads. The mechanism is called the Message -Transport. The Transport sends and delivers the messages asynchronously. -Threads can continue their work until the threads are prepared to process -messages. The Transport always makes sure of the delivery of messages.

                    The -Data Plane corresponds to the Sockets Server API: RSocket.

                    The -following diagram shows the thread divide.

                    - Data Plane in the Communications Framework - -

                    Features

                    The Data Plane:

                      -

                    • exchanges data with -remote peers and uses data transfer protocols

                      • -

                    • allows any number of -conversations at the same time through many protocols

                      • -

                    • enables the transfer -of data to clients of the protocol stack and from clients of the protocol -stack

                      • -

                    • enables the transfer -of data to hardware and from hardware

                      • -
                    -
                    Control Plane

                    The -Control Plane establishes, maintains and modifies the traffic, or conversations -in the Data Plane. Specifically, the Control Pane establishes, controls, re-binds -and tears down the Communications protocol stack based on commands from the -application and from the Management Plane.

                    The Data Plane sends the status of the link and other control information -to the Control Plane. The Control Plane processes the status of the link and -other control information, and allows the Data Plane to give the task of data -transfer the highest priority.

                    A connection can have a number of subconnections. -Subconnections can be called channels. The concepts of connection and subconnection -make it useful to divide the Control Plane into two parts.

                    The Data -Plane corresponds to the Sockets Server APIs: RConnection and RSubConnection.

                    Features

                    The Control Plane:

                      -

                    • creates the Data Plane

                      • -

                    • configures the Data -Plane modules from information provided by the client application or the Management -Plane

                      • -

                    • starts the Data Plane

                      • -

                    • controls and monitors -the Data Plane:

                        -

                      • acts on information -received from the data protocols

                        • -

                      • notifies the Management -Plane or the client application about changes to the state of the Control -Plane or the Data Plane.

                        • -
                      • -

                    • stops the Data Plane

                      • -

                    • destroys the Data Plane

                      • -

                    • manages connection session -timers

                      • -

                    • manages connection data -channels and their properties

                      • -

                    • handles changes to the -status of the network and handles error reports

                      • -
                    -
                    Management -Plane

                    The Management Plane maintains the configuration of the device, -monitors the availability of the network and makes policy decisions for the -Communications Framework. The Management Plane is the main location where -phone creators can customise the behaviour of the Communications protocol -stack.

                    The Management Plane corresponds to the Sockets Server API: RConnectionServ

                    Features

                    The Management Plane:

                      -

                    • selects, constructs -and manages the Communications protocol stack:

                        -

                      • selects the correct -protocol stack for a connection based on client and configuration preferences

                        • -

                      • manages the Control -Plane connections based on the policy set either in the configuration or at -run-time.

                        • -
                      • -

                    • notifies interested -clients about the state of the Communications protocol stack, for example, -bearer and service availability

                      • -

                    • provides an entry point -for third-party plugins to customise and control the Communications protocol -stack

                      • -

                    • controls the Communications -protocol stack. This control is based on policy decisions

                      • -

                    • communicates with the -Control Plane to influence the behaviour of Control or Data flow operations -in the Communications protocol stack

                      • -

                    • supplies configuration -information to the Layer.

                      • -
                    -                     -Socket Server - + + + + + +What +are PlanesThis topic describes the concept of a Plane in the Communications +Framework. +

                    The transmission of data and the management of connections is divided into +separate operations. Symbian platform gives the name Plane to +these operations. The Communications Framework defines three Planes. Each +Plane has a separate role and a separate responsibility. Each Plane matches +a Sockets Server API.

                    +

                    The Planes are called: the Data Plane, the Control Plane and the Management +Plane.

                    +

                    Layers span all three Planes. Code in each Plane operates together to deliver +the required Communications protocol behaviour.

                    +

                    A connection can have a number of subconnections. Subconnections can be +called channels. The concepts of connection and subconnection make it useful +to divide the Control Plane into two parts. The following diagram shows the +concept. The blue arrows indicate dependencies. The vertical dotted lines +indicate the division of Planes.

                    + + Planes in the Communications Framework + + +

                    The following diagram overlays the Planes with an example series of Layers

                    + + Planes and Layers in the Communications Framework + + + +
                      +

                    • Data Plane

                      • +

                    • Control Plane

                      • +

                    • Management Plane

                      • +
                    +
                    Data Plane

                    The +Data Plane carries data and uses Communications protocols. The Data Plane +handles conversations with remote peers.The Control +Plane and the Management +Plane exist to serve the Data Plane.

                    The Data Plane exists +to minimise interruptions to the flow of data. The Data Plane assigns the +response to interruptions to the Control Plane. Interruptions include: the +start of a new network connection, the management of a timeout and the management +of changes to the status of the network.

                    To make sure that interruptions +cannot interfere with the Data Plane, a thread divide exists between the Data +Plane and the Control/Management Planes. The thread division allows the Communications +Framework to give the Data Plane thread a higher priority than the Control +and Management Plane thread. The difference in thread priorities allows the +Communications Framework to give the task of data transfer the highest priority.

                    The +Communications Framework provides a mechanism to send messages between the +threads. The mechanism is called the Message +Transport. The Transport sends and delivers the messages asynchronously. +Threads can continue their work until the threads are prepared to process +messages. The Transport always makes sure of the delivery of messages.

                    The +Data Plane corresponds to the Sockets Server API: RSocket.

                    The +following diagram shows the thread divide.

                    + Data Plane in the Communications Framework + +

                    Features

                    The Data Plane:

                      +

                    • exchanges data with +remote peers and uses data transfer protocols

                      • +

                    • allows any number of +conversations at the same time through many protocols

                      • +

                    • enables the transfer +of data to clients of the protocol stack and from clients of the protocol +stack

                      • +

                    • enables the transfer +of data to hardware and from hardware

                      • +
                    +
                    Control Plane

                    The +Control Plane establishes, maintains and modifies the traffic, or conversations +in the Data Plane. Specifically, the Control Pane establishes, controls, re-binds +and tears down the Communications protocol stack based on commands from the +application and from the Management Plane.

                    The Data Plane sends the status of the link and other control information +to the Control Plane. The Control Plane processes the status of the link and +other control information, and allows the Data Plane to give the task of data +transfer the highest priority.

                    A connection can have a number of subconnections. +Subconnections can be called channels. The concepts of connection and subconnection +make it useful to divide the Control Plane into two parts.

                    The Data +Plane corresponds to the Sockets Server APIs: RConnection and RSubConnection.

                    Features

                    The Control Plane:

                      +

                    • creates the Data Plane

                      • +

                    • configures the Data +Plane modules from information provided by the client application or the Management +Plane

                      • +

                    • starts the Data Plane

                      • +

                    • controls and monitors +the Data Plane:

                        +

                      • acts on information +received from the data protocols

                        • +

                      • notifies the Management +Plane or the client application about changes to the state of the Control +Plane or the Data Plane.

                        • +
                      • +

                    • stops the Data Plane

                      • +

                    • destroys the Data Plane

                      • +

                    • manages connection session +timers

                      • +

                    • manages connection data +channels and their properties

                      • +

                    • handles changes to the +status of the network and handles error reports

                      • +
                    +
                    Management +Plane

                    The Management Plane maintains the configuration of the device, +monitors the availability of the network and makes policy decisions for the +Communications Framework. The Management Plane is the main location where +phone creators can customise the behaviour of the Communications protocol +stack.

                    The Management Plane corresponds to the Sockets Server API: RConnectionServ

                    Features

                    The Management Plane:

                      +

                    • selects, constructs +and manages the Communications protocol stack:

                        +

                      • selects the correct +protocol stack for a connection based on client and configuration preferences

                        • +

                      • manages the Control +Plane connections based on the policy set either in the configuration or at +run-time.

                        • +
                      • +

                    • notifies interested +clients about the state of the Communications protocol stack, for example, +bearer and service availability

                      • +

                    • provides an entry point +for third-party plugins to customise and control the Communications protocol +stack

                      • +

                    • controls the Communications +protocol stack. This control is based on policy decisions

                      • +

                    • communicates with the +Control Plane to influence the behaviour of Control or Data flow operations +in the Communications protocol stack

                      • +

                    • supplies configuration +information to the Layer.

                      • +
                    +                     +Socket Server +                     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F4E64499-57CB-5E4A-AAD7-439191BF5E0F.dita --- a/Symbian3/SDK/Source/GUID-F4E64499-57CB-5E4A-AAD7-439191BF5E0F.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-F4E64499-57CB-5E4A-AAD7-439191BF5E0F.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,16 +1,16 @@ - - - - - -Launching Zsh

                    This topic describes how to launch Zsh using a Telnet session on a PC. You can use the following methods:

                    • Emulator as a Telnet server

                    • Device (phone) as a Telnet server

                    Emulator as a Telnet server

                    To launch Zsh (using a Telnet session) on a PC using an emulator as a Telnet server, perform the following steps:

                    1. Start the emulator by selecting Extras > Eshell.

                    2. Run the following command:

                      TelnetD

                      Note: Before running the Telnetd command, ensure that Zsh.exe and the external command executables such as find.exe, grep.exe, ps.exe, unzip.exe and zip.exe are present in a sys/bin folder. You can copy these files from the /epoc32/release/winscw/<udeb/urel > directory.

                    3. The IP address of the Telnet server running on the emulator is displayed, as shown in the following image:

                      - IP configuration -

                    4. In a scenario where multiple IP addresses are listed, use the ping command from the PC console to identify the IP address that is accessible from the PC, as shown in the following image.

                      - Using the ping command -

                    5. Open command prompt on a Windows PC.

                    6. Run the following command by typing the IP address (associated with the emulator) that is accessible from the PC:

                      telnet <ip-address of the emulator>

                      The emulator and the Telnet client console prompts for an alphanumeric key to authenticate the session.

                    7. Type the same alphanumeric key (which is upto eight characters) both on the emulator console window and also on the Telnet client console.

                      Zsh is successfully launched on the PC.

                    Device (phone) as a Telnet server

                    After establishing a connection between a device and the PC using one of the methods described in the Device Setup section, you can launch Zsh. To launch Zsh (using a Telnet session) on a PC using a device as a Telnet server, perform the following steps:

                    Note: Before starting a Telnet session, ensure that TelnetD and Zsh are installed on the device.

                    1. Start TelnetD on the device by clicking the Zsh icon. The IP address of the Telnet server running on the device is displayed.

                    2. In a scenario where multiple IP addresses are listed, use the ping command from the PC console to identify the IP address of the device that is accessible from the PC.

                    3. Open command prompt on a Windows PC.

                    4. Run the following command, by typing the IP address (associated with the device) that is accessible from the PC:

                      Telnet <ip-address of the device>

                      The device and the Telnet client console prompts for an alphanumeric key to authenticate the session.

                    5. Type the same alphanumeric key (which is upto eight characters) both on the device console window and also on the Telnet client console.

                      Zsh is successfully launched on the PC. The following image shows the result of this command on a Linux PC:

                    Emulator Setup Device Setup Using TelnetD and Zsh                     \ No newline at end of file + + + + + +Launching Zsh

                    This topic describes how to launch Zsh using a Telnet session on a PC. You can use the following methods:

                    • Emulator as a Telnet server

                    • Device (phone) as a Telnet server

                    Emulator as a Telnet server

                    To launch Zsh (using a Telnet session) on a PC using an emulator as a Telnet server, perform the following steps:

                    1. Start the emulator by selecting Extras > Eshell.

                    2. Run the following command:

                      TelnetD

                      Note: Before running the Telnetd command, ensure that Zsh.exe and the external command executables such as find.exe, grep.exe, ps.exe, unzip.exe and zip.exe are present in a sys/bin folder. You can copy these files from the /epoc32/release/winscw/<udeb/urel > directory.

                    3. The IP address of the Telnet server running on the emulator is displayed, as shown in the following image:

                      + IP configuration +

                    4. In a scenario where multiple IP addresses are listed, use the ping command from the PC console to identify the IP address that is accessible from the PC, as shown in the following image.

                      + Using the ping command +

                    5. Open command prompt on a Windows PC.

                    6. Run the following command by typing the IP address (associated with the emulator) that is accessible from the PC:

                      telnet <ip-address of the emulator>

                      The emulator and the Telnet client console prompts for an alphanumeric key to authenticate the session.

                    7. Type the same alphanumeric key (which is upto eight characters) both on the emulator console window and also on the Telnet client console.

                      Zsh is successfully launched on the PC.

                    Device (phone) as a Telnet server

                    After establishing a connection between a device and the PC using one of the methods described in the Device Setup section, you can launch Zsh. To launch Zsh (using a Telnet session) on a PC using a device as a Telnet server, perform the following steps:

                    Note: Before starting a Telnet session, ensure that TelnetD and Zsh are installed on the device.

                    1. Start TelnetD on the device by clicking the Zsh icon. The IP address of the Telnet server running on the device is displayed.

                    2. In a scenario where multiple IP addresses are listed, use the ping command from the PC console to identify the IP address of the device that is accessible from the PC.

                    3. Open command prompt on a Windows PC.

                    4. Run the following command, by typing the IP address (associated with the device) that is accessible from the PC:

                      Telnet <ip-address of the device>

                      The device and the Telnet client console prompts for an alphanumeric key to authenticate the session.

                    5. Type the same alphanumeric key (which is upto eight characters) both on the device console window and also on the Telnet client console.

                      Zsh is successfully launched on the PC. The following image shows the result of this command on a Linux PC:

                    Emulator Setup Device Setup Using TelnetD and Zsh                     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F4F3A37A-AB0C-47B8-A538-C05F1CA73BF3.dita --- a/Symbian3/SDK/Source/GUID-F4F3A37A-AB0C-47B8-A538-C05F1CA73BF3.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-F4F3A37A-AB0C-47B8-A538-C05F1CA73BF3.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,66 +1,52 @@ - - - - - -Touch-enabled -vs. touch-optimized -

                    Rather than being -touch-enabled, certain applications can be touch-optimized, that is, designed -primarily for touch screen interaction. When developing applications for a -touch interface, it is important to consider interactions which benefit the -most from touch UI. While physical strokes and gestures allow for more natural -interaction with objects, the fact that one can apply them does not mean they -are appropriate for every situation.

                    Following are some useful tips -that can be used when designing applications for touch use:

                      -

                    • It is imperative that design decisions are based on real-time touch -use cases.

                      • -

                    • Since touch functions require a fair amount of discovery from the user, -it is good if only very obvious functions are made touch-enabled.

                      • -

                    Why to use touch

                      -

                    • More flexible: Compared to fixed hardware keys, the interface -can change dynamically. This allows for more flexible configurations depending -on the functionality requirements, languages, and so on. Thus a very small -screen can change its buttons as required. Also, with indirect strokes and -gestures, there are numerous possibilities of flexibility. No use of physical -buttons is required.

                      - -
                      • -

                    • More intuitive: Manipulating objects directly by touching them -is natural and intuitive. Keyboards, mice, trackballs, and other input devices -are not able to convey as much subtlety as touch can. Direct manipulation -can deliver a lot more meaning to controlling a tool.

                      • -

                    • More fun: One can design a game in which users press a button -and an on-screen avatar swings a tennis racket. But it can be simply more -entertaining to mimic movements physically, and to see the action mirrored -on-screen. Strokes and gestures encourage play and exploration of a system -by providing a more hands-on experience.

                      • -

                    • More engaging: Through play, users start to engage with the -interface, first by trying it out to see how it works.

                      • -

                    Limitations of touch

                      -

                    • Heavy data input: A hardware keyboard is faster for most people -to use when entering a large amount of text or numbers, and applications which -involve heavy data input are not necessarily ideal for touch devices. Virtual -keyboards are adequate, for example, for messaging applications. Consider -utilizing adaptive methods - such as options and selections filtered according -to what is available on the screen or in a list - and pre-filled items, when -possible.

                      • -

                    • Reliance on the visual: While the Symbian platform provides -tactile feedback capability, some applications can rely heavily on visual -feedback to indicate actions. Allow for scalability, larger buttons and text -sizes, for example, for visually impaired users.

                      • -

                    • Reliance on the physical: Touch interface can be more demanding -on the physical context than mechanical keys. Tapping a touch screen button -can be difficult while wearing winter gloves, or with long fingernails. The -inverse is also true: the more subtle and small the movement, the less likely -it is that everyone will be able to do it. To overcome this, the most basic -use cases, such as answering an incoming phone call, must utilize large enough -elements and straightforward interaction.

                      • -
                    + + + + + +Touch-enabled +vs. touch-optimized +

                    Applications can +be designed primarily for touch screen interaction (touch-optimized) instead +of being touch-enabled. While developing applications for a touch interface, +the design considerations must be based on interactions that benefit the most +from touch UI. Physical strokes and gestures allows natural interaction with +objects but must be used appropriately.

                    Following are few useful tips +that can be used when designing applications for touch interface:

                      +

                    • Design decisions must be based on real-time touch use cases.

                      • +

                    • Only obvious functions can be made touch-enabled.

                      • +

                    Following are the important features of touch:

                      +

                    • Flexibility - Virtual keyboard provides more flexibility than +fixed hardware keys. The dynamically changing interface allows for flexible +configurations depending on the functionality requirements, languages, and +so on. Also, indirect strokes and gestures provide flexibility reducing the +need for physical buttons.

                      + +
                      • +

                    • Intuitive - Manipulating objects directly by touching them is +natural and intuitive. Touch interface allows better real-time experience +for end users. Strokes and gestures encourage play and exploration of a system +by providing a more hands-on experience.

                      • +

                    Limitations of touch

                      +

                    • Data input - touch devices are not ideal for applications involving +huge data entry. Virtual keyboards are adequate, for example, for messaging +applications. Consider utilizing adaptive methods such as options and selections +filtered according to what is available on the screen or in a list - and pre-filled +items, when possible.

                      • +

                    • Reliance on the visual - Although the Symbian platform provides +tactile feedback capability, some applications rely more on visual feedback +to indicate actions. Allow for scalability, larger buttons and text sizes, +for example, for visually impaired users.

                      • +

                    • Reliance on the physical - Touch interface can be more demanding +on the physical context than mechanical keys. Subtle and small movements are +less likely to be achieved. For example, tapping a touch screen +button while wearing winter gloves or with long fingernails can be difficult. +To overcome this limitation, the basic use cases, such as answering an incoming +phone call, must utilize large elements and simple interaction.

                      • +
                     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F5371A59-A637-4623-A2C0-9A8B8E5F3CFB.dita --- a/Symbian3/SDK/Source/GUID-F5371A59-A637-4623-A2C0-9A8B8E5F3CFB.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,59 +0,0 @@ - - - - - -Interaction -with other hardware components -

                    In addition to traditional keys, interaction devices of other types may -be built in the devices. In most scenarios, they produce input events similar -to keys, so that the software need not be changed. The hardware commands do -not have any effect on the application.

                    -

                    Examples of specific interaction devices are:

                      -

                    • Optical joysticks

                      • -

                    • Optical 9-way finger navigation

                      • -

                    • Acceleration sensors

                      • -

                    -
                    Optical joystick

                    An optical joystick can be used -instead of (or in addition to) the traditional navigation keys.

                    When -used in combination with traditional scroll keys, optical joystick performs -same functions as that of mechanical scroll keys. However, the speed of the -movement can differ.

                    When used individually as the only scrolling device, -optical joystick emulates the functions of mechanical scroll keys. Sliding -a finger down over the joystick provides the same function as that of pressing -the down key. Repeat functionality can be produced with longer strokes.

                    -
                    Optical -9-way navigation

                    The Symbian platform supports additional optical -navigation that is integrated to centre Select key. The supported directions -in 9-way rocker key are domed main directions and diagonals by combining the -main directions. Optical navigation allows continues moment of the finger -as observed in touch pad. It is suitable for pointer moving in browser and -content panning, for example, in photos, browser, and maps.

                    -
                    Acceleration -sensor

                    There are three types of interaction events that can be recognized -with acceleration sensors:

                      -

                    1. Tapping the device by -hand (double tap) to perform a given function in set events. Tapping interaction -is not recommended for touch devices to prevent the unintentional touch actions.

                      2. -

                    2. Changing the device’s -orientation from portrait to landscape and back to perform screen re-orientation.

                      3. -

                    3. Changing the device -orientation from screen up (for example on a table) to screen down and back -to silence an alert tone (for example, silencing an incoming call).

                      4. -

                    The system is capable of sensing any of listed events. The supported -sensor interactions are configurable per device, but must be consistent in -not assigning different functions to these standard events. Also, the user -can be provided with the option to set the desired interactions. For example, -it is possible to set methods 1 and 3 (double tap by hand and turning the -screen downwards) for the 'silence incoming call' event. The settings are -available in General Settings. A double tap on the device produces -tactile (vibrating) feedback to reinforce and acknowledge that the interaction -is successful. See Tactile -feedback for more details.
                    -                     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F59B0B89-94C3-4E0B-BF87-2AE5B3811F59.dita --- a/Symbian3/SDK/Source/GUID-F59B0B89-94C3-4E0B-BF87-2AE5B3811F59.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-F59B0B89-94C3-4E0B-BF87-2AE5B3811F59.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,29 +1,29 @@ - - - - - -Smiley -picker -

                    Smiley picker is identical to special character table.

                    -

                    User can enter smileys to editors. For the functionality of touch events, -refer to the default -touch events of special character table. Smiley picker can be opened:

                      -

                    • from touch input Options menu if there is no dedicated Smiley -picker button.

                      • -

                    • from dedicated smiley button in handwriting recognition, full screen -QWERTY and virtual QWERTY keyboard.

                      • -

                    • by pressing the dedicated smiley button in Special -Character Table opened from virtual ITU-T.

                      • -

                    - -Smiley picker in portrait and landscape modes - - + + + + + +Smiley +picker +

                    Smiley picker is similar to special character table.

                    +

                    User can enter smileys to editors. For the functionality of touch events, +refer to the default +touch events of special character table. Smiley picker can be opened:

                      +

                    • from touch input Options menu if there is no dedicated Smiley +picker button.

                      • +

                    • from dedicated smiley button in handwriting recognition, full screen +QWERTY and virtual QWERTY keyboard.

                      • +

                    • by pressing the dedicated smiley button in Special +Character Table opened from virtual ITU-T.

                      • +

                    + +Smiley picker in portrait and landscape modes + +                     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F5A82F61-B93A-5652-93A4-B9CE877B4D4A_d0e332635_href.png Binary file Symbian3/SDK/Source/GUID-F5A82F61-B93A-5652-93A4-B9CE877B4D4A_d0e332635_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F5A82F61-B93A-5652-93A4-B9CE877B4D4A_d0e338792_href.png Binary file Symbian3/SDK/Source/GUID-F5A82F61-B93A-5652-93A4-B9CE877B4D4A_d0e338792_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F5B58B20-B85C-5BCD-B1EB-69CCE42DE6BB_d0e176051_href.png Binary file Symbian3/SDK/Source/GUID-F5B58B20-B85C-5BCD-B1EB-69CCE42DE6BB_d0e176051_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F5B58B20-B85C-5BCD-B1EB-69CCE42DE6BB_d0e182645_href.png Binary file Symbian3/SDK/Source/GUID-F5B58B20-B85C-5BCD-B1EB-69CCE42DE6BB_d0e182645_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F64E6551-670E-5E12-8103-DE504D3EC94F.dita --- a/Symbian3/SDK/Source/GUID-F64E6551-670E-5E12-8103-DE504D3EC94F.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-F64E6551-670E-5E12-8103-DE504D3EC94F.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,71 +1,71 @@ - - - - - -The -Non-ScreenPlay Graphics ArchitectureScreenPlay provides improved support for graphics hardware acceleration -and some other new features. However, it is possible to use the Symbian platform -without enabling ScreenPlay. This is called the non-ScreenPlay variant (sometimes -referred to as the non-NGA variant). This topic provides an introduction -to the graphics architecture when ScreenPlay is not enabled. -

                    The following diagram shows the non-ScreenPlay architecture. It includes -the components in the Graphics package and some closely related components -in other packages.

                    - -The Symbian Foundation non-ScreenPlay graphics architecture - - -

                    The software model is as follows:

                    -
                      -

                    • The Hardware Adaptation -Layer (HAL) consists of the frame buffer and basic attributes. All processes -have equal access to the frame buffer and can both read and write to it.

                      • -

                    • The Screen Driver provides -simple pixel, scan-line and bitmap operations. The Screen Driver has the same -interface for both bitmaps and the frame buffer. Hardware manufacturers can -adapt the Screen Driver to suit the available hardware.

                      • -

                    • The BitGDI component -provides support for higher-level geometric primitives and text. The BitGDI -component is implemented in terms of Screen Driver operations. All BitGDI -rendering operations are synchronous.

                      • -

                    • The Window Server multiplexes -access to the screen and provides a BitGDI-like interface.

                      • -

                    • The Window Server provides -Direct Screen Access (DSA) support for applications that require high frame -rates (such as video and games) to bypass the Window Server and write to the -frame buffer directly. However, some interaction with the Window Server is -needed to prevent the application from drawing over other application's data.

                      • -
                    -

                    In addition, the non-ScreenPlay architecture provides support for EGL, -OpenGL and OpenVG.

                    -

                    The following diagram shows the rendering stack in the non-ScreenPlay variant.

                    - -The rendering stack in the non-ScreenPlay variant - - - -

                    Although DSA provides a solution for applications that require high frame -rates, the non-ScreenPlay architecture has limitations when used on graphics -accelerated hardware and non-uniform memory models. The architecture may require -the copying of buffers between CPU and GPU memory as shown in the following -diagram. ScreenPlay provides a solution that requires less copying of buffers -in this type of use case.

                    - - Example non-uniform memory, non-ScreenPlay hardware model - - -                     -The ScreenPlay -Architecture -Graphics -Hardware Acceleration -Graphics -Concepts + + + + + +The +Non-ScreenPlay Graphics ArchitectureScreenPlay provides improved support for graphics hardware acceleration +and some other new features. However, it is possible to use the Symbian platform +without enabling ScreenPlay. This is called the non-ScreenPlay variant (sometimes +referred to as the non-NGA variant). This topic provides an introduction +to the graphics architecture when ScreenPlay is not enabled. +

                    The following diagram shows the non-ScreenPlay architecture. It includes +the components in the Graphics package and some closely related components +in other packages.

                    + +The Symbian Foundation non-ScreenPlay graphics architecture + + +

                    The software model is as follows:

                    +
                      +

                    • The Hardware Adaptation +Layer (HAL) consists of the frame buffer and basic attributes. All processes +have equal access to the frame buffer and can both read and write to it.

                      • +

                    • The Screen Driver provides +simple pixel, scan-line and bitmap operations. The Screen Driver has the same +interface for both bitmaps and the frame buffer. Hardware manufacturers can +adapt the Screen Driver to suit the available hardware.

                      • +

                    • The BitGDI component +provides support for higher-level geometric primitives and text. The BitGDI +component is implemented in terms of Screen Driver operations. All BitGDI +rendering operations are synchronous.

                      • +

                    • The Window Server multiplexes +access to the screen and provides a BitGDI-like interface.

                      • +

                    • The Window Server provides +Direct Screen Access (DSA) support for applications that require high frame +rates (such as video and games) to bypass the Window Server and write to the +frame buffer directly. However, some interaction with the Window Server is +needed to prevent the application from drawing over other application's data.

                      • +
                    +

                    In addition, the non-ScreenPlay architecture provides support for EGL, +OpenGL and OpenVG.

                    +

                    The following diagram shows the rendering stack in the non-ScreenPlay variant.

                    + +The rendering stack in the non-ScreenPlay variant + + + +

                    Although DSA provides a solution for applications that require high frame +rates, the non-ScreenPlay architecture has limitations when used on graphics +accelerated hardware and non-uniform memory models. The architecture may require +the copying of buffers between CPU and GPU memory as shown in the following +diagram. ScreenPlay provides a solution that requires less copying of buffers +in this type of use case.

                    + + Example non-uniform memory, non-ScreenPlay hardware model + + +                     +The ScreenPlay +Architecture +Graphics +Hardware Acceleration +Graphics +Concepts                     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F66AC845-58B8-4029-AE04-C283226B7C12.dita --- a/Symbian3/SDK/Source/GUID-F66AC845-58B8-4029-AE04-C283226B7C12.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-F66AC845-58B8-4029-AE04-C283226B7C12.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,35 +1,36 @@ - - - - - -Single -tap -

                    In S60 5th Edition, double tap (focus and select) was supported for non-touch -devices. The Symbian platform supports single tap, which activates an item -on direct selection. That is, the UI is no longer focus driven.

                    -

                    The following are the highlighting features of single tap -in the Symbian platform:

                      -

                    • Single click performs the core action without requiring double tap. -If the core action cannot be defined, then the single tap provides the context-sensitive -menu as Selection key press in hybrid devices.

                      • -

                    • By default, no visible focus in touch UI. Focus can be evoked pressing -Selection key or navigation keys in hybrid devices

                      • -

                    • All item-specific options from the Options menu are hidden. -Item-specific options will be available via Stylus popup menu opened with -long tap, or in the next level in the UI hierarchy.

                      • -

                    • Item-specific options are removed from the touch toolbar. If there -are less than three actions left for the touch toolbar, the whole toolbar -is removed.

                      • -

                    • The landscape layout is optimized. Entire main pane area can be utilized -for the application content, when touch toolbar is not required. Toolbars -can still be utilized when the actions apply to the whole view, for example, -in Message viewer and editor.

                      • -

                    + + + + + +Single tap +

                    In S60 5th Edition, double tap (focus and select) was supported +for touch devices. The Symbian platform supports single tap, which +activates an item on direct selection. That is, the UI is no longer +focus driven.

                    +

                    The following are the highlighting features of single tap in the +Symbian platform:

                      +

                    • Single tap performs the core action without requiring double +tap. If the core action cannot be defined, then the single tap provides +the context-sensitive menu as Selection key press in hybrid devices.

                      • +

                    • By default, no visible focus in touch UI. Focus can be evoked +pressing Selection key or navigation keys in hybrid devices

                      • +

                    • All item-specific options from the Options menu are hidden. +Item-specific options will be available via Stylus pop-up menu opened +with long tap, or in the next level in the UI hierarchy.

                      • +

                    • Item-specific +options are removed from the touch toolbar. If there are less +than three actions left for the touch toolbar, the whole toolbar is +removed.

                      • +

                    • The landscape layout is optimized. Entire main pane area can +be utilized for the application content, when touch toolbar is not +required. Toolbars can still be utilized when the actions apply to +the whole view, for example, in Message viewer and editor.

                      • +

                     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F681C857-086F-527A-9946-A91560601658_d0e403679_href.jpg Binary file Symbian3/SDK/Source/GUID-F681C857-086F-527A-9946-A91560601658_d0e403679_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F681C857-086F-527A-9946-A91560601658_d0e403841_href.jpg Binary file Symbian3/SDK/Source/GUID-F681C857-086F-527A-9946-A91560601658_d0e403841_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F68FF4C2-F9DB-5935-9027-9BEC006D031F_d0e324544_href.png Binary file Symbian3/SDK/Source/GUID-F68FF4C2-F9DB-5935-9027-9BEC006D031F_d0e324544_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F68FF4C2-F9DB-5935-9027-9BEC006D031F_d0e330701_href.png Binary file Symbian3/SDK/Source/GUID-F68FF4C2-F9DB-5935-9027-9BEC006D031F_d0e330701_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F6903E31-DF4A-572F-BF2C-65CE618F016E.dita --- a/Symbian3/SDK/Source/GUID-F6903E31-DF4A-572F-BF2C-65CE618F016E.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-F6903E31-DF4A-572F-BF2C-65CE618F016E.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,28 +1,28 @@ - - - - - -Kernel -side object containersThis document describes the use of object containers to maintain -kernel objects. -

                    Kernel objects such as mutexes, semaphores, threads, processes, timers -are reference counting objects, i.e. they are instances of classes derived -from CObject. The Kernel maintains all such objects in object -containers, one container for each type; i.e. one for threads, one for processes, -one for mutexes etc. as shown below.

                    - - - -

                    See also:

                    -
                      -

                    • The -object container

                      • -
                    + + + + + +Kernel +side object containersThis document describes the use of object containers to maintain +kernel objects. +

                    Kernel objects such as mutexes, semaphores, threads, processes, timers +are reference counting objects, i.e. they are instances of classes derived +from CObject. The Kernel maintains all such objects in object +containers, one container for each type; i.e. one for threads, one for processes, +one for mutexes etc. as shown below.

                    + + + +

                    See also:

                    +
                      +

                    • The +object container

                      • +
                     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F690DAC8-688B-5BD7-88DF-0CB3D4ACDCFF.dita --- a/Symbian3/SDK/Source/GUID-F690DAC8-688B-5BD7-88DF-0CB3D4ACDCFF.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,48 +0,0 @@ - - - - - - Capturing -Video -

                    This tutorial describes how to capture video using the Ecam API.

                    -
                    Purpose

                    The -purpose of this tutorial is to show you how to capture video using the Ecam -API.

                    Required -Background

                    For background information, see the Onboard -Camera Overview.

                    Introduction

                    The video capture control allows the client to start, pause, -resume and stop video capture.

                    -
                    Using Video -Capture
                      -

                    • Create a class pointer -using the CCamera::CCameraVideoCaptureControl::NewL() factory -method.

                      • -

                    • Use CCamera::CCameraVideoCaptureControl::PrepareVideoCapture() to -initialize the settings for video capture.

                      • -

                    • Start video capture -using CCamera::CCameraVideoCaptureControl::StartVideoCaptureL().

                      • -

                    • Use CCamera::CCameraVideoCaptureControl::PauseVideoCapture() call -to pause the video capture.

                      • -

                    • Use CCamera::CCameraVideoCaptureControl::ResumeVideoCaptureL() to -resume the video capture.

                      • -

                    • Use CCamera::CCameraVideoCaptureControl::StopVideoCapture() to -stop video capture.

                      • -

                    • Release the resource -that was allocated during PrepareVideoCapture() using the CCamera::CCameraVideoCaptureControl::ReleaseVideoResource() method.

                      • -
                    -                     -Camera API - -Accessing -and Power Control of Camera -Camera Preset -Support -Capturing -Image -                     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F6B5F777-D12F-5913-AECE-047DF8C72F1F.dita --- a/Symbian3/SDK/Source/GUID-F6B5F777-D12F-5913-AECE-047DF8C72F1F.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-F6B5F777-D12F-5913-AECE-047DF8C72F1F.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,204 +1,204 @@ - - - - - -How to Get Location InformationThis document demonstrates how a client application uses the Location Acquisition API to get a position.
                    Purpose

                    This tutorial explains how to get location information using the Location Acquisition API.

                    Required background

                    Location Acquisition API Overview describes the main client/server classes of the API.

                    Position Data and Info Classes describes the classes that hold location information.

                    Getting location information

                    This section describes how to get location information using the Location Acquisition API.

                    Introduction

                    Client applications use the RPositionServer and RPositioner classes to get position updates. RPositionServer is used by client applications to manage a session with the Location Server and to get Positioning Module information. RPositioner is used by client applications to manage a subsession with the Location Server and to get position updates.

                    GPS positioning modes

                    The Global Positioning System (GPS) is a technology that is often included in devices that support LBS.

                    For each location request from a client, the LBS subsystem can operate in one of several different GPS positioning modes. The Location Acquisition API hides the details of which GPS positioning mode is in use from client applications. A client makes the same sequence of calls to the API to get a position update whichever positioning mode is used. Note that only some of these positioning modes may be available to a client application at runtime.

                    Each GPS positioning mode is a different way of getting a position fix:

                    • Autonomous

                      LBS uses a GPS Positioning Module to calculate position fixes without assistance data from the network. This mode typically takes the longest time to obtain a location fix compared to the other modes.

                    • Terminal Based Mode

                      LBS uses an A-GPS Positioning Module to calculate position fixes using assistance data from the network. Assistance data specifies the GPS satellites that are above the horizon as seen from the mobile device's current location. Assistance data is used by an A-GPS Positioning Module to reduce the time necessary to obtain a position fix.

                      The network can also supply a reference position to the LBS subsystem as part of the sequence of events. This position is calculated in the network using cell-based techniques and may be less accurate than that obtained from GPS. If a reference position is available, it may be returned to the client before a GPS position.

                      See Location Acquisition API Runtime Behaviour for more information about the position updates that can be returned by LBS.

                    • Terminal Assisted Mode

                      LBS uses an A-GPS Positioning Module to obtain GPS measurements (using assistance data from the network). GPS measurements are the raw data used to calculate a GPS fix. Measurements are sent to the network and a position fix is calculated by a remote server. The remotely calculated position fix is returned to the mobile device and is known as the final network position. The LBS subsystem returns this position to the client.

                    • Simultaneous Terminal Based Mode and Terminal Assisted Mode.

                      LBS passes GPS measurements to the network (as in Terminal Assisted Mode), but also attempts to use those measurements to calculate a GPS position fix (as in Terminal Based Mode). The position returned to the client may be either a GPS position (calculated in the mobile device) or a final network position (calculated using the measurements by a remote server in the network). The position that is calculated first (the GPS position or the final network position) is generally returned to the client. The final network position may also be returned to the client after the return of the GPS position.

                    Some devices also support a Cell-based Mode in which LBS obtains a position fix from the network without using GPS. This position fix is sometimes less accurate than that obtained using GPS.

                    A client application cannot directly choose the GPS positioning mode that is used for its location request. A handset manufacturer may provide an LBS settings application where the GPS mode can be selected by an end user. However for modes that involve the network (Terminal Based Mode, Terminal Assisted Mode and Cell-based Mode) it is possible for a network operator to override the GPS mode as part of the location request. If a client wants to know precisely how a position fix was calculated, this information is available in the returned position info object (as described in more detail later in this document).

                    Example sequence

                    Figure 1 shows a simplified sequence for a client requesting a position update from LBS. The sequence shows simplified behaviour for Terminal Based Mode. The A-GPS Module is a Positioning Module that uses Assisted GPS to calculate a position. The Network Protocol Module is a Positioning Module that obtains GPS assistance data and reference positions (often approximate positions) from the network. Note that Terminal Based Mode may not be available on all mobile devices. This depends on the Positioning Modules that have been installed by the mobile device creator.

                    - Figure 1. Simplified Terminal Based Mode Sequence -

                    Example code and description

                    The following code shows a simple example of how a client application can get a single position update. The numbers in the code comments refer to sections that follow the code example.

                    #include <lbs.h> -#include <lbserrors.h> - -... - -RPositionServer server; -RPositioner positioner; - -// 1. Create a session with the Location Server -User::LeaveIfError(server.Connect()); -CleanupClosePushL(server); - -// 2. Create a subsession with the Location Server using default positioning module -User::LeaveIfError(positioner.Open(server)); -CleanupClosePushL(positioner); - -// 3. Set the requester information - in this example define a requester stack... - -_LIT(KCntPhone, "+358501234567"); -_LIT(KSrvName, "MyService"); -RRequestorStack stack; -CRequestor* contact = CRequestor::NewLC(CRequestor::ERequestorContact, CRequestor::EFormatTelephone, KCntPhone); -stack.Append(contact); -CRequestor* service = CRequestor::NewLC(CRequestor::ERequestorService, CRequestor::EFormatApplication, KSrvName); -stack.Append(service); -User::LeaveIfError(positioner.SetRequestor(stack)); - -TPositionInfo posInfo; -TPosition pos; -TRequestStatus status; - -/* 4. To set update options, call RPositioner::SetUpdateOptions(). - See the description in section 4 below */ - -/* 5. Request location information - Could also call positioner.GetLastKnownPosition(posInfo, status) - to get cached location information */ -positioner.NotifyPositionUpdate(posInfo, status); -User::WaitForRequest(status); - -// 6. Receive location information -if (status != KErrNone) - { - // Handle possible client/server errors - ... - } - -// Get the position data object from the wrapper info object -posInfo.GetPosition(pos); - -// Use the position data -... - -// Reissue the location request if necessary by calling NotifyPositionUpdate() again - -/* 7. To cancel or complete a location request a client - calls RPositioner::CancelRequest() or RPositioner::CompleteRequest() */ - -// 8. Cleanup -stack.Reset(); -CleanupStack::PopAndDestroy(service); -CleanupStack::PopAndDestroy(contact); -CleanupStack::PopAndDestroy(&positioner); -CleanupStack::PopAndDestroy(&server); -

                    The following describes the steps to get location information as shown in the above example:

                    1. Create a session with the Location Server

                    To create a session with the Location Server, a client application:

                    • Creates an instance of RPositionServer

                    • Calls RPositionServer::Connect()

                    Standard client-server error codes are returned by calls to open the session. A panic occurs if the client application has already created a session with the Location Server. Error and panic codes specific to LBS are defined in LbsErrors.h.

                    2. Create a subsession with the Location Server

                    Location information requests are issued on a subsession.

                    To create a subsession, an application calls one of three overloaded RPositioner::Open() member functions:

                    • RPositioner::Open(RPositionServer& aPosServer) uses the Default Positioning Module to get location information. The client application does not specify any position quality criteria (which specify the required position accuracy) and therefore LBS uses default position quality criteria (horizontal accuracy = 50m, vertical accuracy = 1000m, request timeout = 30 seconds).

                    • RPositioner::Open(RPositionServer& aPosServer, - TPositionModuleId aModuleId) allows a specific Positioning Module to be specified by the client application. LBS uses position quality criteria associated with the specified Positioning Module. No quality criteria are specified and so LBS uses the capabilities of the Positioning Module as the default criteria.

                      See Positioning Modules for information about Positioning Module position quality and How to Use Positioning Module Information for more information about how to get a module ID.

                    The LBS subsystem does not compare the vertical accuracy of a calculated position with the vertical accuracy specified by a client application (specified by position quality criteria, by a quality profile or by a Positioning Module). Only the horizontal accuracy of a calculated position is used to decide if it is accurate enough to be returned to a client application.

                    3. Set client requester details

                    A client application can specify the client requesters by calling RPositioner::SetRequestorL() before calling RPositioner::NotifyPositionUpdate().

                    This is an optional step. Calling SetRequestorL() has no effect in this version of the Symbian platform. Calling SetRequestorL() is required in some devices based on earlier versions of Symbian. To ensure an LBS application runs on devices based on earlier versions of Symbian, it is recommended that it calls SetRequestorL().

                    See Privacy Requester Classes for more information.

                    4. Set update options

                    A client application calls RPositioner::SetUpdateOptions() to set the update options. Calling this method only affects future calls to RPositioner::NotifyPositionUpdate() and RPositioner::GetLastKnownPosition() and does not affect any outstanding requests.

                    A TPositionUpdateOptions parameter specifies the update options and is passed in RPositioner::SetUpdateOptions(). The properties of TPositionUpdateOptions are set either on its construction or via setter methods. The following properties can be defined:

                    • The time interval between position updates

                      TPositionUpdateOptions::SetUpdateInterval(TTimeIntervalMicroSeconds - aInterval) sets the time interval between position updates.

                      Setting a non-zero value indicates that the client requires periodic updates (this is also known as 'tracking'). LBS attempts to send position updates to the client application with this interval between the updates. Note that setting aInterval to 0 (or not setting it) indicates that the client is not tracking.

                      Note that when a client application is tracking, LBS does not return reference positions as periodic updates. See the section on Tracking later in this document for more information on tracking behaviour.

                    • A position update timeout

                      TPositionUpdateOptions::SetUpdateTimeOut(TTimeIntervalMicroSeconds - aTimeOut) sets a timeout for the location request. It specifies how long the client application is prepared to wait to obtain a position update. If the timeout expires RPositioner::NotifyPositionUpdate() completes and the client's RunL() method is called.

                      After a timeout the value set for the client's TRequestStatus parameter depends on the configuration of the LBS subsystem and may be either KErrTimeOut or KPositionQualityLoss. See Location Acquisition API runtime behaviour for more information.

                      Note that calling SetUpdateTimeOut() with a value of 0 (or not setting it) indicates that LBS should not timeout the location request from a client.

                    • The maximum age of a position update

                      TPositionUpdateOptions::SetMaxUpdateAge(TTimeIntervalMicroSeconds - aMaxAge) specifies the maximum age of the position data returned by RPositioner::NotifyPositionUpdate(). Setting this value allows the Location Server to use cached location information in some cases. The default value of 0 indicates that new position data is required.

                    • Acceptance of partial updates

                      A partial update is a position update that contains only partial position data. Such a position is called an incomplete position. An example of an incomplete position is one that contains data about the satellites used to obtain a GPS fix but no latitude or longitude data. LBS defines an incomplete position to be one where either TPosition::Latitude() or TPosition::Longitude() is NaN (Not a Number).

                      TPositionUpdateOptions::SetAcceptPartialUpdates(TBool - aPartial) allows an application to choose to accept partial updates. If a partial update is returned an application's TRequestStatus parameter is set to KPositionPartialUpdate when NotifyPositionUpdate() completes.

                      If partial updates are not set the default behaviour is for RPositioner::NotifyPositionUpdate() to complete only when the Positioning Module used for the location request has obtained as much information as possible. Note however that this behaviour is configurable by a Symbian device creator (see Location Acquisition API runtime behaviour for more information).

                    Important note on setting update options

                    The default constructor of TPositionUpdateOptions sets all update options to zero by default and is the equivalent of calling the following:

                    • TPositionUpdateOptions::SetUpdateInterval(0) meaning that tracking is off

                    • TPositionUpdateOptions::SetUpdateTimeout(0) meaning that LBS should not timeout the client's request

                    • TPositionUpdateOptions::SetMaxUpdateAge(0) meaning that new position data is required

                    • TPositionUpdateOptions::SetAcceptPartialUpdates(EFalse) meaning the partial updates are not returned

                    When setting update options, a client should beware of causing unexpected side effects. For example, if a client wants to accept partial updates, it might do the following:

                    • Create a new TPositionUpdateOptions options object

                    • Call TPositionUpdateOptions::SetAcceptPartialUpdates(ETrue)

                    • Call RPositioner::SetUpdateOptions() passing the options object as a parameter

                    However, this process has the side-effect of setting all the other update options to their default values as described above. In particular the client request will now not timeout which is unlikely to be the desired behaviour. To avoid this, a client should usually modify the current update options as follows:

                    • Get the current update options by calling RPositioner::GetUpdateOptions()

                    • Call the appropriate TPositionUpdateOptions::SetXXX() methods for the options to be changed

                    • Call RPositioner::SetUpdateOptions() passing the modified options object as a parameter

                    Examples

                    The following code shows a simple example of how to set update options. Note that all the options are changed by the client.

                    ... - -TPositionUpdateOptions options; - -// Frequency of updates in microseconds -const TTimeIntervalMicroSeconds KUpdateInterval(2000000); - -// How long the application is willing to wait before timing out the request -const TTimeIntervalMicroSeconds KTimeOut(4000000); - -// The maximum acceptable age of the information in an update -const TTimeIntervalMicroSeconds KMaxUpdateAge(1000000); - -options.SetUpdateInterval(KUpdateInterval); -options.SetUpdateTimeOut(KTimeOut); -options.SetMaxUpdateAge(KMaxUpdateAge); -options.SetAcceptPartialUpdates(EFalse); - -User::LeaveIfError(positioner.SetUpdateOptions(options)); - -/* Now when the application requests location information -it will be provided with these options */ - -positioner.NotifyPositionUpdate(posInfo, status); - -... - -

                    The following code example shows an example of how to change one update option (to accept partial updates).

                    ... - -TPositionUpdateOptions options; - -User::LeaveIfError(positioner.GetUpdateOptions(options)); -options.SetAcceptPartialUpdates(ETrue); -User::LeaveIfError(positioner.SetUpdateOptions(options)); - -// The other update options are unchanged - -positioner.NotifyPositionUpdate(posInfo, status); - -... - -

                    Notes

                    When a call to RPositioner::NotifyPositionUpdate() or RPositioner::GetLastKnownPosition() completes, it is necessary to re-issue the request by calling one of these methods again to obtain further updates even if RPositioner::SetUpdateOptions() has been called. Setting update options allows a client to specify when the next position update is required, but does not cause periodic requests to the Location Server to be made.

                    A client application can only have one outstanding request for location information per RPositioner subsession. An attempt to make a second request for location information while one is still outstanding causes a panic to occur. An application must cancel an outstanding request before it makes another request. This process is described in step 7.

                    5. Request the location information

                    An application can call one the following methods to obtain position data:

                    • RPositioner::NotifyPositionUpdate()

                      A client application calls RPositioner::NotifyPositionUpdate() to request a position update. The LBS subsystem can either request that a Positioning Module obtains a new position and returns it to the client or simply returns an existing position calculated at some earlier time. The precise action taken by LBS depends on the quality of position required by the client because it is possible that a position obtained some time ago may meet the client application's position quality requirements.

                      RPositioner::NotifyPositionUpdate() is a client-server asynchronous call. The client application can pass any position info class that derives from TPositionInfoBase. The standard position info class is TPositionInfo which is supported by all Positioning Modules. An application can get extended location information (if there is a Positioning Module that can supply it) by passing one of the specialised position info classes such as TCourseInfo or TPositionSatelliteInfo instead of TPositionInfo.

                      See Position data and info classes for more information about position data and wrapper info classes.

                    • RPositioner::GetLastKnownPosition()

                      A client application calls RPositioner::GetLastKnownPosition() to request the device's last known position.

                      RPositioner::GetLastKnownPosition() is a client-server asynchronous call. Calling this method does not instigate a new position fix even if the LBS subsystem does not have a last known position. It is therefore possible that this method will fail to return a position if one was not previously calculated. Client applications must check for this possibility by checking the values of TCoordinate::Latitude() and TCoordinate::Longitude() of the TPosition object inside of the TPositionInfo parameter. If latitude and longitude data are not available they are set to NaN (Not a Number). An application may also need to check the timestamp of the information to ensure it still meets its needs as it is possible that the last position update was obtained some time ago.

                      If the LBS subsystem has a position from a previous request a call to RPositioner::GetLastKnownPosition() is more efficient in terms of request response time and device power consumption. It may also be cheaper for the mobile device owner who may be charged to obtain a new position.

                    • RPositioner::GetLastKnownPositionArea()

                      A client application calls RPositioner::GetLastKnownPositionArea() to request the last known position that most closely matches the device's current location. The device's current location is estimated from the network cell ID received from the network.

                      RPositioner::GetLastKnownPositionArea() is a client-server asynchronous call. The client application can request the LBS subsystem to provide either basic or the extended area information. The exact signature of the method is as follows:

                      RPositioner::GetLastKnownPositionArea(TPositionInfoBase& - aPosInfo, TPositionAreaInfoBase& aAreaInfo, TRequestStatus& aStatus) - const;

                      A client passes in aPosInfo, aAreaInfo and aStatus parameters.

                      • On completion, aPosInfo contains the last known position that is the best match with information received from the network.

                      • aAreaInfo contains an estimate of the accuracy of the last known position. TPositionAreaInfoBase is the base class for two position area data classes. A client can pass a TPositionAreaInfo object to get basic position accuracy information, or it can pass a TPositionAreaExtendedInfo object to get extra information about how the accuracy estimate was calculated.

                      If successful, GetLastKnownPositionArea() returns the best matching last known position in the aPosInfo parameter, an estimate of the position accuracy in the aAreaInfo parameter and a result code of KErrNone.

                      See RPositioner::GetLastKnownPositionArea() for more information about using this method and the returned error codes.

                      See Position Area Data Classes for information about the classes that used to obtain the position accuracy estimate.

                      The following code fragment shows how to use the method and check the accuracy of the returned position:

                      -// Create an RPositionServer, RPositioner, TRequestStatus as normal and open a session (see above) - -... - -// Want to know basic position accuracy, so use TPositionAreaInfo - -TRequestStatus status; -TPositionInfo posInfo; -TPositionAreaInfo areaInfo; - -// Get the last known location and an estimate of its accuracy - -positioner.GetLastKnownLocationArea(posInfo, areaInfo, status); -User::WaitForRequest(status); - -// Check the return status - -if ( status == KErrNone ) - { - - TPosition pos; - posInfo.GetPosition(pos); - TReal64 latitude = pos.Latitude(); - TReal64 longitude = pos.Longitude(); - TTime time = pos.Time(); - - /* - Check the posInfo object to see if it contains valid position data before trying to use it. - Check position latitude, longitude and (if necessary) altitude for Math::IsNaN(). - Also a good idea to check the timestamp against current time, because this position could be old. - Details omitted... - */ - - // Get the accuracy of the position - TPositionAreaInfo::TArea area = areaInfo.Area(); - - // Does this position meet your accuracy requirements? - - if (area == TPositionAreaInfo::EAreaCity) - { - - /* - In this example, want city level position accuracy. - Is this position accurate enough for your application? - - If not you could also check for EAreaDistrict and EAreaStreet. - TPositionAreaInfo::_TArea defines the values you can check for. - - If this position is accurate enough, do something useful with your returned position data... - - If it is not accurate enough, you may need to get a new full position fix - Call positioner.NotifyPositionUpdate() to do this. - */ - - } - - } - -else - - { - - /* - Function returned something other than KErrNone. - It could be KErrNotFound which indicates that no stored position was found. - Or it could be a system error code if something went wrong - you need to check it. - */ - - } -

                    Client applications must always check the value of the TRequestStatus parameter as this indicates the success or failure of the location request and may indicate that specified location accuracy criteria could not be satisfied at the time of the request.

                    The value of TRequestStatus that is set when a position update occurs or times out depends on the configuration of the LBS subsystem. See Location Acquisition API runtime behaviour for more information.

                    6. Receive and use the location information

                    When the Location Server obtains a position, the client's TRequestStatus variable is updated. In the example, the TPositionInfo object that was passed to RPositioner::NotifyPositionUpdate() holds the new position data in a TPosition object.

                    Important notes

                    An application should test what kind of position is returned by NotifyPositionUpdate(). TPositionInfoBase::PositionMode() returns a bitmask value of type TPositionModuleInfo::TTechnologyType that is composed of values of type TPositionModuleInfo::_TTechnologyType. Valid combinations of this value are as follows:

                    TPositionInfoBase::PositionMode() Meaning

                    ETechnologyNetwork

                    A reference position obtained from the network

                    ETechnologyTerminal | ETechnologyAssisted

                    A position calculated using GPS with assistance data from the network

                    ETechnologyNetwork | ETechnologyAssisted

                    A position calculated using GPS measurements by a remote server in the network

                    ETechnologyTerminal

                    A position calculated using GPS without assistance data (autonomous mode)

                    A reference position may be returned to a client application by the Location Server before a more accurate position fix is available. Whether a reference position is made available to the Location Server depends on the implementation of the Positioning Modules by the Symbian device creator or handset manufacturer.

                    If a reference position is returned, the behaviour is as follows:

                    For the first call to RPositioner::NotifyPositionUpdate()

                    NotifyPositionUpdate() completes and a reference position is returned to the client. The client application can check for return of a reference position by checking for TPositionInfoBase()::PositionMode() == - TPositionModuleInfo::ETechnologyNetwork. If a reference position is returned it may not satisfy the application's position accuracy quality criteria and the application will need to make another NotifyPositionUpdate() request.

                    For subsequent calls to RPositioner::NotifyPositionUpdate() (made by the same client subsession)

                    NotifyPositionUpdate() completes and a position is returned to the client. This position may be either:

                    • Calculated in the mobile device by GPS with assistance data (for Terminal Based Mode)

                      TPositionInfo::PositionMode() == - TPositionInfoBase::ETechnologyTerminal | - TPositionInfoBase::ETechnologyAssisted

                    • Returned from the network, a position known as the final network position (for Terminal Assisted Mode)

                      The value of TPositionInfo::PositionMode() for a final network position depends on the configuration of the LBS subsystem:

                      Normal behaviour is to return TPositionInfo::PositionMode() - == TPositionModuleInfo::ETechnologyNetwork | - TPositionModuleInfo::ETechnologyAssisted, but it is possible for LBS to return TPositionModuleInfo::ETechnologyTerminal | - TPositionModuleInfo::ETechnologyAssisted if it is configured to do so. See Location Acquisition API runtime behaviour for more information.

                    Note that NotifyPositionUpdate() may complete early if a GPS positioning module signals to LBS that it will be unable to return a location fix with the required quality criteria. In this case the Location Server returns the best location fix it can obtain to the client. The value of the TRequestStatus parameter of the client is set to either KPositionQualityLoss or KErrNone depending on the configuration of Location Acquisition API runtime behaviour.

                    Tracking

                    A position update time line for tracking is shown in figure 2. Note that the exact behaviour of tracking on systems may differ from that shown in Figure 2.

                    A client application has previously called TPositionUpdateOptions::SetUpdateInterval(T) and RPositioner::SetUpdateOptions() (not shown in figure 2). Partial updates are not set. LBS is also configured to return reference positions and accurate positions only (see Location Acquisition API runtime behaviour for more information about this behaviour). The important points are:

                    • A client application makes its first call to RPositioner::NotifyPositionUpdate() (First NPUD in figure 2).

                    • After a time t, the client's RunL() method is called and it receives its first position update (the reference position update Ref Pos in figure 2). This first position update is delivered to the client by LBS as soon as possible (t is as short as possible and is not equal to T). The client then makes its next call to NotifyPositionUpdate() (the next NPUD in figure 2). When tracking, a client application should make its next call to RPositioner::NotifyPositionUpdate() as soon as possible in its RunL() method. The time between the client's RunL() and the client's next NPUD is exaggerated for clarity in Figure 2.

                    • At a time t + T (where T is the update interval) the client's RunL() method is called and it receives the next position update (GPS Pos in figure 2). The client makes its next call to NotifyPositionUpdate().

                    • The next position update is expected at time t + 2T, but in the case shown in figure 2 this is not possible (the mobile device may have moved into an area where the GPS signal is weak). In general if it is not possible to obtain an accurate GPS fix by time t + nT, but the fix is obtained a short time later, the next position update is delivered as soon as possible after time t + nT (after t + 2T in figure 2).

                    • The client makes its next call to NotifyPositionUpdate() and at time t + (n+1)T the next position update is delivered (at t + 3T in figure 2).

                      The important point to note is that LBS attempts to deliver position updates at regular times t + nT but the time interval between position updates may temporarily be greater than or less than T.

                    • Note that if partial updates were enabled, an incomplete position would be delivered at time t + 2T if it were available. Also note that an inaccurate position would be delivered if one was available at that time and LBS was configured to return it.

                    - Figure 2. Position updates when tracking -

                    Error codes

                    The value of a client's TRequestStatus can be set to an LBS error code (defined in lbserrors.h) or an error code defined in a licensee's Positioning Module. An error causes NotifyPositionUpdate() to complete. An application should always check the value of TRequestStatus when its RunL() method is called.

                    7. Cancel or complete a location information request

                    To cancel a location request a client application calls RPositionerSubSessionBase::CancelRequest(), passing a EPositionerNotifyPositionUpdate parameter. The client's TRequestStatus is set to KErrCancel if the request was successfully cancelled and no position update is returned.

                    To complete a location request early, a client application calls RPositionerSubSessionBase::CompleteRequest() passing a EPositionerNotifyPositionUpdate parameter. Calling this method does not cancel the position update, but asks the Location Server to return any available position data. The returned position update may be different from that which would have been returned if the request had been allowed to complete normally. If the request is completed early, the client's TRequestStatus is set to KPositionEarlyComplete.

                    8. Close the subsession and session

                    RPositioner::Close() closes the subsession. RPositionServer::Close() closes the server session. In the code example the cleanup stack function is used. Any privacy requester objects created by a client must also be cleaned up.

                    \ No newline at end of file + + + + + +How to Get Location InformationThis document demonstrates how a client application uses the Location Acquisition API to get a position.
                    Purpose

                    This tutorial explains how to get location information using the Location Acquisition API.

                    Required background

                    Location Acquisition API Overview describes the main client/server classes of the API.

                    Position Data and Info Classes describes the classes that hold location information.

                    Getting location information

                    This section describes how to get location information using the Location Acquisition API.

                    Introduction

                    Client applications use the RPositionServer and RPositioner classes to get position updates. RPositionServer is used by client applications to manage a session with the Location Server and to get Positioning Module information. RPositioner is used by client applications to manage a subsession with the Location Server and to get position updates.

                    GPS positioning modes

                    The Global Positioning System (GPS) is a technology that is often included in devices that support LBS.

                    For each location request from a client, the LBS subsystem can operate in one of several different GPS positioning modes. The Location Acquisition API hides the details of which GPS positioning mode is in use from client applications. A client makes the same sequence of calls to the API to get a position update whichever positioning mode is used. Note that only some of these positioning modes may be available to a client application at runtime.

                    Each GPS positioning mode is a different way of getting a position fix:

                    • Autonomous

                      LBS uses a GPS Positioning Module to calculate position fixes without assistance data from the network. This mode typically takes the longest time to obtain a location fix compared to the other modes.

                    • Terminal Based Mode

                      LBS uses an A-GPS Positioning Module to calculate position fixes using assistance data from the network. Assistance data specifies the GPS satellites that are above the horizon as seen from the mobile device's current location. Assistance data is used by an A-GPS Positioning Module to reduce the time necessary to obtain a position fix.

                      The network can also supply a reference position to the LBS subsystem as part of the sequence of events. This position is calculated in the network using cell-based techniques and may be less accurate than that obtained from GPS. If a reference position is available, it may be returned to the client before a GPS position.

                      See Location Acquisition API Runtime Behaviour for more information about the position updates that can be returned by LBS.

                    • Terminal Assisted Mode

                      LBS uses an A-GPS Positioning Module to obtain GPS measurements (using assistance data from the network). GPS measurements are the raw data used to calculate a GPS fix. Measurements are sent to the network and a position fix is calculated by a remote server. The remotely calculated position fix is returned to the mobile device and is known as the final network position. The LBS subsystem returns this position to the client.

                    • Simultaneous Terminal Based Mode and Terminal Assisted Mode.

                      LBS passes GPS measurements to the network (as in Terminal Assisted Mode), but also attempts to use those measurements to calculate a GPS position fix (as in Terminal Based Mode). The position returned to the client may be either a GPS position (calculated in the mobile device) or a final network position (calculated using the measurements by a remote server in the network). The position that is calculated first (the GPS position or the final network position) is generally returned to the client. The final network position may also be returned to the client after the return of the GPS position.

                    Some devices also support a Cell-based Mode in which LBS obtains a position fix from the network without using GPS. This position fix is sometimes less accurate than that obtained using GPS.

                    A client application cannot directly choose the GPS positioning mode that is used for its location request. A handset manufacturer may provide an LBS settings application where the GPS mode can be selected by an end user. However for modes that involve the network (Terminal Based Mode, Terminal Assisted Mode and Cell-based Mode) it is possible for a network operator to override the GPS mode as part of the location request. If a client wants to know precisely how a position fix was calculated, this information is available in the returned position info object (as described in more detail later in this document).

                    Example sequence

                    Figure 1 shows a simplified sequence for a client requesting a position update from LBS. The sequence shows simplified behaviour for Terminal Based Mode. The A-GPS Module is a Positioning Module that uses Assisted GPS to calculate a position. The Network Protocol Module is a Positioning Module that obtains GPS assistance data and reference positions (often approximate positions) from the network. Note that Terminal Based Mode may not be available on all mobile devices. This depends on the Positioning Modules that have been installed by the mobile device creator.

                    + Figure 1. Simplified Terminal Based Mode Sequence +

                    Example code and description

                    The following code shows a simple example of how a client application can get a single position update. The numbers in the code comments refer to sections that follow the code example.

                    #include <lbs.h> +#include <lbserrors.h> + +... + +RPositionServer server; +RPositioner positioner; + +// 1. Create a session with the Location Server +User::LeaveIfError(server.Connect()); +CleanupClosePushL(server); + +// 2. Create a subsession with the Location Server using default positioning module +User::LeaveIfError(positioner.Open(server)); +CleanupClosePushL(positioner); + +// 3. Set the requester information - in this example define a requester stack... + +_LIT(KCntPhone, "+358501234567"); +_LIT(KSrvName, "MyService"); +RRequestorStack stack; +CRequestor* contact = CRequestor::NewLC(CRequestor::ERequestorContact, CRequestor::EFormatTelephone, KCntPhone); +stack.Append(contact); +CRequestor* service = CRequestor::NewLC(CRequestor::ERequestorService, CRequestor::EFormatApplication, KSrvName); +stack.Append(service); +User::LeaveIfError(positioner.SetRequestor(stack)); + +TPositionInfo posInfo; +TPosition pos; +TRequestStatus status; + +/* 4. To set update options, call RPositioner::SetUpdateOptions(). + See the description in section 4 below */ + +/* 5. Request location information + Could also call positioner.GetLastKnownPosition(posInfo, status) + to get cached location information */ +positioner.NotifyPositionUpdate(posInfo, status); +User::WaitForRequest(status); + +// 6. Receive location information +if (status != KErrNone) + { + // Handle possible client/server errors + ... + } + +// Get the position data object from the wrapper info object +posInfo.GetPosition(pos); + +// Use the position data +... + +// Reissue the location request if necessary by calling NotifyPositionUpdate() again + +/* 7. To cancel or complete a location request a client + calls RPositioner::CancelRequest() or RPositioner::CompleteRequest() */ + +// 8. Cleanup +stack.Reset(); +CleanupStack::PopAndDestroy(service); +CleanupStack::PopAndDestroy(contact); +CleanupStack::PopAndDestroy(&positioner); +CleanupStack::PopAndDestroy(&server); +

                    The following describes the steps to get location information as shown in the above example:

                    1. Create a session with the Location Server

                    To create a session with the Location Server, a client application:

                    • Creates an instance of RPositionServer

                    • Calls RPositionServer::Connect()

                    Standard client-server error codes are returned by calls to open the session. A panic occurs if the client application has already created a session with the Location Server. Error and panic codes specific to LBS are defined in LbsErrors.h.

                    2. Create a subsession with the Location Server

                    Location information requests are issued on a subsession.

                    To create a subsession, an application calls one of three overloaded RPositioner::Open() member functions:

                    • RPositioner::Open(RPositionServer& aPosServer) uses the Default Positioning Module to get location information. The client application does not specify any position quality criteria (which specify the required position accuracy) and therefore LBS uses default position quality criteria (horizontal accuracy = 50m, vertical accuracy = 1000m, request timeout = 30 seconds).

                    • RPositioner::Open(RPositionServer& aPosServer, + TPositionModuleId aModuleId) allows a specific Positioning Module to be specified by the client application. LBS uses position quality criteria associated with the specified Positioning Module. No quality criteria are specified and so LBS uses the capabilities of the Positioning Module as the default criteria.

                      See Positioning Modules for information about Positioning Module position quality and How to Use Positioning Module Information for more information about how to get a module ID.

                    The LBS subsystem does not compare the vertical accuracy of a calculated position with the vertical accuracy specified by a client application (specified by position quality criteria, by a quality profile or by a Positioning Module). Only the horizontal accuracy of a calculated position is used to decide if it is accurate enough to be returned to a client application.

                    3. Set client requester details

                    A client application can specify the client requesters by calling RPositioner::SetRequestorL() before calling RPositioner::NotifyPositionUpdate().

                    This is an optional step. Calling SetRequestorL() has no effect in this version of the Symbian platform. Calling SetRequestorL() is required in some devices based on earlier versions of Symbian. To ensure an LBS application runs on devices based on earlier versions of Symbian, it is recommended that it calls SetRequestorL().

                    See Privacy Requester Classes for more information.

                    4. Set update options

                    A client application calls RPositioner::SetUpdateOptions() to set the update options. Calling this method only affects future calls to RPositioner::NotifyPositionUpdate() and RPositioner::GetLastKnownPosition() and does not affect any outstanding requests.

                    A TPositionUpdateOptions parameter specifies the update options and is passed in RPositioner::SetUpdateOptions(). The properties of TPositionUpdateOptions are set either on its construction or via setter methods. The following properties can be defined:

                    • The time interval between position updates

                      TPositionUpdateOptions::SetUpdateInterval(TTimeIntervalMicroSeconds + aInterval) sets the time interval between position updates.

                      Setting a non-zero value indicates that the client requires periodic updates (this is also known as 'tracking'). LBS attempts to send position updates to the client application with this interval between the updates. Note that setting aInterval to 0 (or not setting it) indicates that the client is not tracking.

                      Note that when a client application is tracking, LBS does not return reference positions as periodic updates. See the section on Tracking later in this document for more information on tracking behaviour.

                    • A position update timeout

                      TPositionUpdateOptions::SetUpdateTimeOut(TTimeIntervalMicroSeconds + aTimeOut) sets a timeout for the location request. It specifies how long the client application is prepared to wait to obtain a position update. If the timeout expires RPositioner::NotifyPositionUpdate() completes and the client's RunL() method is called.

                      After a timeout the value set for the client's TRequestStatus parameter depends on the configuration of the LBS subsystem and may be either KErrTimeOut or KPositionQualityLoss. See Location Acquisition API runtime behaviour for more information.

                      Note that calling SetUpdateTimeOut() with a value of 0 (or not setting it) indicates that LBS should not timeout the location request from a client.

                    • The maximum age of a position update

                      TPositionUpdateOptions::SetMaxUpdateAge(TTimeIntervalMicroSeconds + aMaxAge) specifies the maximum age of the position data returned by RPositioner::NotifyPositionUpdate(). Setting this value allows the Location Server to use cached location information in some cases. The default value of 0 indicates that new position data is required.

                    • Acceptance of partial updates

                      A partial update is a position update that contains only partial position data. Such a position is called an incomplete position. An example of an incomplete position is one that contains data about the satellites used to obtain a GPS fix but no latitude or longitude data. LBS defines an incomplete position to be one where either TPosition::Latitude() or TPosition::Longitude() is NaN (Not a Number).

                      TPositionUpdateOptions::SetAcceptPartialUpdates(TBool + aPartial) allows an application to choose to accept partial updates. If a partial update is returned an application's TRequestStatus parameter is set to KPositionPartialUpdate when NotifyPositionUpdate() completes.

                      If partial updates are not set the default behaviour is for RPositioner::NotifyPositionUpdate() to complete only when the Positioning Module used for the location request has obtained as much information as possible. Note however that this behaviour is configurable by a Symbian device creator (see Location Acquisition API runtime behaviour for more information).

                    Important note on setting update options

                    The default constructor of TPositionUpdateOptions sets all update options to zero by default and is the equivalent of calling the following:

                    • TPositionUpdateOptions::SetUpdateInterval(0) meaning that tracking is off

                    • TPositionUpdateOptions::SetUpdateTimeout(0) meaning that LBS should not timeout the client's request

                    • TPositionUpdateOptions::SetMaxUpdateAge(0) meaning that new position data is required

                    • TPositionUpdateOptions::SetAcceptPartialUpdates(EFalse) meaning the partial updates are not returned

                    When setting update options, a client should beware of causing unexpected side effects. For example, if a client wants to accept partial updates, it might do the following:

                    • Create a new TPositionUpdateOptions options object

                    • Call TPositionUpdateOptions::SetAcceptPartialUpdates(ETrue)

                    • Call RPositioner::SetUpdateOptions() passing the options object as a parameter

                    However, this process has the side-effect of setting all the other update options to their default values as described above. In particular the client request will now not timeout which is unlikely to be the desired behaviour. To avoid this, a client should usually modify the current update options as follows:

                    • Get the current update options by calling RPositioner::GetUpdateOptions()

                    • Call the appropriate TPositionUpdateOptions::SetXXX() methods for the options to be changed

                    • Call RPositioner::SetUpdateOptions() passing the modified options object as a parameter

                    Examples

                    The following code shows a simple example of how to set update options. Note that all the options are changed by the client.

                    ... + +TPositionUpdateOptions options; + +// Frequency of updates in microseconds +const TTimeIntervalMicroSeconds KUpdateInterval(2000000); + +// How long the application is willing to wait before timing out the request +const TTimeIntervalMicroSeconds KTimeOut(4000000); + +// The maximum acceptable age of the information in an update +const TTimeIntervalMicroSeconds KMaxUpdateAge(1000000); + +options.SetUpdateInterval(KUpdateInterval); +options.SetUpdateTimeOut(KTimeOut); +options.SetMaxUpdateAge(KMaxUpdateAge); +options.SetAcceptPartialUpdates(EFalse); + +User::LeaveIfError(positioner.SetUpdateOptions(options)); + +/* Now when the application requests location information +it will be provided with these options */ + +positioner.NotifyPositionUpdate(posInfo, status); + +... + +

                    The following code example shows an example of how to change one update option (to accept partial updates).

                    ... + +TPositionUpdateOptions options; + +User::LeaveIfError(positioner.GetUpdateOptions(options)); +options.SetAcceptPartialUpdates(ETrue); +User::LeaveIfError(positioner.SetUpdateOptions(options)); + +// The other update options are unchanged + +positioner.NotifyPositionUpdate(posInfo, status); + +... + +

                    Notes

                    When a call to RPositioner::NotifyPositionUpdate() or RPositioner::GetLastKnownPosition() completes, it is necessary to re-issue the request by calling one of these methods again to obtain further updates even if RPositioner::SetUpdateOptions() has been called. Setting update options allows a client to specify when the next position update is required, but does not cause periodic requests to the Location Server to be made.

                    A client application can only have one outstanding request for location information per RPositioner subsession. An attempt to make a second request for location information while one is still outstanding causes a panic to occur. An application must cancel an outstanding request before it makes another request. This process is described in step 7.

                    5. Request the location information

                    An application can call one the following methods to obtain position data:

                    • RPositioner::NotifyPositionUpdate()

                      A client application calls RPositioner::NotifyPositionUpdate() to request a position update. The LBS subsystem can either request that a Positioning Module obtains a new position and returns it to the client or simply returns an existing position calculated at some earlier time. The precise action taken by LBS depends on the quality of position required by the client because it is possible that a position obtained some time ago may meet the client application's position quality requirements.

                      RPositioner::NotifyPositionUpdate() is a client-server asynchronous call. The client application can pass any position info class that derives from TPositionInfoBase. The standard position info class is TPositionInfo which is supported by all Positioning Modules. An application can get extended location information (if there is a Positioning Module that can supply it) by passing one of the specialised position info classes such as TCourseInfo or TPositionSatelliteInfo instead of TPositionInfo.

                      See Position data and info classes for more information about position data and wrapper info classes.

                    • RPositioner::GetLastKnownPosition()

                      A client application calls RPositioner::GetLastKnownPosition() to request the device's last known position.

                      RPositioner::GetLastKnownPosition() is a client-server asynchronous call. Calling this method does not instigate a new position fix even if the LBS subsystem does not have a last known position. It is therefore possible that this method will fail to return a position if one was not previously calculated. Client applications must check for this possibility by checking the values of TCoordinate::Latitude() and TCoordinate::Longitude() of the TPosition object inside of the TPositionInfo parameter. If latitude and longitude data are not available they are set to NaN (Not a Number). An application may also need to check the timestamp of the information to ensure it still meets its needs as it is possible that the last position update was obtained some time ago.

                      If the LBS subsystem has a position from a previous request a call to RPositioner::GetLastKnownPosition() is more efficient in terms of request response time and device power consumption. It may also be cheaper for the mobile device owner who may be charged to obtain a new position.

                    • RPositioner::GetLastKnownPositionArea()

                      A client application calls RPositioner::GetLastKnownPositionArea() to request the last known position that most closely matches the device's current location. The device's current location is estimated from the network cell ID received from the network.

                      RPositioner::GetLastKnownPositionArea() is a client-server asynchronous call. The client application can request the LBS subsystem to provide either basic or the extended area information. The exact signature of the method is as follows:

                      RPositioner::GetLastKnownPositionArea(TPositionInfoBase& + aPosInfo, TPositionAreaInfoBase& aAreaInfo, TRequestStatus& aStatus) + const;

                      A client passes in aPosInfo, aAreaInfo and aStatus parameters.

                      • On completion, aPosInfo contains the last known position that is the best match with information received from the network.

                      • aAreaInfo contains an estimate of the accuracy of the last known position. TPositionAreaInfoBase is the base class for two position area data classes. A client can pass a TPositionAreaInfo object to get basic position accuracy information, or it can pass a TPositionAreaExtendedInfo object to get extra information about how the accuracy estimate was calculated.

                      If successful, GetLastKnownPositionArea() returns the best matching last known position in the aPosInfo parameter, an estimate of the position accuracy in the aAreaInfo parameter and a result code of KErrNone.

                      See RPositioner::GetLastKnownPositionArea() for more information about using this method and the returned error codes.

                      See Position Area Data Classes for information about the classes that used to obtain the position accuracy estimate.

                      The following code fragment shows how to use the method and check the accuracy of the returned position:

                      +// Create an RPositionServer, RPositioner, TRequestStatus as normal and open a session (see above) + +... + +// Want to know basic position accuracy, so use TPositionAreaInfo + +TRequestStatus status; +TPositionInfo posInfo; +TPositionAreaInfo areaInfo; + +// Get the last known location and an estimate of its accuracy + +positioner.GetLastKnownLocationArea(posInfo, areaInfo, status); +User::WaitForRequest(status); + +// Check the return status + +if ( status == KErrNone ) + { + + TPosition pos; + posInfo.GetPosition(pos); + TReal64 latitude = pos.Latitude(); + TReal64 longitude = pos.Longitude(); + TTime time = pos.Time(); + + /* + Check the posInfo object to see if it contains valid position data before trying to use it. + Check position latitude, longitude and (if necessary) altitude for Math::IsNaN(). + Also a good idea to check the timestamp against current time, because this position could be old. + Details omitted... + */ + + // Get the accuracy of the position + TPositionAreaInfo::TArea area = areaInfo.Area(); + + // Does this position meet your accuracy requirements? + + if (area == TPositionAreaInfo::EAreaCity) + { + + /* + In this example, want city level position accuracy. + Is this position accurate enough for your application? + + If not you could also check for EAreaDistrict and EAreaStreet. + TPositionAreaInfo::_TArea defines the values you can check for. + + If this position is accurate enough, do something useful with your returned position data... + + If it is not accurate enough, you may need to get a new full position fix + Call positioner.NotifyPositionUpdate() to do this. + */ + + } + + } + +else + + { + + /* + Function returned something other than KErrNone. + It could be KErrNotFound which indicates that no stored position was found. + Or it could be a system error code if something went wrong - you need to check it. + */ + + } +

                    Client applications must always check the value of the TRequestStatus parameter as this indicates the success or failure of the location request and may indicate that specified location accuracy criteria could not be satisfied at the time of the request.

                    The value of TRequestStatus that is set when a position update occurs or times out depends on the configuration of the LBS subsystem. See Location Acquisition API runtime behaviour for more information.

                    6. Receive and use the location information

                    When the Location Server obtains a position, the client's TRequestStatus variable is updated. In the example, the TPositionInfo object that was passed to RPositioner::NotifyPositionUpdate() holds the new position data in a TPosition object.

                    Important notes

                    An application should test what kind of position is returned by NotifyPositionUpdate(). TPositionInfoBase::PositionMode() returns a bitmask value of type TPositionModuleInfo::TTechnologyType that is composed of values of type TPositionModuleInfo::_TTechnologyType. Valid combinations of this value are as follows:

                    TPositionInfoBase::PositionMode() Meaning

                    ETechnologyNetwork

                    A reference position obtained from the network

                    ETechnologyTerminal | ETechnologyAssisted

                    A position calculated using GPS with assistance data from the network

                    ETechnologyNetwork | ETechnologyAssisted

                    A position calculated using GPS measurements by a remote server in the network

                    ETechnologyTerminal

                    A position calculated using GPS without assistance data (autonomous mode)

                    A reference position may be returned to a client application by the Location Server before a more accurate position fix is available. Whether a reference position is made available to the Location Server depends on the implementation of the Positioning Modules by the Symbian device creator or handset manufacturer.

                    If a reference position is returned, the behaviour is as follows:

                    For the first call to RPositioner::NotifyPositionUpdate()

                    NotifyPositionUpdate() completes and a reference position is returned to the client. The client application can check for return of a reference position by checking for TPositionInfoBase()::PositionMode() == + TPositionModuleInfo::ETechnologyNetwork. If a reference position is returned it may not satisfy the application's position accuracy quality criteria and the application will need to make another NotifyPositionUpdate() request.

                    For subsequent calls to RPositioner::NotifyPositionUpdate() (made by the same client subsession)

                    NotifyPositionUpdate() completes and a position is returned to the client. This position may be either:

                    • Calculated in the mobile device by GPS with assistance data (for Terminal Based Mode)

                      TPositionInfo::PositionMode() == + TPositionInfoBase::ETechnologyTerminal | + TPositionInfoBase::ETechnologyAssisted

                    • Returned from the network, a position known as the final network position (for Terminal Assisted Mode)

                      The value of TPositionInfo::PositionMode() for a final network position depends on the configuration of the LBS subsystem:

                      Normal behaviour is to return TPositionInfo::PositionMode() + == TPositionModuleInfo::ETechnologyNetwork | + TPositionModuleInfo::ETechnologyAssisted, but it is possible for LBS to return TPositionModuleInfo::ETechnologyTerminal | + TPositionModuleInfo::ETechnologyAssisted if it is configured to do so. See Location Acquisition API runtime behaviour for more information.

                    Note that NotifyPositionUpdate() may complete early if a GPS positioning module signals to LBS that it will be unable to return a location fix with the required quality criteria. In this case the Location Server returns the best location fix it can obtain to the client. The value of the TRequestStatus parameter of the client is set to either KPositionQualityLoss or KErrNone depending on the configuration of Location Acquisition API runtime behaviour.

                    Tracking

                    A position update time line for tracking is shown in figure 2. Note that the exact behaviour of tracking on systems may differ from that shown in Figure 2.

                    A client application has previously called TPositionUpdateOptions::SetUpdateInterval(T) and RPositioner::SetUpdateOptions() (not shown in figure 2). Partial updates are not set. LBS is also configured to return reference positions and accurate positions only (see Location Acquisition API runtime behaviour for more information about this behaviour). The important points are:

                    • A client application makes its first call to RPositioner::NotifyPositionUpdate() (First NPUD in figure 2).

                    • After a time t, the client's RunL() method is called and it receives its first position update (the reference position update Ref Pos in figure 2). This first position update is delivered to the client by LBS as soon as possible (t is as short as possible and is not equal to T). The client then makes its next call to NotifyPositionUpdate() (the next NPUD in figure 2). When tracking, a client application should make its next call to RPositioner::NotifyPositionUpdate() as soon as possible in its RunL() method. The time between the client's RunL() and the client's next NPUD is exaggerated for clarity in Figure 2.

                    • At a time t + T (where T is the update interval) the client's RunL() method is called and it receives the next position update (GPS Pos in figure 2). The client makes its next call to NotifyPositionUpdate().

                    • The next position update is expected at time t + 2T, but in the case shown in figure 2 this is not possible (the mobile device may have moved into an area where the GPS signal is weak). In general if it is not possible to obtain an accurate GPS fix by time t + nT, but the fix is obtained a short time later, the next position update is delivered as soon as possible after time t + nT (after t + 2T in figure 2).

                    • The client makes its next call to NotifyPositionUpdate() and at time t + (n+1)T the next position update is delivered (at t + 3T in figure 2).

                      The important point to note is that LBS attempts to deliver position updates at regular times t + nT but the time interval between position updates may temporarily be greater than or less than T.

                    • Note that if partial updates were enabled, an incomplete position would be delivered at time t + 2T if it were available. Also note that an inaccurate position would be delivered if one was available at that time and LBS was configured to return it.

                    + Figure 2. Position updates when tracking +

                    Error codes

                    The value of a client's TRequestStatus can be set to an LBS error code (defined in lbserrors.h) or an error code defined in a licensee's Positioning Module. An error causes NotifyPositionUpdate() to complete. An application should always check the value of TRequestStatus when its RunL() method is called.

                    7. Cancel or complete a location information request

                    To cancel a location request a client application calls RPositionerSubSessionBase::CancelRequest(), passing a EPositionerNotifyPositionUpdate parameter. The client's TRequestStatus is set to KErrCancel if the request was successfully cancelled and no position update is returned.

                    To complete a location request early, a client application calls RPositionerSubSessionBase::CompleteRequest() passing a EPositionerNotifyPositionUpdate parameter. Calling this method does not cancel the position update, but asks the Location Server to return any available position data. The returned position update may be different from that which would have been returned if the request had been allowed to complete normally. If the request is completed early, the client's TRequestStatus is set to KPositionEarlyComplete.

                    8. Close the subsession and session

                    RPositioner::Close() closes the subsession. RPositionServer::Close() closes the server session. In the code example the cleanup stack function is used. Any privacy requester objects created by a client must also be cleaned up.

                    \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F6B9860A-E7F2-5B03-878D-9BCA0AF029C2.dita --- a/Symbian3/SDK/Source/GUID-F6B9860A-E7F2-5B03-878D-9BCA0AF029C2.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-F6B9860A-E7F2-5B03-878D-9BCA0AF029C2.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,128 +1,128 @@ - - - - - -Quick -Start -

                    Generic OS Services is a collection of components and libraries that provide -generic OS level services to the Symbian platform components and applications.

                    -
                    Getting started with Generic OS Services

                    The following -list briefly describes how device creators or Symbian Developers can use the -APIs of the components and libraries provided by Generic OS Services:

                      -

                    • Use the Plug-In Framework -(ECom) APIs to register, discover plug-ins and load appropriate plug-ins.

                      • -

                    • Use the P.I.P.S. libraries -(libc, libm, libpthread and libdl) -to port POSIX-based applications to the Symbian platform.

                      • -

                    • Use the Standard C++ -libraries to develop or port Standard C++ applications or libraries to the -Symbian platform.

                      • -

                    • Use the Librt library APIs to port Librt-based applications -onto the Symbian platform quickly and easily.

                      • -

                    • Use the EUser High Level -(EUserHL) library to do better string handling, resource management, and error -handling and object creation along the lines of standard C++ practices. EUserHL -library provides a usability layer to hide away some of the complexities of -the Symbian platform.

                      • -

                    • Use the Zip Compression -Library APIs to perform file and stream compression and decompression.

                      • -

                    • Use the task scheduler -APIs to develop applications with scheduling options and capabilities.

                      • -

                    • Use the Active Backup -Client APIs to create backup and restore software with complete control of -the data backed up and restored.

                      • -

                    • Use the HTTP Utilities -library APIs to extract URI components, construct and modify Uniform Resource -Indicators (URIs), text utilities, and URI component utilities required to -work with URIs.

                      • -

                    • Use the MIME (Multipurpose -Internet Mail Extension) Recognition Framework APIs to implement data type -recognition using MIME recognizer plug-ins.

                      • -

                    • Use the Basic Application -Framework Utilities library (BAFL) to in turn use utilities, such as clipboard, -command-line parser, descriptor array, environment change notifier, incremental -matcher, resource files, localized names of plug-ins, system sounds and string -pools.

                      • -

                    • Use the Base Services -Utility library (BSUL) to validate messages and handle errors.

                      • -

                    • Use the Activity Manager -library to enable clients to monitor user inactivity (idle time) and user -activity (key press).

                      • -

                    • Use the System Utility -library to perform the following tasks:

                        -

                      • Retrieve software and -language package version strings for display purposes.

                        • -

                      • Check for free space -on a disk drive before file creation or writing.

                        • -

                      • Get device type information -(phone model) for display purposes.

                        • -
                      • -
                    -
                    Architecture

                    The Generic OS Services module is -a group of non-related components and libraries that provide OS level services -to other components of the Symbian platform. The components and libraries -in Generic OS Services are grouped into the following collections:

                      -

                    • Compression -Libraries

                      • -

                    • Generic Open -Libraries

                      • -

                    • Generic -Services

                      • -

                    • Low -Level Libraries and Frameworks

                      • -

                    The following diagram outlines the Generic OS Services collections -and components associated with each collection:

                    - Collections and components of Generic OS Services - - -
                    -
                    Technologies

                    Generic OS services enables, implements -or uses the following technologies:

                      -

                    • zlib: The Zip Compression Library (EZLib) -provides C++ wrapper classes that encapsulate the functionality of the Open -Source zlib library -v1.2.3. It provides stream and file compression and decompression functionalities.

                      • -

                    • Standard C++: A -Standard C++ environment with IOStream and STL (Standard Template Library) -libraries enables you to develop or port Standard C++ applications or libraries -quickly and easily onto the Symbian platform. For more information, see the Standard C++ Porting Tutorials section.

                      • -

                    • P.I.P.S. Is POSIX -on Symbian Platform (P.I.P.S.): P.I.P.S. provides an API layer, above -the Symbian platform native APIs, that is more closely aligned with industry -standard APIs making Symbian software development more accessible to Symbian -Developers who program using the C language. Symbian Developers can use the -P.I.P.S. libraries (libc, libm, libpthread and libdl) -to port POSIX-based applications to the Symbian platform. For more information, -see the P.I.P.S. Porting -Tutorials section.

                      • -

                    • POSIX.1b, Real-time -extensions: The Librt library enables support for POSIX.1b, Real-time -extensions on the Symbian platform and is based on the Linux Standard Base -(LSB) 3.1 specification. It covers features such as shared memory, clocks -and real time emulation for timers. Support for the Librt library on the Symbian -platform enables you to port Librt-based applications onto the Symbian platform -quickly and easily. For more information, see the Librt section

                      • -

                    • MIME (Multipurpose -Internet Mail Extension): MIME is an internet standard system -for identifying the type of data in a file or stream. Types can include graphics, -photos, audio, video files and formatted text. MIME type recognition enables -devices to identify data in streams or files and start appropriate applications -automatically.

                      This technology is implemented by the MIME recognition -framework component. The MIME recognition framework implements data recognition -using MIME recogniser plug-ins. For more information, see the MIME -Recognition Framework section.

                      • -

                    • ECom Plug-in: The -Plug-in (ECom) framework is a generic framework that enables registration -and discovery of plug-ins, and the loading of an appropriate plug-in. The -Plug-In framework is intended to provide a common and system-wide mechanism -for instantiating a dynamically determined component. For more information, -see the Plug-in Framework section.

                      • -
                    + + + + + +Quick +Start +

                    Generic OS Services is a collection of components and libraries that provide +generic OS level services to the Symbian platform components and applications.

                    +
                    Getting started with Generic OS Services

                    The following +list briefly describes how device creators or Symbian Developers can use the +APIs of the components and libraries provided by Generic OS Services:

                      +

                    • Use the Plug-In Framework +(ECom) APIs to register, discover plug-ins and load appropriate plug-ins.

                      • +

                    • Use the P.I.P.S. libraries +(libc, libm, libpthread and libdl) +to port POSIX-based applications to the Symbian platform.

                      • +

                    • Use the Standard C++ +libraries to develop or port Standard C++ applications or libraries to the +Symbian platform.

                      • +

                    • Use the Librt library APIs to port Librt-based applications +onto the Symbian platform quickly and easily.

                      • +

                    • Use the EUser High Level +(EUserHL) library to do better string handling, resource management, and error +handling and object creation along the lines of standard C++ practices. EUserHL +library provides a usability layer to hide away some of the complexities of +the Symbian platform.

                      • +

                    • Use the Zip Compression +Library APIs to perform file and stream compression and decompression.

                      • +

                    • Use the task scheduler +APIs to develop applications with scheduling options and capabilities.

                      • +

                    • Use the Active Backup +Client APIs to create backup and restore software with complete control of +the data backed up and restored.

                      • +

                    • Use the HTTP Utilities +library APIs to extract URI components, construct and modify Uniform Resource +Indicators (URIs), text utilities, and URI component utilities required to +work with URIs.

                      • +

                    • Use the MIME (Multipurpose +Internet Mail Extension) Recognition Framework APIs to implement data type +recognition using MIME recognizer plug-ins.

                      • +

                    • Use the Basic Application +Framework Utilities library (BAFL) to in turn use utilities, such as clipboard, +command-line parser, descriptor array, environment change notifier, incremental +matcher, resource files, localized names of plug-ins, system sounds and string +pools.

                      • +

                    • Use the Base Services +Utility library (BSUL) to validate messages and handle errors.

                      • +

                    • Use the Activity Manager +library to enable clients to monitor user inactivity (idle time) and user +activity (key press).

                      • +

                    • Use the System Utility +library to perform the following tasks:

                        +

                      • Retrieve software and +language package version strings for display purposes.

                        • +

                      • Check for free space +on a disk drive before file creation or writing.

                        • +

                      • Get device type information +(phone model) for display purposes.

                        • +
                      • +
                    +
                    Architecture

                    The Generic OS Services module is +a group of non-related components and libraries that provide OS level services +to other components of the Symbian platform. The components and libraries +in Generic OS Services are grouped into the following collections:

                      +

                    • Compression +Libraries

                      • +

                    • Generic Open +Libraries

                      • +

                    • Generic +Services

                      • +

                    • Low +Level Libraries and Frameworks

                      • +

                    The following diagram outlines the Generic OS Services collections +and components associated with each collection:

                    + Collections and components of Generic OS Services + + +
                    +
                    Technologies

                    Generic OS services enables, implements +or uses the following technologies:

                      +

                    • zlib: The Zip Compression Library (EZLib) +provides C++ wrapper classes that encapsulate the functionality of the Open +Source zlib library +v1.2.3. It provides stream and file compression and decompression functionalities.

                      • +

                    • Standard C++: A +Standard C++ environment with IOStream and STL (Standard Template Library) +libraries enables you to develop or port Standard C++ applications or libraries +quickly and easily onto the Symbian platform. For more information, see the Standard C++ Porting Tutorials section.

                      • +

                    • P.I.P.S. Is POSIX +on Symbian Platform (P.I.P.S.): P.I.P.S. provides an API layer, above +the Symbian platform native APIs, that is more closely aligned with industry +standard APIs making Symbian software development more accessible to Symbian +Developers who program using the C language. Symbian Developers can use the +P.I.P.S. libraries (libc, libm, libpthread and libdl) +to port POSIX-based applications to the Symbian platform. For more information, +see the P.I.P.S. Porting +Tutorials section.

                      • +

                    • POSIX.1b, Real-time +extensions: The Librt library enables support for POSIX.1b, Real-time +extensions on the Symbian platform and is based on the Linux Standard Base +(LSB) 3.1 specification. It covers features such as shared memory, clocks +and real time emulation for timers. Support for the Librt library on the Symbian +platform enables you to port Librt-based applications onto the Symbian platform +quickly and easily. For more information, see the Librt section

                      • +

                    • MIME (Multipurpose +Internet Mail Extension): MIME is an internet standard system +for identifying the type of data in a file or stream. Types can include graphics, +photos, audio, video files and formatted text. MIME type recognition enables +devices to identify data in streams or files and start appropriate applications +automatically.

                      This technology is implemented by the MIME recognition +framework component. The MIME recognition framework implements data recognition +using MIME recogniser plug-ins. For more information, see the MIME +Recognition Framework section.

                      • +

                    • ECom Plug-in: The +Plug-in (ECom) framework is a generic framework that enables registration +and discovery of plug-ins, and the loading of an appropriate plug-in. The +Plug-In framework is intended to provide a common and system-wide mechanism +for instantiating a dynamically determined component. For more information, +see the Plug-in Framework section.

                      • +
                     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F740BA72-B00E-5D98-BD0F-5937F60460BC_d0e169201_href.jpg Binary file Symbian3/SDK/Source/GUID-F740BA72-B00E-5D98-BD0F-5937F60460BC_d0e169201_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F740BA72-B00E-5D98-BD0F-5937F60460BC_d0e175802_href.jpg Binary file Symbian3/SDK/Source/GUID-F740BA72-B00E-5D98-BD0F-5937F60460BC_d0e175802_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F765C7EB-A8C6-50C0-B350-85BE04C8984F.dita --- a/Symbian3/SDK/Source/GUID-F765C7EB-A8C6-50C0-B350-85BE04C8984F.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-F765C7EB-A8C6-50C0-B350-85BE04C8984F.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,33 +1,33 @@ - - - - - -Doubly -linked listsThis document is a introduction to doubly linked lists. -

                    A doubly linked list is one where each element has pointers forwards to -the next element and backwards to the previous element. The list is circular -- the last element points forwards to an anchor point, and the anchor point -points back to the last element.

                    -

                    Anchor points are always referred to as headers.

                    -

                    A doubly linked list is useful for maintaining a circular queue of items.

                    - - - -

                    Doubly linked lists involve the creation and use of the classes:

                    -
                      -

                    • TDblQueLink

                      • -

                    • TDblQue<class -T>

                      • -

                    • TDblQueIter<class -T

                      • -
                    -

                    In practice, these classes are almost always used as components of other -classes.

                    + + + + + +Doubly +linked listsThis document is a introduction to doubly linked lists. +

                    A doubly linked list is one where each element has pointers forwards to +the next element and backwards to the previous element. The list is circular +- the last element points forwards to an anchor point, and the anchor point +points back to the last element.

                    +

                    Anchor points are always referred to as headers.

                    +

                    A doubly linked list is useful for maintaining a circular queue of items.

                    + + + +

                    Doubly linked lists involve the creation and use of the classes:

                    +
                      +

                    • TDblQueLink

                      • +

                    • TDblQue<class +T>

                      • +

                    • TDblQueIter<class +T

                      • +
                    +

                    In practice, these classes are almost always used as components of other +classes.

                     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F77CC49A-904D-486B-8D16-972525EC34D5.dita --- a/Symbian3/SDK/Source/GUID-F77CC49A-904D-486B-8D16-972525EC34D5.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-F77CC49A-904D-486B-8D16-972525EC34D5.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,30 +1,31 @@ - - - - - -Data -query -

                    A Data query requests the user to type in some alphanumeric or numeric -information, such as a name or a phone number.

                    -

                    The query contains a prompt text and a user input field. The input field -can have any type of an editor, depending on the context, so that the input -may be restricted to e.g. numeric data, date or time only. Both the prompt -and input fields can be longer than one line when necessary.

                    -

                    The softkeys of a Data query are OK on the left for accepting the -input, and Cancel on the right softkey for discarding the query. The -Selection key accepts the input in the same way as the left softkey.

                    -

                    The Clear key is used for deleting characters and for that purpose only.

                    - -Data query. - - -
                    Using data queries in -C++ applications

                    For implementation information, see Queries.

                    + + + + + +Data +query +

                    A Data query requests the user to type in some alphanumeric or numeric +information, such as a name or a phone number.

                    +

                    The query contains a prompt text and a user input field. The input field +can have any type of an editor, depending on the context, so that the input +may be restricted to, for example, numeric data, date or time only. Both the +prompt and input fields can be longer than one line when necessary.

                    +

                    The softkeys of a Data query are OK on the left for accepting the +input, and Cancel on the right softkey for discarding the query. The +Selection key accepts the input in the same way as the left softkey.

                    +

                    The Clear key is used for deleting characters and for that purpose only.

                    + +Data query. + + +
                    Using +data queries in applications

                    For implementation information, +see Queries.

                     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F78F12AE-64CA-50BD-A715-8F254FBDB793_d0e173024_href.png Binary file Symbian3/SDK/Source/GUID-F78F12AE-64CA-50BD-A715-8F254FBDB793_d0e173024_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F78F12AE-64CA-50BD-A715-8F254FBDB793_d0e179619_href.png Binary file Symbian3/SDK/Source/GUID-F78F12AE-64CA-50BD-A715-8F254FBDB793_d0e179619_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F79A3DD7-DB91-545F-8165-F1F2DD6D0AD2.dita --- a/Symbian3/SDK/Source/GUID-F79A3DD7-DB91-545F-8165-F1F2DD6D0AD2.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-F79A3DD7-DB91-545F-8165-F1F2DD6D0AD2.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,15 +1,15 @@ - - - - - -Creating an Implicitly Bound SocketThis topic describes how create an implicitly bound socket.

                    • An application opens a socket using the default interface connection and binds to a port and IP address of the connection. The application receives inbound traffic only from the interface the socket is bound to.

                      For example, an application opens an implicit UDP socket and listens on port 8000. The UDP socket binds to interface IP address 10.253.4.134. The UDP socket must receive data packets from this interface only.

                    • If an application opens a socket and does not bind to a port or IP address of the default interface connection, then the application receives inbound traffic from multiple interfaces.

                      For example, if an application opens an implicit UDP socket and does not bind the port 8000 to the IP address of the default interface connection, then the application receives inbound traffic from all the interfaces.

                    Implicit binding example

                    Client B creates a socket with implicit binding without specifying the interface connection.

                    -server = RSocketServ.Connect(); -socket1 = RSocket.Open(server); -

                    ESock creates the socket within the default connection and subconnection.

                    Socket Binding                     \ No newline at end of file + + + + + +Creating an Implicitly Bound SocketThis topic describes how create an implicitly bound socket.

                    • An application opens a socket using the default interface connection and binds to a port and IP address of the connection. The application receives inbound traffic only from the interface the socket is bound to.

                      For example, an application opens an implicit UDP socket and listens on port 8000. The UDP socket binds to interface IP address 10.253.4.134. The UDP socket must receive data packets from this interface only.

                    • If an application opens a socket and does not bind to a port or IP address of the default interface connection, then the application receives inbound traffic from multiple interfaces.

                      For example, if an application opens an implicit UDP socket and does not bind the port 8000 to the IP address of the default interface connection, then the application receives inbound traffic from all the interfaces.

                    Implicit binding example

                    Client B creates a socket with implicit binding without specifying the interface connection.

                    +server = RSocketServ.Connect(); +socket1 = RSocket.Open(server); +

                    ESock creates the socket within the default connection and subconnection.

                    Socket Binding                     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F79E4F18-19E2-577E-8409-8B82BD48AC66.dita --- a/Symbian3/SDK/Source/GUID-F79E4F18-19E2-577E-8409-8B82BD48AC66.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-F79E4F18-19E2-577E-8409-8B82BD48AC66.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,181 +1,181 @@ - - - - - -XML -Framework Overview -

                    The XML Framework is a collection of components for event-based XML parsing -and provides content-processing architecture.

                    -
                    Purpose

                    The XML Framework provides configurable -features for parsing XML and WBXML (WAP -Binary XML), with options for validating against a specification and auto-correcting -for spelling errors in the validated text, using a single interface. It is -based on the SAX (Simple -API for XML) specification.

                    -
                    Required background

                    You must have a basic understanding -on XML before using XML Framework.

                    -
                    Key concepts

                    The following are the key concepts -of XML Framework:

                    Attribute

                    A name-value pair separated -by an equals sign, for example author="Jane Austen"

                    Attribute -type

                    One of certain data types defined for attributes, for instance CDATA.

                    Client

                    An -application which uses the XML framework for parsing or generating a document.

                    Document -Type Definition (DTD)

                    A document which defines a particular use -of XML entities (the names, attributes and values permitted).

                    Extension

                    WBXML -extends XML syntax with extension tokens which are used differently by different -applications. For example, extension token is used to refer to a string table -created specifically for each message and transmitted in the introduction -of the message.

                    Parser

                    It is an interface to the XML framework -which allows a client to access the parser plug-ins, which are specific for -a mark-up language. For example, XML Expat Parser and WBXML Parser.

                    String -dictionary collection

                    A class that holds a collection of string -dictionaries.

                    String dictionary plug-ins

                    The XML Framework -allows strings to be stored in DTD document, XML namespace or WBXML code page -in an ECOM plug-in that could be accessed as required by the parser and the -client. These plug-ins are referred as string dictionary plug-ins.

                    String -pool

                    A string pool is a mechanism for storing strings in a particular -way using which the strings can be compared quickly.

                    String table

                    A -WBXML document is encoded and decoded using a table of frequently encountered -strings which the body of the document references by index to compress the -data.

                    Uniform Resource Identifier (URI)

                    The web address -associated with a prefix. For instance, http://www.w3.org/XML/1998/namespace.

                    WBXML

                    WAP -Binary XML (WBXML) is a binary representation of XML. It was developed by -the Open Mobile Alliance as a standard to allow XML documents to be transmitted -in a compact manner over mobile networks and was proposed as an addition to -the World Wide Web Consortium's Wireless Application Protocol family of standards.

                    -
                    Architecture

                    The following diagram illustrates -the XML framework, consisting of client and a parser:

                    - Block diagram of XML framework - -

                    The XML framework consists of classes which model the main constituents -of the architecture - the framework as a whole, the parser plug-ins and extensions -to XML, the content processor chain and the content handler mechanism.

                    The -XML and WBXML parsers convert the contents of a document to UTF-8 format. -This is to ensure that extended characters are not lost from the document -by the String Pool. Expat is the engine behind the XML parser plug-in.

                    The -XML Framework allows strings to be stored for a particular DTD, XML namespace -or WBXML codepage in an ECOM plug-in that can be accessed when requireded -by the Parser and the Client. These plug-ins are referred as String Dictionary -Plug-ins and they are managed through a string dictionary collection object. -See String Dictionary

                    Libxml2 -provides XML processing, parsing and validation APIs. See libxml2.

                    Plug-in -1 and Plug-in 2 are examples of optional processors, which may be chained -together with the parser output to allow further processing of the data, before -the client receives it. Such plug-ins can be a DTD validator or a document -auto-corrector. The chain is not limited to just two plug-ins.

                    Parser -framework

                    The XML framework contains Parser framework which is -represented by the CParser class. A client with an XML -document to be parsed creates a CParser object and calls -its parse functions. CParser obtains the data about plug-ins -and the document to be parsed fromCMatchData and RDocumentParameters classes -respectively.

                    The parser framework conforms to the event-based SAX -specification. It outputs an event when it starts or finishes reading one -of the following:

                      -

                    • a document

                      • -

                    • a start tag

                      • -

                    • an end tag

                      • -

                    • a prefix mapping

                      • -

                    • a processing instruction

                      • -

                    • character data

                      • -

                    • ignorable white space

                      • -

                    For more information on XML-related concepts, refer to W3C or similar -sources.

                    Parser plug-ins

                    The CParser is -the interface to the XML framework allowing the client to access the parser -plug-ins, each one of which is specific to a mark-up language (e.g. XML, WBXML). -Individual parser plug-in implements the MParser interface. -It is associated through the TParserInitParams class, with -a character set converter (to convert other formats to Unicode), a string -dictionary and an element stack.

                    The Symbian platform framework is -delivered with three parser plug-ins, two for XML and one for WBXML.

                      -

                    • The first XML parser -consists of CXmlParser class, which is wrapped around the CExpat class, -an implementation of the stream-based Expat parser.

                      • -

                    • The second XML parser -consists of CXMLEngineSAXPlugin class, which encapsulates -the SAX parser of the libxml2 component. It is not available -if the Symbian platform build excludes this component.

                      • -

                    • The WBXML parser is -implemented as the CWmxmlParser class.

                      • -

                    Extensions to XML

                    The XML framework provides extensions -to XML. At present WBXML is implemented. WBXML requires use of string dictionaries -and extension tokens to store the element strings specific to the WBXML, which -are represented by the RStringDictionaryCollection, MWbxmlExtensionHandler and TExtensionTokens classes.

                    Content processors

                    Content processors are -plug-ins which perform further operations on the output of a parser plug-in. -They implement the MContentProcessor interface and are -associated through the TContentProcessorInitParams class, -with a string dictionary and element stack. They are organised into chains -by the MContentSource class which directs the output of -each plug-in to the next plug-in in the chain.

                    Content handlers

                    A -client application which is designed to react to the output of the XML framework -event must implement the MContentHandler interface. The -functions to be implemented correspond to the SAX specification discussed -in the Parser Framework section.

                    -
                    APIs

                    The XML Framework exports the following APIs:

                    - - - -API -Description - - - - -

                    CExpat

                    -

                    Encapsulates the Expat XML parser.

                    -                     - -

                    CXmlParser

                    -

                    Implementation of the stream-based Expat parser.

                    -                     - -

                    CXMLEngineSAXPlugin

                    -

                    Encapsulates the SAX parser of the libxml2 component.

                    -                     - -

                    CParser

                    -

                    Represents the entire parser framework.

                    -                     - -

                    CMatchData

                    -

                    Consists of the data of the plug-ins.

                    -                     - -

                    CWmxmlParser

                    -

                    WBXML parser implementation.

                    -                     - -

                    RDocumentParameters

                    -

                    Consists of the data about the document to be parsed.

                    -                     - -

                    RElementStack

                    -

                    Data structure used to store XML elements and check the tag ordering.

                    -                     - -

                    RStringDictionaryCollection

                    -

                    Holds a collection of dictionaries requested by the user.

                    -                     - - -
                    -
                    Typical uses

                    The following tasks can be performed -using XML Framework:

                      -

                    • Parsing an XML document.

                      • -

                    • Choosing a parser plug-in.

                      • -

                    • Using content processor.

                      • -

                    • Writing a parser plug-in.

                      • -

                    • Customising a parser -plug-in.

                      • -

                    • Creating a resource -file for a parser plug-in.

                      • -
                    -                     -XML Framework -Tutorials + + + + + +XML +Framework Overview +

                    The XML Framework is a collection of components for event-based XML parsing +and provides content-processing architecture.

                    +
                    Purpose

                    The XML Framework provides configurable +features for parsing XML and WBXML (WAP +Binary XML), with options for validating against a specification and auto-correcting +for spelling errors in the validated text, using a single interface. It is +based on the SAX (Simple +API for XML) specification.

                    +
                    Required background

                    You must have a basic understanding +on XML before using XML Framework.

                    +
                    Key concepts

                    The following are the key concepts +of XML Framework:

                    Attribute

                    A name-value pair separated +by an equals sign, for example author="Jane Austen"

                    Attribute +type

                    One of certain data types defined for attributes, for instance CDATA.

                    Client

                    An +application which uses the XML framework for parsing or generating a document.

                    Document +Type Definition (DTD)

                    A document which defines a particular use +of XML entities (the names, attributes and values permitted).

                    Extension

                    WBXML +extends XML syntax with extension tokens which are used differently by different +applications. For example, extension token is used to refer to a string table +created specifically for each message and transmitted in the introduction +of the message.

                    Parser

                    It is an interface to the XML framework +which allows a client to access the parser plug-ins, which are specific for +a mark-up language. For example, XML Expat Parser and WBXML Parser.

                    String +dictionary collection

                    A class that holds a collection of string +dictionaries.

                    String dictionary plug-ins

                    The XML Framework +allows strings to be stored in DTD document, XML namespace or WBXML code page +in an ECOM plug-in that could be accessed as required by the parser and the +client. These plug-ins are referred as string dictionary plug-ins.

                    String +pool

                    A string pool is a mechanism for storing strings in a particular +way using which the strings can be compared quickly.

                    String table

                    A +WBXML document is encoded and decoded using a table of frequently encountered +strings which the body of the document references by index to compress the +data.

                    Uniform Resource Identifier (URI)

                    The web address +associated with a prefix. For instance, http://www.w3.org/XML/1998/namespace.

                    WBXML

                    WAP +Binary XML (WBXML) is a binary representation of XML. It was developed by +the Open Mobile Alliance as a standard to allow XML documents to be transmitted +in a compact manner over mobile networks and was proposed as an addition to +the World Wide Web Consortium's Wireless Application Protocol family of standards.

                    +
                    Architecture

                    The following diagram illustrates +the XML framework, consisting of client and a parser:

                    + Block diagram of XML framework + +

                    The XML framework consists of classes which model the main constituents +of the architecture - the framework as a whole, the parser plug-ins and extensions +to XML, the content processor chain and the content handler mechanism.

                    The +XML and WBXML parsers convert the contents of a document to UTF-8 format. +This is to ensure that extended characters are not lost from the document +by the String Pool. Expat is the engine behind the XML parser plug-in.

                    The +XML Framework allows strings to be stored for a particular DTD, XML namespace +or WBXML codepage in an ECOM plug-in that can be accessed when requireded +by the Parser and the Client. These plug-ins are referred as String Dictionary +Plug-ins and they are managed through a string dictionary collection object. +See String Dictionary

                    Libxml2 +provides XML processing, parsing and validation APIs. See libxml2.

                    Plug-in +1 and Plug-in 2 are examples of optional processors, which may be chained +together with the parser output to allow further processing of the data, before +the client receives it. Such plug-ins can be a DTD validator or a document +auto-corrector. The chain is not limited to just two plug-ins.

                    Parser +framework

                    The XML framework contains Parser framework which is +represented by the CParser class. A client with an XML +document to be parsed creates a CParser object and calls +its parse functions. CParser obtains the data about plug-ins +and the document to be parsed fromCMatchData and RDocumentParameters classes +respectively.

                    The parser framework conforms to the event-based SAX +specification. It outputs an event when it starts or finishes reading one +of the following:

                      +

                    • a document

                      • +

                    • a start tag

                      • +

                    • an end tag

                      • +

                    • a prefix mapping

                      • +

                    • a processing instruction

                      • +

                    • character data

                      • +

                    • ignorable white space

                      • +

                    For more information on XML-related concepts, refer to W3C or similar +sources.

                    Parser plug-ins

                    The CParser is +the interface to the XML framework allowing the client to access the parser +plug-ins, each one of which is specific to a mark-up language (e.g. XML, WBXML). +Individual parser plug-in implements the MParser interface. +It is associated through the TParserInitParams class, with +a character set converter (to convert other formats to Unicode), a string +dictionary and an element stack.

                    The Symbian platform framework is +delivered with three parser plug-ins, two for XML and one for WBXML.

                      +

                    • The first XML parser +consists of CXmlParser class, which is wrapped around the CExpat class, +an implementation of the stream-based Expat parser.

                      • +

                    • The second XML parser +consists of CXMLEngineSAXPlugin class, which encapsulates +the SAX parser of the libxml2 component. It is not available +if the Symbian platform build excludes this component.

                      • +

                    • The WBXML parser is +implemented as the CWmxmlParser class.

                      • +

                    Extensions to XML

                    The XML framework provides extensions +to XML. At present WBXML is implemented. WBXML requires use of string dictionaries +and extension tokens to store the element strings specific to the WBXML, which +are represented by the RStringDictionaryCollection, MWbxmlExtensionHandler and TExtensionTokens classes.

                    Content processors

                    Content processors are +plug-ins which perform further operations on the output of a parser plug-in. +They implement the MContentProcessor interface and are +associated through the TContentProcessorInitParams class, +with a string dictionary and element stack. They are organised into chains +by the MContentSource class which directs the output of +each plug-in to the next plug-in in the chain.

                    Content handlers

                    A +client application which is designed to react to the output of the XML framework +event must implement the MContentHandler interface. The +functions to be implemented correspond to the SAX specification discussed +in the Parser Framework section.

                    +
                    APIs

                    The XML Framework exports the following APIs:

                    + + + +API +Description + + + + +

                    CExpat

                    +

                    Encapsulates the Expat XML parser.

                    +                     + +

                    CXmlParser

                    +

                    Implementation of the stream-based Expat parser.

                    +                     + +

                    CXMLEngineSAXPlugin

                    +

                    Encapsulates the SAX parser of the libxml2 component.

                    +                     + +

                    CParser

                    +

                    Represents the entire parser framework.

                    +                     + +

                    CMatchData

                    +

                    Consists of the data of the plug-ins.

                    +                     + +

                    CWmxmlParser

                    +

                    WBXML parser implementation.

                    +                     + +

                    RDocumentParameters

                    +

                    Consists of the data about the document to be parsed.

                    +                     + +

                    RElementStack

                    +

                    Data structure used to store XML elements and check the tag ordering.

                    +                     + +

                    RStringDictionaryCollection

                    +

                    Holds a collection of dictionaries requested by the user.

                    +                     + + +
                    +
                    Typical uses

                    The following tasks can be performed +using XML Framework:

                      +

                    • Parsing an XML document.

                      • +

                    • Choosing a parser plug-in.

                      • +

                    • Using content processor.

                      • +

                    • Writing a parser plug-in.

                      • +

                    • Customising a parser +plug-in.

                      • +

                    • Creating a resource +file for a parser plug-in.

                      • +
                    +                     +XML Framework +Tutorials                     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F7A17E65-CB2D-41D3-9404-1A7D7F55FABC_d0e70843_href.png Binary file Symbian3/SDK/Source/GUID-F7A17E65-CB2D-41D3-9404-1A7D7F55FABC_d0e70843_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F7A17E65-CB2D-41D3-9404-1A7D7F55FABC_d0e75876_href.png Binary file Symbian3/SDK/Source/GUID-F7A17E65-CB2D-41D3-9404-1A7D7F55FABC_d0e75876_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F7BFE6E3-0EEE-536C-8411-65D8F5FEBF2E_d0e79126_href.png Binary file Symbian3/SDK/Source/GUID-F7BFE6E3-0EEE-536C-8411-65D8F5FEBF2E_d0e79126_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F7BFE6E3-0EEE-536C-8411-65D8F5FEBF2E_d0e85838_href.png Binary file Symbian3/SDK/Source/GUID-F7BFE6E3-0EEE-536C-8411-65D8F5FEBF2E_d0e85838_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F7C762AA-3961-4739-ADD1-346DBF7CD7F8-master.png Binary file Symbian3/SDK/Source/GUID-F7C762AA-3961-4739-ADD1-346DBF7CD7F8-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F7C762AA-3961-4739-ADD1-346DBF7CD7F8_d0e82262_href.png Binary file Symbian3/SDK/Source/GUID-F7C762AA-3961-4739-ADD1-346DBF7CD7F8_d0e82262_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F7C9730D-7A41-4EE3-881C-393BB52B99C8_d0e36154_href.png Binary file Symbian3/SDK/Source/GUID-F7C9730D-7A41-4EE3-881C-393BB52B99C8_d0e36154_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F7C9730D-7A41-4EE3-881C-393BB52B99C8_d0e41721_href.png Binary file Symbian3/SDK/Source/GUID-F7C9730D-7A41-4EE3-881C-393BB52B99C8_d0e41721_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F7FEB759-E64D-5B6D-9017-C5E982E4FC16.dita --- a/Symbian3/SDK/Source/GUID-F7FEB759-E64D-5B6D-9017-C5E982E4FC16.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-F7FEB759-E64D-5B6D-9017-C5E982E4FC16.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,40 +1,40 @@ - - - - - -Standard -C++ Library Overview -
                    Purpose

                    Standard C++ support on the Symbian platform -helps to port existing Standard C++ applications onto the Symbian platform -quickly and easily. Also, if you have a good understanding of Standard C++ -and STL, you can easily develop a Standard C++ application or library using -the Standard C++ environment supported on the Symbian platform.

                    -
                    Required background

                    To use the Standard C++ environment -supported on the Symbian platform you need a good understanding of C++ and -STL. For complete information about STL, see Wikipedia.

                    Important: Symbian is not -responsible for the information available on external websites.

                    -
                    Architectural relationships

                    The following image -illustrates how Standard C++ interacts with the Symbian platform and P.I.P.S. -libraries:

                    - Standard C++ on the Symbian platform - -
                    -                     -Copyright -Acknowledgments for Standard C++ (STLport) -Standard -C++ Support on the Symbian Platform -Developing -Applications or Libraries Using Standard C++ -Building -a Standard C++ Application or Library -Known Issues - + + + + + +Standard +C++ Library Overview +
                    Purpose

                    Standard C++ support on the Symbian platform +helps to port existing Standard C++ applications onto the Symbian platform +quickly and easily. Also, if you have a good understanding of Standard C++ +and STL, you can easily develop a Standard C++ application or library using +the Standard C++ environment supported on the Symbian platform.

                    +
                    Required background

                    To use the Standard C++ environment +supported on the Symbian platform you need a good understanding of C++ and +STL. For complete information about STL, see Wikipedia.

                    Important: Symbian is not +responsible for the information available on external websites.

                    +
                    Architectural relationships

                    The following image +illustrates how Standard C++ interacts with the Symbian platform and P.I.P.S. +libraries:

                    + Standard C++ on the Symbian platform + +
                    +                     +Copyright +Acknowledgments for Standard C++ (STLport) +Standard +C++ Support on the Symbian Platform +Developing +Applications or Libraries Using Standard C++ +Building +a Standard C++ Application or Library +Known Issues +                     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F8069628-BD32-535C-963A-A1CF8172E275.dita --- a/Symbian3/SDK/Source/GUID-F8069628-BD32-535C-963A-A1CF8172E275.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-F8069628-BD32-535C-963A-A1CF8172E275.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,16 +1,16 @@ - - - - - -What are CF Protocols, Binders, and FlowsThis topic describes the concepts of Communications Framework (CF) Protocols,Binders and Flows in the Communications Framework.

                    In the Communications Architecture each Layer requires the participation of several communications components; namely the Tier Manager, MCPR, CPR, SCPR and the components. The name given to the Data Flow components is a Communications Framework Protocol (CF Protocol).

                    - Figure 1 - A CF Protocol in the Layered Comms Stack -

                    A CF Protocol is a collection of components on the Data Plane, most importantly the Flow and the Binder(s). The Flow is a Node and communicates with the SCPR that caused it to be started, using the asynchronous Message Transport mechanism. Each Flow has one or more Binders which connect the Flow to the layer above.

                    CF Protocol components - Components of a CF Protocol -

                    A CF Protocol is constructed of two main components:

                    • Flow - a single conversation with a remote peer. There can be multiple Flows in a CF Protocol to handle multiple concurrent conversations through the same instance of the CF Protocol.

                    • Binder - A Binder handles the interface between the current Flow and the Layer above. A Binder connects two CF Protocols together so that they can communicate data and sometimes commands. A Flow can have more than one Binder if it needs to connect to more than one Flow in the Layer above.

                      A Protocol Binder is the binding point for de-multiplexed incoming data but provides no flow control, data will be lost if the layer above is not ready to process it.

                      A Session Binder handles flow control by contacting the Layer above to say data is available, and waits for the CF Protocol of the Layer above to request the data.

                    Flow

                    A Flow is an instance of a class which represents a single conversation with a remote peer.

                    There may be many active Flows in a CF Protocol to represent many concurrent conversations through the same instance of the CF Protocol.

                    A Flow is a Stack Node created and controlled by one SCPR.

                    Configuration data for the Flow is provisioned directly by the SCPR and usually originates from the MCPR.

                    Since a Flow handles message exchange with the corresponding SCPR asynchronously, a Flow is always a state machine. State transitions are mostly triggered by exchange of different message types with the remote peer. State transitions may also be triggered by other mechanisms, such as timeouts, that require active objects within the Flow. A Flow is created by a Factory.

                    The Flow can de-multiplex the inbound, though it is up to the specific Flow to have appropriate code to do the de-multiplexing. De-multiplexing could be performed based on address information, port information, protocol specific session, source identifier or other data. De-multiplexing passes data to specific Flows, via individual Protocol Binders, to higher level CF Protocols which can also de-multiplex the data further. If there is no de-multiplexing then the layer above does not have to bind a protocol interface as a data receiver. An example would be an IP Flow, which may contain IPv4 and IPv6 packets and would have separate Protocl Binders for each version.

                    Each Flow must serve the following messages:

                    • TBindTo - tells the Flow which lower Flow to bind to

                    • TProvisionConfig - carries a configuration object

                    • TStartFlow - starts the Flow

                    • TStopFlow - stops the Flow

                    • TDestroy - instructs the Flow to delete itself

                    • TStateChange - the Flow should send this whenever it wants to inform the control side of its state change

                    Binder

                    The Binder is split into two parts:

                    • Binder Control - used by the upper layer to set up the binding with the lower layer.

                    • Binder - the actual binding between two Layers so that data can be sent and received. Again there are two types of Binder, Protocol Binder and Session Binder. It is common for a particular CF Protocol to only support one kind of Binder, Session or Protocol.

                    There will be CF Protocols where it will be a good design to have a Protocol Binder for data, and to use a Session Binder for control messages. These will usually be separate Flows.

                    Protocol Binder

                    A Protocol Binder is used by the Flow as the link to the next higher CF Protocol for inbound data.

                    A Protocol Binder only communicates with the Flow and should never communicate with an SCPR. Any design that would require the Protocol Binder to communicate with the SCPR should be redesigned.

                    Protocol Binders are most commonly used for lower-level protocols (nearer the hardware) rather than the higher-level Link layer protocols.

                    Session Binder

                    A Session Binder offers much richer functionality than a Protocol Binder as it is mostly used by higher level protocols (closer to application space) that are more complex than the lower level ones (closer to hardware). A Session Binder operates independently of the protocol of the next Layer above with which it connects, as opposed to the Protocol Binder which is specific for a particular protocol in the Layer above. A Session Binder may offer functionality that is supported by only some of the protocols using that binder. For example a Session Binder may provide flow control on the data, while a Protocol Binder will pass the data upwards immediately and if the Layer above is not able to accept the data it will be discarded.

                    Layers Planes Nodes                     \ No newline at end of file + + + + + +What are CF Protocols, Binders, and FlowsThis topic describes the concepts of Communications Framework (CF) Protocols,Binders and Flows in the Communications Framework.

                    In the Communications Architecture each Layer requires the participation of several communications components; namely the Tier Manager, MCPR, CPR, SCPR and the components. The name given to the Data Flow components is a Communications Framework Protocol (CF Protocol).

                    + Figure 1 - A CF Protocol in the Layered Comms Stack +

                    A CF Protocol is a collection of components on the Data Plane, most importantly the Flow and the Binder(s). The Flow is a Node and communicates with the SCPR that caused it to be started, using the asynchronous Message Transport mechanism. Each Flow has one or more Binders which connect the Flow to the layer above.

                    CF Protocol components + Components of a CF Protocol +

                    A CF Protocol is constructed of two main components:

                    • Flow - a single conversation with a remote peer. There can be multiple Flows in a CF Protocol to handle multiple concurrent conversations through the same instance of the CF Protocol.

                    • Binder - A Binder handles the interface between the current Flow and the Layer above. A Binder connects two CF Protocols together so that they can communicate data and sometimes commands. A Flow can have more than one Binder if it needs to connect to more than one Flow in the Layer above.

                      A Protocol Binder is the binding point for de-multiplexed incoming data but provides no flow control, data will be lost if the layer above is not ready to process it.

                      A Session Binder handles flow control by contacting the Layer above to say data is available, and waits for the CF Protocol of the Layer above to request the data.

                    Flow

                    A Flow is an instance of a class which represents a single conversation with a remote peer.

                    There may be many active Flows in a CF Protocol to represent many concurrent conversations through the same instance of the CF Protocol.

                    A Flow is a Stack Node created and controlled by one SCPR.

                    Configuration data for the Flow is provisioned directly by the SCPR and usually originates from the MCPR.

                    Since a Flow handles message exchange with the corresponding SCPR asynchronously, a Flow is always a state machine. State transitions are mostly triggered by exchange of different message types with the remote peer. State transitions may also be triggered by other mechanisms, such as timeouts, that require active objects within the Flow. A Flow is created by a Factory.

                    The Flow can de-multiplex the inbound, though it is up to the specific Flow to have appropriate code to do the de-multiplexing. De-multiplexing could be performed based on address information, port information, protocol specific session, source identifier or other data. De-multiplexing passes data to specific Flows, via individual Protocol Binders, to higher level CF Protocols which can also de-multiplex the data further. If there is no de-multiplexing then the layer above does not have to bind a protocol interface as a data receiver. An example would be an IP Flow, which may contain IPv4 and IPv6 packets and would have separate Protocl Binders for each version.

                    Each Flow must serve the following messages:

                    • TBindTo - tells the Flow which lower Flow to bind to

                    • TProvisionConfig - carries a configuration object

                    • TStartFlow - starts the Flow

                    • TStopFlow - stops the Flow

                    • TDestroy - instructs the Flow to delete itself

                    • TStateChange - the Flow should send this whenever it wants to inform the control side of its state change

                    Binder

                    The Binder is split into two parts:

                    • Binder Control - used by the upper layer to set up the binding with the lower layer.

                    • Binder - the actual binding between two Layers so that data can be sent and received. Again there are two types of Binder, Protocol Binder and Session Binder. It is common for a particular CF Protocol to only support one kind of Binder, Session or Protocol.

                    There will be CF Protocols where it will be a good design to have a Protocol Binder for data, and to use a Session Binder for control messages. These will usually be separate Flows.

                    Protocol Binder

                    A Protocol Binder is used by the Flow as the link to the next higher CF Protocol for inbound data.

                    A Protocol Binder only communicates with the Flow and should never communicate with an SCPR. Any design that would require the Protocol Binder to communicate with the SCPR should be redesigned.

                    Protocol Binders are most commonly used for lower-level protocols (nearer the hardware) rather than the higher-level Link layer protocols.

                    Session Binder

                    A Session Binder offers much richer functionality than a Protocol Binder as it is mostly used by higher level protocols (closer to application space) that are more complex than the lower level ones (closer to hardware). A Session Binder operates independently of the protocol of the next Layer above with which it connects, as opposed to the Protocol Binder which is specific for a particular protocol in the Layer above. A Session Binder may offer functionality that is supported by only some of the protocols using that binder. For example a Session Binder may provide flow control on the data, while a Protocol Binder will pass the data upwards immediately and if the Layer above is not able to accept the data it will be discarded.

                    Layers Planes Nodes                     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F82675C4-C2FD-50E2-BEDA-EB454FF1C57E_d0e202130_href.png Binary file Symbian3/SDK/Source/GUID-F82675C4-C2FD-50E2-BEDA-EB454FF1C57E_d0e202130_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F82675C4-C2FD-50E2-BEDA-EB454FF1C57E_d0e207138_href.png Binary file Symbian3/SDK/Source/GUID-F82675C4-C2FD-50E2-BEDA-EB454FF1C57E_d0e207138_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F8A26275-883A-5299-9C37-9DDCC2F62108.dita --- a/Symbian3/SDK/Source/GUID-F8A26275-883A-5299-9C37-9DDCC2F62108.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-F8A26275-883A-5299-9C37-9DDCC2F62108.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,50 +1,50 @@ - - - - - -Eclipsing -

                    Eclipsing is a mechanism to upgrade files existing on the ROM drive, by -installing a new version of the same on the RAM drive. The file name and path -of the existing file and the new version must be the same.

                    -

                    For example, the file, a.exe located on z:\...\, -can be eclipsed by placing a latest version of a.exe on C:\...\.

                    -
                    Eclipsing rules

                    The -eclipsing of binary and data files in the ROM is strictly controlled. That -is, device creators can eclipse only the files that are listed in the Stub -SIS file. The eclipsing fails if there is no associated Stub SIS file present -in ROM.

                    The following are important considerations for eclipsing -ROM files:

                      -

                    • Drives are -scanned in the order Y to A and -lastly the Z drive. Therefore a file in Z drive -can be eclipsed by the newer version of the file placed on any drive between Y to A.

                      • -

                    • The upgrading package -must have the same package UID and non-localized vendor name as the package -that installed the original file.

                      • -

                    • The file in ROM can -be eclipsed only once.

                      • -

                    • The installation is -blocked if a data file with the same name as the file to be eclipsed exists -in the file system. The device creators can configure the installation policy -to enable the Symbian device user to remove the obstructing files and continue -with the installation.

                      • -

                    • Eclipsing of EXEs, DLLs and -data files either by installation or by inserting the media card into the -Symbian device returns an error. This aborts the installation or renders the -media card application unusable until the conflict is resolved. This restriction -is not applicable if the file being eclipsed is an orphaned file.

                      • -
                    -                     -Package Upgrades - -Upgrade Types - - + + + + + +Eclipsing +

                    Eclipsing is a mechanism to upgrade files existing on the ROM drive, by +installing a new version of the same on the RAM drive. The file name and path +of the existing file and the new version must be the same.

                    +

                    For example, the file, a.exe located on z:\...\, +can be eclipsed by placing a latest version of a.exe on C:\...\.

                    +
                    Eclipsing rules

                    The +eclipsing of binary and data files in the ROM is strictly controlled. That +is, device creators can eclipse only the files that are listed in the Stub +SIS file. The eclipsing fails if there is no associated Stub SIS file present +in ROM.

                    The following are important considerations for eclipsing +ROM files:

                      +

                    • Drives are +scanned in the order Y to A and +lastly the Z drive. Therefore a file in Z drive +can be eclipsed by the newer version of the file placed on any drive between Y to A.

                      • +

                    • The upgrading package +must have the same package UID and non-localized vendor name as the package +that installed the original file.

                      • +

                    • The file in ROM can +be eclipsed only once.

                      • +

                    • The installation is +blocked if a data file with the same name as the file to be eclipsed exists +in the file system. The device creators can configure the installation policy +to enable the Symbian device user to remove the obstructing files and continue +with the installation.

                      • +

                    • Eclipsing of EXEs, DLLs and +data files either by installation or by inserting the media card into the +Symbian device returns an error. This aborts the installation or renders the +media card application unusable until the conflict is resolved. This restriction +is not applicable if the file being eclipsed is an orphaned file.

                      • +
                    +                     +Package Upgrades + +Upgrade Types + +                     \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F95A7D74-FD5C-40D2-BF4F-2F75443CAE51.dita --- a/Symbian3/SDK/Source/GUID-F95A7D74-FD5C-40D2-BF4F-2F75443CAE51.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-F95A7D74-FD5C-40D2-BF4F-2F75443CAE51.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,70 +1,70 @@ - - - - - -Column -structure of lists -

                    For visual consistency, the standard list layouts are built around a structure -of three virtual columns. The column borders are aligned with the sides of -the context pane.

                    -

                    The width of list items can be divided in three sections (columns A, B -and C). All three columns need not be used separately in a list layout: combinations -AB, BC or ABC are possible. Column D is basically the very end of column C -where additional indicators can be displayed (see figure below). The area -for these indicators is not strictly an individual column in the same sense -as the other three, because it can be used dynamically, item by item. All -items within a list must use the same column layout.

                    - -Different column arrangements: a) All columns used for a text item. -b) Column A contains an icon, columns B&C combined for text. c) Columns -A&B combined for a large icon, column C contains text. d) Column A: an -icon; column B: a label; column C: text. - - -Standard elements -within list item associated with columns - - - -Column -Description - - - - -

                    Column A

                     -
                      -

                    • Small graphic (icon): an item property indication.

                      • -

                    • The item number (see Numbered -items).

                      • -
                     -                     - -

                    Column B

                     -

                    Heading (the title or attribute of the item).

                     -                     - -

                    Column AB

                     -
                      -

                    • Heading (the title or attribute of the item).

                      • -

                    • Large graphic (for example, an icon or an image thumbnail).

                      • -
                     -                     - -

                    Column C/BC/ABC

                     -

                    The main text of the item.

                     -                     - - -
                    -

                    The list layout can be mirrored for localizations such as Arabic -and Hebrew (for example, column A is in the right edge of the pane). See Layout changes in bi-directional -languages.

                     + + + + + +Column +structure of lists +

                    For visual consistency, the standard list layouts are built around a structure +of three virtual columns. The column borders are aligned with the sides of +the context pane.

                    +

                    The width of list items can be divided in three sections (columns A, B +and C). All three columns need not be used separately in a list layout: combinations +AB, BC or ABC are possible. Column D is basically the very end of column C +where additional indicators can be displayed (see figure below). The area +for these indicators is not strictly an individual column in the same sense +as the other three, because it can be used dynamically, item by item. All +items within a list must use the same column layout.

                    + +Different column arrangements: a) All columns used for a text item. +b) Column A contains an icon, columns B&C combined for text. c) Columns +A&B combined for a large icon, column C contains text. d) Column A: an +icon; column B: a label; column C: text. + + +Standard elements +within list item associated with columns + + + +Column +Description + + + + +

                    Column A

                     +
                      +

                    • Small graphic (icon): an item property indication.

                      • +

                    • The item number (see Numbered +items).

                      • +
                     +                     + +

                    Column B

                     +

                    Heading (the title or attribute of the item).

                     +                     + +

                    Column AB

                     +
                      +

                    • Heading (the title or attribute of the item).

                      • +

                    • Large graphic (for example, an icon or an image thumbnail).

                      • +
                     +                     + +

                    Column C/BC/ABC

                     +

                    The main text of the item.

                     +                     + + +
                    +

                    The list layout can be mirrored for localizations such as Arabic +and Hebrew (for example, column A is in the right edge of the pane). See Layout changes in bi-directional +languages.

                                         \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F96623BF-B646-46B4-942E-69EB065BE491-master.png Binary file Symbian3/SDK/Source/GUID-F96623BF-B646-46B4-942E-69EB065BE491-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F96623BF-B646-46B4-942E-69EB065BE491_d0e57672_href.png Binary file Symbian3/SDK/Source/GUID-F96623BF-B646-46B4-942E-69EB065BE491_d0e57672_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F96623BF-B646-46B4-942E-69EB065BE491_d0e62709_href.png Binary file Symbian3/SDK/Source/GUID-F96623BF-B646-46B4-942E-69EB065BE491_d0e62709_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F96623BF-B646-46B4-942E-69EB065BE491_d0e67818_href.png Binary file Symbian3/SDK/Source/GUID-F96623BF-B646-46B4-942E-69EB065BE491_d0e67818_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F96623BF-B646-46B4-942E-69EB065BE491_d0e69206_href.png Binary file Symbian3/SDK/Source/GUID-F96623BF-B646-46B4-942E-69EB065BE491_d0e69206_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F96623BF-B646-46B4-942E-69EB065BE491_d0e74372_href.png Binary file Symbian3/SDK/Source/GUID-F96623BF-B646-46B4-942E-69EB065BE491_d0e74372_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F96D14A5-58BB-4F1A-A6FB-5D13DCB84B33-master.png Binary file Symbian3/SDK/Source/GUID-F96D14A5-58BB-4F1A-A6FB-5D13DCB84B33-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F96D14A5-58BB-4F1A-A6FB-5D13DCB84B33_d0e61999_href.png Binary file Symbian3/SDK/Source/GUID-F96D14A5-58BB-4F1A-A6FB-5D13DCB84B33_d0e61999_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F97EA91E-35E3-5E69-A4C4-7415AB91C1BC_d0e77110_href.png Binary file Symbian3/SDK/Source/GUID-F97EA91E-35E3-5E69-A4C4-7415AB91C1BC_d0e77110_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F97EA91E-35E3-5E69-A4C4-7415AB91C1BC_d0e83822_href.png Binary file Symbian3/SDK/Source/GUID-F97EA91E-35E3-5E69-A4C4-7415AB91C1BC_d0e83822_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F9896E96-1076-552D-AE54-8F9DABED867F.dita --- a/Symbian3/SDK/Source/GUID-F9896E96-1076-552D-AE54-8F9DABED867F.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-F9896E96-1076-552D-AE54-8F9DABED867F.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,59 +1,59 @@ - - - - - -Configuring the Video Player

                    This tutorial describes how to configure the video player.

                    Purpose

                    The purpose of this tutorial is to show you how to make configuration adjustments to the video player.

                    Required Background

                    The Video Client Overview introduces the video client utilities.

                    Introduction

                    The video player utility is used to open, play, and obtain information from sampled video data. This functionality is implemented by the CVideoPlayerUtility class. The video data can be supplied either in a file, a descriptor or a URL.

                    Using Video Player

                    The following tasks will be covered in this tutorial:

                    • Set the Display Window

                    • Query and Set the Volume

                    • Query and Set the Balance

                    • Query and Set the Priority

                    • Query and Set the Bit and Frame Rate

                    • Query and Set the Current Playback Position

                    • Query and Set the MIME and Codec Type

                    Setting the Display Window

                    The high level steps to set the display window are shown here:

                    • CVideoPlayerUtility::SetDisplayWindowL: This is used to provide the video controller with an area of display to render the current video frame. It can be represented pictorially as shown below:

                      - Video display regions -

                      The screeenRect specifies the area within the window provided for displaying the video image. This rectangle is in screen coordinates. The video frame will be fitted to this rectangle as best possible, while maintaining the original aspect ratio.

                      The ClipRect specifies the region to draw. The drawn region will be the intersection between the ClipRect and the ScreenRect.

                      A crop region is defined as a region in the source video frame. The cropped region is displayed in the center of the ScreenRect with the same scaling as if it was displayed as part of the whole image. This could be used to zoom in on a region by setting the crop region, and setting the scale factor to fill the WindowRect.

                      void CPlayVideo::SetDisplayWindowL(RWsSession &aWs, CWsScreenDevice &aScreenDevice, RWindowBase &aWindow, const TRect &aWindowRect, const TRect &aClipRect) - { - iVideoUtility->SetDisplayWindowL(aWs, aScreenDevice, aWindow, aWindowRect, aClipRect); - } -

                    Querying and Setting the Volume

                    The current volume settings can be reported and set appropriately with the help of the following functions: :

                    • CVideoPlayerUtility::Volume(): Returns the current playback volume for the audio track of the video clip.

                      TInt CPlayVideo::Volume() - { - return iVideoUtility->Volume(); - }

                    • CVideoPlayerUtility::MaxVolume(): Returns the maximum volume that the audio track can support.

                    • CVideoPlayerUtility::SetVolumeL(): This function allows the volume of the audio track of the video clip to be set. The volume can be changed before or during playback and comes to effect immediately. The volume can be set to a value anywhere between zero and the maximum permissible volume.

                      TInt volume; - -volume = iVideoPlayer.MaxVolume(); \\Returns maximum volume -void CPlayVideo::SetVolumeL(TInt aVolume) \\Set the audio volume - { - iVideoUtility->SetVolumeL(aVolume); - } - -//The volume must be a value between 0 and the value returned by the MaxVolume function. - -

                    Querying and Setting the Balance

                    The audio playback balance settings can be done using the following functions:

                    • CVideoPlayerUtility::SetBalanceL(): This function sets the current playback balance for the audio track of the video clip. It can be any value between KMMFBalanceMaxLeft and KMMFBalanceMaxRight.

                      void CPlayVideo::SetBalanceL(TInt aBalance) - { - iVideoUtility->SetBalanceL(aBalance); - }

                    • CVideoPlayerUtility::Balance(): This function returns the current playback balance settings for the audio track of the video clip.

                      TInt CPlayVideo::Balance() - { - return iVideoUtility->Balance(); - }

                    Querying and Setting the Priority

                    To set the priority for the playback to access the sound hardware, use the following methods:

                    • PriorityL(): This function returns the current playback priority. This is used to arbitrate between multiple objects simultaneously trying to accesses the sound hardware.

                    • SetPriorityL(): This function sets the playback priority.

                      void CPlayVideo::SetPriorityL(TInt aPriority, TMdaPriorityPreference aPref) - { - iVideoUtility->SetPriorityL(aPriority, aPref); - }

                    Querying and Setting the Bit and Frame Rate

                    The high level steps to query and set the bit and frame rate:

                    • CVideoPlayerUtility::VideoBitRateL(): This function returns the bit rate of the video clip. This returns the video clip's bit rate in bits per second.

                      TInt CPlayVideo::VideoBitRateL() - { - return iVideoUtility->VideoBitRateL(); - }

                    • CVideoPlayerUtility::VideoFrameRateL(): This function returns the video frame rate. This returns the video frame rate in frames per second.

                      TReal32 CPlayVideo::VideoFrameRateL() - { - return iVideoUtility->VideoFrameRateL(); - }

                    • CVideoPlayerUtility::SetVideoFrameRateL(): This function is used to set the number of video frames to be displayed per second.

                      void CPlayVideo::SetVideoFrameRateL(TReal32 aFramesPerSecond) - { - iVideoUtility->SetVideoFrameRateL(aFramesPerSecond); - }

                    Note: The presence of an audio track within a video clip can be determined using AudioEnabledL().

                    Querying and Setting the Current Playback Position

                    The current playback position can be queried and set using the following functions:

                    • CVideoPlayerUtility::PositionL(): This function returns the current playback position. It returns the current position from the start of the clip in microseconds.

                    • CVideoPlayerUtility::SetPositionL(): This function sets the position for the playback within the video clip to start.

                      TTimeIntervalMicroSeconds pos; -TTimeIntervalMicroSeconds CPlayVideo::PositionL() \\ retrieves the current playback position within the video clip - { - return iVideoUtility->PositionL(); - }

                    Querying and Setting the MIME and Codec Type

                    This section explains the functions that reports and sets the MIME type and codecs for video and audio data that is already open. The functions are as stated below:

                    • CVideoPlayerUtility::VideoFormatMimeType(): This returns the current MIME type of the video clip currently open.

                      const TDesC8 & CPlayVideo::VideoFormatMimeType() - { - return iVideoUtility->VideoFormatMimeType(); - }

                    • The datatype of the audio track used by the video clip can be retrieved using and AudioTypeL().

                      TFourCC CPlayVideo::AudioTypeL() \\retrieves the codecs used by audio track - { - return iVideoUtility->AudioTypeL(); + + + + + +Configuring the Video Player

                      This tutorial describes how to configure the video player.

                      Purpose

                      The purpose of this tutorial is to show you how to make configuration adjustments to the video player.

                      Required Background

                      The Video Client Overview introduces the video client utilities.

                      Introduction

                      The video player utility is used to open, play, and obtain information from sampled video data. This functionality is implemented by the CVideoPlayerUtility class. The video data can be supplied either in a file, a descriptor or a URL.

                      Using Video Player

                      The following tasks will be covered in this tutorial:

                      • Set the Display Window

                      • Query and Set the Volume

                      • Query and Set the Balance

                      • Query and Set the Priority

                      • Query and Set the Bit and Frame Rate

                      • Query and Set the Current Playback Position

                      • Query and Set the MIME and Codec Type

                      Setting the Display Window

                      The high level steps to set the display window are shown here:

                      • CVideoPlayerUtility::SetDisplayWindowL: This is used to provide the video controller with an area of display to render the current video frame. It can be represented pictorially as shown below:

                        + Video display regions +

                        The screeenRect specifies the area within the window provided for displaying the video image. This rectangle is in screen coordinates. The video frame will be fitted to this rectangle as best possible, while maintaining the original aspect ratio.

                        The ClipRect specifies the region to draw. The drawn region will be the intersection between the ClipRect and the ScreenRect.

                        A crop region is defined as a region in the source video frame. The cropped region is displayed in the center of the ScreenRect with the same scaling as if it was displayed as part of the whole image. This could be used to zoom in on a region by setting the crop region, and setting the scale factor to fill the WindowRect.

                        void CPlayVideo::SetDisplayWindowL(RWsSession &aWs, CWsScreenDevice &aScreenDevice, RWindowBase &aWindow, const TRect &aWindowRect, const TRect &aClipRect) + { + iVideoUtility->SetDisplayWindowL(aWs, aScreenDevice, aWindow, aWindowRect, aClipRect); + } +

                      Querying and Setting the Volume

                      The current volume settings can be reported and set appropriately with the help of the following functions: :

                      • CVideoPlayerUtility::Volume(): Returns the current playback volume for the audio track of the video clip.

                        TInt CPlayVideo::Volume() + { + return iVideoUtility->Volume(); + }

                      • CVideoPlayerUtility::MaxVolume(): Returns the maximum volume that the audio track can support.

                      • CVideoPlayerUtility::SetVolumeL(): This function allows the volume of the audio track of the video clip to be set. The volume can be changed before or during playback and comes to effect immediately. The volume can be set to a value anywhere between zero and the maximum permissible volume.

                        TInt volume; + +volume = iVideoPlayer.MaxVolume(); \\Returns maximum volume +void CPlayVideo::SetVolumeL(TInt aVolume) \\Set the audio volume + { + iVideoUtility->SetVolumeL(aVolume); + } + +//The volume must be a value between 0 and the value returned by the MaxVolume function. + +

                      Querying and Setting the Balance

                      The audio playback balance settings can be done using the following functions:

                      • CVideoPlayerUtility::SetBalanceL(): This function sets the current playback balance for the audio track of the video clip. It can be any value between KMMFBalanceMaxLeft and KMMFBalanceMaxRight.

                        void CPlayVideo::SetBalanceL(TInt aBalance) + { + iVideoUtility->SetBalanceL(aBalance); + }

                      • CVideoPlayerUtility::Balance(): This function returns the current playback balance settings for the audio track of the video clip.

                        TInt CPlayVideo::Balance() + { + return iVideoUtility->Balance(); + }

                      Querying and Setting the Priority

                      To set the priority for the playback to access the sound hardware, use the following methods:

                      • PriorityL(): This function returns the current playback priority. This is used to arbitrate between multiple objects simultaneously trying to accesses the sound hardware.

                      • SetPriorityL(): This function sets the playback priority.

                        void CPlayVideo::SetPriorityL(TInt aPriority, TMdaPriorityPreference aPref) + { + iVideoUtility->SetPriorityL(aPriority, aPref); + }

                      Querying and Setting the Bit and Frame Rate

                      The high level steps to query and set the bit and frame rate:

                      • CVideoPlayerUtility::VideoBitRateL(): This function returns the bit rate of the video clip. This returns the video clip's bit rate in bits per second.

                        TInt CPlayVideo::VideoBitRateL() + { + return iVideoUtility->VideoBitRateL(); + }

                      • CVideoPlayerUtility::VideoFrameRateL(): This function returns the video frame rate. This returns the video frame rate in frames per second.

                        TReal32 CPlayVideo::VideoFrameRateL() + { + return iVideoUtility->VideoFrameRateL(); + }

                      • CVideoPlayerUtility::SetVideoFrameRateL(): This function is used to set the number of video frames to be displayed per second.

                        void CPlayVideo::SetVideoFrameRateL(TReal32 aFramesPerSecond) + { + iVideoUtility->SetVideoFrameRateL(aFramesPerSecond); + }

                      Note: The presence of an audio track within a video clip can be determined using AudioEnabledL().

                      Querying and Setting the Current Playback Position

                      The current playback position can be queried and set using the following functions:

                      • CVideoPlayerUtility::PositionL(): This function returns the current playback position. It returns the current position from the start of the clip in microseconds.

                      • CVideoPlayerUtility::SetPositionL(): This function sets the position for the playback within the video clip to start.

                        TTimeIntervalMicroSeconds pos; +TTimeIntervalMicroSeconds CPlayVideo::PositionL() \\ retrieves the current playback position within the video clip + { + return iVideoUtility->PositionL(); + }

                      Querying and Setting the MIME and Codec Type

                      This section explains the functions that reports and sets the MIME type and codecs for video and audio data that is already open. The functions are as stated below:

                      • CVideoPlayerUtility::VideoFormatMimeType(): This returns the current MIME type of the video clip currently open.

                        const TDesC8 & CPlayVideo::VideoFormatMimeType() + { + return iVideoUtility->VideoFormatMimeType(); + }

                      • The datatype of the audio track used by the video clip can be retrieved using and AudioTypeL().

                        TFourCC CPlayVideo::AudioTypeL() \\retrieves the codecs used by audio track + { + return iVideoUtility->AudioTypeL(); }
                      See Also

                      Creating and Preparing a Video Player

                      Enabling/Disabling Audio or Video Playback Separately

                      Scaling Automatically

                      Controlling Video Playback

                      Fast Forwarding and Rewinding

                      Stepping Frames

                      Controlling the Video Controller Plugin

                      \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F99938E9-9E06-53C0-B762-2CE51BC5F1E2_d0e427411_href.png Binary file Symbian3/SDK/Source/GUID-F99938E9-9E06-53C0-B762-2CE51BC5F1E2_d0e427411_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F99938E9-9E06-53C0-B762-2CE51BC5F1E2_d0e427573_href.png Binary file Symbian3/SDK/Source/GUID-F99938E9-9E06-53C0-B762-2CE51BC5F1E2_d0e427573_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-F9C12192-EDA8-4220-87DF-E7F1EA50CDEF.dita --- a/Symbian3/SDK/Source/GUID-F9C12192-EDA8-4220-87DF-E7F1EA50CDEF.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-F9C12192-EDA8-4220-87DF-E7F1EA50CDEF.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,662 +1,662 @@ - - - - - -List -item types -

                      The appearance of list items can be chosen from the following types. The -examples are from lists displayed in the main pane; for most item types a -similar component for use in pop-up windows is possible.

                      -List item types - - - -Item -Description - - - - -

                      Single-line item

                       -

                      ABC

                       -

                      Main text

                      -

                      Primary font

                       -                       - -

                      [list_single_pane]

                       -

                      D

                       -

                      Item status graphics

                      -

                      Single color

                       -                       - - -
                        -

                      • Menu lists

                        • -

                      • Selection lists

                        • -

                      • Markable lists

                        • -

                      Note: Item status graphics in column D may be empty; they indicate -e.g. temporary item states.

                       -                       - -

                      Single-line item with a number

                       -

                      A

                       -

                      Ordinal number

                       -

                      Primary font small

                       -                       - -

                      [list_single_number_pane]

                       -

                      BC

                       -

                      Main text

                       -

                      Primary font

                       -                       - - -

                      D

                       -

                      Item status graphics

                       -

                      Single color

                       -                       - - -
                        -

                      • Menu lists

                        • -

                      • Selection lists

                        • -

                      • Markable lists

                        • -

                      Note: Numbered lists should only be used when numbering offers some -added value.

                       -                       - -

                      Single-line item with a graphic

                       -

                      A

                       -

                      Item property graphic

                       -

                      Color

                       -                       - -

                      [list_single_graphic_pane]

                       -

                      BC

                       -

                      Main text

                      -

                      Primary font

                       -                       - - -

                      D

                       -

                      Item status graphics

                       -

                      Single color

                       -                       - - -
                        -

                      • Menu lists

                        • -

                      • Selection lists

                        • -

                      • Multi-selection lists

                        • -

                      • Markable lists

                        • -
                       -                       - -

                      Single-line item with a heading

                       -

                      AB

                       -

                      Heading

                      -

                      Secondary font

                       -                       - -

                      [list_single_heading_pane]

                       -

                      C

                       -

                      Main text

                      -

                      Primary font

                       -                       - - -

                      D

                       -

                      Item status graphics

                      -

                      Single color

                       -                       - - -
                        -

                      • Menu lists

                        • -

                      • Selection lists

                        • -

                      • Markable lists

                        • -
                       -                       - -

                      Single-line item with a number and a heading

                       -

                      A

                       -

                      Ordinal number

                       -

                      Secondary font

                       -                       - -

                      [list_single_number_heading_pane]

                       -

                      B

                       -

                      Heading

                       -

                      Secondary font

                       -                       - - -

                      C

                       -

                      Main text

                       -

                      Primary font

                       -                       - - -

                      D

                       -

                      Item status graphics

                       -

                      Single color

                       -                       - - -
                        -

                      • Menu lists

                        • -

                      • Selection lists

                        • -

                      • Markable lists

                        • -
                       -                       - -

                      Single-line item with a graphic and a heading

                       -

                      A

                       -

                      Item property graphic

                       -

                      Color

                       -                       - -

                      [list_single_graphic_heading_pane]

                       -

                      B

                       -

                      Heading

                       -

                      Secondary font

                       -                       - - -

                      C

                       -

                      Main text

                       -

                      Primary font

                       -                       - - -

                      D

                       -

                      Item status graphics

                       -

                      Single color

                       -                       - - -
                        -

                      • Menu lists

                        • -

                      • Selection lists

                        • -

                      • Multi-selection lists

                        • -

                      • Markable lists

                        • -
                       -                       - -

                      Single-line item with a large graphic

                       -

                      AB

                       -

                      Large graphic

                       -

                      Color

                       -                       - -

                      [list_single_large_graphic_pane]

                       -

                      C

                       -

                      Main text

                       -

                      Primary font

                       -                       - - -

                      D

                       -

                      Item status graphics

                       -

                      Single color

                       -                       - - -
                        -

                      • Menu lists

                        • -

                      • Selection lists

                        • -

                      • Markable lists

                        • -

                      Note: A large graphic may be e.g. an image or indicate item property.

                       -                       - -

                      Two-line item

                       -

                      ABC (line 1)

                       -

                      Main text

                      -

                      Primary font

                       -                       - -

                      [list_double_pane]

                       -

                      ABC (line 2)

                       -

                      Additional text

                       -

                      Secondary font

                       -                       - - -

                      D (line1)

                       -

                      Item status graphics

                       -

                      Single color

                       -                       - - -
                        -

                      • Menu lists

                        • -

                      • Selection lists

                        • -

                      • Markable lists

                        • -

                      Note: The second line may be empty.

                      -                       - -

                      Two-line item with a number

                       -

                      A

                       -

                      Ordinal number

                       -

                      Primary font small

                       -                       - -

                      [list_double_number_pane]

                       -

                      BC (line 1)

                       -

                      Main text

                       -

                      Primary font

                       -                       - - -

                      BC (line 2)

                       -

                      Additional text

                      -

                      Secondary font

                       -                       - - -

                      D (line1)

                      -

                      Item status graphics

                       -

                      Single color

                       -                       - - -
                        -

                      • Menu lists

                        • -

                      • Selection lists

                        • -

                      • Markable lists

                        • -
                       -                       - -

                      Two-line item with a graphic

                       -

                      A

                       -

                      Item property graphic

                       -

                      Color

                       -                       - -

                      [list_double_graphic_pane]

                       -

                      BC (line 1)

                       -

                      Main text

                       -

                      Primary font

                       -                       - - -

                      BC (line 2)

                       -

                      Additional text

                      -

                      Secondary font

                       -                       - - -

                      D

                       -

                      Item status graphics

                       -

                      Single color

                       -                       - - -
                        -

                      • Menu lists

                        • -

                      • Selection lists

                        • -

                      • Markable lists

                        • -
                       -                       - -

                      Two-line item with a heading

                       -

                      ABC (line1)

                       -

                      Heading

                       -

                      Secondary font

                       -                       - -

                      [list_double_heading_pane]

                       -

                      ABC (line 2)

                       -

                      Main text

                       -

                      Primary font

                       -                       - - -

                      D (line 1)

                       -

                      Item status graphics

                       -

                      Single color

                       -                       - - -
                        -

                      • Menu lists

                        • -

                      • Selection lists

                        • -

                      • Markable lists

                        • -
                       -                       - -

                      Two-line item with a large graphic

                       -

                      AB

                       -

                      Large graphic

                       -

                      Color

                       -                       - -

                      [list_double_large_graphic_pane]

                       -

                      C (line 1)

                       -

                      Main text

                      -

                      Primary font

                       -                       - - -

                      C (line 2)

                       -

                      Additional text

                       -

                      Secondary font

                       -                       - - -

                      D (line 1)

                       -

                      Item status graphics

                       - -                       - - -
                        -

                      • Menu lists

                        • -

                      • Selection lists

                        • -

                      • Markable lists

                        • -
                       -                       - -

                      Two-line item with a graphic and a heading

                       -

                      A

                       -

                      Item property graphic

                       -

                      Color

                       -                       - -

                      [list_double_graphic_heading_pane]

                       -

                      BC (line 1)

                       -

                      Heading

                       -

                      Secondary font

                       -                       - - -

                      BC (line 2)

                       -

                      Main text

                       -

                      Primary font

                       -                       - - -

                      D (line 1)

                       -

                      Two additional graphics possible

                       -

                      Single color

                       -                       - - -
                        -

                      • Menu lists

                        • -

                      • Selection lists

                        • -

                      • Markable lists

                        • -
                       -                       - -

                      Two-line item with time

                       -

                      AB

                       -

                      Time

                       -

                      Digital font

                       -                       - -

                      [list_double_time_pane]

                       -

                      C (line 1)

                       -

                      Main text

                       -

                      Primary font

                       -                       - - -

                      C (line 2)

                       -

                      Additional text

                       -

                      Secondary font

                       -                       - - -

                      D (line 1)

                       -

                      Item status graphics

                       -

                      Single color

                       -                       - - -

                      Clock alarm lists

                       -                       - -

                      Two-line item, style 2

                       -

                      ABC (line 1)

                       -

                      Main text

                       -

                      Primary font

                       -                       - -

                      [list_double2_pane]

                       -

                      ABC (line 2)

                       -

                      Main text continues

                       -

                      Primary font

                       -                       - - -

                      D (line1)

                      -

                      Item status graphics

                       -

                      Single color

                       -                       - - -
                        -

                      • Menu lists

                        • -

                      • Selection lists

                        • -

                      • Markable lists

                        • -

                      Note: One text item that can extend to a second line.

                       -                       - -

                      Two-line item with a graphic, style 2

                       -

                      A

                       -

                      Item property graphic

                       -

                      Color

                       -                       - -

                      [list_double2_graphic_pane]

                       -

                      BC (line 1)

                       -

                      Main text

                      -

                      Primary font

                       -                       - - -

                      BC (line 2)

                       -

                      Main text (continued)

                       -

                      Primary font

                       -                       - - -

                      D

                       -

                      Item status graphics

                       -

                      Single color

                       -                       - - -
                        -

                      • Menu lists

                        • -

                      • Selection lists

                        • -

                      • Markable lists

                        • -
                       -                       - -

                      Two-line item with a large graphic, style 2

                       -

                      AB

                       -

                      Large graphic

                       -

                      Color

                       -                       - -

                      [list_double2_large_graphic_pane]

                       -

                      C (line 1)

                       -

                      Main text

                       -

                      Primary font

                       -                       - - -

                      C (line 2)

                       -

                      Main text (continued)

                       -

                      Primary font

                       -                       - - -

                      D

                       -

                      Item status graphics

                       -

                      Single color

                       -                       - - -
                        -

                      • Menu lists

                        • -

                      • Selection lists

                        • -

                      • Markable lists

                        • -
                       -                       - -

                      Settings item

                       -

                      ABC (line 1)

                       -

                      Setting item text

                      -

                      Primary font

                       -                       - -

                      [list_setting_pane]

                       -

                      ABC (line 2)

                       -

                      Value item status

                       -

                      Primary font small

                       -                       - - -

                      D (line1)

                       -

                      Item status graphics

                       -

                      Single color

                       -                       - - -

                      Setting lists

                      Note: The value -item may be omitted in order to create a regular selection item within a setting -list.

                       -                       - -

                      Setting item with a number

                       -

                      A

                       -

                      Ordinal number

                       -

                      Primary font small

                       -                       - -

                      [list_setting_number_pane]

                       -

                      BC (line 1)

                       -

                      Setting item text

                      -

                      Primary font

                       -                       - - -

                      BC (line 2)

                       -

                      Value item status

                       -

                      Primary font small

                       -                       - - -

                      D (line1)

                      -

                      Item status graphics

                       -

                      Single color

                       -                       - - -

                      Setting lists

                      Note: The value -item may be omitted in order to create a regular selection item within a setting -list.

                       -                       - -

                      Single-line item with two graphics

                       -

                      A

                       -

                      Item selection graphic

                       -

                      Single color

                       -                       - -

                      [list_single_2graphic_pane]

                       -

                      B

                       -

                      Item property graphic

                       -

                      Color

                       -                       - - -

                      C

                       -

                      Main text

                       -

                      Primary font

                       -                       - - -

                      D

                       -

                      Item status graphics

                       -

                      Single color

                       -                       - - -
                        -

                      • Menu lists

                        • -

                      • Selection lists

                        • -

                      • Multi-selection lists

                        • -

                      • Markable lists

                        • -
                       -                       - -

                      Two-line item with a graphic and a large graphic, style 2

                       -

                      A

                       -

                      Item selection graphic

                       -

                      Single color

                       -                       - -

                      [list_double_graphic_large_graphic_pane]

                       -

                      B

                       -

                      Large graphic

                       -

                      Color

                       -                       - - -

                      C

                       -

                      Main text

                       -

                      Primary font

                       -                       - - -

                      D

                       -

                      Item status graphics

                       -

                      Single color

                       -                       - - -
                        -

                      • Menu lists

                        • -

                      • Selection lists

                        • -

                      • Multi-selection lists

                        • -

                      • Markable lists

                        • -
                       -                       - - -
                      -

                      There is a corresponding pop-up window list item for the following components:

                      -
                        -

                      • single-line item

                        • -

                      • single-line item with a number

                        • -

                      • single-line item with a graphic

                        • -

                      • single-line item with a heading

                        • -

                      • single-line item with a number and a heading

                        • -

                      • single-line item with a graphic and a heading

                        • -

                      • single-line item with a large graphic

                        • -

                      • single-line item with two graphics

                        • -

                      • two-line item

                        • -

                      • two-line item with a number

                        • -

                      • two-line item with a graphic

                        • -

                      • two-line item with a heading

                        • -

                      • two-line item with a large graphic

                        • -

                      • two-line item, style 2

                        • -

                      • two-line item with a graphic, style 2

                        • -

                      • two line item with a large graphic, style 2

                        • -
                      -
                      Using -list item types in C++ applications

                      For the C++ classes used for -the different list item types, see List box item layouts in the Lists -API documentation.

                      + + + + + +List +item types +

                      The appearance of list items can be chosen from the following types. The +examples are from lists displayed in the main pane; for most item types a +similar component for use in pop-up windows is possible.

                      +List item types + + + +Item +Description + + + + +

                      Single-line item

                       +

                      ABC

                       +

                      Main text

                      +

                      Primary font

                       +                       + +

                      [list_single_pane]

                       +

                      D

                       +

                      Item status graphics

                      +

                      Single color

                       +                       + + +
                        +

                      • Menu lists

                        • +

                      • Selection lists

                        • +

                      • Markable lists

                        • +

                      Note: Item status graphics in column D may be empty; they indicate, +for example, temporary item states.

                       +                       + +

                      Single-line item with a number

                       +

                      A

                       +

                      Ordinal number

                       +

                      Primary font small

                       +                       + +

                      [list_single_number_pane]

                       +

                      BC

                       +

                      Main text

                       +

                      Primary font

                       +                       + + +

                      D

                       +

                      Item status graphics

                       +

                      Single color

                       +                       + + +
                        +

                      • Menu lists

                        • +

                      • Selection lists

                        • +

                      • Markable lists

                        • +

                      Note: Numbered lists should only be used when numbering offers some +added value.

                       +                       + +

                      Single-line item with a graphic

                       +

                      A

                       +

                      Item property graphic

                       +

                      Color

                       +                       + +

                      [list_single_graphic_pane]

                       +

                      BC

                       +

                      Main text

                      +

                      Primary font

                       +                       + + +

                      D

                       +

                      Item status graphics

                       +

                      Single color

                       +                       + + +
                        +

                      • Menu lists

                        • +

                      • Selection lists

                        • +

                      • Multi-selection lists

                        • +

                      • Markable lists

                        • +
                       +                       + +

                      Single-line item with a heading

                       +

                      AB

                       +

                      Heading

                      +

                      Secondary font

                       +                       + +

                      [list_single_heading_pane]

                       +

                      C

                       +

                      Main text

                      +

                      Primary font

                       +                       + + +

                      D

                       +

                      Item status graphics

                      +

                      Single color

                       +                       + + +
                        +

                      • Menu lists

                        • +

                      • Selection lists

                        • +

                      • Markable lists

                        • +
                       +                       + +

                      Single-line item with a number and a heading

                       +

                      A

                       +

                      Ordinal number

                       +

                      Secondary font

                       +                       + +

                      [list_single_number_heading_pane]

                       +

                      B

                       +

                      Heading

                       +

                      Secondary font

                       +                       + + +

                      C

                       +

                      Main text

                       +

                      Primary font

                       +                       + + +

                      D

                       +

                      Item status graphics

                       +

                      Single color

                       +                       + + +
                        +

                      • Menu lists

                        • +

                      • Selection lists

                        • +

                      • Markable lists

                        • +
                       +                       + +

                      Single-line item with a graphic and a heading

                       +

                      A

                       +

                      Item property graphic

                       +

                      Color

                       +                       + +

                      [list_single_graphic_heading_pane]

                       +

                      B

                       +

                      Heading

                       +

                      Secondary font

                       +                       + + +

                      C

                       +

                      Main text

                       +

                      Primary font

                       +                       + + +

                      D

                       +

                      Item status graphics

                       +

                      Single color

                       +                       + + +
                        +

                      • Menu lists

                        • +

                      • Selection lists

                        • +

                      • Multi-selection lists

                        • +

                      • Markable lists

                        • +
                       +                       + +

                      Single-line item with a large graphic

                       +

                      AB

                       +

                      Large graphic

                       +

                      Color

                       +                       + +

                      [list_single_large_graphic_pane]

                       +

                      C

                       +

                      Main text

                       +

                      Primary font

                       +                       + + +

                      D

                       +

                      Item status graphics

                       +

                      Single color

                       +                       + + +
                        +

                      • Menu lists

                        • +

                      • Selection lists

                        • +

                      • Markable lists

                        • +

                      Note: A large graphic may be , for example, an image or indicate item +property.

                       +                       + +

                      Two-line item

                       +

                      ABC (line 1)

                       +

                      Main text

                      +

                      Primary font

                       +                       + +

                      [list_double_pane]

                       +

                      ABC (line 2)

                       +

                      Additional text

                       +

                      Secondary font

                       +                       + + +

                      D (line1)

                       +

                      Item status graphics

                       +

                      Single color

                       +                       + + +
                        +

                      • Menu lists

                        • +

                      • Selection lists

                        • +

                      • Markable lists

                        • +

                      Note: The second line may be empty.

                      +                       + +

                      Two-line item with a number

                       +

                      A

                       +

                      Ordinal number

                       +

                      Primary font small

                       +                       + +

                      [list_double_number_pane]

                       +

                      BC (line 1)

                       +

                      Main text

                       +

                      Primary font

                       +                       + + +

                      BC (line 2)

                       +

                      Additional text

                      +

                      Secondary font

                       +                       + + +

                      D (line1)

                      +

                      Item status graphics

                       +

                      Single color

                       +                       + + +
                        +

                      • Menu lists

                        • +

                      • Selection lists

                        • +

                      • Markable lists

                        • +
                       +                       + +

                      Two-line item with a graphic

                       +

                      A

                       +

                      Item property graphic

                       +

                      Color

                       +                       + +

                      [list_double_graphic_pane]

                       +

                      BC (line 1)

                       +

                      Main text

                       +

                      Primary font

                       +                       + + +

                      BC (line 2)

                       +

                      Additional text

                      +

                      Secondary font

                       +                       + + +

                      D

                       +

                      Item status graphics

                       +

                      Single color

                       +                       + + +
                        +

                      • Menu lists

                        • +

                      • Selection lists

                        • +

                      • Markable lists

                        • +
                       +                       + +

                      Two-line item with a heading

                       +

                      ABC (line1)

                       +

                      Heading

                       +

                      Secondary font

                       +                       + +

                      [list_double_heading_pane]

                       +

                      ABC (line 2)

                       +

                      Main text

                       +

                      Primary font

                       +                       + + +

                      D (line 1)

                       +

                      Item status graphics

                       +

                      Single color

                       +                       + + +
                        +

                      • Menu lists

                        • +

                      • Selection lists

                        • +

                      • Markable lists

                        • +
                       +                       + +

                      Two-line item with a large graphic

                       +

                      AB

                       +

                      Large graphic

                       +

                      Color

                       +                       + +

                      [list_double_large_graphic_pane]

                       +

                      C (line 1)

                       +

                      Main text

                      +

                      Primary font

                       +                       + + +

                      C (line 2)

                       +

                      Additional text

                       +

                      Secondary font

                       +                       + + +

                      D (line 1)

                       +

                      Item status graphics

                       + +                       + + +
                        +

                      • Menu lists

                        • +

                      • Selection lists

                        • +

                      • Markable lists

                        • +
                       +                       + +

                      Two-line item with a graphic and a heading

                       +

                      A

                       +

                      Item property graphic

                       +

                      Color

                       +                       + +

                      [list_double_graphic_heading_pane]

                       +

                      BC (line 1)

                       +

                      Heading

                       +

                      Secondary font

                       +                       + + +

                      BC (line 2)

                       +

                      Main text

                       +

                      Primary font

                       +                       + + +

                      D (line 1)

                       +

                      Two additional graphics possible

                       +

                      Single color

                       +                       + + +
                        +

                      • Menu lists

                        • +

                      • Selection lists

                        • +

                      • Markable lists

                        • +
                       +                       + +

                      Two-line item with time

                       +

                      AB

                       +

                      Time

                       +

                      Digital font

                       +                       + +

                      [list_double_time_pane]

                       +

                      C (line 1)

                       +

                      Main text

                       +

                      Primary font

                       +                       + + +

                      C (line 2)

                       +

                      Additional text

                       +

                      Secondary font

                       +                       + + +

                      D (line 1)

                       +

                      Item status graphics

                       +

                      Single color

                       +                       + + +

                      Clock alarm lists

                       +                       + +

                      Two-line item, style 2

                       +

                      ABC (line 1)

                       +

                      Main text

                       +

                      Primary font

                       +                       + +

                      [list_double2_pane]

                       +

                      ABC (line 2)

                       +

                      Main text continues

                       +

                      Primary font

                       +                       + + +

                      D (line1)

                      +

                      Item status graphics

                       +

                      Single color

                       +                       + + +
                        +

                      • Menu lists

                        • +

                      • Selection lists

                        • +

                      • Markable lists

                        • +

                      Note: One text item that can extend to a second line.

                       +                       + +

                      Two-line item with a graphic, style 2

                       +

                      A

                       +

                      Item property graphic

                       +

                      Color

                       +                       + +

                      [list_double2_graphic_pane]

                       +

                      BC (line 1)

                       +

                      Main text

                      +

                      Primary font

                       +                       + + +

                      BC (line 2)

                       +

                      Main text (continued)

                       +

                      Primary font

                       +                       + + +

                      D

                       +

                      Item status graphics

                       +

                      Single color

                       +                       + + +
                        +

                      • Menu lists

                        • +

                      • Selection lists

                        • +

                      • Markable lists

                        • +
                       +                       + +

                      Two-line item with a large graphic, style 2

                       +

                      AB

                       +

                      Large graphic

                       +

                      Color

                       +                       + +

                      [list_double2_large_graphic_pane]

                       +

                      C (line 1)

                       +

                      Main text

                       +

                      Primary font

                       +                       + + +

                      C (line 2)

                       +

                      Main text (continued)

                       +

                      Primary font

                       +                       + + +

                      D

                       +

                      Item status graphics

                       +

                      Single color

                       +                       + + +
                        +

                      • Menu lists

                        • +

                      • Selection lists

                        • +

                      • Markable lists

                        • +
                       +                       + +

                      Settings item

                       +

                      ABC (line 1)

                       +

                      Setting item text

                      +

                      Primary font

                       +                       + +

                      [list_setting_pane]

                       +

                      ABC (line 2)

                       +

                      Value item status

                       +

                      Primary font small

                       +                       + + +

                      D (line1)

                       +

                      Item status graphics

                       +

                      Single color

                       +                       + + +

                      Setting lists

                      Note: The value +item may be omitted in order to create a regular selection item within a setting +list.

                       +                       + +

                      Setting item with a number

                       +

                      A

                       +

                      Ordinal number

                       +

                      Primary font small

                       +                       + +

                      [list_setting_number_pane]

                       +

                      BC (line 1)

                       +

                      Setting item text

                      +

                      Primary font

                       +                       + + +

                      BC (line 2)

                       +

                      Value item status

                       +

                      Primary font small

                       +                       + + +

                      D (line1)

                      +

                      Item status graphics

                       +

                      Single color

                       +                       + + +

                      Setting lists

                      Note: The value +item may be omitted in order to create a regular selection item within a setting +list.

                       +                       + +

                      Single-line item with two graphics

                       +

                      A

                       +

                      Item selection graphic

                       +

                      Single color

                       +                       + +

                      [list_single_2graphic_pane]

                       +

                      B

                       +

                      Item property graphic

                       +

                      Color

                       +                       + + +

                      C

                       +

                      Main text

                       +

                      Primary font

                       +                       + + +

                      D

                       +

                      Item status graphics

                       +

                      Single color

                       +                       + + +
                        +

                      • Menu lists

                        • +

                      • Selection lists

                        • +

                      • Multi-selection lists

                        • +

                      • Markable lists

                        • +
                       +                       + +

                      Two-line item with a graphic and a large graphic, style 2

                       +

                      A

                       +

                      Item selection graphic

                       +

                      Single color

                       +                       + +

                      [list_double_graphic_large_graphic_pane]

                       +

                      B

                       +

                      Large graphic

                       +

                      Color

                       +                       + + +

                      C

                       +

                      Main text

                       +

                      Primary font

                       +                       + + +

                      D

                       +

                      Item status graphics

                       +

                      Single color

                       +                       + + +
                        +

                      • Menu lists

                        • +

                      • Selection lists

                        • +

                      • Multi-selection lists

                        • +

                      • Markable lists

                        • +
                       +                       + + +
                      +

                      There is a corresponding pop-up window list item for the following components:

                      +
                        +

                      • single-line item

                        • +

                      • single-line item with a number

                        • +

                      • single-line item with a graphic

                        • +

                      • single-line item with a heading

                        • +

                      • single-line item with a number and a heading

                        • +

                      • single-line item with a graphic and a heading

                        • +

                      • single-line item with a large graphic

                        • +

                      • single-line item with two graphics

                        • +

                      • two-line item

                        • +

                      • two-line item with a number

                        • +

                      • two-line item with a graphic

                        • +

                      • two-line item with a heading

                        • +

                      • two-line item with a large graphic

                        • +

                      • two-line item, style 2

                        • +

                      • two-line item with a graphic, style 2

                        • +

                      • two line item with a large graphic, style 2

                        • +
                      +
                      Using +list item types in applications

                      For the C++ classes used for the +different list item types, see List box item layouts in the Lists API documentation.

                       \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FA12B3F7-4E84-5BBD-8598-9A974FFA7FCC.dita --- a/Symbian3/SDK/Source/GUID-FA12B3F7-4E84-5BBD-8598-9A974FFA7FCC.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-FA12B3F7-4E84-5BBD-8598-9A974FFA7FCC.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,51 +1,51 @@ - - - - - -What -is Root Server Configurator? -

                      Root Server Configurator is the starter program for the C32exe process. -Root Server Configurator is started during device startup and then Root Server -Configurator starts all the other servers used for device communication.

                      -

                      Examples of these servers are the Sockets -Server, the Telephony -Server and the Serial -Communications Server.

                      -

                      The Root Server Configurator is a separate process to the Root Server.

                      -

                      To start the Root Server Configurator, a process must start either the c32start.exe program, -or must call the StartC32() function. In the Techview reference -version of Symbian platform, the steps in the startup up of the -communications servers are:

                      -
                        -

                      1. System -Starter calls c32start.exe to start the Root Server -Configurator.

                        2. -

                      2. The Root Server Configurator -loads the CMI files

                        3. -

                      3. The Root Server Configurator -calls RProcess::Create() to start the C32exe process. This -starts the Root Server.

                        The Root Server Configurator makes requests -to Root Server for Root Server to load all the Comms Provider Modules.

                        4. -
                      -

                      After step 3, the device communications servers are all loaded and ready -for use by applications.

                      -

                      Figure 1 shows these three steps and how the Root Server and Root Server -Configurator relate:

                      - - Figure 1 - How Root Server and Root Server relate, and the -steps involved during startup - - -

                      Root Server Configurator is configured by two types of files: CMI -files, and the c32start.ini file.

                      -

                      Root Server Configurator does not provide a published API to its server. -Root Server Configurator is the only application which uses the Root Server -API.

                      + + + + + +What +is Root Server Configurator? +

                      Root Server Configurator is the starter program for the C32exe process. +Root Server Configurator is started during device startup and then Root Server +Configurator starts all the other servers used for device communication.

                      +

                      Examples of these servers are the Sockets +Server, the Telephony +Server and the Serial +Communications Server.

                      +

                      The Root Server Configurator is a separate process to the Root Server.

                      +

                      To start the Root Server Configurator, a process must start either the c32start.exe program, +or must call the StartC32() function. In the Techview reference +version of Symbian platform, the steps in the startup up of the +communications servers are:

                      +
                        +

                      1. System +Starter calls c32start.exe to start the Root Server +Configurator.

                        2. +

                      2. The Root Server Configurator +loads the CMI files

                        3. +

                      3. The Root Server Configurator +calls RProcess::Create() to start the C32exe process. This +starts the Root Server.

                        The Root Server Configurator makes requests +to Root Server for Root Server to load all the Comms Provider Modules.

                        4. +
                      +

                      After step 3, the device communications servers are all loaded and ready +for use by applications.

                      +

                      Figure 1 shows these three steps and how the Root Server and Root Server +Configurator relate:

                      + + Figure 1 - How Root Server and Root Server relate, and the +steps involved during startup + + +

                      Root Server Configurator is configured by two types of files: CMI +files, and the c32start.ini file.

                      +

                      Root Server Configurator does not provide a published API to its server. +Root Server Configurator is the only application which uses the Root Server +API.

                      \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FAB548CF-24EB-52D1-A7A1-9446BA67C7A5.dita --- a/Symbian3/SDK/Source/GUID-FAB548CF-24EB-52D1-A7A1-9446BA67C7A5.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,13 +0,0 @@ - - - - - -Camera Preset Support

                      This document describes about the preset support provided as part of Ecam component.

                      Providing Improved Camera Preset Support

                      The following steps allows the clients to receive notification about possible changes in supported values and ranges, when camera operates in a particular preset mode.

                      1. Create a new UID KUidECamEventRangeRestricted to notify the clients about the possible range restrictions, when camera operates in a particular preset mode.

                      2. Use TECAMEvent class to report this event to the client.

                      3. Client gets the list of UIDs for which range has been restricted using CCamera::CCameraPresets::GetFeatureRestrictedSettingsL method.

                      4. Notify the client about the restricted features using the UID KUidECamEventFeatureRestricted invoked by ECAM implementation, when camera works in a specific preset mode.

                      5. Client retrieves the list of uids representing the settings which do not support few feature values using GetFeatureRestrictedSettingsL method. An array of TUid aFeatureRestrictedSettings, retrieves the settings for which the current preset has imposed feature value restrictions. If no restrictions have been imposed, an empty array will be returned.

                      6. Clients can retrieve information if the preset unlock feature is supported using CCamera::CCameraPresets::IsPresetUnlockSupportedL method.

                        Unlocking preset settings of the camera that worked in a particular preset mode earlier, helps to make changes to the settings subsequently. This can be done as follows:

                        • ECAM implementation uses appropriate settings in the camera, to meet the specific preset requirements requested by the client, and the camera with the specific preset is in locked state.

                          By default, the client cannot customise this preset value, without unlocking the preset.

                        • Unlock the preset using CCamera::CCameraPresets::UnlockPresetL(), to change the settings.

                        • Make sure to lock the preset using CCamera::CCameraPresets::LockPresetL(), when the changes are made. This prevents further changes in settings.

                        • Whenever client customizes the camera settings after putting the camera in a particular preset, the ECam implementation realises that the preset to be KUidECamPresetNone instead of the preset previously set by the client. So CCamera::CCameraPresets::Preset() will always retrieve KUidECamPresetNone, when client customises the actual preset settings.

                      Accessing and Power Control of - Camera Capturing Image Capturing Video                       \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FAC309FE-B7DA-572B-9165-BC9BEF944D83_d0e334695_href.png Binary file Symbian3/SDK/Source/GUID-FAC309FE-B7DA-572B-9165-BC9BEF944D83_d0e334695_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FAC309FE-B7DA-572B-9165-BC9BEF944D83_d0e340852_href.png Binary file Symbian3/SDK/Source/GUID-FAC309FE-B7DA-572B-9165-BC9BEF944D83_d0e340852_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FB12481D-B3F6-5901-A0DC-DF92BCED3B18_d0e169039_href.jpg Binary file Symbian3/SDK/Source/GUID-FB12481D-B3F6-5901-A0DC-DF92BCED3B18_d0e169039_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FB12481D-B3F6-5901-A0DC-DF92BCED3B18_d0e175640_href.jpg Binary file Symbian3/SDK/Source/GUID-FB12481D-B3F6-5901-A0DC-DF92BCED3B18_d0e175640_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FB45BC8B-FE99-5616-9270-132C4174DAE7-master.png Binary file Symbian3/SDK/Source/GUID-FB45BC8B-FE99-5616-9270-132C4174DAE7-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FB45BC8B-FE99-5616-9270-132C4174DAE7_d0e383750_href.png Binary file Symbian3/SDK/Source/GUID-FB45BC8B-FE99-5616-9270-132C4174DAE7_d0e383750_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FB479891-8788-5548-B875-A5C637EC2DE6_d0e177098_href.png Binary file Symbian3/SDK/Source/GUID-FB479891-8788-5548-B875-A5C637EC2DE6_d0e177098_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FB479891-8788-5548-B875-A5C637EC2DE6_d0e183692_href.png Binary file Symbian3/SDK/Source/GUID-FB479891-8788-5548-B875-A5C637EC2DE6_d0e183692_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FB654184-C256-546F-AF6C-E0FADA78D5D0_d0e214615_href.png Binary file Symbian3/SDK/Source/GUID-FB654184-C256-546F-AF6C-E0FADA78D5D0_d0e214615_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FB654184-C256-546F-AF6C-E0FADA78D5D0_d0e218352_href.png Binary file Symbian3/SDK/Source/GUID-FB654184-C256-546F-AF6C-E0FADA78D5D0_d0e218352_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FBB9ED48-3C0F-4B2D-90FC-52127698F253.dita --- a/Symbian3/SDK/Source/GUID-FBB9ED48-3C0F-4B2D-90FC-52127698F253.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-FBB9ED48-3C0F-4B2D-90FC-52127698F253.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,30 +1,30 @@ - - - - - -IPv4/IPv6 -dual-stack -

                      The IP protocol is responsible for routing the data between networks -and it employs an addressing system to achieve this. The Internet protocol -version 4 (IPv4) has a number of security problems and lacks privacy and authentication -mechanisms below the application layer. IPv6 provided numerous security enhancements, -such as mandatory implementation of Authentication Header and Encapsulated -Security Payload.

                      -

                      IPv4/IPv6 dual-stack enables applications to choose the protocol -to use or automatically select it according to address type. This feature -is supported from Symbian OS v7.0s onwards.

                      -IPv4/IPv6 dual-protocol stack -

                      It is possible to establish a secure connection from application to -application and also from router to router. Security features implemented -in low-level protocols (like IPv6) are automatically available to higher-level -protocols and applications.

                      -

                      For more information, see Networking -Services Guide.

                      + + + + + +IPv4/IPv6 +dual-stack +

                      The IP protocol is responsible for routing the data between networks +and it employs an addressing system to achieve this. The Internet protocol +version 4 (IPv4) has a number of security problems and lacks privacy and authentication +mechanisms below the application layer. IPv6 provided numerous security enhancements, +such as mandatory implementation of Authentication Header and Encapsulated +Security Payload.

                      +

                      IPv4/IPv6 dual-stack enables applications to choose the protocol +to use or automatically select it according to address type. This feature +is supported from Symbian OS v7.0s onwards.

                      +IPv4/IPv6 dual-protocol stack +

                      It is possible to establish a secure connection from application to +application and also from router to router. Security features implemented +in low-level protocols (like IPv6) are automatically available to higher-level +protocols and applications.

                      +

                      For more information, see Networking +Services Guide.

                       \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FBBC7F0D-FD4B-58B7-BEAC-B68EEBD19ACF_d0e76136_href.png Binary file Symbian3/SDK/Source/GUID-FBBC7F0D-FD4B-58B7-BEAC-B68EEBD19ACF_d0e76136_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FBBC7F0D-FD4B-58B7-BEAC-B68EEBD19ACF_d0e82848_href.png Binary file Symbian3/SDK/Source/GUID-FBBC7F0D-FD4B-58B7-BEAC-B68EEBD19ACF_d0e82848_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FBC9FA67-847F-599B-B244-3E9B72D40505_d0e323758_href.jpg Binary file Symbian3/SDK/Source/GUID-FBC9FA67-847F-599B-B244-3E9B72D40505_d0e323758_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FBC9FA67-847F-599B-B244-3E9B72D40505_d0e329915_href.jpg Binary file Symbian3/SDK/Source/GUID-FBC9FA67-847F-599B-B244-3E9B72D40505_d0e329915_href.jpg has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FBCBF8A0-7922-5881-A1C5-5DB41630E75A.dita --- a/Symbian3/SDK/Source/GUID-FBCBF8A0-7922-5881-A1C5-5DB41630E75A.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-FBCBF8A0-7922-5881-A1C5-5DB41630E75A.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,15 +1,17 @@ - - - - - -Persistent Data Services -GuideProvides services to enable and support persistence. - + + + + + +Persistent +Data Services GuideProvides services to enable and support persistence. + + + \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FC230C68-18FC-5DB9-A5B2-942B48DC5590_d0e334707_href.png Binary file Symbian3/SDK/Source/GUID-FC230C68-18FC-5DB9-A5B2-942B48DC5590_d0e334707_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FC230C68-18FC-5DB9-A5B2-942B48DC5590_d0e340864_href.png Binary file Symbian3/SDK/Source/GUID-FC230C68-18FC-5DB9-A5B2-942B48DC5590_d0e340864_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FCC51FFE-DC34-5168-9564-8F30273DE1BD_d0e306369_href.png Binary file Symbian3/SDK/Source/GUID-FCC51FFE-DC34-5168-9564-8F30273DE1BD_d0e306369_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FCC51FFE-DC34-5168-9564-8F30273DE1BD_d0e312384_href.png Binary file Symbian3/SDK/Source/GUID-FCC51FFE-DC34-5168-9564-8F30273DE1BD_d0e312384_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FCEDC338-61CA-5D10-A8DB-E44A3EBBDE5E-GENID-1-8-1-3-1-1-9-1-3-1.dita --- a/Symbian3/SDK/Source/GUID-FCEDC338-61CA-5D10-A8DB-E44A3EBBDE5E-GENID-1-8-1-3-1-1-9-1-3-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,58 +0,0 @@ - - - - - -Front -End Processor Overview -
                      Purpose

                      Front -End Processors, or FEPs, enable users to input characters that are not on -the device keyboard. For most phones a FEP is essential for entering anything -anything other than numbers. Typically FEPs are used for processing multi-tap -keypad input, predictive text, handwriting recognition, voice recognition -and character selection.

                      -
                      Architectural -relationships

                      FEPs are ECOM plugins that implement the FEP interface. -They typically use the UI Control Framework to intercept key and pointer events -which are processed as necessary and the output sent to the current application. -Applications do not need to be aware that a FEP is present.

                      Note that -until the introduction of Platform -Security FEPs were implemented as polymorphic DLLs. Significantly, -under Platsec, FEPs require a capability of All - Tcb as they may be -loaded by any application.

                      -
                      Description

                      The -API has five key concepts: FEP base, control input capability, FEP-aware text -editor, foreground observer and focus observer.

                      FEP Base

                      The -FEP base, CCoeFep, is the abstract base class from which -a FEP is derived. A FEP is typically implemented to have a window owning control, -the standard means of receiving input events. The UI Control Framework uses -a control stack to determine the order in which controls are offered key events. -A FEP places its control on the stack with a high priority such that it has -first access to key events.

                      - FEP Base - -

                      The Window Server provides support for windows that float above -other windows in the application. This allows a FEP to have a visible presence.

                      Each -running application has its own instance of the current FEP. Support is provided -for synchronising attributes across all instances so that there appears to -be only one.

                      Control input-capabilities

                      A FEP must -be able to discover the input-capabilities of the target control(s) to determine -what output is appropriate. Input capabilities are provided by TCoeInputCapabilities.

                      FEP-aware -text editors

                      A text-editing control can be designed to be closely -integrated with a FEP by implementing MCoeFepAwareTextEditor. -Most of the Symbian provided editing controls do this. The use of in-line -editing in FEP aware editors can mean that a FEP has no obvious visible presence -at all.

                      Foreground observer

                      A FEP can implement an -observer interface to be notified when the application goes into the foreground -or background. The foreground observer is MCoeForegroundObserver.

                      Focus -observer

                      A FEP can implement an observer to be notified when controls -under the FEP gain or lose focus. The FEP can then discover the input-capabilities -of the current target control(s). The focus observer is MCoeFocusObserver.

                      -
                      See also

                      UI Control Framework Overview

                      -                       \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FCEDC338-61CA-5D10-A8DB-E44A3EBBDE5E-GENID-1-8-1-6-1-1-4-1-8-1-3-1.dita --- a/Symbian3/SDK/Source/GUID-FCEDC338-61CA-5D10-A8DB-E44A3EBBDE5E-GENID-1-8-1-6-1-1-4-1-8-1-3-1.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,58 +0,0 @@ - - - - - -Front -End Processor Overview -
                      Purpose

                      Front -End Processors, or FEPs, enable users to input characters that are not on -the device keyboard. For most phones a FEP is essential for entering anything -anything other than numbers. Typically FEPs are used for processing multi-tap -keypad input, predictive text, handwriting recognition, voice recognition -and character selection.

                      -
                      Architectural -relationships

                      FEPs are ECOM plugins that implement the FEP interface. -They typically use the UI Control Framework to intercept key and pointer events -which are processed as necessary and the output sent to the current application. -Applications do not need to be aware that a FEP is present.

                      Note that -until the introduction of Platform -Security FEPs were implemented as polymorphic DLLs. Significantly, -under Platsec, FEPs require a capability of All - Tcb as they may be -loaded by any application.

                      -
                      Description

                      The -API has five key concepts: FEP base, control input capability, FEP-aware text -editor, foreground observer and focus observer.

                      FEP Base

                      The -FEP base, CCoeFep, is the abstract base class from which -a FEP is derived. A FEP is typically implemented to have a window owning control, -the standard means of receiving input events. The UI Control Framework uses -a control stack to determine the order in which controls are offered key events. -A FEP places its control on the stack with a high priority such that it has -first access to key events.

                      - FEP Base - -

                      The Window Server provides support for windows that float above -other windows in the application. This allows a FEP to have a visible presence.

                      Each -running application has its own instance of the current FEP. Support is provided -for synchronising attributes across all instances so that there appears to -be only one.

                      Control input-capabilities

                      A FEP must -be able to discover the input-capabilities of the target control(s) to determine -what output is appropriate. Input capabilities are provided by TCoeInputCapabilities.

                      FEP-aware -text editors

                      A text-editing control can be designed to be closely -integrated with a FEP by implementing MCoeFepAwareTextEditor. -Most of the Symbian provided editing controls do this. The use of in-line -editing in FEP aware editors can mean that a FEP has no obvious visible presence -at all.

                      Foreground observer

                      A FEP can implement an -observer interface to be notified when the application goes into the foreground -or background. The foreground observer is MCoeForegroundObserver.

                      Focus -observer

                      A FEP can implement an observer to be notified when controls -under the FEP gain or lose focus. The FEP can then discover the input-capabilities -of the current target control(s). The focus observer is MCoeFocusObserver.

                      -
                      See also

                      UI Control Framework Overview

                      -                       \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FCEDC338-61CA-5D10-A8DB-E44A3EBBDE5E.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-FCEDC338-61CA-5D10-A8DB-E44A3EBBDE5E.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,58 @@ + + + + + +Front +End Processor Overview +
                      Purpose

                      Front +End Processors, or FEPs, enable users to input characters that are not on +the device keyboard. For most phones a FEP is essential for entering anything +anything other than numbers. Typically FEPs are used for processing multi-tap +keypad input, predictive text, handwriting recognition, voice recognition +and character selection.

                      +
                      Architectural +relationships

                      FEPs are ECOM plugins that implement the FEP interface. +They typically use the UI Control Framework to intercept key and pointer events +which are processed as necessary and the output sent to the current application. +Applications do not need to be aware that a FEP is present.

                      Note that +until the introduction of Platform +Security FEPs were implemented as polymorphic DLLs. Significantly, +under Platsec, FEPs require a capability of All - Tcb as they may be +loaded by any application.

                      +
                      Description

                      The +API has five key concepts: FEP base, control input capability, FEP-aware text +editor, foreground observer and focus observer.

                      FEP Base

                      The +FEP base, CCoeFep, is the abstract base class from which +a FEP is derived. A FEP is typically implemented to have a window owning control, +the standard means of receiving input events. The UI Control Framework uses +a control stack to determine the order in which controls are offered key events. +A FEP places its control on the stack with a high priority such that it has +first access to key events.

                      + FEP Base + +

                      The Window Server provides support for windows that float above +other windows in the application. This allows a FEP to have a visible presence.

                      Each +running application has its own instance of the current FEP. Support is provided +for synchronising attributes across all instances so that there appears to +be only one.

                      Control input-capabilities

                      A FEP must +be able to discover the input-capabilities of the target control(s) to determine +what output is appropriate. Input capabilities are provided by TCoeInputCapabilities.

                      FEP-aware +text editors

                      A text-editing control can be designed to be closely +integrated with a FEP by implementing MCoeFepAwareTextEditor. +Most of the Symbian provided editing controls do this. The use of in-line +editing in FEP aware editors can mean that a FEP has no obvious visible presence +at all.

                      Foreground observer

                      A FEP can implement an +observer interface to be notified when the application goes into the foreground +or background. The foreground observer is MCoeForegroundObserver.

                      Focus +observer

                      A FEP can implement an observer to be notified when controls +under the FEP gain or lose focus. The FEP can then discover the input-capabilities +of the current target control(s). The focus observer is MCoeFocusObserver.

                      +
                      See also

                      UI Control Framework Overview

                      +                       \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FCFF0750-0AE9-5F51-B4F7-B1655E1AD244_d0e215760_href.png Binary file Symbian3/SDK/Source/GUID-FCFF0750-0AE9-5F51-B4F7-B1655E1AD244_d0e215760_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FCFF0750-0AE9-5F51-B4F7-B1655E1AD244_d0e219497_href.png Binary file Symbian3/SDK/Source/GUID-FCFF0750-0AE9-5F51-B4F7-B1655E1AD244_d0e219497_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FD0593E7-A36C-4656-A85A-9D62DFBCC42F_d0e194260_href.png Binary file Symbian3/SDK/Source/GUID-FD0593E7-A36C-4656-A85A-9D62DFBCC42F_d0e194260_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FD0593E7-A36C-4656-A85A-9D62DFBCC42F_d0e199268_href.png Binary file Symbian3/SDK/Source/GUID-FD0593E7-A36C-4656-A85A-9D62DFBCC42F_d0e199268_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FD1BB5C6-A042-56C9-8F1F-B51BF9DF5389_d0e383543_href.png Binary file Symbian3/SDK/Source/GUID-FD1BB5C6-A042-56C9-8F1F-B51BF9DF5389_d0e383543_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FD1BB5C6-A042-56C9-8F1F-B51BF9DF5389_d0e388684_href.png Binary file Symbian3/SDK/Source/GUID-FD1BB5C6-A042-56C9-8F1F-B51BF9DF5389_d0e388684_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FD21D8B1-EB37-409A-9158-19DBBF1A67B7_d0e72846_href.png Binary file Symbian3/SDK/Source/GUID-FD21D8B1-EB37-409A-9158-19DBBF1A67B7_d0e72846_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FD21D8B1-EB37-409A-9158-19DBBF1A67B7_d0e78000_href.png Binary file Symbian3/SDK/Source/GUID-FD21D8B1-EB37-409A-9158-19DBBF1A67B7_d0e78000_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FD2CDEB8-0784-4BE5-A775-170F57D71BBC.dita --- a/Symbian3/SDK/Source/GUID-FD2CDEB8-0784-4BE5-A775-170F57D71BBC.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-FD2CDEB8-0784-4BE5-A775-170F57D71BBC.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,55 +1,55 @@ - - - - - -UI controller -

                      The term UI controller refers to an object derived from either CAknAppUi or CAknViewAppUi, -depending on your UI architecture. The UI controller is a required part of -GUI-based applications.

                      -

                      Examples of services and responsibilities provided by the UI controller -are as follows:

                      -
                        -

                      • control stack for event -handling

                        • -

                      • construction of views for -applications

                        • -

                      • the top-level window owning control of -the application

                        • -
                      -

                      For more information on the UI controller, see:

                      -
                        -

                      • The -Application User Interface

                        • -

                      • The -run-time control hierarchy

                        • -
                      -

                      The UI controller is part of the controller structure in the Model - -View - Controller (MVC) -design pattern used to design the architecture of many GUI-based mobile -applications.

                      -

                      The CAknDocument -derived -class of your application contains the first -phase constructor of the UI controller.

                      - -

                      The second-phase constructor is called by the application framework.

                      -                       -

                      The UI controller is implemented in one of the following classes:

                      -
                        -

                      • In a traditional -architecture application architecture, the UI controller must be derived -from CAknAppUi.

                        • -

                      • In Symbian -view architecture, the UI controller must be derived from CAknViewAppUi.

                        -
                        • -

                      • In dialog -architecture, the UI controller is typically derived from CAknAppUi.

                        -
                        • -
                      + + + + + +UI controller +

                      The term UI controller refers to an object derived from either CAknAppUi or CAknViewAppUi, +depending on your UI architecture. The UI controller is a required part of +GUI-based applications.

                      +

                      Examples of services and responsibilities provided by the UI controller +are as follows:

                      +
                        +

                      • control stack for event +handling

                        • +

                      • construction of views for +applications

                        • +

                      • the top-level window owning control of +the application

                        • +
                      +

                      For more information on the UI controller, see:

                      +
                        +

                      • The +Application User Interface

                        • +

                      • The +run-time control hierarchy

                        • +
                      +

                      The UI controller is part of the controller structure in the Model - +View - Controller (MVC) +design pattern used to design the architecture of many GUI-based mobile +applications.

                      +

                      The CAknDocument -derived +class of your application contains the first +phase constructor of the UI controller.

                      + +

                      The second-phase constructor is called by the application framework.

                      +                       +

                      The UI controller is implemented in one of the following classes:

                      +
                        +

                      • In a traditional +architecture application architecture, the UI controller must be derived +from CAknAppUi.

                        • +

                      • In Symbian +view architecture, the UI controller must be derived from CAknViewAppUi.

                        +
                        • +

                      • In dialog +architecture, the UI controller is typically derived from CAknAppUi.

                        +
                        • +
                       \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FD503B6E-889C-521F-B61A-0EBDCA8CD9AC_d0e355285_href.png Binary file Symbian3/SDK/Source/GUID-FD503B6E-889C-521F-B61A-0EBDCA8CD9AC_d0e355285_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FD503B6E-889C-521F-B61A-0EBDCA8CD9AC_d0e361365_href.png Binary file Symbian3/SDK/Source/GUID-FD503B6E-889C-521F-B61A-0EBDCA8CD9AC_d0e361365_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FD52DFC5-03CD-4C7A-B118-0D5C90D99F1A_d0e71700_href.png Binary file Symbian3/SDK/Source/GUID-FD52DFC5-03CD-4C7A-B118-0D5C90D99F1A_d0e71700_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FD52DFC5-03CD-4C7A-B118-0D5C90D99F1A_d0e76845_href.png Binary file Symbian3/SDK/Source/GUID-FD52DFC5-03CD-4C7A-B118-0D5C90D99F1A_d0e76845_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FDD68915-5B6F-4091-A99A-64F91D508B3E.dita --- a/Symbian3/SDK/Source/GUID-FDD68915-5B6F-4091-A99A-64F91D508B3E.dita Wed Mar 31 11:11:55 2010 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,15 +0,0 @@ - - - - - -Changes -and release information -

                      The Choice list API is an SDK API and first released in S60 5th Edition.

                      -                       \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FE3825C5-BDEE-5F18-9FFD-2E794E618FEC.dita --- a/Symbian3/SDK/Source/GUID-FE3825C5-BDEE-5F18-9FFD-2E794E618FEC.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-FE3825C5-BDEE-5F18-9FFD-2E794E618FEC.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,49 +1,49 @@ - - - - - -Data Access ExampleThis example describes typical processing of the data in an RMBufChain.
                      Downwards flow - Example : flow going downwards -

                      The following function is a simplified example of how a component in the middle of the stack could process data sent to the driver. As shown in the above diagram, the upper layer provides the data in the RMBufChain parameter.

                      -void Send (RMBufChain &aChain) -{ - TBuf8<KHeaderLength> aHeader; - - // [...] fill the header - - // request space in front of the data - aChain.Prepend(KHeaderLength); - - // add the protocol header - aChain.CopyIn(aHeader); - - // send the updated chain to the next layer - downwardComponent->Send(aChain); -} -

                      Note that depending on the available space remaining in front of the data in the MBuf, the RMBufChain::Prepend() method may request the pond to add a new MBuf to the front of the chain. For more information, see Buffer layout.

                      Upwards flow - Example : flow going upwards -

                      The following function is a simplified example of how a component in the middle of the stack could process data received by the driver. As shown in the above diagram, the underlying layer provides the data in the RMBufChain parameter.

                      -void Process (RMBufChain &aChain) -{ - TBuf8<KHeaderLength> aHeader; - - // get a copy of the header - aChain.CopyOut(KHeaderLength, &aHeader); - - // discard the header in the chain - aChain.TrimStart(KHeaderLength); - - // [...] process the header - - // send the updated chain to the next layer - appropriateUpwardComponent->Process(aChain); -} -

                      Note that the header might not be stored in a contiguous memory area: it can be splitted accross several chained MBufs. For a better performance, you should define a buffer size slightly bigger than your MTU: for more information, see Pond Configuration : Recommendations.

                      Overview Comms Buffers (MBuf) + + + + + +Data Access ExampleThis example describes typical processing of the data in an RMBufChain.
                      Downwards flow + Example : flow going downwards +

                      The following function is a simplified example of how a component in the middle of the stack could process data sent to the driver. As shown in the above diagram, the upper layer provides the data in the RMBufChain parameter.

                      +void Send (RMBufChain &aChain) +{ + TBuf8<KHeaderLength> aHeader; + + // [...] fill the header + + // request space in front of the data + aChain.Prepend(KHeaderLength); + + // add the protocol header + aChain.CopyIn(aHeader); + + // send the updated chain to the next layer + downwardComponent->Send(aChain); +} +

                      Note that depending on the available space remaining in front of the data in the MBuf, the RMBufChain::Prepend() method may request the pond to add a new MBuf to the front of the chain. For more information, see Buffer layout.

                      Upwards flow + Example : flow going upwards +

                      The following function is a simplified example of how a component in the middle of the stack could process data received by the driver. As shown in the above diagram, the underlying layer provides the data in the RMBufChain parameter.

                      +void Process (RMBufChain &aChain) +{ + TBuf8<KHeaderLength> aHeader; + + // get a copy of the header + aChain.CopyOut(KHeaderLength, &aHeader); + + // discard the header in the chain + aChain.TrimStart(KHeaderLength); + + // [...] process the header + + // send the updated chain to the next layer + appropriateUpwardComponent->Process(aChain); +} +

                      Note that the header might not be stored in a contiguous memory area: it can be splitted accross several chained MBufs. For a better performance, you should define a buffer size slightly bigger than your MTU: for more information, see Pond Configuration : Recommendations.

                      Overview Comms Buffers (MBuf) and Comms Chains                       \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FE3AFA30-4097-51B2-B31B-9EF4A04FE7A5.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-FE3AFA30-4097-51B2-B31B-9EF4A04FE7A5.dita Fri Jun 11 12:39:03 2010 +0100 @@ -0,0 +1,13 @@ + + + + + +Windowing Example CodeExample code for the Windowing collection. Windowing + Collection \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FE3C8D39-CE17-5AC7-AB6A-4D6664D52196_d0e184843_href.png Binary file Symbian3/SDK/Source/GUID-FE3C8D39-CE17-5AC7-AB6A-4D6664D52196_d0e184843_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FE3C8D39-CE17-5AC7-AB6A-4D6664D52196_d0e191439_href.png Binary file Symbian3/SDK/Source/GUID-FE3C8D39-CE17-5AC7-AB6A-4D6664D52196_d0e191439_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FE4BBEB4-4E5A-5BF2-A72F-AF53BAD83518-master.png Binary file Symbian3/SDK/Source/GUID-FE4BBEB4-4E5A-5BF2-A72F-AF53BAD83518-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FE4BBEB4-4E5A-5BF2-A72F-AF53BAD83518_d0e187538_href.png Binary file Symbian3/SDK/Source/GUID-FE4BBEB4-4E5A-5BF2-A72F-AF53BAD83518_d0e187538_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FE922294-380D-447D-AC46-A46EFAD79168.dita --- a/Symbian3/SDK/Source/GUID-FE922294-380D-447D-AC46-A46EFAD79168.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-FE922294-380D-447D-AC46-A46EFAD79168.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,121 +1,125 @@ - - - - - -Order -of items and browsing in grids -

                      In a grid, the available items are in a rectangular arrangement of cells -and browsing is possible in four directions. In addition to the up and down -functions, the user can press the Arrow right key to move the focus one step -to the right, or the Arrow left key to move the focus one step to the left.

                      -

                      The number of items can be larger than what fits in the view, so the grid -items may scroll in the view when browsing.

                      -
                        -

                      • The preferred scrolling dimension is vertical; this means that when -more items are added, the number of items in a grid grows downwards line by -line, but not outside the window to the left or right.

                        • -

                      • A grid should not be scrollable in both dimensions; it is acceptable -only in cases where the grid has a natural geometry that cannot be changed. -Calendar's Month view is an example of this kind of geometry (but even in -that case it is better to fit the whole month on the screen rather than make -it scrollable in both dimensions).

                        • -

                      • The default filling order of choice items in a grid is first left to -right, then top-to-bottom. In right-to-left languages, the order is flipped -horizontally.

                        • -
                      -Default grid-filling -order: Left-to-right UI languages - - - -

                      1

                       -

                      2

                       -

                      3

                       -                       - -

                      4

                       -

                      5

                       -

                      6

                       -                       - -

                      7

                       -

                      8

                       -

                      9

                       -                       - - -
                      Default -grid-filling order: Right-to-left UI languages - - - -

                      3

                       -

                      2

                       -

                      1

                       -                       - -

                      6

                       -

                      5

                       -

                      4

                       -                       - -

                      9

                       -

                      8

                       -

                      7

                       -                       - - -
                      -

                      In certain cases, it is possible that a grid is not filled completely. -Depending on the application, the grid can be auto-filling (for example, the -cells are moved within the grid so that empty cells in the middle get filled), -in which case there can only be empty cells on the rightmost part of the last -line. Other applications may allow empty cells anywhere, so that the grid -can be sparse.

                      -

                      Browsing in grids that scroll vertically resembles traditional scrolling -in text editors, based on the idea that the user can always move to the correct -row first and then move within the row to the correct item. The following -rules are applied:

                      -
                        -

                      • Empty cells are skipped: the focus is never on an empty cell.

                        Note: -An exception to this occurs when the user is moving items around in a grid; -in that case, all cells are accessible.

                        • -

                      • When browsing up or down, the focus is moved to the adjacent cell directly -below or above the current cell if that cell is filled. In case it is empty, -the nearest cell towards the beginning of the same row gets the focus. If -all cells on the row are empty, the search continues on the next row in the -same direction, and so on, until a filled cell is found.

                        • -

                      • When browsing towards the end of a row, the focus moves to the following -filled cell on the same row. If there are no filled cells in that direction -on the row, the search continues from the beginning of the next row, and so -on, until a filled cell is found.

                        • -

                      • Browsing towards the beginning of a row moves the focus to the previous -filled cell on the same row, or continues searching from the end of the previous -row. Using only the Arrow right or Arrow left key, the user can thus go through -every item in the grid, regardless of the distribution of items in it.

                        Note: -In right-to-left UI languages, such as Arabic and Hebrew, the end of a row -is on the left-hand side. Respectively, the beginning of the line is on the -right.

                        • -

                      • The grid is scrolled (moved within the view) only when the item that -is becoming focused is not fully visible already.

                        • -

                      • A grid may also loop vertically within the same column. When browsing -down from the cell at the bottom of a column, the focus moves to the choice -item at the top of the next column and vice versa. If the focus is in the -last column when applying the previous rule, the focus loops over to the top -of the first column and vice versa.

                        • -
                      - -Examples of moving the focus in a grid. a) Left-to-right UI language; -only scroll down commands used. b) Left-to-right UI language; only scroll -right commands used. c) Right-to-left UI language; only scroll -down used. d) Right-to-left UI language; only scroll right used. - - + + + + + +Order +of items and browsing in grids +

                      In a grid, the available items are in a rectangular arrangement of cells +and browsing is possible in four directions. In addition to the up and down +functions, the user can press the Arrow right key to move the focus one step +to the right, or the Arrow left key to move the focus one step to the left.

                      +

                      The number of items can be larger than what fits in the view, so the grid +items may scroll in the view when browsing.

                      +
                        +

                      • The preferred scrolling dimension is vertical; this means that when +more items are added, the number of items in a grid grows downwards line by +line, but not outside the window to the left or right.

                        • +

                      • A grid should not be scrollable in both dimensions; it is acceptable +only in cases where the grid has a natural geometry that cannot be changed. +Calendar's Month view is an example of this kind of geometry (but even in +that case it is better to fit the whole month on the screen rather than make +it scrollable in both dimensions).

                        • +

                      • The default filling order of choice items in a grid is first left to +right, then top-to-bottom. In right-to-left languages, the order is flipped +horizontally.

                        • +
                      +Default grid-filling +order: Left-to-right UI languages + + + + +

                      1

                       +

                      2

                       +

                      3

                       +                       + + +

                      4

                       +

                      5

                       +

                      6

                       +                       + + +

                      7

                       +

                      8

                       +

                      9

                       +                       + + +
                      Default +grid-filling order: Right-to-left UI languages + + + + +

                      3

                       +

                      2

                       +

                      1

                       +                       + +

                      6

                       +

                      5

                       +

                      4

                       +                       + +

                      9

                       +

                      8

                       +

                      7

                       +                       + + +
                      +

                      In certain cases, it is possible that a grid is not filled completely. +Depending on the application, the grid can be auto-filling (for example, the +cells are moved within the grid so that empty cells in the middle get filled), +in which case there can only be empty cells on the rightmost part of the last +line. Other applications may allow empty cells anywhere, so that the grid +can be sparse.

                      +

                      Browsing in grids that scroll vertically resembles traditional scrolling +in text editors, based on the idea that the user can always move to the correct +row first and then move within the row to the correct item. The following +rules are applied:

                      +
                        +

                      • Empty cells are skipped: the focus is never on an empty cell.

                        Note: +An exception to this occurs when the user is moving items around in a grid; +in that case, all cells are accessible.

                        • +

                      • When browsing up or down, the focus is moved to the adjacent cell directly +below or above the current cell if that cell is filled. In case it is empty, +the nearest cell towards the beginning of the same row gets the focus. If +all cells on the row are empty, the search continues on the next row in the +same direction, and so on, until a filled cell is found.

                        • +

                      • When browsing towards the end of a row, the focus moves to the following +filled cell on the same row. If there are no filled cells in that direction +on the row, the search continues from the beginning of the next row, and so +on, until a filled cell is found.

                        • +

                      • Browsing towards the beginning of a row moves the focus to the previous +filled cell on the same row, or continues searching from the end of the previous +row. Using only the Arrow right or Arrow left key, the user can thus go through +every item in the grid, regardless of the distribution of items in it.

                        Note: +In right-to-left UI languages, such as Arabic and Hebrew, the end of a row +is on the left-hand side. Respectively, the beginning of the line is on the +right.

                        • +

                      • The grid is scrolled (moved within the view) only when the item that +is becoming focused is not fully visible already.

                        • +

                      • A grid may also loop vertically within the same column. When browsing +down from the cell at the bottom of a column, the focus moves to the choice +item at the top of the next column and vice versa. If the focus is in the +last column when applying the previous rule, the focus loops over to the top +of the first column and vice versa.

                        • +
                      + +Examples of moving the focus in a grid. a) Left-to-right UI language; +only scroll down commands used. b) Left-to-right UI language; only scroll +right commands used. c) Right-to-left UI language; only scroll down used. +d) Right-to-left UI language; only scroll right used. + +                       \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FE94596E-B5BB-51FE-BE38-069840323915.dita --- a/Symbian3/SDK/Source/GUID-FE94596E-B5BB-51FE-BE38-069840323915.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-FE94596E-B5BB-51FE-BE38-069840323915.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,191 +1,191 @@ - - - - - -Encoding -Types -

                      This topic describes the types of SMS encoding.

                      -
                      7-bit GSM encoding

                      7-bit -GSM encoding supports the GSM 7-bit default alphabet and GSM 7-bit default -alphabet extension table through an escape mechanism.

                      Figure 1

                      - Escape mechanism - -

                      The GSM 7-bit default alphabet consists of 128 characters. Each -character is represented by 7 bits. 10 extra characters are defined in the -GSM 7-bit default extension table. These characters are represented by an -escape mechanism using the escape character (0x1B). For example, 0x1B65 maps -to the Euro sign € (U+20AC). If an escape character byte is followed by a -character that is not included in the 10 characters, the escape character -is just ignored. This means 0x1B41 maps to Latin capital letter A (U+0041).

                      For -more information about the GSM 7-bit default table, extension table and escape -mechanism, see 3GPP TS 23.038 V8.1.0.

                      -
                      Lossy 7-bit -encoding

                      Lossy 7-bit encoding enlarges the character set supported -by 7-bit GSM encoding. Some Unicode Characters do not exist in the target -7-bit set. These characters are converted to ones that do exist in the target -7-bit set and closely resemble the original, intended character. A lossy encoding -using a 7-bit encoding is more cost effective than a UCS-2 encoding.

                      Example -of 7-bit encoding

                      Accented Latin characters are not supported -by 7-bit GSM encoding. Figure 2 describes how an accented Latin characters -Á, is sent by SMS. Á has a Unicode value of 0x00C1. When it is processed by -the Lossy converter the character is converted from the Unicode to 7-bit code -letter A. A has a 7-bit code of 0x41. The SMS receiver reads A instead of -Á. By substituting the character that is similar enough to the original, the -reader can understand the word. The process of converting Á to A is called -a lossy conversion.

                      Note: The 7-bit code of A (0x41) can only -be decoded back to the same Unicode letter A instead of Á.

                      Figure -2

                      - Lossy conversion - -
                      -
                      16-bit Unicode -encoding

                      Unicode is an international standard character set. It -includes the characters of every language. In Unicode, each character is usually -encoded in two 8-bit bytes, and takes up more space than 7-bit encoding.

                      -
                      National language -encoding

                      According to 3GPP TS 23.038 V8.1.0, National Language -Encoding supports additional characters for certain languages which cannot -be represented in the GSM default 7-bit alphabet. It defines two mechanisms -for doing this:

                        -

                      • Locking shift mechanism–the -default GSM table is replaced with a table containing the character set needed -for a language. The table is referred to as locking shift table.

                        • -

                      • Single shift mechanism–the -GSM extension table is replaced with a table containing the character set -needed for a language. The table is referred to as single shift table.

                        • -

                      When the locking shift mechanism is used, the escape table can be -the existing GSM extension table or it can be the escape table used by the -single shift mechanism. This supports three possible mappings as shown in -Figure 3:

                        -

                      • The GSM 7-bit default -escapes to language-specific escape table. It is referred to as GSM-single.

                        • -

                      • The Language-specific -basic table escapes to GSM 7-bit default extension table. It is referred to -as locking-GSM ext.

                        • -

                      • The Language-specific -basic table escapes to language-specific extension table. It is referred to -as locking-single.

                        • -

                      Figure 3

                      - National language encoding - -

                      The single shift mechanism is useful when a message contains only -a few characters outside the default GSM table. It is however inefficient -when a message contains many unsupported characters, because each escaped -character must occupy 2 bytes. GSM-single supports more characters than locking-GSM -ext, but these characters are in the single table, which takes 2 bytes. Locking-single -is used more for the decoding purpose in case the extra characters can come -from the locking or single table.

                      The locking or single table is not -a complete replacement. For example, the locking table for Turkish redefines -only 8-character codes from the default GSM table, as shown in table 1. The -escape table for Turkish adds 7 characters to the GSM extension, as shown -in table 2.

                      Table 1 - - - -

                      GSM 7-Bit Code

                       -

                      Turkish Locking Shift Table

                       -

                      GSM 7-Bit Default Table

                       -                       - - - -

                      0x40

                       -

                      I LATIN CAPITAL LETTER I WITH DOT ABOVE

                       -

                      ¡ INVERTED EXCLAMATION MARK

                      -                       - -

                      0x60

                       -

                      ç LATIN SMALL LETTER C WITH CEDILLA

                       -

                      ¿ INVERTED QUESTION MARK

                       -                       - -

                      0x04

                       -

                      € EURO SIGN

                       -

                      è LATIN SMALL LETTER E WITH GRAVE

                       -                       - -

                      0x07

                       -

                      i LATIN SMALL LETTER DOTLESS

                       -

                      ì LATIN SMALL LETTER I WITH GRAVE

                       -                       - -

                      0x0B

                       -

                      G LATIN CAPITAL LETTER G WITH BREVE

                       -

                      Ø LATIN CAPITAL LETTER O WITH STROKE

                       -                       - -

                      0x0C

                       -

                      g LATIN SMALL LETTER G WITH BREVE

                       -

                      ø LATIN SMALL LETTER O WITH STROKE

                       -                       - -

                      0x1C

                       -

                      S LATIN CAPITAL LETTER S WITH CEDILLA *

                       -

                      Æ LATIN CAPITAL LETTER AE

                       -                       - -

                      0x1D

                       -

                      s LATIN SMALL LETTER S WITH CEDILLA *

                       -

                      æ LATIN SMALL LETTER AE

                       -                       - - -
                      Table 2 - - - -

                      GSM 7-Bit Code

                       -

                      Turkish Single Shift Table

                       -

                      GSM 7-Bit Extension Table

                       -                       - - - -

                      0x1B49

                       -

                      I LATIN CAPITAL LETTER I WITH DOT ABOVE

                       -

                      - - -

                      0x1B63

                       -

                      ç LATIN SMALL LETTER C WITH CEDILLA

                       -

                      - - -

                      0x1B69

                       -

                      i LATIN SMALL LETTER DOTLESS

                       -

                      - - -

                      0x1B47

                       -

                      G LATIN CAPITAL LETTER G WITH BREVE

                       -

                      - - -

                      0x1B67

                       -

                      g LATIN SMALL LETTER G WITH BREVE

                       -

                      - - -

                      0x1B53

                       -

                      S LATIN CAPITAL LETTER S WITH CEDILLA *

                       -

                      - - -

                      0x1B73

                       -

                      s LATIN SMALL LETTER S WITH CEDILLA *

                       -

                      - -

                       - -

                      For more information about the National Language Identifier, Single -or Locking mechanism, see 3GPP TS 23.038 V8.1.0: National Language Identifier.

                      -
                      See also

                      SMS -Encodings and Converters Overview

                      + + + + + +Encoding +Types +

                      This topic describes the types of SMS encoding.

                      +
                      7-bit GSM encoding

                      7-bit +GSM encoding supports the GSM 7-bit default alphabet and GSM 7-bit default +alphabet extension table through an escape mechanism.

                      Figure 1

                      + Escape mechanism + +

                      The GSM 7-bit default alphabet consists of 128 characters. Each +character is represented by 7 bits. 10 extra characters are defined in the +GSM 7-bit default extension table. These characters are represented by an +escape mechanism using the escape character (0x1B). For example, 0x1B65 maps +to the Euro sign € (U+20AC). If an escape character byte is followed by a +character that is not included in the 10 characters, the escape character +is just ignored. This means 0x1B41 maps to Latin capital letter A (U+0041).

                      For +more information about the GSM 7-bit default table, extension table and escape +mechanism, see 3GPP TS 23.038 V8.1.0.

                      +
                      Lossy 7-bit +encoding

                      Lossy 7-bit encoding enlarges the character set supported +by 7-bit GSM encoding. Some Unicode Characters do not exist in the target +7-bit set. These characters are converted to ones that do exist in the target +7-bit set and closely resemble the original, intended character. A lossy encoding +using a 7-bit encoding is more cost effective than a UCS-2 encoding.

                      Example +of 7-bit encoding

                      Accented Latin characters are not supported +by 7-bit GSM encoding. Figure 2 describes how an accented Latin characters +Á, is sent by SMS. Á has a Unicode value of 0x00C1. When it is processed by +the Lossy converter the character is converted from the Unicode to 7-bit code +letter A. A has a 7-bit code of 0x41. The SMS receiver reads A instead of +Á. By substituting the character that is similar enough to the original, the +reader can understand the word. The process of converting Á to A is called +a lossy conversion.

                      Note: The 7-bit code of A (0x41) can only +be decoded back to the same Unicode letter A instead of Á.

                      Figure +2

                      + Lossy conversion + +
                      +
                      16-bit Unicode +encoding

                      Unicode is an international standard character set. It +includes the characters of every language. In Unicode, each character is usually +encoded in two 8-bit bytes, and takes up more space than 7-bit encoding.

                      +
                      National language +encoding

                      According to 3GPP TS 23.038 V8.1.0, National Language +Encoding supports additional characters for certain languages which cannot +be represented in the GSM default 7-bit alphabet. It defines two mechanisms +for doing this:

                        +

                      • Locking shift mechanism–the +default GSM table is replaced with a table containing the character set needed +for a language. The table is referred to as locking shift table.

                        • +

                      • Single shift mechanism–the +GSM extension table is replaced with a table containing the character set +needed for a language. The table is referred to as single shift table.

                        • +

                      When the locking shift mechanism is used, the escape table can be +the existing GSM extension table or it can be the escape table used by the +single shift mechanism. This supports three possible mappings as shown in +Figure 3:

                        +

                      • The GSM 7-bit default +escapes to language-specific escape table. It is referred to as GSM-single.

                        • +

                      • The Language-specific +basic table escapes to GSM 7-bit default extension table. It is referred to +as locking-GSM ext.

                        • +

                      • The Language-specific +basic table escapes to language-specific extension table. It is referred to +as locking-single.

                        • +

                      Figure 3

                      + National language encoding + +

                      The single shift mechanism is useful when a message contains only +a few characters outside the default GSM table. It is however inefficient +when a message contains many unsupported characters, because each escaped +character must occupy 2 bytes. GSM-single supports more characters than locking-GSM +ext, but these characters are in the single table, which takes 2 bytes. Locking-single +is used more for the decoding purpose in case the extra characters can come +from the locking or single table.

                      The locking or single table is not +a complete replacement. For example, the locking table for Turkish redefines +only 8-character codes from the default GSM table, as shown in table 1. The +escape table for Turkish adds 7 characters to the GSM extension, as shown +in table 2.

                      Table 1 + + + +

                      GSM 7-Bit Code

                       +

                      Turkish Locking Shift Table

                       +

                      GSM 7-Bit Default Table

                       +                       + + + +

                      0x40

                       +

                      I LATIN CAPITAL LETTER I WITH DOT ABOVE

                       +

                      ¡ INVERTED EXCLAMATION MARK

                      +                       + +

                      0x60

                       +

                      ç LATIN SMALL LETTER C WITH CEDILLA

                       +

                      ¿ INVERTED QUESTION MARK

                       +                       + +

                      0x04

                       +

                      € EURO SIGN

                       +

                      è LATIN SMALL LETTER E WITH GRAVE

                       +                       + +

                      0x07

                       +

                      i LATIN SMALL LETTER DOTLESS

                       +

                      ì LATIN SMALL LETTER I WITH GRAVE

                       +                       + +

                      0x0B

                       +

                      G LATIN CAPITAL LETTER G WITH BREVE

                       +

                      Ø LATIN CAPITAL LETTER O WITH STROKE

                       +                       + +

                      0x0C

                       +

                      g LATIN SMALL LETTER G WITH BREVE

                       +

                      ø LATIN SMALL LETTER O WITH STROKE

                       +                       + +

                      0x1C

                       +

                      S LATIN CAPITAL LETTER S WITH CEDILLA *

                       +

                      Æ LATIN CAPITAL LETTER AE

                       +                       + +

                      0x1D

                       +

                      s LATIN SMALL LETTER S WITH CEDILLA *

                       +

                      æ LATIN SMALL LETTER AE

                       +                       + + +
                      Table 2 + + + +

                      GSM 7-Bit Code

                       +

                      Turkish Single Shift Table

                       +

                      GSM 7-Bit Extension Table

                       +                       + + + +

                      0x1B49

                       +

                      I LATIN CAPITAL LETTER I WITH DOT ABOVE

                       +

                      + + +

                      0x1B63

                       +

                      ç LATIN SMALL LETTER C WITH CEDILLA

                       +

                      + + +

                      0x1B69

                       +

                      i LATIN SMALL LETTER DOTLESS

                       +

                      + + +

                      0x1B47

                       +

                      G LATIN CAPITAL LETTER G WITH BREVE

                       +

                      + + +

                      0x1B67

                       +

                      g LATIN SMALL LETTER G WITH BREVE

                       +

                      + + +

                      0x1B53

                       +

                      S LATIN CAPITAL LETTER S WITH CEDILLA *

                       +

                      + + +

                      0x1B73

                       +

                      s LATIN SMALL LETTER S WITH CEDILLA *

                       +

                      + +

                       + +

                      For more information about the National Language Identifier, Single +or Locking mechanism, see 3GPP TS 23.038 V8.1.0: National Language Identifier.

                      +
                      See also

                      SMS +Encodings and Converters Overview

                      \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FEFF353E-DE8A-5FBA-B696-CD01D06BE813-master.png Binary file Symbian3/SDK/Source/GUID-FEFF353E-DE8A-5FBA-B696-CD01D06BE813-master.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FEFF353E-DE8A-5FBA-B696-CD01D06BE813_d0e187563_href.png Binary file Symbian3/SDK/Source/GUID-FEFF353E-DE8A-5FBA-B696-CD01D06BE813_d0e187563_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FF08B8F5-9881-5BA3-ACD1-C09E40A09438.dita --- a/Symbian3/SDK/Source/GUID-FF08B8F5-9881-5BA3-ACD1-C09E40A09438.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-FF08B8F5-9881-5BA3-ACD1-C09E40A09438.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,71 +1,71 @@ - - - - - -Multimedia -Plug-ins OverviewThis topic provides an overview of the components that form the -Multimedia Plug-ins collection. -
                      Purpose

                      The Multimedia Plug-ins collection represents -a plug-in framework for handling multimedia data.

                      -
                      Architecture

                      The components in the Multimedia Plug-ins -collection are used by the components in the Multimedia APIs and Frameworks -collection. The following diagram shows the architecture of the Multimedia -Plug-ins collection:

                      - Multimedia Plug-ins architecture - -
                      -
                      Description

                      The Multimedia Plug-ins collection -provides a generic plug-in architecture for the Camera Framework, Imaging -Frameworks and Multimedia Framework (MMF) components. The following types -of plug-ins are available:

                        -

                      • Codec plug-ins provide -the conversion between different data types.

                        • -

                      • Controller plug-ins -enable support for audio and video formats.

                        • -

                      • Content Rendering Plug-ins -(CRPs) are plug-ins that are loaded into the Window Server process for server-side -rendering. For more information, see Window -Server Component.

                        • -
                      -
                      Components

                      The Multimedia Plug-ins collection comprises -the following components:

                        - -

                      • Camera Plug-ins - -provides a Camera stub plug-in implementation. For information about Camera -Plug-ins see, Camera -Plug-in Overview.

                        • -

                      • Imaging Plug-ins - -encodes and decodes various imaging formats, for example, GIF and JPEG. For -information about Imaging Plug-ins see, Imaging -Plug-ins Overview.

                        • -

                      • Video Subtitle CRP -(Content Rendering Plug-in) - displays video subtitles. For information -about Video Subtitle CRP see, Video -Subtitle CRP Overview.

                        • -
                      -
                      Using Multimedia Plug-ins

                      You can use the functionality -provided by the Multimedia Plug-ins collection to:

                        -

                      • Implement the camera -stub plug-in.

                        • -

                      • Encode and decode imaging -formats.

                        • -

                      • Display video subtitles.

                        • -
                      -                       - -Camera Plug-in - -Imaging Plug-in - -Video Subtitle -CRP -Writing - Multimedia Framework Plug-ins + + + + + +Multimedia +Plug-ins OverviewThis topic provides an overview of the components that form the +Multimedia Plug-ins collection. +
                      Purpose

                      The Multimedia Plug-ins collection represents +a plug-in framework for handling multimedia data.

                      +
                      Architecture

                      The components in the Multimedia Plug-ins +collection are used by the components in the Multimedia APIs and Frameworks +collection. The following diagram shows the architecture of the Multimedia +Plug-ins collection:

                      + Multimedia Plug-ins architecture + +
                      +
                      Description

                      The Multimedia Plug-ins collection +provides a generic plug-in architecture for the Camera Framework, Imaging +Frameworks and Multimedia Framework (MMF) components. The following types +of plug-ins are available:

                        +

                      • Codec plug-ins provide +the conversion between different data types.

                        • +

                      • Controller plug-ins +enable support for audio and video formats.

                        • +

                      • Content Rendering Plug-ins +(CRPs) are plug-ins that are loaded into the Window Server process for server-side +rendering. For more information, see Window +Server Component.

                        • +
                      +
                      Components

                      The Multimedia Plug-ins collection comprises +the following components:

                        + +

                      • Camera Plug-ins - +provides a Camera stub plug-in implementation. For information about Camera +Plug-ins see, Camera +Plug-in Overview.

                        • +

                      • Imaging Plug-ins - +encodes and decodes various imaging formats, for example, GIF and JPEG. For +information about Imaging Plug-ins see, Imaging +Plug-ins Overview.

                        • +

                      • Video Subtitle CRP +(Content Rendering Plug-in) - displays video subtitles. For information +about Video Subtitle CRP see, Video +Subtitle CRP Overview.

                        • +
                      +
                      Using Multimedia Plug-ins

                      You can use the functionality +provided by the Multimedia Plug-ins collection to:

                        +

                      • Implement the camera +stub plug-in.

                        • +

                      • Encode and decode imaging +formats.

                        • +

                      • Display video subtitles.

                        • +
                      +                       + +Camera Plug-in + +Imaging Plug-in + +Video Subtitle +CRP +Writing + Multimedia Framework Plug-ins                       \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FF81C5C5-09B7-5194-928E-0BA87417B2CD.dita --- a/Symbian3/SDK/Source/GUID-FF81C5C5-09B7-5194-928E-0BA87417B2CD.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-FF81C5C5-09B7-5194-928E-0BA87417B2CD.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,15 +1,15 @@ - - - - - -What are Access Point Priorities?This topic explains access point priorities and how the values are inherited.

                      Contention management issues are resolved using the priorities associated with the Access Points. Priorities are assigned to Access Point Layers. If an incoming GPRS connection has a higher priority than an existing GRPS connection, the existing connection is stopped and the new connection is started. If the incoming GPRS connection has a lower priority than all existing GPRS connections the incoming GPRS connection is discarded.

                      The Access Point priority is stored in the CommsDat AccessPointTable. You can specify a priority for access point using the CommsData config file in “cfg” format. The priority range is 1-KMaxTUint where 1 is high priority and KMaxTUint is low priority. If a priority is not assigned to an access point the default value is KMaxTUint is given. A zero priority value is not allowed.

                      Access Point Priority Inheritance Example

                      Access Point Priorities can be inherited between Access Point Layers. The current Access Point Layer priority is compared to the inherited Access Point priority, the highest priority is assigned to the Point Layer. This means that the priority of an Access point layer can be overridden by an inherited priority.

                      CurrentPriority = max_priority{AccessPointPriority, - inherited_priority}

                      The following diagram contains three Access Point Layers. Each Access Point Layer has an associated priority.

                      As a result of inheritance the following priorities are applied.

                      For IP_MCPR1 the resultant priority is {3, KmaxTUint} = 3

                      For IPPROTO_MCPR1 the resultant priority is {3, 5} = 3

                      For PDP_MCPR1 the resultant priority is {4, 3} = 3

                      Changes in Access Point Priorities at Runtime

                      The following diagram outlines how priorities can change at runtime.

                      In this example:

                      • Two stack configurations (SNAP1 and SNAP2) are defined in the CommsDat. The configurations have different settings for the IP layer but the same IPProto and PDP layers.

                      • An application is started on SNAP1. IP_CPR1 and IP_MCPR1 are created.

                      • A second application is started on SNAP2. IP_CPR2 and IP_MCPR2 are created.

                      • Current priorities for IPProto and PDP layer will be recalculated. On this example they do not change because priority 6 is the lowest priority in this stack.

                      • If first application stops its connection and second application continue to work, IP_CPR1 is destroyed. IPPROTO_CPR1 and PDP_CPR1 priorities will be recalculated.

                        IPPROTO_CPR1 priority = max_priority{5, 6} = 5

                        PDP_CPR1 priority = max_priority{4, 5} = 4

                      What is Contention? What is Contention - Management? Starting a Network Connection + + + + + +What are Access Point Priorities?This topic explains access point priorities and how the values are inherited.

                      Contention management issues are resolved using the priorities associated with the Access Points. Priorities are assigned to Access Point Layers. If an incoming GPRS connection has a higher priority than an existing GRPS connection, the existing connection is stopped and the new connection is started. If the incoming GPRS connection has a lower priority than all existing GPRS connections the incoming GPRS connection is discarded.

                      The Access Point priority is stored in the CommsDat AccessPointTable. You can specify a priority for access point using the CommsData config file in “cfg” format. The priority range is 1-KMaxTUint where 1 is high priority and KMaxTUint is low priority. If a priority is not assigned to an access point the default value is KMaxTUint is given. A zero priority value is not allowed.

                      Access Point Priority Inheritance Example

                      Access Point Priorities can be inherited between Access Point Layers. The current Access Point Layer priority is compared to the inherited Access Point priority, the highest priority is assigned to the Point Layer. This means that the priority of an Access point layer can be overridden by an inherited priority.

                      CurrentPriority = max_priority{AccessPointPriority, + inherited_priority}

                      The following diagram contains three Access Point Layers. Each Access Point Layer has an associated priority.

                      As a result of inheritance the following priorities are applied.

                      For IP_MCPR1 the resultant priority is {3, KmaxTUint} = 3

                      For IPPROTO_MCPR1 the resultant priority is {3, 5} = 3

                      For PDP_MCPR1 the resultant priority is {4, 3} = 3

                      Changes in Access Point Priorities at Runtime

                      The following diagram outlines how priorities can change at runtime.

                      In this example:

                      • Two stack configurations (SNAP1 and SNAP2) are defined in the CommsDat. The configurations have different settings for the IP layer but the same IPProto and PDP layers.

                      • An application is started on SNAP1. IP_CPR1 and IP_MCPR1 are created.

                      • A second application is started on SNAP2. IP_CPR2 and IP_MCPR2 are created.

                      • Current priorities for IPProto and PDP layer will be recalculated. On this example they do not change because priority 6 is the lowest priority in this stack.

                      • If first application stops its connection and second application continue to work, IP_CPR1 is destroyed. IPPROTO_CPR1 and PDP_CPR1 priorities will be recalculated.

                        IPPROTO_CPR1 priority = max_priority{5, 6} = 5

                        PDP_CPR1 priority = max_priority{4, 5} = 4

                      What is Contention? What is Contention + Management? Starting a Network Connection Tutorial                       \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FFBB390B-0A5D-5ABC-A111-95B3C84818DE_d0e79983_href.png Binary file Symbian3/SDK/Source/GUID-FFBB390B-0A5D-5ABC-A111-95B3C84818DE_d0e79983_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FFBB390B-0A5D-5ABC-A111-95B3C84818DE_d0e86695_href.png Binary file Symbian3/SDK/Source/GUID-FFBB390B-0A5D-5ABC-A111-95B3C84818DE_d0e86695_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FFC6F01E-15AB-43E6-90E8-0E42DA297AE9_d0e3849_href.png Binary file Symbian3/SDK/Source/GUID-FFC6F01E-15AB-43E6-90E8-0E42DA297AE9_d0e3849_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FFC6F01E-15AB-43E6-90E8-0E42DA297AE9_d0e5124_href.png Binary file Symbian3/SDK/Source/GUID-FFC6F01E-15AB-43E6-90E8-0E42DA297AE9_d0e5124_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FFE69A34-2FF8-5FC9-A295-5D3C05A2D7D7.dita --- a/Symbian3/SDK/Source/GUID-FFE69A34-2FF8-5FC9-A295-5D3C05A2D7D7.dita Wed Mar 31 11:11:55 2010 +0100 +++ b/Symbian3/SDK/Source/GUID-FFE69A34-2FF8-5FC9-A295-5D3C05A2D7D7.dita Fri Jun 11 12:39:03 2010 +0100 @@ -1,12 +1,30 @@ - - - - - -List of Constants and Enumerations

                      The following are the SIP profile settings that are available as a part of the SIP Profile API:

                      KSIPProfileId, KSIPProviderName, KSIPAccessPointId, KSIPSigComp, KSIPSecurityNegotiation, KSIPAutoRegistration, KSIPUserAor, KSIPProfileRegistered, KSIPRegisteredAors, KSIPNegotiatedSecurityMechanism, KSIPDefaultProfile, KSIPContactHeaderParams, KSIPRegistrar, KSIPResolveProxy, KSIPOutboundProxy, KSIPRegisteredContact, KSIPDigestUserName, KSIPDigestRealm, KSIPServerAddress, KSIPSnapId, KSIPContactHeaderUser, KSIPSoIpTOS.

                      The following are the Profile Registry Events that are available as a part of the SIP Profile API:

                      EProfileCreated, EProfileUpdated, EProfileRegistered, EProfileDeregistered, EProfileDestroyed.

                      The following are the Container for the profile type information as a part of the SIP Profile API.

                      EInternet, EIms, EOther.

                      The following are the SIP Profile ALR events as part of the SIP Profile API:

                      EIapAvailable, EMigrationStarted, EMigrationCompleted.

                      The following are the SIP Managed Profile settings that are available as a part of the SIP Managed Profile API:

                      KSIPPrivateIdentity, KSIPDigestPassword, KSIPHeaders, KSIPAllowIMSRegistration, KSIPProfileLocked, KSIPAllowAutoRegistrationOnlyOnHomeNetwork.

                      \ No newline at end of file + + + + + +List of +Constants and Enumerations +

                      The following are the SIP profile settings that are available as a part +of the SIP Profile API:

                      +

                      KSIPProfileId, KSIPProviderName, KSIPAccessPointId, KSIPSigComp, KSIPSecurityNegotiation, KSIPAutoRegistration,KSIPUserAor , KSIPProfileRegistered, KSIPRegisteredAors, KSIPNegotiatedSecurityMechanism, KSIPDefaultProfile, KSIPContactHeaderParamsKSIPRegistrar, KSIPResolveProxy, KSIPOutboundProxy, KSIPRegisteredContact, KSIPDigestUserName, KSIPDigestRealm, KSIPServerAddress, KSIPSnapId, KSIPContactHeaderUser, KSIPSoIpTOS.

                      +

                      The following are the Profile Registry Events that are available as a part +of the SIP Profile API:

                      +

                      EProfileCreated , EProfileUpdated, EProfileRegistered, EProfileDeregistered, EProfileDestroyed.

                      +

                      The following are the Container for the profile type information as a part +of the SIP Profile API.

                      +

                      EInternet, EIms, EOther.

                      +

                      The following are the SIP Profile ALR events as part of the SIP Profile +API:

                      +

                      EIapAvailable, EMigrationStarted, EMigrationCompleted.

                      +

                      The following are the SIP Managed Profile settings that are available as +a part of the SIP Managed Profile API:

                      +

                      KSIPPrivateIdentity, KSIPDigestPassword, KSIPHeaders, KSIPAllowIMSRegistration, KSIPProfileLocked, KSIPAllowAutoRegistrationOnlyOnHomeNetwork.

                      +

                      +                       \ No newline at end of file diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FFE6BAF8-C093-53FC-8672-365BAF38E048_d0e338240_href.png Binary file Symbian3/SDK/Source/GUID-FFE6BAF8-C093-53FC-8672-365BAF38E048_d0e338240_href.png has changed diff -r 51a74ef9ed63 -r ae94777fff8f Symbian3/SDK/Source/GUID-FFE6BAF8-C093-53FC-8672-365BAF38E048_d0e344437_href.png Binary file Symbian3/SDK/Source/GUID-FFE6BAF8-C093-53FC-8672-365BAF38E048_d0e344437_href.png has changed